> 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-incident-template-polling.md). # Freshservice Incident Template (Polling) This guide explains how to use the Freshservice Incident Polling Template. {% hint style="info" %} For access to this template please contact us. {% endhint %} ## Overview The Freshservice template acts as a starting point for building an integration between Unifi and Freshservice. This version of the template integrates ServiceNow Incident's with tickets on Freshservice. This integration works by sending data bi-directionally, using messages and Pollers in Unifi to send and retrieve data from Freshservice. This template has been simplified to basic field and messages making it a good starting point for building an integration. {% hint style="warning" %} This document and accompanying template are provided for general use only. Information may be incomplete, outdated, or inaccurate. No responsibility or liability is accepted for any use or reliance on its contents. Users should review and verify all information independently. {% endhint %}
ItemValue
Source SystemServiceNow
Target SystemFreshservice
DirectionBidirectional
Source Recordincident
Target RecordTicket
Inbound sync methodPolling
Target APIFreshservice API v2
Template Version1.0.0
### Freshservice API Freshworks has a range of API's to interact with their services; this template focuses on tickets and notes as those combine to closely resemble the ServiceNow Task structure with journal fields being used as a stand-in for notes. * Updating [tickets](https://developers.Freshservice.com/api/#tickets) `PUT /api/v2/tickets/[ticket_id]` allows for updating of state, assigned agent and other details. * Creating [notes](https://developers.Freshservice.com/api/#conversations) on Freshservice requires a call to `POST /api/v2/tickets/[ticket_id]/notes`, so some state transitions where a single action is taken of ServiceNow lead to two events being sent to Freshservice, updating the ticket and creation of a note. * Inbound: Requires a combination of `GET` requests to various endpoints to retrieve tickets and notes and the activities that took place to identify the inbound update type. ### Features * Bidirectional creation, updating and closing of tickets. * Bidirectional comments and worknotes. * Attachment sync: * Full outbound sync. * Inbound attachments on incident and notes. * Inbound embedded attachments on the description and in notes. *These are synced and attached but not inline.* #### Issues / Limitations * Doesn't create inbound contacts/requesters where one doesn't exist on ServiceNow. * Doesn't include syncs for supporting data, such as requests, locations and groups. * For syncing supporting data see the Case poller template. ### Pre-requisites * Access to a Freshservice instance. * Including a user with the API-key option enabled * A custom field on Freshservice to store the ServiceNow incident number. * This template uses a field called `servicenow_task` * Template can be adapted to not require this field. * A ServiceNow development instance with Unifi installed. ## Implementation The process to make a new integration from the template is as follows. ### Usage 1. Import and make a new integration from the template 2. Setup a [connection](/unifi/configure/connections.md) between the two systems. 3. Create a ticket/incident that triggers the integration and test functionality. 4. Review [Configuration Notes](#configuration-notes) to decide on changes needed to adapt the integration to your instance. 5. Customise the template for your use case. ### Make a new integration from the Template Import the integration; for guidance, see the following: [Import the Integration (external instance)](https://docs.sharelogic.com/unifi/~/changes/25/integration-guides/bidirectional-asynchronous-incident-guide/build-the-other-half/move-the-integration#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 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 the API uses to make changes as 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. * **`default_contact`** The fresh\_id of user to send if the selected user in ServiceNow doesn't have enough details to create or identify a Freshservice contact. ## Configuration Notes Configuration notes give you an overview of what exist in the integration and can be used to figure out where changes should be made to alter functionality, ### Field maps The following field maps exist in the integration. | Fields Map | Usage | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | External Reference | Sets external\_reference for Freshservice (ticket id) and stores it in a field. | | Internal Reference | Sets internal\_reference and sends it outbound. | | String | Standard Field Map for String values | | Default Value | Send the default value set for this field. | | Note Processer |

Process notes to create comments and worknotes and vice versa.
Inbound extracts attachments and makes note of if note is an update or if the note user is recognised.
Outbound sends journal text adding user signature and other fields.

| | Choice (Integer) |

Map choice field values to another value on in/outbound.
Freshdesk expects integers in the format "Property" : 2 rather than "Property":"2" as with the non-int version of this map.
Note: Choice options will be found using the parent choice field even when inheritance is disabled.

| | Request headers | Sets the outbound HTTP headers for Unifi messages. | | Requester |

Freshdesk requires one of {requester\_id, email, facebook\_id, (phone + name), twitter\_id, unique\_external\_id}.
Outbound this field will look at the contact field on ServiceNow and send all available fields. If no contact is set the integration will attempt to send the connection variable 'Default\_Contact'.
Inbound looks for the contact based on available fields. If no user if found on inbound create the users details are logged to worknotes.

| | Description (HTML) |

Field for handling the description from Freshdesk.
Inbound removes HTML tags and processes attachments.
Outbound replaces plaintext details with HTML tags.

| | User (CorrelationId) |

Not in use.
Find a sys\_user or customer\_contact based on correlation\_id. Prefer sys\_user but fall-back to contacts if a user isn't found

| ### Fields #### Pulling field 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. ### Messages The following messages exist in the integration. #### Outbound
MessageEndpointTrigger(ServiceNow)Functionality
AddAttachmentTicketAttachment is added to the Incident.Sends attachment to Freshservice.
CreateReceiptTicketA new Incident is created on ServiceNow.Add the ServiceNow task number to the Freshservice Ticket.
CreateTicketTicketAn unbonded Incident is added to integration company.Create the Ticket in Freshservice.
PrivateNoteNotesWorknote added.Create the worknote as a private note on Freshservice.
PublicNoteNotesComment added.Create the comment as a public note on Freshservice.
UpdateTicketTicketIncident updates that don't change state.Send the update to Freshservice. Updates basic ticket fields
#### Inbound | Message | Trigger(Freshservice/Pollers) | Functionality | | ------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------- | | AddAttachment | Pollers send a polled attachment into the integration. | Logs attachments added by pollers. | | CreateIncident | Poller finds a ticket with an empty `servicenow_task` field. | Create the Incident in ServiceNow. | | UpdateIncident | Poller detects a bonded Tickets has been updated without changing state. | Update the Incident. | | UpdateIncidentState | Poller detects a bonded Tickets status has changed. | Update the Incident including the state. | | UpdateJournals | Poller detect note(s) added to a bonded ticket. | Add the note to the comments or work\_notes journal. | | AttachmentResponse | Freshservice responds to us adding an attachment. | Store the attachments id on Fresh so it isn't redownloaded. | | CreateResponse | Freshservice responds to our CreateTicket message. | Store the id of the newly created ticket. | | Response | Freshservice responds to a message. | Processing the response. | #### Suggestions Generally in Unifi integration we suggest one message for each state change rather than a general `UpdateIncidentState` message. This makes it easier to configure states with required fields like hold reasons or close codes. For this integration it's easiest to add all the fields needed into the `UpdateIncidentState` message and customise it for each state. ### 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. #### Get Ticket Poll Processor The ‘Get Ticket’ poller determines which message an inbound ticket should trigger using a case statement. If inbound message names or state/status mappings have changed, this code will need to be updated to reflect the change. These changes may be made in the `getMessageName` function on the poll processor's response script. #### Other Poll Processors Containing Message Names The following poll processors contain message names and will need to be updated if message names change. | Poll Processor | Message names | | ----------------------- | ---------------------------- | | Get Attachment | `AddAttachment` | | Get Conversations | `UpdateJournals` | | Get Embedded Attachment | `AddAttachment` | | Get Ticket | *All ticket update messages* | ## Conclusion With the above guidance, you should be able to configure a Freshservice Poller integration in Unifi. If you encounter any difficulties, please reach out to support, and we would be happy to help. *** ## Change History | Version | Date | Changes | | ------- | ---------- | ---------------- | | 1.0.0 | 2026-07-29 | Initial template |