Integrations (Generic Service)

Integrations (Generic Service)

Norsk

Step-by-step guide

  1. What is an Integration?

  2. How do you create an integration?

    1. Settings

    2. Request headers

    3. Request body

    4. Response

  3. 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.

 

image-20240819-083412.png

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.)

 

image-20240819-083904.png

 

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.

 

image-20240819-084007.png

 

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.

 

image-20240819-084141.png

 

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.

 

image-20240819-084249.png

 

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.

 

image-20240819-084414.png

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 (+).

 

image-20240819-084500.png

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.

 

image-20240819-085108.png

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. 

 

image-20240819-085515.png

 

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.

 

image-20240819-090006.png

 

Save the service, and create a new version by clicking the New version button.

 

image-20240819-090934.png

 

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.

image-20240819-075020.png

 

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.

 

image-20240819-080317.png

Next, Click on the response button on the left-hand panel and click on the transformation Script for the response variable.

image-20240819-080822.png

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

image-20240819-081154.png