> 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/servicenow-table-api/table-api-incident-template-polling.md).

# Table API: Incident Template (Polling)

This guide explains how to use the ServiceNow Table API Incident Polling Template.

{% hint style="info" %}
For access to this template please contact us.
{% endhint %}

## Overview

The ServiceNow Incident Polling template acts as a **starting point** for building a **Bi-directional Incident integration** between a **ServiceNow** instance with **Unifi** and one without by using the **Table API**. The template works by sending data outbound using messages from **Unifi** and **Polling** to get updates inbound from the other instance.

{% 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 %}

<table data-header-hidden data-search="false"><thead><tr><th>Item</th><th>Value</th></tr></thead><tbody><tr><td>Source System</td><td>ServiceNow (With Unifi)</td></tr><tr><td>Target System</td><td>ServiceNow (Without Unifi)</td></tr><tr><td>Direction</td><td>Bi-directional</td></tr><tr><td>Source Record</td><td><code>incident</code></td></tr><tr><td>Target Record</td><td><code>incident</code></td></tr><tr><td>Inbound sync method</td><td>Polling</td></tr><tr><td>Target API</td><td>ServiceNow Table API (latest)</td></tr><tr><td>Template Version</td><td>1.0.0</td></tr></tbody></table>

### ServiceNow Table API

* This template uses the [ServiceNow Table API](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_TableAPI.html).
* Polling is used to keep the configuration on the instance with Unifi.
  * This template assumes you have the Table API enabled on the target ServiceNow instance.
  * Journal support is implemented by getting display values from the `incident` endpoint.
* Here are a few features of the API you may use when building an integration or adapting this one:
  * Attachments are supported through the [Attachment API](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_AttachmentAPI.html).
  * Authentication may be achieved using a 'Web service access only' user with Basic or OAuth 2.0.

### Features

* Bi-directional creation, updating and closing of incidents.
* Bi-directional comments and attachment sending.

#### Issues / limitations

* This integration **only syncs ServiceNow incidents updated since the first poll**.
  * **To back-sync** this poller, it may be **run with an earlier 'updated since' datetime**.
  * Or **update** an incident meeting the trigger conditions and it will be sync'd.
* As this integration is poller based, if **updates** are **made** to an incident on ServiceNow and not polled **before an inbound update**, they **may be overwritten**.
* The **inbound messages** are **selected** by **comparing the current record state with the inbound state**. For asymmetric mappings this **may lead to the wrong inbound message being selected**.
  * This **may be remedied by storing the other instance's state and comparing against that** for changes.

### Pre-Requisites

* Access to a ServiceNow instance and test environment with Table API enabled.
  * An **integration user** account on ServiceNow in the **GMT timezone** with sufficient access to the test environment.
  * The Attachment API also needs to be enabled for attachments to function correctly.
* A ServiceNow development instance with **Unifi** installed.

## Implementation

The following describes the template configuration on ServiceNow and the steps to implement on the Unifi ServiceNow instance. Please review how this configuration should be translated to your own instance.

### Usage

1. **Import** and make a **new integration from** the **template**.
2. **Set up** integration users on both systems.
3. **Set up** a **connection** to the target system.
4. **Create** an **incident** to **trigger the integration** and **test** functionality.
5. **Review** **Configuration Notes** to decide on changes needed to adapt the integration to your instance.
6. **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/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 template** and **select** it; the option to create a **new integration from** the **template** will appear.

**Name** the new integration and '**Create**'. 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 ServiceNow sandbox and another to production. Within each connection enter the following details:

**Details**

* **Environment:** Sandbox or Production
* **Direction:** Bi-directional

**Outbound**

* **Endpoint URL:** `https://changeme.service-now.com`
* **Authentication:** Basic or OAuth
* **User:** `{integrationuser@email.com}`
* **Password:** `{integrationUserPassword}`

**Inbound**

* **Inbound User:** `{Select user created in next section}`

#### **Account Setup**

Integration users need to be created on both ServiceNow instances; these are the user accounts the API uses to make changes on their respective systems.

**ServiceNow Unifi 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 the same process share the same endpoint, so when data is sent inbound, the inbound user is used to identify which integration to target, requiring a unique user per integration in the process. **This user should then be set on the connection**.

**Table API ServiceNow User (Outbound user)**\
To connect to the other ServiceNow instance, we need to create a `Web service access only` user with roles that allow access to `Table API` and `Attachment API`. This user's timezone must be set to GMT, as filtering journals in the `Poll Incidents` poller uses system time, so the string time in journal fields must be polled by a user in GMT to match. This user should then be added to the Unifi instances' outbound connection.

## Configuration Notes

Configuration notes are given as an overview of what exists in the integration and can be used to help understand where changes should be made to alter functionality.

### Field Maps

The following field maps are used in the integration.

<table><thead><tr><th width="158">Field Map</th><th>Usage</th></tr></thead><tbody><tr><td>Journal field - Table API</td><td>Transforms journal fields into a formatted string, on create all entries are consolidated and sent.<br>Inbound formats the journal array to a string and writes it to the correct field.</td></tr><tr><td>Raw</td><td>Field map for sending and setting the raw value for fields.<br>Used to avoid situations where the field's 'value' is sent but 'display value' is set, causing the fields to misalign.</td></tr><tr><td>Choice</td><td>Map choices between inbound and outbound values.<br>Note: This map gets the choices list from the parent even when inheritance is disabled.</td></tr><tr><td>String</td><td>Standard Field Map for String values.</td></tr><tr><td>Reference - Table API</td><td>Field map for reference values. Assumes the instances share the same sys_id's.<br>Outbound sends 'Field': 'sys_id'.<br>Inbound expects Table API response 'field':{'value':'sys_id', ...}</td></tr><tr><td>Reference Correlation Id - Table API</td><td><p>Field map for reference values. Outbound sends correlation_id or u_correlation_id assuming this is the sys_id on the other instance.</p><p>Outbound sends 'Field': 'correlation_id'.<br>Inbound expects Table API response 'field':{'value':'correlation_id', ...}</p></td></tr><tr><td>Correlation Values</td><td>Sets external reference, correlation ID and display values.<br>Used to identify the bond on inbound messages.</td></tr></tbody></table>

### Choice Mappings

Mappings between fields will need to be reviewed to see if they match your configuration. These used the `Choice_id` field map. This field map looks for a mapping on the parent field map regardless of if inheritance is enabled.

<table data-search="false"><thead><tr><th width="127.20001220703125">SN Field</th><th width="135">Remote Field</th><th>Configuration</th></tr></thead><tbody><tr><td>category</td><td>category</td><td>Maps category between the two systems.</td></tr><tr><td>close_code</td><td>close_code</td><td>Maps close_code between the two systems.</td></tr><tr><td>contact_type</td><td>contact_type</td><td>Maps contact_type between the two systems.</td></tr><tr><td>hold_reason</td><td>hold_reason</td><td>The reason the incident is in the On Hold state.</td></tr><tr><td>impact</td><td>impact</td><td>The impact of the incident.</td></tr><tr><td>state</td><td>state</td><td>The incident lifecycle state</td></tr><tr><td>urgency</td><td>urgency</td><td>Maps urgency between the two systems.</td></tr></tbody></table>

### Messages

The following messages exist in the integration.

#### Outbound

<table><thead><tr><th width="166.5999755859375">Message</th><th width="84">Method</th><th>Trigger</th><th>Function</th></tr></thead><tbody><tr><td>IncidentCreate</td><td>POST</td><td>Incident assigned to the integration company and <code>correlation_id</code> is empty.</td><td>Create an Incident on the other ServiceNow instance when this messages conditions are met.</td></tr><tr><td>IncidentCreateReceipt</td><td>PUT</td><td>Receipt to the <code>IncidentCreate[In]</code> message.</td><td>Outbound message used to respond to the inbound create and update the remote instance with the correlation id and display.</td></tr><tr><td>IncidentUpdate</td><td>PUT</td><td>Incident changed but 'state', hasn't.</td><td>Sends incident updates when state has not changed.</td></tr><tr><td>IncidentNew</td><td>PUT</td><td>Incident state change to 'New'.</td><td>Sent when incident state changes to 'New'.</td></tr><tr><td>IncidentInProgress</td><td>PUT</td><td>Incident state change to 'In Progress'.</td><td>Sent when incident state changes to 'In Progress'.</td></tr><tr><td>IncidentOnHold</td><td>PUT</td><td>Incident state change to 'On Hold'.</td><td>Sent when incident state changes to 'On Hold', also sends hold reason.</td></tr><tr><td>IncidentResolved</td><td>PUT</td><td>Incident state change to 'Resolved'.</td><td>Sent when incident state changes to 'Resolved'.</td></tr><tr><td>IncidentClosed</td><td>PUT</td><td>Incident state change to 'Closed'.</td><td>Sent when incident state changes to 'Closed'.<br>Response to this message closes the bond.</td></tr><tr><td>IncidentCanceled</td><td>PUT</td><td>Incident state change to 'Canceled'.</td><td>Sent when incident state changes to 'Canceled'.<br>Response to this message closes the bond.</td></tr><tr><td>AddAttachment</td><td>POST</td><td>Attachment is added to a bonded incident.</td><td>Sends attachments outbound with the attachment API.</td></tr></tbody></table>

#### Inbound

Inbound messages are triggered from the `Get Incident` and `Get Attachment` pollers. Responses to messages are used to process the inbound response to their respective outbound message.

<table><thead><tr><th width="212.20001220703125">Message</th><th>Function</th></tr></thead><tbody><tr><td>IncidentCreate[In]</td><td>Inbound message used to process incidents to be created polled from Table API.<br>For inbound conditions, see the 'Poll Incidents' poller. OTB: Company name matches</td></tr><tr><td>IncidentUpdate[In]</td><td>Inbound message used to process updates polled from table API.</td></tr><tr><td>IncidentNew[In]</td><td>Inbound message used to process updates in the New state.</td></tr><tr><td>IncidentInProgress[In]</td><td>Message processes inbound updates that have changed into the 'In Progress' state since the last poll.</td></tr><tr><td>IncidentOnHold[In]</td><td>Message processes inbound updates that have changed into the 'On Hold' state since the last poll.</td></tr><tr><td>IncidentResolved[In]</td><td>Message processes inbound updates that have changed into the 'Resolved' state since the last poll.<br>Include fields required for inbound resolution.</td></tr><tr><td>IncidentClosed[In]</td><td>Message processes inbound updates that have changed into the 'Resolved' state since the last poll.<br>Includes fields required for inbound closure and closes the bond.</td></tr><tr><td>IncidentCancelled[In]</td><td>Message processes inbound updates that have changed into the 'Resolved' state since the last poll.<br>Includes fields required for inbound closure and closes the bond.</td></tr><tr><td>AddAttachment</td><td>Inbound messages used to process attachments polled from the attachment API.</td></tr><tr><td>IncidentCreateResponse</td><td>Process response to outbound incident creation.</td></tr><tr><td>IncidentCloseResponse</td><td>Close the bond when we received a response to an outbound closure or cancellation.</td></tr><tr><td>Response</td><td>Process the inbound response to general outbound messages.</td></tr></tbody></table>

### Poll Processors

Poll processors for this integration work in a parent-child structure where the `Poll Incidents` poller gets a list of records updated. Each incident is then polled with `Poll Incident` and filtered to pass into an inbound message. Each incident is also polled with the `Check Attachments on Incident` poller to get any updates.

The '**Poll Incident**' poll processor has been configured to **pass through the whole incident body** into Unifi so that there will be **no need to update the poll processor even if the object itself is updated**.

It also **determines which message an inbound incident should trigger** by querying the bond. **If more messages are introduced** to give granular control over the Incident process **this will need to be updated** to determine the message to call.

<table><thead><tr><th width="176.4000244140625">Poller (Poll processor)</th><th>Function</th></tr></thead><tbody><tr><td>Poll Incidents</td><td>Runs periodically to get Incidents updated since the last run time meeting conditions in the poll processer.</td></tr><tr><td>Get Incident</td><td>Get the whole incident when triggered by the <code>Poll Incidents</code> poller.</td></tr><tr><td>Check Attachments on Incident</td><td>Checks for attachments added to an updated incident. Triggered from the <code>Get Incident</code> poller, when the incident is not closed or cancelled.</td></tr><tr><td>Get Attachment</td><td>Fetches attachments found by the <code>Check Attachments on Incident</code> poller.</td></tr></tbody></table>

#### Poll Processors Containing Message Names

The following poll processors contain message names and **will also need to be updated if message names change**.

<table><thead><tr><th width="252.4000244140625">Poll Processor</th><th>Message names</th></tr></thead><tbody><tr><td>Get Attachment</td><td><code>AddAttachment</code></td></tr><tr><td>Get Incident</td><td>All inbound incident messages</td></tr></tbody></table>

## Conclusion

With the above guidance, you should be able to configure a ServiceNow Incident integration between Unifi and a ServiceNow instance using the Table API. If you encounter any difficulties, **please reach out to support**, and **we would be happy to help**.

***

## Change History

<table><thead><tr><th width="84.79998779296875">Version</th><th width="124.39996337890625">Date</th><th>Changes</th></tr></thead><tbody><tr><td>1.0.0</td><td>2026-10-04</td><td>Initial template</td></tr><tr><td>1.1.0</td><td>2026-10-14</td><td>Replace inbound polling of the <code>sys_journal_field</code> with getting journal values as display values from the <code>incident</code> endpoint. This is done as making the <code>sys_journal_field</code> 'reportable' requires changing of a 'high risk' property. Without this property the endpoint returns a 200 with no data.</td></tr></tbody></table>
