Installing or Upgrading IssueSync for Jira
This article explains how to install or upgrade issuesync for Jira.
Installing IssueSync for Jira
These installation instructions assume that Jira and Digital.ai Agility are already installed and working properly.
Determine Install Location
The integration can be installed on any Windows system with HTTP access to both Digital.ai Agility and Jira. Exact placement should be determined by your internal software management requirements. The integration system must meet the System Requirements.
Extract Files
Download the integration from the Application Catalog and extract it into a folder of your choice.
Configure
Configuration for the Integration is a 3 step process.
- Configuring Jira
- Configuring Digital.ai Agility
- Configuring ServiceHost
Step 1. Configuring Jira
This section describes how to modify your Jira instance for use with the integration. Before you begin, you need decide if you want to the Assign or Label method to indicate the Jira issues you want visible in Digital.ai Agility.
Select or Create a Jira User
The integration requires a valid Jira User ID and a Password in order to connect to Jira. This user must have sufficient rights to accept work and modify issues (i.e. must be assigned to the Developer Role on the project). This user must also have rights to the actions being performed by the integration (for example, the user must have rights to close Issues).
Although the integration does not require administrator access to run, there are some validation rules that can only be checked with a Jira Administrator role. To help check first-time configuration, the recommended approach is to elevate the integration user to Administrator. After the integration has been verified (start the integration in the below steps) and before starting as a service (install as Windows Service in the below steps), reduce the Jira access to the Developer Role. Then you can safely ignore log warnings about validation rules that require administrator access.
Create Filters for Defects and Stories
These filters must be available through the credentials used by the integration; hence, it is recommended that you create these filters using the same credentials to avoid the complexity of shared filters.
The results of a Jira filter are used to determine which Jira Issues will be transferred to Digital.ai Agility. By using a Jira filter, you can make the integration fit with your existing Jira workflow and fields. The details of writing such a filter are beyond the scope of this document; however, the following are some simple examples.
| Filter | Description |
|---|---|
| Type and Status Filter | The simplest Filter is to move all Jira Issues of a certain type and state to Digital.ai Agility. |
| Assigned User Filter | If only a subset of Jira Issues of a type and status should be moved, then you may want to create a Filter that transfers all Jira Issues that are associated with a specified user. This method is not supported when integrating with Jira 5.2 or earlier. |
| Label Filter | Another method of transferring only a subset of Jira Issues of a type and status would be to create a Filter that transfers all Jira Issues that are labeled with "Agility" or some other value you or your organization designates. Please note that the label value must already exist on an Issue in order to create this type of Filter. |
| Custom Field or Combination | If the Jira fields above would conflict with existing workflow, you may want to create a Custom Field and use it as part of the Filter. |
| Create a Custom Field to hold the URL to the Digital.ai Agility Workitem | By default the integration puts the Digital.ai Agility Workitem information in the "Comments" section of the Issue. This information includes a URL to the Digital.ai Agility Workitem. You may optionally add another field to hold this data as necessary. To do this create the Jira Custom Field and note the 'fieldId' value in the Jira URL. This value is available to the Jira Administrator. |
Step 2. Configure Digital.ai Agility
-
Add "Jira" to Source of the Global List Types:
-
Determine where to store the Jira ID
The integration needs a text field in Digital.ai Agility to store the Jira identifier; by default this is the Reference field. If you are already using this field, you'll need to create a custom text field in Digital.ai Agility and note the name.
Step 3. Configuring ServiceHost
To configure the Jira integration you need to run the ServiceHost configuration tool: ServiceHostConfigTool.exe
The following section describes how to configure the integration using the configuration tool.
On the General tab, specify your Digital.ai Agility connection details:
The following table describes the fields on this tab:
| Field | Description |
|---|---|
| Authentication | The API authentication method used by the integration to connect to the Digital.ai Agility server. |
| Access Token | The access token generated for the Digital.ai Agility member account that the integration will use. |
| Server URL | This is the URL to your Digital.ai Agility server. |
| Username | Digital.ai Agility user that will create Workitems (Defects and Stories), used only when not using an access token. |
| Password | Password for the specified Digital.ai Agility user, used only when not using an access token. |
If there's a proxy between this machine and the Digital.ai Agility instance, you'll also need to configure the following settings:
| Field | Description |
|---|---|
| Use Proxy For Connection | Determines if the integration tries to connect through a Proxy. |
| Proxy URL | This is the URL to your Proxy Server. |
| Proxy Username | The username that will get you past this Proxy. |
| Proxy Password | The password for the Proxy Username. |
| Proxy Domain | Name of the Proxy Domain. |
Once the Digital.ai Agility parameters are specified, click Validate button to continue. You should see a "VersionOne settings are valid" message appear before you can advance to the next step.
In the Workitems section, specify the Digital.ai Agility field that will hold the Jira ID.
The following table describes the fields on this tab:
| Field | Description |
|---|---|
| Reference Field Name | Digital.ai Agility field used to hold Jira ID; by default this is the Reference field. If you created a custom field in Digital.ai Agility for this value, enter it here. |
| Disabled | Check this box to disable polling Digital.ai Agility for Workitem updates. |
On the Jira tab, specify your Jira connection details and the Issue transfer behavior.
Configure the Jira connection.
| Field | Description |
|---|---|
| Disabled | Check this box if you want to disable polling Jira for new Issues. |
| Jira URL | Fully qualified URL to your Jira instance. Don't forget /rest/api/latest |
| Username | Valid Jira user. This user must be able to see and update Issues in the appropriate projects. |
| Password | Password for specified user. |
Configure Poll Interval.
| Field | Description |
|---|---|
| Poll Interval | Determines how frequently the integration polls Jira looking for issues in minutes. |
Configure Find Jira Issues.
| Field | Description |
|---|---|
| Create Defect Filter ID | Jira identifier for the filter used to determine which issues are pushed to Digital.ai Agility as Defects. This field cannot be empty. |
| Create Story Filter ID | Jira identifier for the filter used to determine which issues are pushed to Digital.ai Agility as Stories. This field cannot be empty. |
Configure Update JIRA Issue.
| Field | Description |
|---|---|
| Link to Digital.ai Agility Field ID | Custom Field Id in Jira used to hold Digital.ai Agility URL. If blank, the URL will be created in the Comments field in Jira. |
| Create Field ID | Name of the Jira Custom Field to update after a Workitem is created in Digital.ai Agility. If left blank, the JIRA Issue Status field will be updated. |
| Create Field Value | Value to set in "Create Field ID" after a Workitem is created in Digital.ai Agility. If left blank, the Jira Issue Status field will be updated to IN PROGRESS. |
| Close Field ID | Name of the Jira Custom Field to update after a Digital.ai Agility Workitem is closed. If left blank, the Jira Issue Status field will be updated. |
| Close Field Value | Value to set in "Closed Field ID" after a the Digital.ai Agility Worktiem is closed. If left blank, the Jira Issue Status field will be updated to RESOLVED. |
| Assignee State Changed | The name of the Jira user to assign to the Issue once it's closed in Digital.ai Agility. A value of -1 will cause Jira to set the assignee based on workflow rules. |
| Progress Workflow Created | The Jira Workflow Transition ID to set once it's created in Digital.ai Agility. |
| Progress Workflow Closed | The Jira Workflow Transition ID to set once it's closed in Digital.ai Agility. |
Map your Projects
Project Mapping allows you to specify where Workitems are created in Digital.ai Agility. The algorithm for selecting a project is as follows: First, the integration looks for the Jira Project Name in the map. If it exists, the Workitem is created in the corresponding Digital.ai Agility Project. If the Jira Project Name is not found, the integration attempts to find a Digital.ai Agility Project with the same name. If found, the integration creates the Workitem in the Digital.ai Agility Project with a matching name. If it cannot find a Digital.ai Agility Project with a name that matches the Jira Project, the integration will create the Workitem in the root level node of the Digital.ai Agility Project Tree or in the first project in the list if there are multiple top level nodes.
To add a Project Mapping you need to do the following:
- Click on the Project and Priority Mappings tab
- In the Project Mapping grid, select a Digital.ai Agility Project value from the drop-down list.
- Supply the corresponding Jira Project name.
- To remove a mapping: Select the desired row.
- Click the Delete selected row button.
Map your Priority Values
Priority mapping allows you to configure how the Digital.ai Agility Workitem priority value is set based on the Jira Priority value. The algorithm for mapping is simple, if the Jira Priority value is in the mapping, the Digital.ai Agility Workitem priority value is set to the mapped value. If the Jira Priority value is not found, the Digital.ai Agility Worktiem priority value is not set.
To add a Priority Mapping you need to do the following:
- Click on the Project and Priority Mappings tab.
- In the Priority Mappings grid, select a Digital.ai Agility Priority value from the drop-down.
- Select the corresponding Jira Priority value. Note that one Digital.ai Agility priority value may map to more than one Jira priority value.
- To remove a mapping: Select the desired row.
- Click the Delete selected row button.
- Save your changes and exit the configuration tool.
Upgrading IssueSync for Jira
If you already have the integration running in your environment, you should backup the existing integration before installing the current version.