Setting up WorkZone to pull in form submissions from Interact
You have the form set up in Interact and submissions are coming in, but what exactly is required on the WorkZone side, to get the form submissions imported into KMD WorkZone?
This article is the second in a series of six that will be released over the coming weeks. The articles will describe an example of how to digitize a complete business process using the configuration tools you have at your disposal in KMD WorkZone. In the first article, focus was on the setup in Interact. In this article, we will look at what is required in KMD WorkZone to pull in new submissions from a specific Interact form.
Once you have the form ready, you need to setup WorkZone to keep an eye out for new submissions of the form. There are different ways you can administer this and which way you prefer is completely up to you.
Before the configuration can work, there are some initial configurations that have to be taken care of (most likely by a WorkZone technician – but get in touch with our support team if in doubt about whether or not this has been done):
- There must be open for https (443) requests from WorkZone (both web and agent servers) to Interact
- A certificate must be installed to ensure the communication between Interact and WorkZone is secure.
Once this one-time setup is in place, we can move on to the configuration of the service workflow, which is what is used to pull the submissions into WorkZone.
So, head to WorkZone Configurator and go to Process > Service workflows. You need to have the access code PROCESSADM to make any changes here.
If you have many workflows configured, you can use the filter option to show workflows of the type Interact connector only, which is what we are interested in in this context.
Basically, service workflows are workflows that run continuously in the background and carry out different tasks. There are a few different types of service workflows in WorkZone and the type that is responsible for the connection to Interact, is called an Interact connector service workflow. What this workflow does is to ask Interact at set intervals if there are any new submissions. And then it creates cases based on the submission content.
You can have several connector workflows running in your WorkZone environment, but you can also have one workflow that watches all the different Interact forms. So, let us have a look at the different configuration options.
Creating a new service workflow is a two-step process. First you select the type and give it a name. You must give it a description to make it easier for others to understand exactly what the workflow does.
Once you have provided those details, you click Create.
Now you need to configure the service workflow. You do this by hovering over the icon to the left of the name of the service workflow and then clicking on the settings icon that will pop up (the icon in the middle of the three that appear when hovering over the icon at the right):
That will open the settings for the service workflow, and this is where you need to provide the last bit of information before you can enable the workflow.
Here you will need to let WorkZone know how often to check for new submissions received in Interact. You need to specify this in seconds and the lowest number you can provide is 30. In that case we will ask every 30 seconds if new submissions are available. We recommend, that you choose larger intervals, so as to put less strain on the system. However, this decision depends on how important it is to have cases created quickly after a form has been submitted.
Secondly, you need to provide the URL of the Interact REST API. If you do not know this URL, you will probably need to get in touch with WorkZone support or whoever is responsible for your Interact installation.
The client ID is also something that you need to get from whoever is responsible for your Interact environment. This is set up in the database in Interact when the REST API is configured there.
Then you need to have the certificate thumbprint from the certificate that I mentioned in the beginning of this article.
In the field FormIDs, you have a few different options:
- Leave the field empty. Then the workflow will retrieve submissions from all published forms in Interact.
- Just provide a single ID and use separate workflows for each form you want to check.
- Provide a comma separated list of different IDs.
Generally, we recommend the last option as this gives you the best overview of which form is being retrieved from Interact.
The form IDs that you need to provide, you find in the Interact client. The easiest way to find the correct ID is to make a test submission of the form in the Interact LAB-environment and then go to Submitted dialogue, select the Lab database, choose the correct form/dialogue from the dropdown and click Retrieve dialogue. Then you take the third part of the xml or pdf file name as seen below:
Switching back to the WorkZone Configurator, the last parameter you need to provide is the executing user. This is the user that will be used to create the cases, documents, contacts and so on, when the submission is retrieved into WorkZone. You can select any user, but it is of course important that the user you select has sufficient privileges to perform these actions in WorkZone. For more information on this, see the section on ExecutingUser in the documentation.
Once all the parameters have been put in, you hit Save. Then you can enable the workflow by again hovering over the icon to the left of the service workflow name on the overview, and this time select the first of the little icons that appear:
In the modal that shows up you enable the workflow on the little toggle that you see and hit Save once more.
Now you are all set and after a few minutes the workflow will kick into action and start pulling in the submissions from Interact. So, basically, if there are already some form submissions waiting to be imported, these will be retrieved as soon as the workflow is up and running. It does take a few minutes, so go and get yourself a cup of coffee, come back and have a look at all the newly created cases. Magic.
Ok, we are almost done for this article, but let us just mention two additional things.
If you are like most people, you may not have gotten the mapping, that we talked about in the first article, completely right the first time around. You may have forgotten to provide a value for a field that is required to create a case in WorkZone. If this happens, the case cannot be created successfully. Instead an error case is created, and you can look in the case text for clues as to what you need to correct before it will work as intended. Error cases have the title [INTERACT ERROR] (always in English):
It can be a good idea to set up a dashboard in WorkZone to keep track these error cases. Errors can also happen later, if changes are made to the relevant fields in WorkZone and the mapping in Interact is not updated.
Finally, let us have a look in the Interact client how you can see which form submissions have been imported into WorkZone and what the different statuses that a submission can have in Interact means.
In Interact, you go to Submitted dialogue in the Administration section on the left menu. Here you choose the correct database, which will in a production setup be External. Then you choose the relevant form in the Dialogue dropdown and click Retrieve dialogue.
On the resulting overview, you see the reference ID for the specific submission (1). And you can also see the status of the submission (2). Imported means that the form has been retrieved successfully by WorkZone. However, it is important to be aware that it does not mean that the data from the form was mapped correctly. It could also mean that the form was retrieved but an error case was created in WorkZone.
If the status is Delivered it means that the form was submitted successfully but not yet retrieved by WorkZone.
Another status to be aware of is Temporarily blocked. This means that WorkZone has tried to retrieve the submission, but something went wrong. In this case, it is necessary to dive into the WorkZone Process Workflow Logs to investigate what has gone wrong.
That was it for the second article in this series.
Now we have the form set up and new submissions result in new cases in WorkZone. But to really kick in with some automation magic, we need something more to happen when we get the cases created in WorkZone. So, in the next article we will look at how to use another type of service workflow to apply a Case Activity List and start off with some automatic case management.
See you back here for the next installment!
Here is a reminder of the topics for the different articles:
- Mapping input from an Interact form to fields in WorkZone
- The Interact service workflow – how you connect Interact and your WorkZone backend (this article)
- Using the case monitor to automatically initiate case management
- Setting up a DCR graph as the basis for a WorkZone case activity list
- The connection between the DCR Designer and WorkZone
- A summary article where we recap how all the different elements work in unison
Relevant documentation links for this article:
- The Interact Connector
- Interact documentation about the Submitted dialogue section