Selected Interventions - Echo
The Selected Interventions Echo integration allows Events to be created in Echo using data from Jadu Connect cases. Jadu Connect cases are also automatically updated when an associated Event is updated in Echo. The integration is compatible with Veolia and Suez Echo implementations.
Limitations
- Existing Events in Echo cannot currently be updated via Jadu Connect.
General settings
On the General tab you can enable/disable the integration with Echo, and configure its settings.
When you save the settings, with the integration enabled, Jadu Connect will attempt to connect to Echo to verify the settings.
If the connection fails, the settings will not be saved, and an error message detailing the reason for the failed connection will be displayed.
- Base url - the URL to the Echo service API.
- Username - the username of the account that you wish Jadu Connect to transact with.
- Password - the password of the account that you wish Jadu Connect to transact with.
References
A Reference is a special type of field used to store an Event identifier against a case. When creating a mapping template, the reference to which the template applies must be selected.
Mapping templates
A Mapping template is a set of mappings which define the data to be passed between Jadu Connect and Echo when creating Events.
After giving your mapping template a name, you must select the type. 2 types of mapping template can be created:
- Create Event (outgoing) - defines the fields to be populated when creating an Event.
- Event updated (incoming) - defines the Event data which should be pulled back from Echo and stored on the Jadu Connect case, following a Create Event action, or when an update is received from Echo for this Event.
Finally, you must complete the mappings.
In the first row of the mappings, you must select which Reference the template applies to. For Create Event templates, this means that the reference number for the new Event will be stored in this Reference. For Event updated (incoming) templates, this means that the template would be applied following a Create Event action that is linked to this Reference, or when an update is received from Echo for this Event.
The subsequent rows are field mappings. To create an Event in Echo, at a minimum the Reference (Event Number), Service ID and Event Type ID for the Event must be set. You can then add as many additional mappings as you wish by clicking the Add Another button.
The following type of data can be used from the Jadu Connect case:
- Case field values
- Case dates
- Linked Person details
- Linked Address details
You can also configure a manual text mapping if the value of the Event field should be the same each time that mapping template is used.
You should not rely on the integration to ensure that data is removed from the Jadu Connect case or the Echo Event automatically when clearing down personal data in either system. The specific tools provided in each system should be used directly to ensure that no personal data is left unnecessarily.
Outgoing mapping templates are applied via rules, using the Apply integration action.
Incoming mapping templates are applied as a result of a Create Event mapping template being applied, or when an update is received from Echo for an Event. All incoming mapping templates for the applicable Reference will be applied.
Since integrations are run as background tasks and will be retried in the case of any connectivity failure, any subsequent rule actions (e.g. sending an email) will likely be performed before the Event has been created in Echo. This should therefore be accounted for when designing workflows.
Extended data
Echo has an Extended data section of an Event. These fields can be populated in Connect by setting the Additional Connect field value to the value of the extended data item, and the Selected Interventions Echo field with the data type ID of the extended data item.
For boolean data types, such as a checkbox, the values 1, true, yes, y, 0, false, no and n are accepted.
Image uploads
For case attachment images to be uploaded to the Echo service, the Create Event action must be run after the files have been attached to the case. Also, for each image, an extended data field mapping must be set up with its value set to the image name.
As an example, a Connect case could be submitted by filling out a form in Jadu Central. When the end user attaches images to the XFP form, all image names can be set to a single field value in Jadu Central. E.g:
image1.jpg, image2.jpg, image3.jpg.
In the Connect mapping template, this value can be used in all image extended data fields set in Echo:
| Additional Connect field | Actual value | Selected Interventions Echo field |
|---|---|---|
| ImageNames | image1.jpg, image2.jpg, image3.jpg | 123 |
| ImageNames | image1.jpg, image2.jpg, image3.jpg | 123 |
| ImageNames | image1.jpg, image2.jpg, image3.jpg | 123 |
| ImageNames | image1.jpg, image2.jpg, image3.jpg | 123 |
As a result of this mapping, field 1 will be populated with a link to image1.jpg, 2 with image2.jpg and 3 with image3.jpg. Though a mapping exists for field 4, the user in this scenario only uploaded 3 images, so the 4th field will be left empty.
Central Forms will attach files from the form submission after the case has been created, so to avoid the integration creating the Event in Echo before all files have been attached, the time in status or date triggers can be used within the workflow setup:
Any files uploaded to the Jadu Connect case after the Event has been created do not get added to the Event in Echo.
Event updates
Echo can be configured to send a JSON request to a configured endpoint when an Event is updated.
Jadu Connect provides an endpoint to receive these requests and update the associated case accordingly.
The Echo compatible Connect endpoint implements a custom method of authentication over the rest of the Service API. The value of a Basic Authorization header is made up of the word “Basic”, followed by a space, followed by a concatenated then base64 encoded string in the format username:password. The Jadu Connect endpoint expects the username to be the email address of the API user in lowercase, and the password to be the Service API key.
Endpoint format is as follows:
<service-api-url>/integration/echo/case/update/NotifyEventUpdated
Log
The integration log provides a summary of case integration actions that have occurred; including where Events have been successfully created, and where Events have failed to be created (including the reason for the failure, if known). The log also details any validation failures when creating the Event, or when updating the case with values from the Event. Reviewing the integration log can help to identify incorrect mappings or areas where validation during data capture is insufficient.
Where an action has failed due to a connection issue or other intermittent error, it will be retried up to a maximum of ten times. If integration has failed due to a validation error (e.g. due to an invalid mapping value), it will not be retried.
