Integration Manager
Introduction
The integration manager is used to create a wide range of integrations used within a process from an email confirming receipt of a completed form to a citizen, to a complex webservice updating a back office system. Access to the Integration manager is controlled through Permission Manager - and it can be accessed at yourformsite.achieveservice.com/admin/integrations. The library of integrations allows for standard integrations to be built and reused as appropriate for a range of processes.
The Integration manager can also be accessed from the menu from the right hand settings cog - ie click on your logon name which will give you the following menu options dependent upon permissions.
Click on Integrations Manager which will take you to the Integrations Manager page.
To access Integrations manager a user will require both AF Designer and AF Integrations permission from Permission Manager
Integration list
The ‘Integrations’ page lists the ‘Name’ and ‘Type’ of each integration. You can also search for specific integrations in the search bar or filter the search by ordering the columns or typing in a keyword.
Adding a new integration
From the +New Integration you can create a new integrations
Adding a new integration
- Category: gives you a drop down list of the different types of categories to select for your integration. You can also create a new category. This new Category will appear on the main Integrations Page on the left hand side along with the other existing integrations. (Note: If you remove all the integrations from a category they are associated to, the category will deleted automatically)
- Integration name: where you enter the name of your new integration. No two integrations can share the same name.
- LIM: gives you a drop down list of the different LIMs for you to select for your integration to run on. Note: If email integrations are sent from Lim14 then they are likely to be regarded as spam by recipients email services. We advise to change to local LIM to prevent this issue.
- Type: here you select the specific type of integration being created (Please note Case integrations are not available)
- Data Type: Setting the integration as an 'Integration' means it can be added to stages inside a process and set to run on Submission, Pre-Submission, Escalation, etc. A 'Lookup' can be added inside a form, such as to specific field types like buttons or select fields. An 'Integration/Lookup' is an integration that is both an integration and a lookup, ie. you can add it to run on a process stage or you can add it to a specific field. Note: 'Data-Set' is deprecated and should not be used.
- Allow Offline: enables the use of the integration with a special mobile integration, which allows you to download a dataset by passing in limit and offset. This means you can copy a database such as LLPG onto your device.
When you choose a ‘Type’ of integration whether that be ‘Database’, ‘Email’ or any of the others, you are given a ‘Failure Notification’ option to fill out. Once again, you need to choose a LIM from the drop down options and you can enter an email address to receive the failure notification. (Multiple email addresses can be entered. All will receive the notifications.) Also, you can define if the integration activity is only logged when there is an error - selecting No will record all integrations within the logs. (You are advised to use LIM14 to send the failure notification, otherwise if the LIM is the point of failure you will not receive the notification). Once a Process is stable it is advised to switch the logging to log only on error, this will help keep minimal logs and ensure you can search the Logs when needed. The Compliance console will delete all logs over 3 months old. It is possible to switch logging back on as required for debugging.
Please note that you must press submit when editing or creating an integration in order to save it.
Amending an existing integration
You can make a change to an integration and the change will be picked up next time it's run, there is no requirement to republish the relevant processes. The integration definition is not stored within the form so it is evaluated on the fly every time the integration is run
Integration Timeouts
V1 integrations time out after 30 seconds. They then retry up to 5 times after this. Additionally, if the integration is a lookup/presubmission integration, there is a total timeout limit of 60 seconds. This means if all the presubmission integrations together exceed 60 seconds they will time out.
V2 integrations time out after 60 seconds and there is no retry or overall limit.
top of page
Token Assistant
The token assistant allows you to easily access a list of tokens for use in the integration based on the tokens for a specific form, environment tokens or general tokens.
To move a token from the token assistant to the content of the integration,simply click in the token name within the assistant, this removes the risk of keying the token incorrectly.
Test Assistant
Can be used to test an integration without the need to complete the form itself - note: payment integrations cannot be tested using the test assistant
The Test assistant allows inputs to be made as defined in the integration based on the tokens used and then on running the test the integration will be run in test mode so the output can be checked - reduces the need to keep filing in the whole form and submitting when testing integrations.
Environment (LIMS)
The LIM provides a secure way for our cloud-based systems to integrate with local services, such as databases, email, and 3rd party applications. It has no user interface, but instead acts as a web server that can service requests that originate from the cloud.
Some customers set up more than one LIM to provide a fail safe option (see below), there is also the option to have a specific LIM to manager Inbox for enhanced security
for those concerned about the LIM being a single point of failure:
Systems
Systems are used to connect to external database systems using either the ODBC or OCI interface. Before creating a Database Lookup or a Database Integration, you must first configure a connection to the required database (this is a System ).
- Click New System button
- Select a category (for ease of finding)
- Select an Organization where applicable - usually default
- Enter System Name
- Enter System Value (Connecting String)
- Select LIM (ie local Lim or Lim 14 as applicable)
- Select System Type - eg ODBC/OCI
- Select Default - No
- Click Submit to Save the new System
- In the Systems Search Bar, enter the System Name to check whether it was successfully created
- Use System Test assistant to check that the connection works
Note: The LIM uses ODBC for connecting to SQL Server, so you need to use uid= and pwd= attributes in your connection string, not User Id= and Password=
To check which system an existing integration is using, you need to go into the integration itself. There is no reporting feature for this.
top of page
Tokens/Environment Tokens
Additional locally required tokens can be created within this section of the integration manager and defined which can then be reused as required throughout forms to pass standard local content to the form/process as per the example above for Suggestions for controlling availability of a form for completion where an integration is unavailable. Such tokens can be used by setting the default value of a field to the Environment token.
Standard local tokens can be used to update all forms simply by updating the content of the one token (useful for calculating credit card surcharges for example).
Known Behaviour
- Environment tokens cannot be exported or transferred between sites
- Environment tokens cannot be used within the Self configuration pages in the Admin Console (Content/Translations>Page Components)
Language Tokens
Language tokens can be set up to automatically translate form/process content when the Language Translation UI is being used and ensures that standard form content is translated across all forms/processes.
Language tokens cannot be exported or transferred between sites at this time.
Logs
The Integration logs provide a wealth of useful information especially in respect of integration failures. They also allow integrations to be re - run as required. (When creating an integration you can define whether to log errors only or successful integrations as well)
Unsuccessful integrations will be highlighted red (you can use the "Show Only Error Logs" to list only those that have resulted in an error as required - or search for an integraton relating to a specific form/process by reference number/name etc
Clicking on a row in the integration log will provide the status and integration details - providing details for diagnostics as required,including:
- Form/integration details/identity
- Date/time
- Error message
- Template
- Requested Data
- Response Data
There is also an option to change the LIM used for the integration and to rerun the integration
Errors and their meanings
'Maximum Call Stack Size Exceeded' - Similar to a timeout in terms of the outcome. The difference is that a timeout means the integration received no response, whereas 'maximum call stack size exceeded' is a recursion error, so something is triggering something else within the platform so many times that it hits the call stack limit. It is a node error, so it is not usually your integration which is the issue. You do not need to notify us about this error as it cannot be traced to a specific event and will be resolved as we make platform performance improvements.
'CSRF check' - These errors can appear for some customers intermittently. This error log is generated to allow us to trace the particular submissions where an issue has occurred so that we may improve the handling of future errors. Currently the feature only logs the error in the integration manager and does not block functionality while we work to make the system handle the functionality more uniformly. These errors should not be effecting any of your users and are not a cause for concern - you do not need to notify us about their appearance and they will eventually stop appearing.
'Cannot read property 'data' of undefined' - This occurs specifically in V2 integrations if the integration is returning an HTML entity code (eg.  ). Generally, this error suggests the integration is breaking due to an unrecognised character.
'End tag afend:repeat]] does not match tag af:repeat at line 00, character 0' or similar - this is because you have not correctly spaced the CDATA tag in a V2 integration using @af:if or @af:repeat. Please ensure you retain the spaces around the inner text as this is essential in Integrations V2.
'Cannot proceed with submission: Node appears to be down' - usually seen in Fill Task API or Start Thread API calls, this error means that there was a temporary issue on our end which should be resolved by trying again after a few moments. We do not need to be notified of this error unless it happens consistently.
'TypeError: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt' - This message indicates a local issue with your LIM. Firmstep usually cannot be of assistance in resolving this error so we recommend if you begin to see this error frequently, you contact your internal IT team.
'Request payload too large' - The integration log is over 2MB in size. This means we will not store the payload for the integration. This is not the actual error message for the integration, it just means what it requested was too large to show in the logs and will slow them down.
List Of Integrations For a Process
From the Process Settings tab it is possible to create a download of all integrations used by the process
(there is no option to list all processes associated with any given integration)
top of page
Further useful reading:
- Tokens available through the platform
t
