Learn more about creating a custom integration.

This working example will create a fully functional integration between Jira and ServiceNow from scratch. While there are specifics and differences from one integration to another, the concept behind most of the steps below applies to all integrations and system types.

Let’s create a total of 3 operations, which will work together to form one fully functional integration:

  • 1st operation will transfer Jira tasks to incidents in ServiceNow
  • 2nd operation will transfer changes from our Jira tasks to their correlated incidents in ServiceNow, including user comments
  • 3rd operation will transfer changes from our ServiceNow incidents back to their correlated tasks in Jira, including work notes

Please note that it is recommended to start by creating a connected system before proceeding with creating a custom integration.

Creating a custom integration

If you prefer not to use the available integration templates and create your own custom integration from scratch, you should go to the Configurator page and click the Create Custom Integration button.

 Example

Configuring the Global Integration Settings

The new integration will have one draft operation by default, which you could customize later. Before we add our operations, we need to configure the integration settings, which affect all integration operations. They're distributed in the following sections:

  • Integrated Systems
  • Integrated Entities
  • Operations
  • Correlation

Integrated Systems

The Integrated Systems section selects which 2 systems we want to integrate. The first system we need to select is the target system, along with the entity and the action type we need, which is Create in this example. Next, we need to select the target system and the target entity. Placing the mouse cursor on any of the fields will automatically bring a list of the existing connected systems, which you could integrate.

Once we're ready with the selections, we need to select a trigger for the integration.

Please note that the recommended polling interval is 1 minute.


 Example


Integrated Entities

After the connected systems are selected, we should continue by selecting the source and the target entities, which we would like to integrate.


Please note that the available Jira entities are displayed as a combination of the Jira project and corresponding issue type, separated by a dot, i.e. project.task.


 Example

Operations

The Operations section is entirely informational. It is basically a list of all operations available in the template. Clicking on any operation will redirect us to the corresponding operation configuration page.

 Example

Correlation

In the Correlation section, we could map 1 (or more) fields, which ZigiOps will use to correlate (or link) the integrated entities. This is required so ZigiOps will be able to update (or synchronize the changes) already integrated records, i.e., if a change is made in an integrated record, then this change will be synchronized to the other system (if the updated field is part of the mapping).

Please note that it is strongly recommended to use fields, which carry unique identifier information for the records, such as IDs or keys.

In our example integration, we are using the "key" field of the Jira tasks to map it to the "correlation_id" of the ServiceNow incidents. For example, after ZigiOps will collect a Jira task to create a ServiceNow incident, the newly created incident will carry the key of the corresponding Jira task in its "correlation_id" field.

Please note that we can use any Jira text field to store the correlation information, but It is recommended that we use a custom field for this purpose. This is a best practice to prevent interference with fields that might be used by the users, another integration, script, etc.

Configuring our create operation

After we have configured our general integration settings, we can move on to configuring the operations. Let's continue with configuring the first operation, which is of type "create."

Expressions

It is recommended to start with an expression of type "Last Time," which we will use later in the trigger condition section. This expression is important because it is a preventive mechanism that allows ZigiOps to collect only records, which are created after the previously collected records, in order to avoid creating duplicate records. This is how ZigiOps keeps track of the previously collected records. Once a new record is created, or an already transferred record is updated, ZigiOps will not collect it again.

Please note that if we don't create a Last Time expression, ZigiOps will continuously collect previously collected data from the source system, regardless of whether it was already created in the target system or not, causing data duplication!

After the new expression is added, we should input a name for it. In our case, we've called it "lasttime," but we're free to input any suitable name. Next, we need to select a source field from which the expression will take its value. In this case, we will use the "create" field as a source since it contains the creation time of the Jira records. Finally, we need to select the "Last Time" expression type from the drop-down menu.

 Example

Trigger Conditions

In this section, we will define the records collection criteria (or filter), which the source system records should match, so they could be collected by ZigiOps. We've configured 3 trigger conditions in our example.

  • We would like to collect records, which CREATED date is newer than the CREATED date of the previously collected records, i.e., if the previously collected record was created on 1/June/2020 at 10:00, ZigiOps will now look for records created after this time.
  • We would like to collect records, which REPORTER/KEY is different than the one of the integration user, defined in the Jira connected system. This condition ensures that ZigiOps will only collect records created by real users and not records that have been created by the integration user.
  • We would like to collect records, which are empty. In our Jira instance, this custom field is intended to carry the ServiceNow record number, and if it is not empty, this would mean that the Jira record has already been collected; thus, it is actively being synchronized with a corresponding ServiceNow record.
 Example

Field Map

In this section, we can create the field mapping for this operation. We've defined 3 fields in this example integration.

  • We've mapped the SUMMARY field from Jira and to the SHORT_DESCRIPTION field in ServiceNow.
  • We've mapped the DESCRIPTION field from Jira and to the DESCRIPTION field in ServiceNow.
  • We've mapped the URGENCY field from Jira and to the PRIORITY field in ServiceNow.
 Example

Configuring our update operation

Our previous operation is taking care of transferring the newly created records from Jira to ServiceNow. Let’s configure our second operation, which will synchronize the changes, made to the Jira records to the ServiceNow records. To create a new blank operation, we can click on the Plus button of the integration itself. A new draft operation will be added automatically at the bottom of our list of operations. Since this operation will update our ServiceNow incidents, we should set its type to Update from the top menu bar; this way, we are instructing ZigiOps to use the correlation information to synchronize the entities.

Expressions

In this operation, we will create 2 additional expressions of the type "Last Time."

  • lastupdated - This lasttime expression is responsible for the collection of only Jira tasks that have been modified since the last run of the operation.
  • lastchangelog - This lasttime expression monitor was the last time the changelog history field in Jira was updated.
  • lastcomment - This lasttime expression monitor, when was the last time a comment was submitted in any of the tasks in Jira.

In the next steps, we will use these additional last time expressions in the Trigger Conditions section. This will allow us to collect only Jira tasks that have been modified or the ones that have new user comments.

 Example

Trigger Conditions

We want our operation to update the incidents in ServiceNow only when there are new changes or new comments in their correlated Jira tasks. In order to achieve this, we have set the following trigger rules for our operation.

  • updated is greater than {lastupdated}
  • reporter/key is not the integration user
  • Changelog history or the comments sections are not empty.
 Example

This configuration so far will make sure the operation collects Jira tasks that have something in their changelog or comments, but we also need to add our additional last time expressions for the comments and changelog fields as a preventive measure. To do this, we need to expand the Related Records section from the + button.

This will expand the additional conditions that we can set for any child fields. In our case, they are changelog/histories and comments, as shown below.

 Example

In our example integration, we've set a condition for the changelog/histories field, where its time of creation is later than the last run of the operation, via our {lasttimechangelog} expression, and the author is not the integration user.

Similarly, we've done the same configuration for the comment field, where we are using our {lasttimecomment} expression.

Please note that if we don't set a preventive condition for the integration user, ZigiOps will continuously collect already collected comments from the source system, regardless of whether they were already sent to the target system or not, causing the creation of duplicate comments!

At a glance, this configuration will ensure that ZigiOps collects only changes that have been made by real users and only after the last run of the operation, where data has been collected and transferred.

Field Map

Our mapping configuration will be almost identical to our previous operation but with an additional mapping for the state field. This will ensure that when we update the state of our Jira tasks, the state in their correlating ServiceNow incidents will also be updated.

Once we go to the mapping, we will set several conditions for the state field in Jira. These conditions are responsible for the proper adjustment of the status field in ServiceNow.

 Example

With the configuration above, we're instructing ZigiOps to perform the following mapping, based on our conditions:

  • If the state of the Jira task is "To Do," set the status of the correlating ServiceNow incident to 1
  • If the Jira state is "In Progress," set the ServiceNow incident status to 2
  • If the Jira state is "Done," set the status of the ServiceNow incident to 6
 Example


The last step in the mapping section for this operation is to map the value of the comment section in Jira to the work notes section in ServiceNow. These fields are nested, so we need to use the Related Records menu of the mappings. It can be accessed by clicking the + icon at the bottom of the Field Map section.

In the example above, we're mapping the target system (ServiceNow), next to the entity (work_notes), and the action (Update). After that, we need to add the source system (Jira) and its entity (comment).

 Example


Creating and configuring our third operation

Finally, our third operation will be responsible for transferring updates from our ServiceNow incidents back to their correlated tasks in Jira. This means we need to set the integration direction in the top menu bar to point back to the Jira tasks.

Expressions

In this operation, we will use the {sys_updated_on} field from ServiceNow as a reference for our lasttime variable.

 Example

Trigger Conditions

In order for ZigiOps to update our Jira tasks with changes from their correlated incidents in ServiceNow, we'll set the following trigger conditions:

  • sys_updated_on is greater than our {lasttime}
  • sys_updated_by is not the integration user
  • sys_created_by is the integration user
 Example

This means that ZigiOps will collect only incidents that have been created by the integration but updated only by real users. And just like before, the lasttime makes sure ZigiOps collects changes only from incidents that have been updated since the last run of the operation.

We also need to configure conditions for the work notes in our ServiceNow incidents. Since work_notes is a nested field, we need to expand the Related Records section and place our conditions there:

  • sys_created_by is not the integration user
  • sys_updated_on is greater than our {lasttime}
 Example

This will ensure that we collect only the latest work notes that have been posted by real users.

 Example

Field Map

The mappings in this update operation are generally mirroring the mappings from our previous operation. We have switched the fields so that Jira is being targeted in this flow.

In this case are mapping the value of the short_description field to the summary field in Jira, the descriptions of both entities, and their priorities. We have also created a mapping for the state field of ServiceNow with several conditions to make sure the proper status is assigned in Jira:

 Example

Finally, we need to make sure the comment sections from both systems are properly mapped. Just like in the previous operation, we need to use the related records section of the mappings. We will map the {value} of the ServiceNow work_notes to the body of the comment/comments section in Jira.

 Example

Troubleshooting

It is possible to encounter minor issues during the integration setup. The user interface is designed to display configuration errors, pointing to a possible root cause. However, there are few common issues that may require manual resolution.

Errors when saving an integration/operation.

Few reasons that might cause an error to occur while saving an integration or operation:

  • We are using an invalid field that does not exist in the systems that we are trying to integrate.
  • A mandatory field was left blank. Mandatory fields can be found in the Integrated Systems, Integrated Entities, and Mapping sections.

Errors when activating an integration/operation.

  • Attempting to activate integration with missing mandatory fields will also result in an error.
  • We haven't loaded a valid license or don't have enough integration points available.

Missing fields or suggestions

If we don't have suggested fields in the Conditions or Mappings section, this might be due to:

  • There is no proper connection to the connected systems. Go to the Connected Systems page, review the connection details, and hit the Test Connection button to ensure the connection was successful.
  • If there are new fields or projects that have been added to your systems after the creation of integration, they might not be available in the suggestions. To resolve this, navigate to the Connected Systems page, select the system and click the Save button on the top-right. This will restart the connection process and re-download any missing projects and/or fields.

Summary

Once we save our operations and we get no errors, we can test our integration by activating each operation separately or the entire integration globally. Now, whenever a new task in Jira is created, it will be automatically transferred to ServiceNow, and both related entities will be kept in sync with their state and user comments.

In this working example, we will create a fully functional integration between Jira and ServiceNow from scratch. While there are specifics and differences from one integration to another, the concept behind most of the steps below applies to all integrations and system types.

Let’s create a total of 3 operations, which will work together to form one fully functional integration:

  • 1st operation will transfer Jira tasks to incidents in ServiceNow
  • 2nd operation will transfer changes from our Jira tasks to their correlated incidents in ServiceNow, including user comments
  • 3rd operation will transfer changes from our ServiceNow incidents back to their correlated tasks in Jira, including work notes

Please note that it is recommended to start by creating a connected system before proceeding with creating a custom integration.

Creating a custom integration

If you prefer not to use the available integration templates and create your own custom integration from scratch, you should access the Configurator page and click the Create custom integration button.

 Example

Configuring the Global Integration Settings

Once you click the Create Custom Integration button, a new integration will be added to the left sidebar, as shown on the next screenshot. The new integration will have one draft operation by default, which you will be able to customize later. Before we proceed with adding our operations, we need to configure the Global Integration Settings, which influence all operations within the integration. These global settings are separated into the following sections:

  • Integrated Systems
  • Integrated Entities
  • Operations
  • Correlation

Integrated Systems

The Integrated Systems section is where we select which two systems we want to integrate together. The first system we need to select is the target system, also the entity, and the action we need, which is Create. Next, we need to choose the target system and the entity as well. Clicking inside any of the fields, there will automatically appear a list with suggestions.  What type of entities we can select to integrate with - In the example below, we're instructing ZigiOps to collect entities of type Bug from the TEST project in Jira (test.bug) and create entities of type Incident in ServiceNow. You may select virtually any of the available entities and make various combinations between events, incidents, bugs, tasks, change requests, and so on.

After this is ready, we need to add a polling interval; by default, it is configured for 1 minute. Shorter than 1-minute periods are recommended only for testing purposes.

 Example


Once we've selected two valid systems, the Integrated Entities section below will become available, and we can proceed with the setup.

Integrated Entities

After the setup of the integration setup, we selected the systems and the type of entities we'd like to integrate with. Now we can see and change them from here.

 Example

Operations

The Operations section is entirely informational. It lists all our available operations and their current status.

We can click any of them, and we will be redirected to the configuration page for the operation.

 Example

Correlation

In the Correlation section, we need to map two fields from each system, so ZigiOps can link the entities together. This is required, so it knows which entity from System A correlates to which entity from System B in order to keep them in sync. It is recommended that we use fields that hold unique identifier information for the entities, such as keys and IDs.

In our example integration, we are taking the unique keys of our Jira tasks and mapping them to the correlation_id fields of our ServiceNow incidents. So whenever we transfer a Jira task to ServiceNow, the newly created incident in ServiceNow will hold the unique key of the Jira task in its correlation_id field.

It is similar in the opposite direction - When we transfer a Jira task as an incident to ServiceNow, the unique sys_id of the newly created incident will be automatically returned to its correlating task in Jira by ZigiOps. The sys_id will populate a simple custom text field (customfield_10008), which we have created in Jira beforehand.

We can use any text field in Jira to store the correlation information, but It is recommended that we use a custom text field for this purpose. This way, ZigiOps will not interfere with fields that might be used by the users or are used by another integration, script, and so on.

Configuring our first operation

Now that we have configured our global integration settings, we can move on to configuring each of our operations separately. Since we've started off with just one operation by default, we can use it as the starting point of our integration flow. We will configure it to transfer newly created Jira tasks to incidents in ServiceNow.

Expressions

First, we need to create a "Last Time" expression that we will later use as a trigger condition. This is required because it is a preventive mechanism that allows ZigiOps to collect only the newest changes and entities from each system in order to avoid making duplicate entries. This way, ZigiOps keeps track of when was the last time each operation has collected something new from the source system. Once a new entity or a change is collected, it will not be collected again on the next run of the operation unless we make new changes to it.

Please note that if we don't create a Last Time expression, ZigiOps will continuously collect already collected data from the source system, regardless of whether it was already created in the target system or not, causing the creation of duplicate entries!

Once we add a new expression section of our operation, we first need to set a name for it. In our case, we've called it lasttime. After that, we need to select from which field we want to check the time the source entity has been created or modified. For our first operation, we are using the {create} field. It contains the time when the Jira entity has been created. Finally, we need to select the "Last Time" expression type from the drop-down menu.

 Example

Trigger Conditions

In the Trigger Conditions section, we will define what criteria need to be met in order for ZigiOps to execute our operation. Think of it as a filter. In our example, we've set 3 conditions:

  • The lasttime variable from the expressions section. We want to execute our operation only when the value of the created field in Jira is greater than our last time value. Said otherwise, ZigiOps will collect entities from Jira that have been created only after the last execution of the operation.
  • The reporter/key is not {Jira/source/username}. This condition ensures that ZigiOps only collects entities created by real users and prevents the collection of entities that have been created by the integration user. This will prevent duplicate entries in ServiceNow.
  • The customfield_10008 is empty. Our custom field in Jira holds the unique key of the correlating incident in ServiceNow. If this field is not empty, this means the Jira entity has already been collected, and it is actively being synchronized with its correlating incident. If this field is empty, then the Jira entity has recently been created and hasn't been transferred and linked with an incident in ServiceNow. 
 Example

Field map

In the Field Map section, we can map as many fields as we'd like to use. For the purpose of our demo integration, our operation only has 3 simple mappings.

  • We will use the summary field from Jira and assign its value to the short_description field in ServiceNow.
  • We will map the descriptions and priorities of both entities in a similar fashion, as shown in the screenshot below. 
 Example

Once we've configured all sections of the operation, we can finally save it and move on to creating additional operations.

Creating and configuring our second operation

Our previous operation is taking care of transferring the newly created entities from Jira to ServiceNow. Now, let’s configure our second operation, which will synchronize the changes from Jira to ServiceNow. To create a new blank operation, we can click on the Plus button of the integration itself. A new draft operation will be added automatically at the bottom of our list of operations. Since this operation will update our ServiceNow incidents, we should set its type to Update from the top menu bar; this way, we are instructing ZigiOps to use the correlation information to synchronize the entities.

Expressions

For this operation, we will create two additional expressions of type Last Time.

  • lastupdated - This lasttime expression is responsible for the collection of only Jira tasks that have been modified since the last run of the operation.
  • lastchangelog - This lasttime expression monitors when was the last time the changelog history field in Jira was updated.
  • lastcomment - This lasttime expression monitors when was the last time a comment was submitted in any of the tasks in Jira.

In the next steps, we will use these additional last time expressions in the Trigger Conditions section. This will allow us to collect only Jira tasks that have been modified or the ones that have new user comments.

 Example

Trigger Conditions

We want our operation to update the incidents in ServiceNow only when there are new changes or new comments in their correlated Jira tasks. In order to achieve this, we have set the following trigger rules for our operation.

  • updated is greater than {lastupdated}
  • reporter/key is not the integration user
  • Changelog history or the comments sections are not empty.
 Example

This configuration so far will make sure the operation collects Jira tasks that have something in their changelog or comments, but we also need to add our additional last time expressions for the comments and changelog fields as a preventive measure. To do this, we need to expand the Related Records section from the + button.

This will expand the additional conditions that we can set for any child fields. In our case, they are changelog/histories and comments, as shown below.

 Example

In our example integration, we've set a condition for the changelog/histories field, where its time of creation is later than the last run of the operation, via our {lasttimechangelog} expression, and the author is not the integration user.

Similarly, we've done the same configuration for the comment field, where we are using our {lasttimecomment} expression.

Please note that if we don't set a preventive condition for the integration user, ZigiOps will continuously collect already collected comments from the source system, regardless of whether they were already sent to the target system or not, causing the creation of duplicate comments!

At a glance, this configuration will ensure that ZigiOps collects only changes that have been made by real users and only after the last run of the operation, where data has been collected and transferred.

Field Map

Our mapping configuration will be almost identical to our previous operation but with an additional mapping for the state field. This will ensure that when we update the state of our Jira tasks, the state in their correlating ServiceNow incidents will also be updated.

Once we go to the mapping, we will set several conditions for the state field in Jira. These conditions are responsible for the proper adjustment of the status field in ServiceNow.

 Example

With the configuration above, we're instructing ZigiOps to perform the following mapping, based on our conditions:

  • If the state of the Jira task is "To Do," set the status of the correlating ServiceNow incident to 1
  • If the Jira state is "In Progress," set the ServiceNow incident status to 2
  • If the Jira state is "Done," set the status of the ServiceNow incident to 6
 Example


The last step in the mapping section for this operation is to map the value of the comment section in Jira to the work notes section in ServiceNow. These fields are nested, so we need to use the Related Records menu of the mappings. It can be accessed by clicking the + icon at the bottom of the Field Map section.

In the example above, we're mapping the target system (ServiceNow), next to the entity (work_notes), and the action (Update). After that, we need to add the source system (Jira) and its entity (comment).

 Example


Creating and configuring our third operation

Finally, our third operation will be responsible for transferring updates from our ServiceNow incidents back to their correlated tasks in Jira. This means we need to set the integration direction in the top menu bar to point back to the Jira tasks.

Expressions

In this operation, we will use the {sys_updated_on} field from ServiceNow as a reference for our lasttime variable.

 Example

Trigger Conditions

In order for ZigiOps to update our Jira tasks with changes from their correlated incidents in ServiceNow, we'll set the following trigger conditions:

  • sys_updated_on is greater than our {lasttime}
  • sys_updated_by is not the integration user
  • sys_created_by is the integration user
 Example

This means that ZigiOps will collect only incidents that have been created by the integration but updated only by real users. And just like before, the lasttime makes sure ZigiOps collects changes only from incidents that have been updated since the last run of the operation.

We also need to configure conditions for the work notes in our ServiceNow incidents. Since work_notes is a nested field, we need to expand the Related Records section and place our conditions there:

  • sys_created_by is not the integration user
  • sys_updated_on is greater than our {lasttime}
 Example

This will ensure that we collect only the latest work notes that have been posted by real users.

 Example

Field Map

The mappings in this update operation are generally mirroring the mappings from our previous operation. We have switched the fields so that Jira is being targeted in this flow.

In this case are mapping the value of the short_description field to the summary field in Jira, the descriptions of both entities, and their priorities. We have also created a mapping for the state field of ServiceNow with several conditions to make sure the proper status is assigned in Jira:

 Example

Finally, we need to make sure the comment sections from both systems are properly mapped. Just like in the previous operation, we need to use the related records section of the mappings. We will map the {value} of the ServiceNow work_notes to the body of the comment/comments section in Jira.

 Example

Troubleshooting

It is possible to encounter minor issues during the integration setup. The user interface is designed to display configuration errors, pointing to a possible root cause. However, there are few common issues that may require manual resolution.

Errors when saving an integration/operation.

Few reasons that might cause an error to occur while saving an integration or operation:

  • We are using an invalid field that does not exist in the systems that we are trying to integrate.
  • A mandatory field was left blank. Mandatory fields can be found in the Integrated Systems, Integrated Entities, and Mapping sections.

Errors when activating an integration/operation.

  • Attempting to activate integration with missing mandatory fields will also result in an error.
  • We haven't loaded a valid license or don't have enough integration points available.

Missing fields or suggestions

If we don't have suggested fields in the Conditions or Mappings section, this might be due to:

  • There is no proper connection to the connected systems. Go to the Connected Systems page, review the connection details, and hit the Test Connection button to ensure the connection was successful.
  • If there are new fields or projects that have been added to your systems after the creation of integration, they might not be available in the suggestions. To resolve this, navigate to the Connected Systems page, select the system and click the Save button on the top-right. This will restart the connection process and re-download any missing projects and/or fields.

Summary

Once we save our operations and we get no errors, we can test our integration by activating each operation separately or the entire integration globally. Now whenever a new task in Jira is created, it will be automatically transferred to ServiceNow, and both related entities will be kept in sync with their state and user comments.

In this working example, we will create a fully functional integration between Jira and ServiceNow from scratch. While there are specifics and differences from one integration to another, the concept behind most of the steps below applies to all integrations and system types.

Let’s create a total of 3 operations, which will work together to form one fully functional integration:

  • 1st operation will transfer Jira tasks to incidents in ServiceNow
  • 2nd operation will transfer changes from our Jira tasks to their correlated incidents in ServiceNow, including user comments
  • 3rd operation will transfer changes from our ServiceNow incidents back to their correlated tasks in Jira, including work notes

Please note that it is recommended to start by creating a connected system before proceed with creating a custom integration.

Creating a custom integration

If you prefer not to use the available integration templates and create your own custom integration from scratch, you should access the Configurator page and click the Create custom integration button.

 Example

Configuring the Global Integration Settings

Once you click the Create Custom Integration button, a new integration will be added to the left sidebar, as shown on the next screenshot. The new integration will have one draft operation by default, which you will be able to customize later. Before we proceed with adding our operations, we need to configure the Global Integration Settings, which influence all operations within the integration. These global settings are separated into the following sections:

  • Integrated Systems
  • Integrated Entities
  • Operations
  • Correlation

Integrated Systems

The Integrated Systems section is where we select which two systems we want to integrate together. The first system we need to select is the target system, also the entity, and the action we need, which is Create. Next, we need to choose the target system and the entity as well. Clicking inside any of the fields there will be automatically appear a list with suggestions.  What type of entities we can select to integrate with - In the example below, we're instructing ZigiOps to collect entities of type Bug from the TEST project in Jira (test.bug) and create entities of type Incident in ServiceNow. You may select virtually any of the available entities and make various combinations between events, incidents, bugs, tasks, change requests and so on.

After this is ready, we need to add polling interval by default it is configured on 1 minute. Shorter than 1-minute periods are recommended only for testing purposes.

 Example


Once we've selected two valid systems, the Integrated Entities section below will become available and we can proceed with the setup.

Integrated Entities

After the setup of the integration setup we selected the systems and the type of entities we'd like to integrate with. Now we can see and change them from here.

 Example

Operations

The Operations section is entirely informational. It lists all our available operations and their current status.

We can click any of them and we will be redirected to the configuration page for the operation.

 Example

Correlation

In the Correlation section, we need to map two fields from each system, so ZigiOps can link the entities together. This is required so it knows which entity from System A correlates to which entity from System B in order to keep them in sync. It is recommended that we use fields that hold unique identifier information for the entities, such as keys and IDs.

In our example integration, we are taking the unique keys of our Jira tasks and mapping them to the correlation_id fields of our ServiceNow incidents. So whenever we transfer a Jira task to ServiceNow, the newly created incident in ServiceNow will hold the unique key of the Jira task in its correlation_id field.

It is similar in the opposite direction - When we transfer a Jira task as an incident to ServiceNow, the unique sys_id of the newly created incident will be automatically returned to its correlating task in Jira by ZigiOps. The sys_id will populate a simple custom text field (customfield_10008), which we have created in Jira beforehand.

We can use any text field in Jira to store the correlation information, but It is recommended that we use a custom text field for this purpose. This way ZigiOps will not interfere with fields that might be used by the users or are used by another integration, script and so on.

Configuring our first operation

Now that we have configured our global integration settings, we can move on to configuring each of our operations separately. Since we've started off with just one operation by default, we can use it as the starting point of our integration flow. We will configure it to transfer newly created Jira tasks to incidents in ServiceNow.

Expressions

First, we need to create a "Last Time" expression that we will later use as a trigger condition. This is required, because it is a preventive mechanism that allows ZigiOps to collect only the newest changes and entities from each system, in order avoid making duplicate entries. This way ZigiOps keeps track of when was the last time each operation has collected something new from the source system. Once a new entity or a change is collected, it will not be collected again on the next run of the operation, unless we make new changes to it.

Please note that if we don't create a Last Time expression, ZigiOps will continuously collect already collected data from the source system, regardless of whether it was already created in the target system or not, causing creation of duplicate entries!

Once we add new expression section of our operation, we first need to set a name for it. In our case, we've called it lasttime. After that, we need to select from which field we want to check the time the source entity has been created or modified. For our first operation, we are using the {create} field. It contains the time when the Jira entity has been created. Finally, we need to select the "Last Time" expression type from the drop-down menu.

 Example

Trigger Conditions

In the Trigger Conditions section, we will define what criteria needs to be met, in order for ZigiOps to execute our operation. Think of it as a filter. In our example, we've set 3 conditions:

  • The lasttime variable from the expressions section. We want to execute our operation, only when the value of the created field in Jira is greater than our last time value. Said otherwise, ZigiOps will collect entities from Jira that have been created only after the last execution of the operation.
  • The reporter/key is not {Jira/source/username}. This condition endures that ZigiOps only collects entities, created by real users and prevents collection of entities that have been created by the integration user. This will prevent duplicate entries in ServiceNow.
  • The customfield_10008 is empty. Our custom field in Jira holds the unique key of the correlating incident in ServiceNow. If this field is not empty, this means the Jira entity has already been collected and it is actively being synchronized with its correlating incident. If this field is empty, then the Jira entity has recently been created and hasn't been transferred and linked with an incident in ServiceNow. 
 Example

Field map

In the Field Map section, we can map as many fields as we'd like to use. For the purpose of our demo integration, our operation only has 3 simple mappings.

  • We will use the summary field from Jira and assign its value to the short_description field in ServiceNow.
  • We will map the descriptions and priorities of both entities in a similar fashion, as shown on the screenshot below. 
 Example

Once we've configured all sections of the operation, we can finally save it and move on to creating additional operations.

Creating and configuring our second operation

Our previous operation is taking care for transferring the newly created entities from Jira to ServiceNow. Now, let’s configure our second operation, which will synchronize the changes from Jira to ServiceNow. To create a new blank operation, we can click on the Plus button of the integration itself. A new draft operation will be added automatically at the bottom of our list of operations. Since this operation will update our ServiceNow incidents, we should set its type to Update from the top menu bar, this way we are instructing ZigiOps to use the correlation information to synchronize the entities.

Expressions

For this operation, we will create two additional expressions of type Last Time.

  • lastupdated - This lasttime expression is responsible for the collection of only Jira tasks that have been modified since the last run of the operation.
  • lastchangelog - This lasttime expression monitors when was the last time the changelog history field in Jira was updated.
  • lastcomment - This lasttime expression monitors when was the last time a comment was submitted in any of the tasks in Jira.

In the next steps, we will use these additional last time expressions in the Trigger Conditions section. This will allow us to collect only Jira tasks that have been modified or the ones that have new user comments.

 Example

Trigger Conditions

We want our operation to update the incidents in ServiceNow only when there are new changes or new comments in their correlated Jira tasks. In order to achieve this, we have set the following trigger rules for our operation.

  • updated is greater than {lastupdated}
  • reporter/key is not the integration user
  • Changelog history or the comments sections are not empty
 Example

This configuration so far will make sure the operation collects Jira tasks that have something in their changelog or comments, but we also need to add our additional last time expressions for the comments and changelog fields, as a preventive measure. To do this, we need to expand the Related Records section from the + button.

This will expand the additional conditions that we can set for any child fields. In our case, they are changelog/histories and comment, as shown below.

 Example

In our example integration, we've set a condition for the changelog/histories field, where its time of creation is later than the last run of the operation, via our {lasttimechangelog} expression and the author is not the integration user.

Similarly, we've done the same configuration for the comment field, where we are using our {lasttimecomment} expression.

Please note that if we don't set a preventive condition for the integration user, ZigiOps will will continuously collect already collected comments from the source system, regardless of whether they were already sent to the target system or not, causing creation of duplicate comments!

In a glance, this configuration will ensure that ZigiOps collects only changes that have been made by real users and only after the last run of the operation, where data has been collected and transferred.

Field Map

Our mapping configuration will be almost identical to our previous operation, but with an additional mapping for the state field. This will ensure that when we update the state of our Jira tasks, the state in their correlating ServiceNow incidents will also be updated.

Once we go to the mapping, we will set several conditions for the state field in Jira. These conditions are responsible for the proper adjustment of the status field in ServiceNow.

 Example

With the configuration above, we're instructing ZigiOps to perform the following mapping, based on our conditions:

  • If the state of the Jira task is "To Do", set the status of the correlating ServiceNow incident to 1
  • If the Jira state is "In Progress", set the ServiceNow incident status to 2
  • If the Jira state is "Done", set the status of the ServiceNow incident to 6
 Example


The last step in the mapping section for this operation is to map the value of the comment section in Jira to the work notes section in ServiceNow. These fields are nested, so we need to use the Related Records menu of the mappings. It can be accessed by clicking the + icon at the bottom of the Field Map section.

In the example above, we're mapping the target system (ServiceNow), next the entity (work_notes) and the action (Update). After that we need to add the source system (Jira) and its entity (comment).

 Example


Creating and configuring our third operation

Finally, our third operation will be responsible for transferring updates from our ServiceNow incidents back to their correlated tasks in Jira. This means we need to set the integration direction in the top menu bar to point back to the Jira tasks.

Expressions

In this operation, we will use the {sys_updated_on} field from ServiceNow as reference for our lasttime variable.

 Example

Trigger Conditions

In order for ZigiOps to update our Jira tasks with changes from their correlated incidents in ServiceNow, we'll set the following trigger conditions:

  • sys_updated_on is greater than our {lasttime}
  • sys_updated_by is not the integration user
  • sys_created_by is the integration user
 Example

This means that ZigiOps will collect only incidents that have been created by the integration but updated only by real users. And just like before, the lasttime makes sure ZigiOps collects changes only from incidents that have been updated since the last run of the operation.

We also need to configure conditions for the work notes in our ServiceNow incidents. Since work_notes is a nested field, we need to expand the Related Records section and place our conditions there:

  • sys_created_by is not the integration user
  • sys_updated_on is greater than our {lasttime}
 Example

This will ensure that we collect only the latest work notes that have been posted by real users.

 Example

Field Map

The mappings in this update operation are generally mirroring the mappings from our previous operation. We have switched the fields so that Jira is being targeted in this flow.

In this case are mapping the value of the short_description field to the summary field in Jira, the descriptions of both entities and their priorities. We have also created a mapping for the state field of ServiceNow with several conditions, to make sure the proper status is assigned in Jira:

 Example

Finally, we need to make sure the comment sections from both systems are properly mapped. Just like in the previous operation, we need to use the related records section of the mappings. We will map the {value} of the ServiceNow work_notes to the body of the comment/comments section in Jira.

 Example

Troubleshooting

It is possible to encounter minor issues during the integration setup. The user interface is designed to display configuration errors, pointing to a possible root cause. However, there are few common issues that may require manual resolution.

Errors, when saving an integration/operation

Few reasons, that might cause an error to occur, while saving an integration or operation:

  • We are using an invalid field that does not exist in the systems that we are trying to integrate
  • A mandatory field was left blank. Mandatory fields can be found in the Integrated Systems, Integrated Entities and Mapping sections

Errors, when activating an integration/operation

  • Attempting to activate an integration with missing mandatory fields will also result in an error
  • We haven't loaded a valid license or don't have enough integration points available

Missing fields or suggestions

If we don't have suggested fields in the Conditions or Mappings section, this might be due to:

  • There is no proper connection to the connected systems. Go to the Connected Systems page, review the connection details and hit the Test Connection button to ensure the connection was successful.
  • If there are new fields or projects that have been added in your systems, after the creation of an integration, they might not be available in the suggestions. To resolve this, navigate to the Connected Systems page, select the system and click the Save button on the top-right. This will restart the connection process and re-download any missing projects and/or fields.

Summary

Once we save our operations and we get no errors, we can test our integration by activating each operation separately, or the entire integration globally. Now whenever a new task in Jira is created, it will be automatically transferred to ServiceNow and both related entities will be kept in sync with their state and user comments.

In this working example, we will create a fully functional integration between Jira and ServiceNow from scratch. While there are specifics and differences from one integration to another, the concept behind most of the steps below applies to all integrations and system types.

Let’s create a total of 3 operations, which will work together to form one fully functional integration:

  • 1st operation will transfer Jira tasks to incidents in ServiceNow
  • 2nd operation will transfer changes from our Jira tasks to their correlated incidents in ServiceNow, including user comments
  • 3rd operation will transfer changes from our ServiceNow incidents back to their correlated tasks in Jira, including work notes

Please note that it is recommended to start by creating a connected system, before proceed with creating a custom integration.

Creating a custom integration

If you prefer not to use the available integration templates and create your own custom integration from scratch, you should access the Configurator page and click the Create custom integration button.

 Example

Configuring the Global Integration Settings

Once you click the Create Custom Integration button, a new integration will be added to the left sidebar, as shown on the next screenshot. The new integration will have one draft operation by default, which you will be able to customize later. Before we proceed with adding our operations, we need to configure the Global Integration Settings, which influence all operations within the integration. These global settings are separated in the following sections:

  • Integrated Systems
  • Integrated Entities
  • Operations
  • Correlation

Integrated Systems

The Integrated Systems section is where we select which two systems we want to integrate together. First system we need to select is the target system, also the entity and the action we need which is Create. Next, we need to choose the target system and the entity as well. Clicking inside any of the fields there will be automatically appear a list with suggestions.  What type of entities we can select to integrate with - In the example below, we're instructing ZigiOps to collect entities of type Bug from the TEST project in Jira (test.bug) and create entities of type Incident in ServiceNow. You may select virtually any of the available entities and make various combinations between events, incidents, bugs, tasks, change requests and so on.

After this is ready, we need to add polling interval by default it is configured on 1 minute. Shorter than 1-minute periods are recommended only for testing purposes.

 Example


Once we've selected two valid systems, the Integrated Entities section below will become available and we can proceed with the setup.

Integrated Entities

After the setup of the integration setup we selected the systems and the type of entities we'd like to integrate with. Now we can see and change them from here.

 Example

Operations

The Operations section is entirely informational. It lists all our available operations and their current status.

We can click any of them and we will be redirected to the configuration page for the operation.

 Example

Correlation

In the Correlation section, we need to map two fields from each system, so ZigiOps can link the entities together. This is required so it knows which entity from System A correlates to which entity from System B in order to keep them in sync. It is recommended that we use fields that hold unique identifier information for the entities, such as keys and IDs.

In our example integration, we are taking the unique keys of our Jira tasks and mapping them to the correlation_id fields of our ServiceNow incidents. So whenever we transfer a Jira task to ServiceNow, the newly created incident in ServiceNow will hold the unique key of the Jira task in its correlation_id field.

It is similar in the opposite direction - When we transfer a Jira task as an incident to ServiceNow, the unique sys_id of the newly created incident will be automatically returned to its correlating task in Jira by ZigiOps. The sys_id will populate a simple custom text field (customfield_10008), which we have created in Jira beforehand.

We can use any text field in Jira to store the correlation information, but It is recommended that we use a custom text field for this purpose. This way ZigiOps will not interfere with fields that might be used by the users or are used by another integration, script and so on.

Configuring our first operation

Now that we have configured our global integration settings, we can move on to configuring each of our operations separately. Since we've started off with just one operation by default, we can use it as the starting point of our integration flow. We will configure it to transfer newly created Jira tasks to incidents in ServiceNow.

Expressions

First, we need to create a "Last Time" expression that we will later use as a trigger condition. This is required, because it is a preventive mechanism that allows ZigiOps to collect only the newest changes and entities from each system, in order avoid making duplicate entries. This way ZigiOps keeps track of when was the last time each operation has collected something new from the source system. Once a new entity or a change is collected, it will not be collected again on the next run of the operation, unless we make new changes to it.

Please note that if we don't create a Last Time expression, ZigiOps will continuously collect already collected data from the source system, regardless of whether it was already created in the target system or not, causing creation of duplicate entries!

Once we add new expression section of our operation, we first need to set a name for it. In our case, we've called it lasttime. After that, we need to select from which field we want to check the time the source entity has been created or modified. For our first operation, we are using the {create} field. It contains the time when the Jira entity has been created. Finally, we need to select the "Last Time" expression type from the drop-down menu.

 Example

Trigger Conditions

In the Trigger Conditions section, we will define what criteria needs to be met, in order for ZigiOps to execute our operation. Think of it as a filter. In our example, we've set 3 conditions:

  • The lasttime variable from the expressions section. We want to execute our operation, only when the value of the created field in Jira is greater than our last time value. Said otherwise, ZigiOps will collect entities from Jira that have been created only after the last execution of the operation.
  • The reporter/key is not {Jira/source/username}. This condition endures that ZigiOps only collects entities, created by real users and prevents collection of entities that have been created by the integration user. This will prevent duplicate entries in ServiceNow.
  • The customfield_10008 is empty. Our custom field in Jira holds the unique key of the correlating incident in ServiceNow. If this field is not empty, this means the Jira entity has already been collected and it is actively being synchronized with its correlating incident. If this field is empty, then the Jira entity has recently been created and hasn't been transferred and linked with an incident in ServiceNow. 
 Example

Field map

In the Field Map section, we can map as many fields as we'd like to use. For the purpose of our demo integration, our operation only has 3 simple mappings.

  • We will use the summary field from Jira and assign its value to the short_description field in ServiceNow.
  • We will map the descriptions and priorities of both entities in a similar fashion, as shown on the screenshot below. 
 Example

Once we've configured all sections of the operation, we can finally save it and move on to creating additional operations.

Creating and configuring our second operation

Our previous operation is taking care for transferring the newly created entities from Jira to ServiceNow. Now, let’s configure our second operation, which will synchronize the changes from Jira to ServiceNow. To create a new blank operation, we can click on the Plus button of the integration itself. A new draft operation will be added automatically at the bottom of our list of operations. Since this operation will update our ServiceNow incidents, we should set its type to Update from the top menu bar, this way we are instructing ZigiOps to use the correlation information to synchronize the entities.

Expressions

For this operation, we will create two additional expressions of type Last Time.

  • lastupdated - This lasttime expression is responsible for the collection of only Jira tasks that have been modified since the last run of the operation.
  • lastchangelog - This lasttime expression monitors when was the last time the changelog history field in Jira was updated.
  • lastcomment - This lasttime expression monitors when was the last time a comment was submitted in any of the tasks in Jira.

In the next steps, we will use these additional last time expressions in the Trigger Conditions section. This will allow us to collect only Jira tasks that have been modified or the ones that have new user comments.

 Example

Trigger Conditions

We want our operation to update the incidents in ServiceNow only when there are new changes or new comments in their correlated Jira tasks. In order to achieve this, we have set the following trigger rules for our operation.

  • updated is greater than {lastupdated}
  • reporter/key is not the integration user
  • Changelog history or the comments sections are not empty
 Example

This configuration so far will make sure the operation collects Jira tasks that have something in their changelog or comments, but we also need to add our additional last time expressions for the comments and changelog fields, as a preventive measure. To do this, we need to expand the Related Records section from the + button.

This will expand the additional conditions that we can set for any child fields. In our case, they are changelog/histories and comment, as shown below.

 Example

In our example integration, we've set a condition for the changelog/histories field, where its time of creation is later than the last run of the operation, via our {lasttimechangelog} expression and the author is not the integration user.

Similarly, we've done the same configuration for the comment field, where we are using our {lasttimecomment} expression.

Please note that if we don't set a preventive condition for the integration user, ZigiOps will will continuously collect already collected comments from the source system, regardless of whether they were already sent to the target system or not, causing creation of duplicate comments!

In a glance, this configuration will ensure that ZigiOps collects only changes that have been made by real users and only after the last run of the operation, where data has been collected and transferred.

Field Map

Our mapping configuration will be almost identical to our previous operation, but with an additional mapping for the state field. This will ensure that when we update the state of our Jira tasks, the state in their correlating ServiceNow incidents will also be updated.

Once we go to the mapping, we will set several conditions for the state field in Jira. These conditions are responsible for the proper adjustment of the status field in ServiceNow.

 Example

With the configuration above, we're instructing ZigiOps to perform the following mapping, based on our conditions:

  • If the state of the Jira task is "To Do", set the status of the correlating ServiceNow incident to 1
  • If the Jira state is "In Progress", set the ServiceNow incident status to 2
  • If the Jira state is "Done", set the status of the ServiceNow incident to 6
 Example


The last step in the mapping section for this operation is to map the value of the comment section in Jira to the work notes section in ServiceNow. These fields are nested, so we need to use the Related Records menu of the mappings. It can be accessed by clicking the + icon at the bottom of the Field Map section.

In the example above, we're mapping the target system (ServiceNow), next the entity (work_notes) and the action (Update). After that we need to add the source system (Jira) and its entity (comment).

 Example


Creating and configuring our third operation

Finally, our third operation will be responsible for transferring updates from our ServiceNow incidents back to their correlated tasks in Jira. This means we need to set the integration direction in the top menu bar to point back to the Jira tasks.

Expressions

In this operation, we will use the {sys_updated_on} field from ServiceNow as reference for our lasttime variable.

 Example

Trigger Conditions

In order for ZigiOps to update our Jira tasks with changes from their correlated incidents in ServiceNow, we'll set the following trigger conditions:

  • sys_updated_on is greater than our {lasttime}
  • sys_updated_by is not the integration user
  • sys_created_by is the integration user
 Example

This means that ZigiOps will collect only incidents that have been created by the integration but updated only by real users. And just like before, the lasttime makes sure ZigiOps collects changes only from incidents that have been updated since the last run of the operation.

We also need to configure conditions for the work notes in our ServiceNow incidents. Since work_notes is a nested field, we need to expand the Related Records section and place our conditions there:

  • sys_created_by is not the integration user
  • sys_updated_on is greater than our {lasttime}
 Example

This will ensure that we collect only the latest work notes that have been posted by real users.

 Example

Field Map

The mappings in this update operation are generally mirroring the mappings from our previous operation. We have switched the fields so that Jira is being targeted in this flow.

In this case are mapping the value of the short_description field to the summary field in Jira, the descriptions of both entities and their priorities. We have also created a mapping for the state field of ServiceNow with several conditions, to make sure the proper status is assigned in Jira:

 Example

Finally, we need to make sure the comment sections from both systems are properly mapped. Just like in the previous operation, we need to use the related records section of the mappings. We will map the {value} of the ServiceNow work_notes to the body of the comment/comments section in Jira.

 Example

Troubleshooting

It is possible to encounter minor issues during the integration setup. The user interface is designed to display configuration errors, pointing to a possible root cause. However, there are few common issues that may require manual resolution.

Errors, when saving an integration/operation

Few reasons, that might cause an error to occur, while saving an integration or operation:

  • We are using an invalid field that does not exist in the systems that we are trying to integrate
  • A mandatory field was left blank. Mandatory fields can be found in the Integrated Systems, Integrated Entities and Mapping sections

Errors, when activating an integration/operation

  • Attempting to activate an integration with missing mandatory fields will also result in an error
  • We haven't loaded a valid license or don't have enough integration points available

Missing fields or suggestions

If we don't have suggested fields in the Conditions or Mappings section, this might be due to:

  • There is no proper connection to the connected systems. Go to the Connected Systems page, review the connection details and hit the Test Connection button to ensure the connection was successful.
  • If there are new fields or projects that have been added in your systems, after the creation of an integration, they might not be available in the suggestions. To resolve this, navigate to the Connected Systems page, select the system and click the Save button on the top-right. This will restart the connection process and re-download any missing projects and/or fields.

Summary

Once we save our operations and we get no errors, we can test our integration by activating each operation separately, or the entire integration globally. Now whenever a new task in Jira is created, it will be automatically transferred to ServiceNow and both related entities will be kept in sync with their state and user comments.