Generic services (form and workflow population)
Compose Enterprise is going through a design update. The illustrations on this page might be of the old design, but the information is up to date. Thank you for your patience during this update!
Generic services are immensely practical when creating services. They embody the essence of automation as you can use them to populate option sources, directly in the option source builder or in multiselect question elements, and populate workflows and forms. This user guide will walk you through how to connect generic services to forms and workflows with three user cases. We will cover:
How to call a generic service with an event in the form builder
How to populate a form via a service in the workflow builder
To learn how to build generic services, see the Integration Builder and Integrations (Generic Service) documentation, or watch this Compose tutorial on how to create a generic service – Generic Service Towards An Open API (English subtitles available). To learn how to populate option sources, see the Option source - Auto-populate via service user guide.
Form Builder - Call Generic Service
This example will be with a generic service call triggered by an event populating a form with business information from Brønnøysundregisteret. We want the input of an organization number by the end user to trigger a population of the form with business information (such as the name of the business, address, zip code and city).
The generic service we will connect to the form has the organization number as the request variable, and the business information as response variables.
Since we want the action of writing the organization number to trigger the population of the other form fields, we select the Organization number question element and click the Events button.
The Events Configuration menu will pop up. Click New event to continue.
In the two columns Event and Action, we choose respectively which event that triggers which action. We want the form population to occur after the answer is completed, and the action is calling upon a generic service (Call Generic service).
Now we can introduce our generic service. Click Browse, traverse your workspace and select the generic service you want to call upon.
Our generic service has the name “Business information”. Choose the version of your generic service you would like to connect to the form. First off, we need to connect the question element in the form, which takes in the request variable of the generic service. That would be the organization number in our case. Click the Map Request Variables button.
In the Variables menu, the request variables from the generic service is listed on the left (in this case there is only one). Select the variable, click the Value from form radio button and click Browse to locate the organization number question field.
Open up the data model, locate and select the form element equivalent to the request variable, in our case the organization number. Click OK, and OK again to go back to the Events Configuration menu.
Now it is time to map the response variables from the generic service to the corresponding form elements. Click the Map Response Variables button.
Similar to the Variables menu for the request variables, the response variables are also listed on the left. Select one of the variables and click Select Question From Model in order to conduct the mapping process, very much similar to the mapping of the request variable.
Choose the corresponding question element to the response variable you selected, click OK and repeat the process for all the response variables you wish to map. Note: In this case, the response variable and question element names were chosen meticulously to illustrate an intuitive example. The mapping in your case might be confusing if your names are not corresponding, so one should keep that in mind when creating generic services intended for form population.
In the Value column, the question IDs (Q4, Q5, Q6 etc.) to the elements mapped to the response variables are displayed. It is not necessary to map every response variables in order to be able to run the generic service. However, you must map all request variables. Click OK twice to close the Variables and Events Configuration windows.
As you can see, a green dot has been added to the top left corner of the Organization number element. This indicates that the field has an event connected to it. Click Save Draft and preview the form to test your event.
Hopefully, your form should be populated with no problems!
Workflow Builder – Populate via Service
Create a sample workflow with at least one Form activity. To connect the service to your workflow, select Populate via service in the Form Activity properties panel to the right of the workflow. You will need to pick a previously created generic service. Select Workspace item and Browse to find the generic service.
The dialog box shows an overview of all the items available to you in the Organizer. Please select a generic service from the list and click OK.
You will now find the name of your selected generic service in the Form Activity properties panel. If the generic service has more than one version, please select the Version you would like to use. Compose also gives you the option to Update to highest minor version automatically. If this is checked, the workflow will automatically use the newest minor version of your service. Hence, you will not have to update the workflow if smaller changes are done to the generic service.
A new major version will be created whenever there is a change to the variable sets, names or types. Anything else (e.g. changing the request, or the XPath expressions) counts as a minor change.
You will also have to map the existing request and response variables in the service, much like the Generic Service Call example. Click on Request Variables. To map a variable, select a request variable in the list. The variable details appears on the right. Compose provides you with two options – map to a Static Value or Value From Workflow. If Static Value is selected, please enter the correct value in the input field. If you would like to map the request variable to a workflow value (e.g. the value of a form question), select Value From Workflow and Browse to find the preferred value.
If the service has more than one request variable, repeat this until you have mapped all the request variables to either static values or values from the workflow.
In the Form Activity’s properties panel you will also find Response Variables. Click the button, and a pop-up with all the existing response variables appear. When you select one of the response variables from the list, the details for this output variable will appear on the right. To populate a form question, click Select Question Form Model. When all the desired response variables have been mapped, click OK. Note that it is mandatory to map all the request variables, but it is not mandatory to do so for response variables – one can choose not to map any at all, although the usefulness of that in this case is limited.
These were the necessary steps to set up and use a generic service. You will need to configure the remaining workflow elements, Save draft and Create a Version of the workflow. Then navigate to the Organizer to start and execute your workflow to test the service.
Generic Service – Workflow activity
The Generic Service activity provides you with the possibility to run generic service calls at any chosen time in a workflow. As long as it is placed between the start point and the end point, the designer is free to place it as desired. The activity needs to be connected to a generic service created in Compose, and can use values from workflow activities like form answers or workflow variables as request/response variables. You can find the Generic Service activity under Data Delivery in the Activities panel in the Workflow Builder.
In this example we will do the same form population as demonstrated in the first example of this user guide, only with a fixed organization number in the generic service activity. Create or open a workflow including a Start Point, a Generic Service activity, a Form activity and an End Point. If you need more information to set up the other workflow activities, please refer to the Build a simple workflow user guide.
Select the Generic Service activity on the canvas to reveal the Properties panel on the right. Click Browse to find the generic service you wish to connect.
Choose a generic service and click OK.
If the generic service you’ve chosen has request variables, you need to map them. Click the Map Request Variables button to open a familiar Variables menu if you’ve mapped variables before.
Select the variable and provide a static value, aka. an organization number. The goal is to have the form pre-filled when opened by the end user. Then click OK.
Then select the Form activity in the canvas. If you have not yet connected the form to a versioned form, you will need to do that first. When a form has been connected, click the Pre populate question button.
In the Question Answers menu you will have to select the questions you wish to pre-populate. Click the Select Question From Model button.
Select the question you wish to pre-populate, click OK and repeat this for all questions you wish to pre-populate.
Select the first question. For this example we wish to have the form questions populated by the response variables from the Generic Service activity. Choose the Value from Workflow radio button and click Browse to browse the accessible variables.
Expand the Generic Service activity by clicking the arrow and find the correct Response Variable. Select the variable and press OK.
The Response variable value will be displayed next to the question ID in the list of selected questions.
Repeat these mapping steps for all the selected questions. When the list of questions and values is completed, click OK.
Please make sure the other workflow element properties are set and remember to save the draft and create a version.
As you can see, the mapping of request and response variables follow the same recipe, but you have the freedom to use your generic services at multiple places across Compose Builders.