Getting Started
Installation
First, install Jira Integration Framework on your ServiceNow instance via the System Applications application in your left nav. Visit Jira Integration Framework in your left nav and peruse the available modules. Be sure to enable annotations in your instance by clicking the ‘…’ icon in the top-right of any form. Every Jira Integration Framework form includes documentation to help you along.
Roles
x_yala_jira.user: Basic user role for end users that may need to interact interact with the Jira integration.
x_yala_jira.admin: Administrative user role. This role gives you access to the configuration & diagnostic modules for the integration framework. Those creating integration points will need access to this role.
x_yala_jira.mid_server: Role that should be given to the MID Server's authenticating user account in ServiceNow.
Service Account for ServiceNow
Create a Service Account in ServiceNow that has the roles required to interact with the ServiceNow components to be integrated with. Also, grant that service account user the “x_yala_jira.admin” role.
Set a reference to the Service Account by navigating to Jira Integration Framework > General Settings. Select the Service Account in the field, Jira Service Account.
Storing Webhook data
As the system receives webhook data from Jira, you can choose to discard that data so it is not stored in the instance, or you can choose to store that data in case there are errors that would be helpful to troubleshoot by seeing that webhook data was received recently.
You can set up this preference by navigating to Jira Integration Framework > General Settings.
Your options are as follows:
None - no data is retained
All - any webhook data received is retained
Handled only - any webhook data received that matched a handler rule will be retained
Unhandled only - any webhook data received that did not match a configured handler and was thus ignored will be retained
If you choose to retain any webhook data, you can specify how many hours that data will be retained.
Setting up application logging
The application comes with some helpful logging features. You can set logging preferences by following these instructions.
Setting up a connection to Jira
A Jira Connector record defines a connection to a Jira instance. You can have any number of Jira Connectors. These connectors can be configured from either the General Settings module of the application or from Jira Integration Framework > Jira Connectors.
Basic Connection Information
Name your connector in a way that it is easy to tell which Jira instance you are connected to. Your first connector should also be marked as the "Default" connector. Only one connector can be default at a time. If an API call is made and no connector is specified, then the default connector is used.
Your endpoint will be the base URL to your Jira instance (eg. https://mycompany.atlassian.net).
If using a MID Server to connect to the Jira instance, you will want to specify that MID Server here. At this time, MID Servers are required for advanced attachment synchronization. If you have a direct connection to your Jira instance, but do want to synchronize attachments, specify the MID Server and click the checkbox, "Use MID only for Attachments".
User and Authentication Information
Request that your Jira administrator create a service account for the ServiceNow instance to use to make API calls into Jira. This service account will need to have adequate roles to all of the projects, issue types, users, etc that is required for the various resources in Jira that you wish to integrate with.
When using the Jira Cloud Platform as your Jira instance, you will need to generate an API token for that user. You supply that API token in the "Password / API Token" field. If you are using another version of Jira that does not require API Tokens for API access, then you will just use the service account password.
Most versions of Jira will not return user information such as email addresses or user names with API calls. In these cases, you will also want to specify the Account ID of the service account user in the "Account ID" field. Jira Account IDs usually look something like: 897335:29981ac7-3973-4b66-c685-9a2be233g028.
Currently, the way to get an Account ID for a Jira user is to click on your user icon in the upper right portion of a Jira page and choose the menu item Jira > Profile. Then, look at the URL for that user's profile. The last part of the URL will contain the user account ID. (eg. https://MYCOMPANY.atlassian.net/jira/people/897335%3A29981ac7-3973-4b66-c685-9a2be233g028). You will want to unescape the %3A character which should translate to ":".
Data Import Settings
By default, the framework will automatically download metadata for Projects, Issue Types, and Record Fields and more. In most cases, none of these settings should be changed. However, if you wish to change how often that data is downloaded, you can do so in the fields that have "Frequency" in their label. These fields are a minimum number of minutes between imports of the metadata.
You can force an import outside of those scheduled timeframes by clicking the links found in the "Related Links" section of that form.
Testing the Connector
Once you have the connector information filled in and marked "Active", you can click the "Test the connector" button to have the system perform a simple API call to make sure that basic connectivity was successfully established. Please note, it does not test the service account for necessary access rights.
Checklist for Initial Configuration
The framework does provide a checklist utility that helps to ensure that these steps were performed. Some basic checks will occur and recommendations will be given of steps that might not yet be complete.
You can access this tool by navigating to Jira Integration Framework > Configuration > Initial Configuration
Last updated
