# Correlation
Correlation is the mechanism ZigiOps uses to maintain a persistent link between related records across integrated systems. It is what allows ZigiOps to know that a specific Jira task corresponds to a specific ServiceNow incident, and to keep both records in sync over their entire lifecycle.
Without correlation, ZigiOps has no reliable way to distinguish between creating a new record and updating an existing one. Every polling cycle would risk generating duplicate records instead of applying updates to the correct entity.
What Is Correlation and Why Does Every Workflow Need It?
Every ZigiOps workflow contains a correlation configuration. This configuration defines a dedicated field in one or both integrated systems where ZigiOps stores a unique identifier that links the two records together.
When ZigiOps creates a record in the target system, it stores the resulting record ID back into the correlation field of the source record. On all subsequent polling cycles, ZigiOps reads the correlation field to determine whether a record has already been synchronized. If the correlation field contains a value, ZigiOps performs an update. If it is empty, ZigiOps treats the record as new and creates it.
This distinction between create and update is fundamental to reliable integration. A missing or misconfigured correlation field is one of the most common causes of duplicate records in production environments.
Where Is Correlation Data Stored?
Correlation data can be stored in the source system, the target system, or in both at the same time. The recommended approach for bi-directional integrations is to store the correlation data in both systems, so that each side has a reference to the other's record ID.
| Storage Location | What Is Stored | When to Use |
| ---------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| Source only | The target record ID is stored in the source system | Common for one-way sync; source system tracks where data was sent |
| Target only | The source record ID is stored in the target system | Useful when the target system owns the correlation record |
| Both systems | Each system stores the other system's record ID | Required for reliable bi-directional sync; recommended default |
The storage location is configured in the **Correlation** section of each workflow in ZigiOps. You specify which field in each system holds the correlation value, and ZigiOps handles reading and writing that value automatically during each action cycle.
How Does Correlation Work Across Different Systems?
Different systems use different approaches for correlation fields. Some have a built-in field that ZigiOps uses by default; others require a custom field to be created before the integration can be configured.
| System | Default Correlation Field | Notes |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
| Jira | Dedicated custom text field (e.g., Correlation ID) | Must be created manually and associated with Create/Edit/View screens |
| ServiceNow | Built-in `correlation_id` field | Available by default; no custom field creation required |
| BMC Remedy / Helix | Vendor Ticket Number field | Native field used for external reference tracking |
| Cherwell | Custom text field (e.g., Correlation ID) | Must be created in the Business Object; set length to 150+ characters |
| Azure DevOps | Custom field or work item tag | Typically a custom text field added to the work item type |
| Salesforce | Custom field on the relevant object | Created as a text field on Case, Incident, or similar object |
When a system provides a built-in correlation field, such as ServiceNow's `correlation_id`, no additional setup is required in that system. When a system does not have a dedicated field, such as Jira, the field must be created manually and then referenced in the ZigiOps workflow configuration.
How Do I Set Up a Correlation Field in Jira?
Jira does not include a built-in correlation field. Before configuring correlation in a ZigiOps workflow that involves Jira, you must create a custom field and associate it with the relevant project screens. The steps below apply to both Jira Software and Jira Service Management.
Create a Custom Text FieldLog in to your Jira instance with an administrator account.Navigate to Administration > Issues > Custom Fields.Click Create custom field in the upper right corner.Select Text Field (single line) as the field type.Enter a name for the field. The recommended name is Correlation ID, though any descriptive label is acceptable as long as it is consistently referenced in your ZigiOps workflow\.Click Create to save the field.Associate the Field with the Relevant Project ScreensA custom field in Jira is not visible in workflows or API responses until it is associated with the correct project screens. This step is required for ZigiOps to read from and write to the field.In the Custom Fields list, locate the correlation field you just created.Click the three-dot menu next to the field and select Edit Field.Under the Screens section, associate the field with the following screens for each relevant project:Create Issue ScreenEdit Issue ScreenView Issue ScreenSave the changes.If you are using Jira Service Management, also associate the field with the relevant Request Type screens. The field must be present on both the agent view and the portal view to ensure ZigiOps can access it in all contexts.Update the ZigiOps Workflow to Use the New FieldOnce the field exists in Jira and is visible on the correct screens, reference it inside the ZigiOps workflow\.In ZigiOps, open the workflow that connects Jira to the other system.Navigate to the Correlation section of the workflow\.Replace the default correlation field reference with the name of the custom field you created.Save the workflow and run a test cycle to confirm that the correlation field is being populated correctly.The field name entered in ZigiOps must exactly match the internal field name used by the Jira API, not the display label. If you named the field Correlation ID, the internal API name will typically be customfield\_XXXXX. Confirm the correct API name by inspecting the Jira issue JSON response, or by checking the field details in Jira Administration > Issues > Custom Fields.
What Happens During a Workflow Cycle When Correlation Is Configured?
Understanding what ZigiOps does with the correlation field during each cycle helps when troubleshooting unexpected behavior.
### On Record Creation
1. ZigiOps collects a new record from the source system (for example, a new Jira task).
2. It checks the correlation field of that record. The field is empty because the record has not been synchronized yet.
3. ZigiOps creates a new record in the target system (for example, a new ServiceNow incident).
4. It stores the target system's record ID (for example, the ServiceNow incident number) back into the correlation field of the source record.
5. If correlation is configured for both systems, ZigiOps also stores the source record ID in the target system's correlation field.
### On Subsequent Updates
1. ZigiOps collects the updated source record.
2. It reads the correlation field and finds a value.
3. It uses that value to locate the corresponding record in the target system.
4. It applies only the changed fields as an update to the existing target record.
This create-then-update cycle repeats for every record throughout the entire integration lifecycle. The correlation field is the anchor that ensures each update reaches the correct record rather than generating a new one.
What Is the Role of Respond Field Mapping in Correlation?
Respond field mapping is the mechanism ZigiOps uses to write the target record's ID back to the source system after a creation action completes. It is what populates the correlation field in the source system.
Without a respond field mapping that writes the target record ID back to the source correlation field, ZigiOps cannot complete the correlation loop. Every subsequent polling cycle would see an empty correlation field and attempt to create a new record rather than update the existing one.
**Example:** After ZigiOps creates a ServiceNow incident from a Jira task, the respond mapping writes the ServiceNow incident number (e.g., `INC0012345`) into the Correlation ID custom field on the Jira task. On the next poll, ZigiOps reads that value and knows to update `INC0012345` rather than create a new incident.
Can Correlation Work Across More Than Two Systems?
Yes. A single ZigiOps deployment can run multiple workflows, each with its own correlation configuration. If the same Jira task is integrated with both ServiceNow and Azure DevOps through separate workflows, each workflow maintains its own correlation field. You would typically use two separate custom fields in Jira - one for each integration - to keep the correlation data for each system pair independent.
In multi-system orchestrations, use distinct, clearly named correlation fields for each system pair to avoid confusion and cross-contamination of correlation data.
What Are the Most Common Correlation Problems and How Do I Fix Them?
| Symptom | Likely Cause | Fix |
| ----------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Duplicate records created on every sync cycle | Correlation field is empty or not being read correctly | Verify the correlation field name in the workflow matches the actual field in the system |
| Updates going to the wrong record | Correlation field contains a non-unique value | Ensure the correlation field is a single-line text field with no default value and no shared values |
| Correlation field not populated after record creation | Respond field mapping is missing or misconfigured | Add a respond mapping that writes the target system's record ID back to the source correlation field |
| Correlation field value is truncated | Field length in the target system is too short | Set the correlation field length to at least 150 characters to accommodate system-generated IDs |
| Integration works in one direction but not the other | Correlation is stored in source only; target has no reference | Configure correlation to store in both systems for reliable bi-directional operation |
| Custom field not visible in ZigiOps field list | Field is not associated with the correct screen or entity | Associate the custom field with the Create, Edit, and View screens of the relevant project or entity |
What Are the Best Practices for Configuring Correlation?
### Always Use a Dedicated Field Per System Pair
Never reuse a field that serves another purpose as a correlation field. The correlation field must always be empty when a record is first created, and it must not be writable by end users or other automation. Any unexpected value in the field will cause ZigiOps to attempt an update instead of a create, pointing to the wrong target record.
### Set the Field Length to at Least 150 Characters
System-generated record IDs from enterprise platforms can be long, particularly in cloud-hosted systems. A field length of 150 characters prevents truncation, which would render the stored ID unreadable and break the correlation lookup.
### Configure Correlation Storage in Both Systems for Bi-Directional Integrations
When data flows in both directions, both systems need to hold a reference to the other system's record. Storing correlation in only one system creates a single point of failure: if the system that holds the data becomes unavailable or the field is cleared, the integration loses its record linking entirely.
### Test Correlation Before Enabling Production Workflows
After setting up the correlation field and configuring the workflow, trigger a single test creation and verify that the correlation field in the source system is populated with the target record's ID. Only proceed to full production activation after confirming the correlation loop works end to end.
### Audit Correlation Fields After System Upgrades
System upgrades, screen reconfigurations, or field schema changes can silently remove a custom field's association with project screens or change its internal API name. Include correlation field validation in your post-upgrade checklist for any system involved in a ZigiOps integration.
Where Can I Go from Here?
Correlation works closely with the other building blocks of ZigiOps integrations. The following topics are closely related:
* **Data Mapping Fundamentals:** Understand how field mapping and respond mapping work alongside correlation
* **Filters and Conditions:** Learn how source filters determine which records enter the correlation-create-update cycle
* **Transformations and Expressions:** Apply data transformations to fields before they are stored in or read from correlation fields
* **Best Practices:** End-to-end guidance for designing and maintaining integrations with robust correlation setups
* **Troubleshooting:** Detailed steps for diagnosing correlation failures in running integrations
---
# Agent Instructions: 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:
```
GET https://docs.zigiwave.com/design-and-mappings/correlation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.