Web Service Integrations allow you to pass data from a submitted form to a web service, which can then initiate further processing of the data. This could include:
- Inserting the data into one or more SQL databases
- Triggering workflow or other back-office process?
- Sending notifications to interested parties
Both LIM14 and the council's own LIM are capable of making connections to the outside internet. Generally a council will lock down a LIM on installation so it can only access internal systems. So if a LIM needs to be locked down to only access internal systems, then it is possible to use LIM14 for external services, but that is up to your discretion.
Webservice
WSDL URL - This is the webservice url
WSDL LIM - This is the webservice lim
Validate & Populate - Clicking this will autodisplay the Available Functions along with the URL. Selecting the required function will then automatically display the correct Action and the corresponding Payload.
When adding client credentials in the case of most webservices the authentication credentials will need to be added to the SOAP header within the payload. We would suggest using an external app like SoapUI to build the xml payload and then copy that in.
Note that it is also possible to use @af:if statements in the payload to make parts of it conditional on the values of fields in a form.
In the 'Fields' box, you should enter fields in JSON format to edit how the Formatted Results are displayed.
The XSLT Stylesheet should only be entered in XML format and this is used to change the output of an XML using another XML.
Web Service integrations supports Version 1.0 of XSLT
Results Page
This allows you to set the "Results Page Columns".
You need to enter JSON into the box similar to defining the "Fields" in the results, Note:The JSON needs to refer to the transformed value of a response if any of the response columns have been altered by the Fields JSON.
e.g.
The WS returns a node <value1>
In the Fields JSON you have:
{ "value1":"field-dataname" }
to transform the name of the node to the dataname of the field it will populate.
Then in "Results Page Columns" you will need to use:
{ "field-dataname":"friendly result column header" }
Authentication
Secure fields - This should be JSON format 'key:value', where key is the secure token name and value is the field to be used as the value
Authentication Type = select WSSE or HTTP (note: only Webservice Version 2 can use WSSE Authntication)
Occasionally a Web Service or HTTP integration can potentially return either single records or multiple records of data. Single results are not wrapped inside a “RepeatableNode” whereas multiple records are. This can potentially cause issues with the “Path to values” field when trying to parse data from the integration response due to the discrepancy in the XML.
When this is the case, the attached XSLT can be pasted into the XSLT box against the integration which will wrap the single response in a RepeatableNode to ensure all responses are handled the same way
Testing
The web service integration can be tested using the test assistant
The “Raw Results” Tab displays the response of the Webservice.
The “Transformed Results” Tab displays the results after being modified by the Xslt Stylesheet.
The “ Formatted Results “ after transforming the response with the Xslt Stylesheet and for the fields chosen are :
Returning Webservice Integrations into a Select Field
In an HTTP/Webservice integration, the fields box can be used to map data returned by the API to form fields e.g.
{
"uprn":"uprn",
"postcode":"postcode",
"locality":"locality",
"town":"town",
"county":"display",
"street": "name",
}
* The key/value pair works like this
{
"nameOfColumn":"dataNameofFormField"
}
i.e. The name of what the integration returns goes on the left and the field in your form you want that value to go in goes on the right.
If you are returning values from http/webservice to a select list you will need to use this fields box to map some of the fields returned by the integrations to "name" and "display".
A common use of this functionality is with an LLPG lookup.
Further useful reading:
top of page
- There are some known issues with the product not loading in correct payloads via a WSDL.
When this occurs the payload can be copied in manually into the payload box.
- Data Type - Data Set
This is a deprecated data type and can be ignored
- On validate & populate the error "No data returned from URL - Check LIM / Version" is seen
This is a generic error message. The validate & populate functionality only works with some standards for webservices, if it produces an error it just means you need to implement the webservice more manually.
- When V2 finds an array in the <body> of a Webservice/HTTP integration response it will introduce a <RepeatableNode> element. This was introduced to make it easier for customers who were previously having to write extensive XSLT to handle array returns. The <RepeatableNode> is expected behaviour for V2 integrations. You can tell if an integration returns an array or not by looking at the Raw Response. An item will return like this: <Body>{"itemName... whereas an array will return <Body>[{"postNumber... - ie. a square bracket indicates your integration is returning an array. Even if your array returns one item it will introduce the repeatable node element.
