> For the complete documentation index, see [llms.txt](https://docs.zigiwave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigiwave.com/integration-guides/jira-servicenow-integration-guide.md).

# Jira ServiceNow Integration Guide

This guide explains how to configure a bi-directional integration between Jira and ServiceNow using ZigiOps. It covers adding system instances, selecting entity pairs, configuring correlation, building field mappings, applying filters, and testing the workflow. No scripting or coding is required at any stage.

For a full overview of the sync capabilities between the two platforms, see the [Jira and ServiceNow integration page](https://www.zigiwave.com/integrations/jira-integration-with-servicenow) on the ZigiWave website.

### Overview

The Jira-ServiceNow integration synchronizes records between your ITSM platform (ServiceNow) and your project tracking tool (Jira) automatically. When a record is created or updated in one system, ZigiOps reflects the change in the other system based on the workflow configuration.

{% embed url="<https://youtu.be/20AwIMqIgM0?si=MGk87_N4ZRF6oW4->" %}

**Most common supported entity pairs:**

| ServiceNow Entity      | Jira Entity                              | Sync Direction         |
| ---------------------- | ---------------------------------------- | ---------------------- |
| Incident               | Issue / Task                             | Bi-directional         |
| Problem                | Bug                                      | Bi-directional         |
| Change Request         | Task                                     | Bi-directional         |
| Service Catalog Task   | Task                                     | ServiceNow to Jira     |
| Work Notes             | Comment                                  | Configurable           |
| Additional Comments    | Comment                                  | Configurable           |
| Priority (numeric 1-4) | Priority (Highest / High / Medium / Low) | Mapped with conditions |
| State (numeric)        | Status (text transition)                 | Mapped with conditions |

{% hint style="info" %}
ZigiOps supports all Jira and ServiceNow entities. Contact support if you have questions for entities that are not mentioned here or for more complex use cases: <support@zigiwave.com>.
{% endhint %}

### Prerequisites

Before configuring this integration, confirm that the following requirements are met:

* **ZigiOps instance:** installed and running. See the Installation guide.
* **Jira:** a dedicated integration user account with API token access and project-level permissions.
* **ServiceNow:** a dedicated integration user with read and write permissions on Incident, Problem, or Change Request tables.
* **Custom fields:** correlation fields must be created in both systems before configuring the workflow. See the [Correlation section](#step-4-configure-correlation) below.
* **License:** the ZigiOps license must include the Jira-ServiceNow system pair.

{% stepper %}
{% step %}

### Add System Instances

A system instance defines the connection between ZigiOps and a specific Jira or ServiceNow environment. You must add one instance for each system before configuring a workflow.

#### Add a Jira System Instance

1. Log into your ZigiOps instance.
2. Navigate to **Connected Systems** > **Add New System** > **Jira**.
3. Enter the following connection parameters:
   * **Server URL:** the base URL of your Jira environment (for example, `https://yourcompany.atlassian.net`).
   * **Username:** the Jira user account ZigiOps will use for API calls.
   * **API Token:** generated in your Atlassian account settings under Security > API tokens.
   * **Project Key:** scopes the integration to the correct Jira project.
   * **Proxy Settings:** configure if your environment requires routing traffic through a proxy.
4. Click **Save** to store the configuration.
5. Click **Test Connection** to verify that ZigiOps can reach the Jira API. If the test succeeds, available fields and projects are downloaded automatically.

<figure><img src="/files/1Ijvkr7qFOzmHeNV8HPt" alt=""><figcaption><p><em>ZigiOps UI - Adding Jira as a Connected System.</em></p></figcaption></figure>

#### Add a ServiceNow System Instance

1. Log into your ZigiOps instance.
2. Navigate to **Connected Systems** > **Add New System** > **ServiceNow**.
3. Enter the following connection parameters:
   * **Instance URL:** the base URL of your ServiceNow instance (for example, `https://yourcompany.service-now.com`).
   * **Username:** the ServiceNow integration user account.
   * **Password:** the password for the integration user.
   * **OAuth Credentials (optional):** Client ID and Client Secret, required if your ServiceNow instance enforces OAuth 2.0 authentication.
4. Click **Save**.
5. Click **Test Connection** to verify connectivity.

<figure><img src="/files/3Q2EIgDHoO1XRXa3ifW7" alt=""><figcaption><p><em>ZigiOps UI - Adding ServiceNow as a Connected System.</em></p></figcaption></figure>

{% hint style="info" %}
If the Test Connection fails, verify that the integration user has the required API permissions and that the instance URL does not include a trailing slash.
{% endhint %}
{% endstep %}

{% step %}

### Create or Load a Workflow

A workflow defines the complete configuration for your integration, including the entity pair, triggers, field mappings, filters, and correlation logic.

ZigiOps provides pre-built workflow templates for the most common Jira-ServiceNow use cases. A template includes pre-configured field mappings for summary, description, and priority, as well as basic correlation and trigger settings. You can load a template and adjust it to match your environment, or create a custom workflow from scratch.

#### Option A: Load a Workflow Template

1. Navigate to **Configurator** > **Workflows** > **Add New Workflow**.
2. Select **Load from Template**.
3. Locate the relevant Jira-ServiceNow template (for example, ServiceNow Incidents to Jira Tasks).
4. Click **Load** and then adjust the configuration as needed.

<figure><img src="/files/ksziRic5ENzZiIXOQ4SM" alt=""><figcaption><p><em>ZigiOps UI - Workflow template selection screen.</em></p></figcaption></figure>

#### Option B: Create a Custom Workflow

1. Navigate to **Configurator** > **Workflows** > **Add New Workflow**.
2. Select **Custom Integration**.
3. Assign a name to the workflow and proceed to configure each section as described in the steps below.
   {% endstep %}

{% step %}

### Select the Entity Pair

The entity pair defines which record types in each system will be synchronized. Select the combination that matches your use case.

| Use Case                              | ServiceNow Entity    | Jira Entity  |
| ------------------------------------- | -------------------- | ------------ |
| Incident-driven development           | Incident             | Issue / Task |
| Root cause analysis alignment         | Problem              | Bug          |
| Change management and sprint planning | Change Request       | Task         |
| Service request fulfillment           | Service Catalog Task | Task         |

For a fully bi-directional synchronization, configure at least two actions within the workflow: one to create and update Jira records from ServiceNow records, and one to update ServiceNow records when Jira records change.

<figure><img src="/files/5xjdjw0Xi9XRRqbhDx5J" alt=""><figcaption><p><em>ZigiOps UI - Entity pair selection screen.</em></p></figcaption></figure>
{% endstep %}

{% step %}

### Configure Correlation

Correlation is the mechanism ZigiOps uses to match existing records across systems during update cycles. It stores only unique identifiers, not business data. Without correlation, every sync cycle would create new records rather than updating existing ones.

You define which field in each system stores the unique identifier of its counterpart. Common patterns are:

* **Jira custom field (for example, "ServiceNow ID"):** stores the ServiceNow `sys_id` of the linked incident.
* **ServiceNow field (for example, "correlation\_id" or a custom field "Jira Reference"):** stores the Jira issue key (for example, `OPS-4512`).

Create the required custom fields in each system **before** configuring correlation in ZigiOps. Once the fields exist, map them in the Correlation section of the workflow.

<figure><img src="/files/WQzU8VN0v6LpqTpBJ2Ta" alt=""><figcaption><p><em>ZigiOps UI - Correlation configuration screen.</em></p></figcaption></figure>

{% hint style="info" %}
ZigiOps supports one-to-one correlation by default. Each Jira record maps to exactly one ServiceNow record. This prevents duplicate creation even if an event is processed more than once.
{% endhint %}
{% endstep %}

{% step %}

### Configure Field Mappings

Field mappings define which fields are synchronized between the two systems and how their values are transformed. Mappings are configured separately for each action direction.

<figure><img src="/files/7ZKssbFlRQN1xK7XqqFW" alt=""><figcaption><p><em>ZigiOps UI - Field Mapping table.</em></p></figcaption></figure>

#### Minimum Required Field Mappings

| ServiceNow Field            | Jira Field                   | Notes                                                           |
| --------------------------- | ---------------------------- | --------------------------------------------------------------- |
| `short_description`         | `summary`                    | Direct text mapping                                             |
| `description`               | `description`                | Direct text mapping                                             |
| `priority` (numeric)        | `priority` (text)            | Requires conditional mapping                                    |
| `state` (numeric)           | `status` (text transition)   | Requires conditional mapping with Jira transition IDs           |
| `work_notes`                | `comment.body`               | Internal notes only. Apply author filter to prevent echo loops. |
| `assignment_group`          | `assignee` or `component`    | Map based on team structure                                     |
| `sys_id`                    | Custom field: ServiceNow ID  | Used for correlation. Not displayed to end users.               |
| `number` (e.g., INC0012345) | Custom field: SNOW Reference | Human-readable cross-reference                                  |

#### State Mapping

ServiceNow uses a numeric State field based on an ITIL state machine. Jira uses a text-based Status field controlled by workflow transitions. These must be mapped conditionally, not as a direct value lookup.

| ServiceNow State (numeric) | ServiceNow Label | Jira Status          | Notes                                                 |
| -------------------------- | ---------------- | -------------------- | ----------------------------------------------------- |
| 1                          | New              | To Do                | Direct mapping                                        |
| 2                          | In Progress      | In Progress          | Direct mapping                                        |
| 3                          | On Hold          | On Hold / Blocked    | Map to custom Jira status if available                |
| 6                          | Resolved         | Done                 | Requires `close_code` and `close_notes` in ServiceNow |
| 7                          | Closed           | Done                 | Terminal state. Do not reopen via integration.        |
| 8                          | Cancelled        | Cancelled / Won't Do | Map to custom Jira status if available                |

{% hint style="info" %}
Closing a ServiceNow incident requires both `close_code` and `close_notes`. If these fields are not included in the mapping when Jira status is set to Done, the ServiceNow API call will fail. Add a conditional mapping: when Jira status = Done, send `close_code` = `'Closed/Resolved by Caller'` and `close_notes` = `'Closed by Jira integration'`.
{% endhint %}

When mapping ServiceNow Resolved to Jira Done, use the Jira transition ID rather than setting the status field value directly. This ensures that Jira workflow validators, post-functions, and required fields are respected.

<figure><img src="/files/0km06jEt4Am2wRgCqlZT" alt=""><figcaption><p><em>ZigiOps UI - State conditional mapping.</em></p></figcaption></figure>

#### Priority Mapping

ServiceNow calculates priority from a combination of Impact and Urgency. Jira uses a flat text-based priority list. A direct numeric-to-text mapping will often misrepresent business impact. The recommended approach uses both source fields together:

| ServiceNow Priority | ServiceNow Impact | ServiceNow Urgency | Jira Priority |
| ------------------- | ----------------- | ------------------ | ------------- |
| 1 - Critical        | 1 - High          | 1 - High           | Highest       |
| 2 - High            | 1 - High          | 2 - Medium         | High          |
| 2 - High            | 2 - Medium        | 1 - High           | High          |
| 3 - Moderate        | 2 - Medium        | 2 - Medium         | Medium        |
| 4 - Low             | 3 - Low           | Any                | Low           |

<figure><img src="/files/wYASb9Vpp5Cx7KEuOa0J" alt=""><figcaption><p><em>ZigiOps UI - Priority conditional mapping.</em></p></figcaption></figure>

#### Comment Synchronization

ServiceNow distinguishes between Work Notes (internal) and Additional Comments (customer-visible). Jira does not make this distinction. Syncing all ServiceNow notes to Jira without filtering may expose internal information to development teams.

Recommended comment mapping:

* **ServiceNow Additional Comments to Jira:** sync public-facing comments only.
* **Jira comments to ServiceNow:** map to Work Notes (internal) to preserve visibility boundaries.
* **Author filter:** exclude comments authored by the integration user to prevent echo loops.
* **Last Time expression:** use `{lasttimecomment}` to collect only comments created after the last successful run.

Configure comment synchronization via the Related Records section of the field mapping configuration in ZigiOps.
{% endstep %}

{% step %}

### Configure Triggers

Triggers define when ZigiOps collects data from the source system. ZigiOps supports two trigger types, which can be used together for the most reliable coverage.

| Trigger Type | Mechanism                                                                                                                          | Recommended Use                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Poller       | ZigiOps queries the source system API on a configurable schedule (default: every 1 minute).                                        | SLA monitoring, controlled sync cycles, systems without webhook support          |
| Web Listener | ZigiOps registers an HTTP endpoint and waits for the source system to push data via webhook. Activated when the action is enabled. | Real-time status updates, incident creation alerts, near-instant synchronization |

Using both trigger types in combination is the recommended approach for production deployments. The Poller provides complete coverage; the Web Listener reduces latency for time-critical events.

<figure><img src="/files/QJQDksjpr4oAt2B9mNNL" alt=""><figcaption><p><em>ZigiOps UI - Trigger configuration.</em></p></figcaption></figure>
{% endstep %}

{% step %}

### Add Filters and Conditions

Filters control which records are collected and when. Without proper filtering, the integration may process records that should be excluded or miss critical records that need to be synced.

Common filter configurations for Jira-ServiceNow workflows:

* **Last Time expression:** collect only records created or updated since the previous run. Use the `{lasttime}` expression in the filter condition.
* **Environment scope:** exclude records from test or sandbox projects.
* **Priority threshold:** sync P1 and P2 incidents in real time; batch-sync lower priorities.
* **Author exclusion:** filter out comments where the author matches the integration user account, to prevent duplicate comment loops.
* **Production-only scope:** apply environment-based conditions to sync only production-affecting incidents.

ZigiOps supports AND and OR logic, with operators including: is, is not, is one of, is not one of, is empty, is not empty, contains, does not contain, less than, greater than, and equals. Conditions can be applied to any field available from the connected system.

<figure><img src="/files/moiNqHbJtCFzRtXh3n2q" alt=""><figcaption><p><em>ZigiOps UI - Filter and Condition Builder.</em></p></figcaption></figure>
{% endstep %}

{% step %}

### Use Expressions for Data Transformation (Optional)

Expressions apply transformations to field values after data is collected from the source and before it is delivered to the target. They are configured in the Source and Target tabs of the workflow action and do not require any scripting.

| Expression                    | What It Does                                                                                         | Jira-ServiceNow Example                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Date and Time Format          | Converts epoch timestamps to a human-readable string                                                 | Convert ServiceNow `sys_created_on` to a readable date for a Jira custom field       |
| First N Characters            | Extracts the first N characters of a field value                                                     | Truncate long ServiceNow descriptions to fit Jira's 255-character summary limit      |
| Pattern (RegEx)               | Extracts a value matching a regular expression. Group 1 is returned if a capturing group is defined. | Extract environment name (for example, PROD-EU-WEST) from a monitoring alert payload |
| Replace Text                  | Replaces a specific substring with another value                                                     | Replace internal codenames with public-facing system names before syncing to Jira    |
| Replace Pattern (RegEx)       | Replaces all matches of a RegEx pattern                                                              | Mask IP addresses or credentials before syncing logs from ServiceNow to Jira         |
| Build Array                   | Combines multiple values into a comma-separated array                                                | Aggregate multiple ServiceNow tags into a Jira label array                           |
| Last Time                     | Stores the timestamp of the last successful run; auto-increments on each execution                   | Collect only records updated after `{lasttime}` to prevent duplication               |
| To Lower Case / To Upper Case | Normalizes text casing                                                                               | Align status values or category names that differ only in casing between systems     |

<figure><img src="/files/23bWO0DjZex61JeGiCkb" alt=""><figcaption><p><em>ZigiOps UI - Expression configuration.</em></p></figcaption></figure>
{% endstep %}

{% step %}

### Test and Activate the Workflow

Before activating the workflow in production, test each action individually using the built-in troubleshooting tools.

#### Testing Tools Available in ZigiOps

* **Real-time operation logs:** show every record collected, processed, and delivered.
* **Payload inspector:** displays the raw data sent to and received from each system, useful for debugging field mapping issues.
* **HTTP request and response data:** provides API-level details for connectivity troubleshooting.
* **Error classification:** distinguishes between mapping errors, connectivity issues, and API rejections.

**To activate the workflow:**

1. Run the workflow in **test mode** against a non-production record.
2. Verify that the target record is created with the correct field values.
3. Check the Activity Log for any errors or unexpected field values.
4. Once results are confirmed, set the workflow status to **Active**.
   {% endstep %}
   {% endstepper %}

<figure><img src="/files/IULOHmVF01a2jdK7Iwx0" alt=""><figcaption><p><em>ZigiOps Dashboard - Monitoring view.</em></p></figcaption></figure>

### Advanced: Governance and Reliability

The following practices apply to production deployments and regulated environments.

#### Idempotency via Correlation Lookup

Before any write operation, ZigiOps checks whether a correlated record already exists in the target system. If one exists, it performs an update. If none exists, it creates a new record. This two-path logic prevents duplicate records when events are reprocessed after a failure or retry.

#### Retry Logic

Failed operations caused by transient API errors (rate limits, maintenance windows, network interruptions) are retried automatically. ZigiOps distinguishes between transient failures (retried) and permanent failures (logged and surfaced in the Activity Log). Retries do not create duplicate records due to the correlation lookup described above.

#### Governance Recommendations

| Practice                                 | Why It Matters                                                             | How ZigiOps Supports It                                                         |
| ---------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Define integration ownership             | Someone must be accountable for mapping logic and change testing           | ZigiOps provides user-level access control and admin roles                      |
| Test changes in staging first            | Untested mapping changes can silently misbehave in production              | ZigiOps supports multiple environments; test before activating                  |
| Export and version integration templates | Integration configurations should be treated like production code          | Export templates and store in a version control system                          |
| Monitor operational health continuously  | Silent failures are as damaging as loud ones                               | ZigiOps provides dashboards with real-time error tracking and operation metrics |
| Audit comment and attachment sync rules  | Internal notes may be exposed to unauthorized teams if filters are missing | Use conditional mapping and author filters to enforce data classification       |

### Troubleshooting

| Issue                                                       | Likely Cause                                                                                                     | Resolution                                                                                                         |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Fields are missing from mapping suggestions                 | The system schema was not refreshed after new fields were added                                                  | Navigate to Connected Systems, select the system, and click Save to re-download the schema                         |
| Duplicate comments appear in the target system              | Integration user exclusion filter is missing, or `{lasttimecomment}` expression is not configured                | Add a trigger condition excluding the integration user as comment author; configure the `{lasttimecomment}` filter |
| ServiceNow incident fails to resolve via Jira               | `close_code` and `close_notes` are required by ServiceNow but are not included in the mapping                    | Add conditional mappings: send `close_code` and `close_notes` only when Jira status = Done                         |
| Jira status does not update after a ServiceNow state change | The mapping is setting the status field value directly rather than using a Jira workflow transition ID           | Replace the status field value with the correct Jira transition ID in the mapping configuration                    |
| Workflow saves but fails to activate                        | A mandatory configuration field is missing, or the license does not include the Jira-ServiceNow system pair      | Review the error message in the UI; verify the license status under Admin > About                                  |
| Priority values do not match between systems                | ServiceNow numeric priorities are mapped directly to Jira priority labels without considering Impact and Urgency | Use conditional mapping to evaluate Impact and Urgency together and produce the correct Jira priority output       |

### Related Resources

* [Workflow Templates - ServiceNow Incidents to Jira Tasks](/integration-catalog/jira-servicenow-integration.md)
* [Building Integrations - Data Mapping Fundamentals](/design-and-mappings/data-mapping-fundamentals.md)
* [Building Integrations - Filters and Conditions](/design-and-mappings/filters-and-conditions.md)
* [Building Integrations - Transformations and Expressions](/design-and-mappings/transformations-and-expressions.md)
* [Building Integrations - Comments and Attachment Sync](/design-and-mappings/attachments-and-comments.md)
* [Troubleshooting - Mapping Issues](/operations-and-monitoring/troubleshooting.md)
* [ZigiOps System Requirements](/integration-platform/system-requirements.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zigiwave.com/integration-guides/jira-servicenow-integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.