> For the complete documentation index, see [llms.txt](https://docs.sharelogic.com/unifi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sharelogic.com/unifi/integration-guides/freshservice/freshservice-standard-case-template-polling.md). # Freshservice Standard Case Template (Polling) This guide explains how to adapt the Freshservice Case Polling Template for your Freshservice Instance. {% hint style="info" %} For access to this template please contact us. {% endhint %} ## Overview The Case integration template integrates Standard Cases (`sn_tech_product_support_case`) for a given ServiceNow company with Tickets on their customers' Freshservice instance.
ItemValue
Source SystemServiceNow
Target SystemFreshservice
DirectionBidirectional
Source Recordsn_tech_product_support_case
Target RecordTicket
Sync methodPolling
Target APIFreshservice API v2
Template Version1.0.0
The integration consists of two parts; a bidirectional integration of ServiceNow Cases and Freshservice Tickets, and a supporting data sync that pulls data from Freshservice into ServiceNow. The supporting sync makes additional details available to agents such as information on customers, agents, groups, departments and locations in the connected companies Freshservice. {% hint style="info" %} This guide assumes familiarity with Unifi integrations, field maps, messages, and connections. {% endhint %} ### Features * Bidirectional creation, updating and closing of tickets. * Attachment sync, including limited syncing of images added in notes. * Supporting data sync easily adaptable to existing data. ### Issues * Syncing of contacts (callers) uses the Fresh id of these users. These will need to be synced for this feature to function. * Polling increases probability of updates being overwritten if both systems are updated in the poll interval. ### Pre-requisites * Access to a Freshservice instance. * Including a user with the API-key option enabled * (Optional) A custom field on Freshservice to store the ServiceNow incident number. * A ServiceNow development instance with Unifi installed. ## Implementation Guide The process to make a new integration from the template is as follows. #### Make a new integration from the Template Import the integration; for guidance, see the following: [Move the Integration](/unifi/integration-guides/unifi/bidirectional-asynchronous-incident-guide/build-the-other-half/move-the-integration.md#import-the-integration-external-instance) Once imported open Unifi and navigate to the the template and select it, the option to create a new integration from the template will appear. Name the new integration and click 'Create' the integration will now be created. This will duplicate all components of the integration and change their sys\_id’s. #### Connection Setup Update the connection and authentication to point at the customers Freshservice instance. For this, an integration user will be needed on ServiceNow and Freshservice. Connection variables will also need to be updated. Further details are given in [Connection Setup](#connection-setup-1) below. #### Creating a Mapping Document Create a mapping document to detail how the integration is to be updated to sync to the desired fields on the new instance. Details on this process are given in [Creating a Mapping Document](#creating-a-mapping-document-1) below. #### Configure the Messages Messages comprise the bulk of the integration and include the fields and field maps that map data in and out. They need to be updated based on the new mapping document to understand data being received from and sent to the remote system. Details on the updates required are given in [Configuring Integration Messages](#configuring-integration-messages). #### Configure Poll Processors Poll processors are used to get updates from the Freshservice instance, removing the need for an integration to be setup Freshservice side in addition to syncing supporting data such as users, locations, group etc. Pollers handling ticket sync will need to be update to reflect changes in message names and supporting pollers for any changes to field names in supporting date. More details are given in [Configure Poll Processors](#configure-poll-processors-1). #### Test the Integration Following updates, it is advisable to re-test the integration. To do this, create a Ticket on FreshService and attempt to move it through all the integrated states of Freshservice from ServiceNow. Note, some messages are set up to close the integration bond, so multiple tickets may be needed to test these states. Now re-attempt the test, creating the Case on ServiceNow and moving through the states from Freshservice. More extensive testing should be conducted, but these basic checks should be a starting point for testing updates. *** ### Connection Setup Connections store integration environment details; more can be found about these in Unifi’s documentation here: [Connections | Unifi Documentation](https://docs.sharelogic.com/unifi/configure/connections). Connections and connection variables need to be reconfigured for each environment connected to. Steps required for configuring the connection are given below. #### Connections Two connections will need to be created, one connection to the customer's Freshservice sandbox and another to production. Within each connection enter the following details: **Details** * **Environment:** Sandbox or Production * **Direction:** Bidirectional **Outbound** * **Endpoint URL:** `http://{customers-test-or-prod}.freshservice.com` * **Authentication:** Basic * **User:** `{Your-API-Key}` * **Password:** `X` **Inbound** * **Inbound User:** `{Select user created in next section}` #### Account Setup Integration users need to be created on Freshservice and ServiceNow, these are the user accounts changes are made under on their respective systems. **ServiceNow User (Inbound user)** An inbound user is required for the integration to make updates. For this we create a ServiceNow user with the [`x_snd_eb.integration`](https://docs.sharelogic.com/unifi/about/roles) role. All integrations within a process have the same endpoint, so when data is sent inbound the inbound user is used to identify the integration within the process, requiring a user per integration in the process. This user should then be selected on the connection. **Freshservice User** To connect to Freshservice we need an account with the ‘API Key’ option enabled. Documentation on finding this account's key is here: [How To Find Your API Key | Freshworks](https://crmsupport.freshworks.com/support/solutions/articles/215517-how-to-find-your-api-key). Add this key into the connection as shown in the connection section above. This user should only be used on the integration, as their actions are filtered out of synchronisation to prevent looping. #### Connection Variables Connection variables make variables accessible for integration configuration. They are different per connection, allowing the integration to behave differently when connecting to different systems. The following updates need to be made to the variables on Fresh integrations. * Variables ending in **`_poller`** store the sys\_id’s of pollers in the ‘Pollers’ tab, as these have been copied they will all need updating to point to the new versions. * **`Integration_user`** The fresh\_id of the integration user, this is used in pollers to avoid syncing updates made by the integration. ### Creating a Mapping Document A mapping document says which fields are synced between Fresh and ServiceNow, this is foundational for making sure the integration functions as expected. To create this document we need a list of the fields on the ServiceNow record being integrated and a list of the ticket fields on Fresh. The steps to do this are as follows and assume you already have a list of ServiceNow fields to be integrated. #### Pulling the data from Freshservice The integration includes a one-time poller to pull Ticket fields from the Freshservice instance; this is found on *Pollers > Get ticket form fields* and may be run by selecting ‘Execute Now’ to send the request. The request should open in a new tab and if it executes successfully after a few seconds a file will be attached called `response_payload.txt`. This file contains a JSON object listing all the ticket fields and choices on the Freshservice Instance. If the request cannot be found check you are in the correct domain. If the request fails to authenticate check connection setup. #### Document creation Review the list of ServiceNow fields to be integrated and match them with the fields returned by the poll response above. For each mapping make note of if the mapping taking place is direct, choice or reference and any other transformations that may be needed. **Map Choice Fields** Where a field is mapped using a choice list, check if the values on the new instance are the same, if not, make sure to re-map the new values in the mapping document. **Review supporting data maps** If supporting data; Agents, Requesters, Departments, Groups or Locations have a different set of fields these will need to be remapped to the respective fields in ServiceNow. ### Configuring Integration Messages Updating the messages to the new configuration can be done in any sequence, though the most efficient is likely to be creating the new fields, enable them on each message with inheritance enabled, update message names and triggers. Then update the field maps and choice values while testing functionality to ensure they behave as expected. #### Add Custom Fields and New Mappings Create a new field for each new mapping, where replacing existing fields it’s suggested to update the parent field on the integration so it will already be created on the correct message. If the field has the same behaviour and JSON path in all messages it’s suggested to enabled inheritance, this will result in the child field mirroring updates made to the parent. When creating fields aim to select a field map that best matches the desired translation. Once all the new fields are created enable them on the relevant messages, to do this open each message and select the active toggle on each field. After all fields are created, select the ‘Build integration’ button, this will generate message scripts for each field based on its field map. #### Configure Message Names and Triggers If the state or conditions that trigger integration events are different for the new customer it’s good practice to rename the outbound messages to better match the event taking place. The event trigger will also need updating if conditions have changed. #### Make changes to field maps If newly created fields don’t have a suitable map find the best existing map and click the three dot’s and select copy, then adapt this copy to your new field mapping. #### Configure Field Choices For each choice field navigate to the parent field, that is the field where the ‘message’ parameter is empty and update this list of choices based on the mapping in 2.3.3. If re-mapping the Freshservice Category and Subcategory fields to Business Service and Service Offerings consider importing choice directly from the mapping document using the process below, this can also be a practical choice for other larger mappings. #### Bulk Importing Choices from Excel For choice mappings with 10’s or 100’s of entries it often make sense to import them directly into the `x_snd_eb_field_choice` table. As this table is in the Unifi application, importing into it directly from the list view is prevented by business rules. Instead we’ve included in the template an update set with a pre-made transform map and table in the Unifi application scope. **Excel Document Creation** First step is to create a mapping document matching the template, this can be obtained by opening the `x_snd_eb_field_choice` list view in the Unifi application scope and right-clicking on a list title and selecting ‘import’, then ‘Create Excel template’ and download the created template. Alternatively, an excel document may be created with the following headers: ``` Label, Value, External Value, Active, Integration, Field, Domain, Direction, Qualifier ``` Note the Integration and Field columns should contain the sys\_id of the field being linked to and coalesce is done on the Choice’s label so this should be unique. **Usage** In the global application scope: 1. Navigate to: **All > System Import Sets > Load Data** 2. Select: **Import set table > Existing table** and choose: `Imp Tmpl X Snd Eb Field Choice` 3. Set: **Source of the import** to `File`, then select your spreadsheet. 4. Click: **Submit** and wait for the import to complete. 5. Optional: From **Next steps**, select **Import Sets** to review the loaded data. 6. From **Next steps**, select **Run Transform**. 7. On the Transform screen: * Select your import set. * Choose the map: `u_imp_tmpl_x_snd_eb_field_choice`. * Click: **Transform**. 8. Confirm the transform completes successfully. Status should show **Complete**, with a name similar to `Transforming: ISET00xxxx`. ### Configure Poll Processors Ticket poll processors have been configured to pass through the whole ticket body when polling tickets as such, changes aren’t needed when fields are changed on Freshservice, the field may be mapped in from the request body. Supporting pollers contain the mappings for the data they sync, so will need to be updated for changes to supporting data structure. #### Get Ticket Poll Processor The ‘Get Ticket’ poller determines which message an inbound ticket is sent in as using a case statement, if inbound message names or state/status mappings have changed this will need to be updated to reflect the change. These changes may be made in the `getMessageName` function on the poll processors response script. #### Supporting Poll Processors If field names have changed in supporting data this can be added or removed from the `field_map` code at the top of poll processors. For direct mappings this change is simple, for reference fields the `mapReference` function may be used, for more complex mappings changes will extend beyond this code. #### Other Poll Processors Containing Message Names The following pollers contain message names and will need to be update if message names change. | Poller | Message names | | ----------------------- | ---------------------------- | | Get Attachment | `AddAttachment[In]` | | Get Conversations | `UpdateNotes[In]` | | Get Embedded Attachment | `AddAttachment[In]` | | Get Ticket | *All ticket update messages* |