Creating a Custom Integration
Summary
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
Note that it is recommended to start by creating a connected system before creating a custom integration.
Creating a Custom Integration
Suppose you prefer not to use the available integration templates and create your own custom integration from scratch. In that case, you should go to the Configurator page and click the Create Custom Integration button.
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 and the entity and 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 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.
Integrated Entities
After the connected systems are selected, we should continue 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.
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 can 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 use the "key" field of the Jira tasks to map it to the "correlation_id" of the ServiceNow incidents. For example, after ZigiOps collects 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 we recommend using 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 created after the previously collected records to avoid 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, 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.
Trigger Conditions
This section will define the records collection criteria (or filter), which the source system records should match so that ZigiOps can collect them. We've configured 3 trigger conditions in our example.
We want to collect records, which Created date is newer than the Created date of the previously collected records, i.e., if you created the previously collected record on 1/June/2020 at 10:00, ZigiOps will now look for records created after this time.
We want to collect records, which Reporter/Key is different from one of the integration users defined in the Jira connected system. This condition ensures that ZigiOps will only collect records created by real users and not records that the integration user has created.
We want to collect empty records. In our Jira instance, this custom field is intended to carry the ServiceNow record number. 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.
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.
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 collecting only Jira tasks that have been modified since the last run of the operation.
lastchangelog - This lasttime expression monitor was the last time someone updated the changelog history field in Jira.
lastcomment - This lasttime expression monitor, when was the last time someone submitted a comment in any of the tasks in Jira.
We will use these additional “Last Time” expressions in the Trigger Conditions section in the next steps. This will allow us to collect only Jira tasks that have been modified or the ones that have new user comments.
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. 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.
This configuration will make sure the operation collects Jira tasks that have something in their changelog or comments. Still, 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 field. In our case, they are changelog/histories and comments, as shown below.
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.
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
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).
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.
Trigger Conditions
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
This means that ZigiOps will collect only incidents that have been created by the integration but updated only by real users. And 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}
This will ensure that we collect only the latest work notes that real users have posted.
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, 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:
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.
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, few common issues 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 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 some new fields or projects have been added to your systems after creating 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.