Idox Cloud / Tascomi
Tascomi was acquired by Idox in August 2019 and rebranded as Idox Cloud in October 2020. Whilst the software and the documentation below still refers to "Tascomi", we understand the integration continues to work as expected with Idox Cloud.
The Tascomi integration allows Service Requests to be raised in Tascomi using data from CXM cases.
Limitations
- Currently only one-way integration is possible; updates made to the Service Request directly in Tascomi would not be pushed back to CXM.
- There is currently no support for populating additional fields which may be enabled based upon certain Request codes (i.e. those relating to Food Complaints, Trading Standards, Fly Tipping, and Port Health).
- It is not possible to create manually entered addresses for Service Request Locations. If a Service Request Location needs to be set, a valid UPRN or USRN must be present in the mappings.
- Contact History is not populated in Tascomi when a Contact Record (linked to a Service Request) is updated via the integration.
General settings
On the General tab you can enable / disable the integration with Tascomi, and configure its settings.
When you save the settings, with the integration enabled, CXM will attempt to connect to Tascomi in order 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.
- API base url - The base URL of the REST API, e.g. https://my-council.tascomi.com/rest. This should exclude the version portion (e.g.
/v1/) of the base url supplied within the Tascomi REST API documentation. - API public key and API private key - Keys required to access the API, these will be provided by Tascomi. Please see the API access section below for the minimum table access the API key must have in order for the integration to fully function.
- Timezone - the timezone set for Tascomi in "Location/Area" format (list of supported timezones). Defaults to
Europe/London. - Street Record text - This is used, along with a USRN, to identify a street in Tascomi's dft_locations table. Defaults to
STREET RECORD.
References
A Reference is a special type of field used to store a Service Request number against a case. When creating a mapping template, the reference which the template applies to must be selected.
Mapping templates
A Mapping template is a set of mappings which define the data to be passed between CXM and Tascomi when creating and updating Service Requests.
After giving your mapping template a name, you must select the type. There are 3 types of mapping template that can be created:
- Create Service Request (outgoing) - defines the fields to be populated when creating a Service Request.
- Update Service Request (outgoing) - defines the fields to be updated when updating a Service Request.
- Service Request (incoming) - can be used to pull back the Service Request Number after creation of Service Request, to store in a field on the CXM case.
Finally you must complete the mappings.
In the first row of the mappings you must select which Reference the template applies to. For Create Service Request templates, this means that the reference number for the new Service Request will be stored in this Reference. For Update Service Request templates, this means that the reference number of the Service Request to be updated, is held in this Reference. For Service Request templates, this means that the template would be applied following a create/update action linked to this Reference.
The subsequent rows are field mappings. In order to raise a Service Request in Tascomi, at a minimum the Core Function (code), Request Code and Investigating Officer (code) for the Service Request 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 CXM 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 Service Request field should be the same each time that mapping template is used.
Contact records
Rather than creating a new Contact record for each Service Request raised via the the integration, the Contact Reference field can be used prevent duplicate records being created.
The logic that will be followed is: when the mapping template is evaluated, if there is a value for the “Requester Reference” field, it will first search Tascomi for an existing Contact with this Reference. If exactly one record is found, this will be linked to the “Requester” field on the Service Request. If any further “Requester” mappings have values (name, address, contact details, etc), the Contact record will be updated with these. If zero or many Contact records are found with this reference, a new record will be created for the purposes of this Service Request. If any further “Requester” mappings have values (name, address, contact details, etc), these will be populated on the new Contact record.
The same logic will be followed for the “Contact Request” field.
It is advised that the CXM Person reference is used for this purpose, where the user is signed in, or the case has been created ‘on behalf of’ a Person. For Service Requests where the Requester’s details do not need to be captured, an “anonymous” Contact record could be created in Tascomi with a specific Reference e.g. “ANON”, which could be specified in the CXM mapping template.
Warning: GDPR - deleting case / service request data
You should not rely on the integration to ensure that data is removed from the CXM case or the Tascomi Service Request 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 or Update Service Request mapping template being applied. All incoming mapping templates for the applicable Reference will be applied.
Note: Apply integration rule action
Since integrations are run as background tasks and will be retried in the case of any connectivity failure, it is likely that any subsequent rule actions (e.g. sending an email) will be performed before the Service Request has been created / updated in Tascomi. This should therefore be accounted for when designing workflows.
Log
The integration log provides a summary of case integration actions that have occurred; including where service requests have been successfully created or updated, and where service requests have failed to be created (including the reason for the failure, if known). The log also details any validation failures when creating or updating the Service Request, or when updating the case with values from the Service Request. Reviewing the integration log can help to identify incorrect mappings, or areas where validation during data capture are 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.
Note: Intermittent connection error
Due to the way that Tascomi validates API requests using a timestamp (to minute accuracy), where the request is sent on or close to the minute mark, Tascomi will reject the request as invalid, despite best efforts being made to ensure the timestamp that CXM sends is in sync with Tascomi.
The error which will be seen in the integration log in this scenario is: Cannot connect to Tascomi. Unable to connect to Tascomi API. Error: Authentication failures, invalid public key or HMAC
The fact that CXM will retry failed requests however should ensure that the integration request is reattempted shortly afterwards.
API access
In order for the integration to function as intended, the API key that is used for the integration should have the following access to the tables (resources) in Tascomi as a minimum. Per-field access requirements are not defined, the same access level as defined below, should be enabled for all fields in the table.
| Table / resource name | View | Create & Update |
|---|---|---|
| complaint_action_required | ✔ | |
| complaint_codes | ✔ | |
| complaints | ✔ | ✔ |
| contacts | ✔ | ✔ |
| core_functions | ✔ | |
| dtf_locations | ✔ | |
| organizational_units | ✔ | |
| reporting_methods | ✔ | |
| request_categories | ✔ | |
| titles | ✔ | |
| users | ✔ |