Integrations (Generic Service)
Step-by-step guide
What is an Integration?
How do you create an integration?
Settings
Request headers
Request body
Response
How do you reference request variables in response variable transformation scripts?
What is an Integration?
Compose provides you with the possibility to populate form answers using a generic webservice. Any external service that accepts and produces XML or JSON data can be used in Compose through this option. The external service is represented as a set of request and response variables towards the workflow, where they can be mapped to e.g. question answers. The request is formatted using the same principles as in Text Generators - using request variables it is possible to tailor the request format to the needs of the given external system. The data retrieved from the external service is parsed, and response variable values are extracted using XPath expressions that are configured in the Generic Service builder.
How do you create an Integration?
In addition to the step-by-step guide below, a video tutorial of how you create a Generic Service is available here. The tutorial is in Norwegian, but English subtitles are available.
A Generic Service can be created/edited in the generic service builder, but you may also create a new generic service directly from the Organizer. Please click Create Generic Service from the top menu in the Organizer and enter your preferred service name.
Settings section
Open the newly created generic service and navigate to the Settings section in the Generic Service Builder. Under properties, you will find the URL input field, which can also be parameterized using {} notation. (This can be useful for instance in cases where organizational information is provided through a URL and where the information provided is based on organizational number. By adding the organizational number as a parameter {orgnr} in the URL, you can look up organizational information with an organizational number entered by a respondent.)
Select the service method – Compose supports GET/PUT/POST/DELETE. Note that for GET requests – based on the HTTP standard – using a request body is not supported.
In this example, we will use the POST method. To do this you need to create request variables. Click the Create button (+) and enter the preferred name for the request variable.
When you have created the request variable, double-click on it to edit the properties. In this example, we will set our variable to be a String.
Repeat until you have added as many request variables as required for your service.
The service also requires response variables. The response variables contain the returned data from the service call and have to be created and configured under Response variables.
Create, name and configure the properties of each response variable by double-clicking on the variable. Repeat this for as many response variables as required for your service.
Select the data-interchange format in the response variable menu.
Request Headers section
If your generic service integrates toward a private API or any register where authentication is necessary, you may add new request headers in this section by clicking the Create button (+).
Request Body section
Here you can define the request format using the defined request variables. The format should comply with the format of the service endpoint. Since Compose provides a Text Generator-like interface, here it is possible to define an arbitrary request format.
Response section
For each response variable you need to specify the XPath expression to use with the data-interchange format you picked in the Settings section. Pay attention to the data types and that the XPath expression should not return a node, but a value.
If you want to customize the value of your response variables, you may write a transformation script by clicking the green Transformation button. The programming language is Groovy.
Save the service, and create a new version by clicking the New version button.
When a generic service has been created, it can be used in multiple workflows and forms. Check out either the video tutorial at the top or the Generic services (form and workflow population) user guide, to learn how to connect generic services to forms and workflows.
How do you reference request variables in response variable transformation scripts?
Previously we were only able to define the lists filtered by workflow IDs. In a recent development, we were able to further filter these lists within the same workflow. We can use the filter value dynamically by using the request variable as a filter value within the response variable. an example is given below,
Example- You would like to filter out all the students in a school. further you want to filter out all the grade 1 students in that school. you can do so by following the steps below.
First step, create a list of your choice. You can follow this link to learn how to create lists.https://composetogo.atlassian.net/wiki/x/RAAc with the request variables added.
Next, Create an integration and add request and response variables.
in the given example, we have named the request variable as the “filterValue” where it acts as a parameter that determines which records are included in the resulting list. and the response variable as the “filteredList” where the filtered list of case records is based on the “filterValue” provided in the request.
Next, Click on the response button on the left-hand panel and click on the transformation Script for the response variable.
now you can call the variable value that you created in the request variable (filterValue) within the script to further filter out the records that were filtered with the workflow ID