The real-time integration of Path to Agility Navigator with Atlassian Jira follows these rules:
- The integration involves Action Items in Navigator
- Only Action Items created in Navigator can be synchronized with Jira
- Work Items created in Jira, will not be synchronized with Navigator
- Navigator will listen for updates to work items it created in Jira. When updates are detected, Navigator will update the corresponding Action Item in Navigator
- Configuration will be required in Jira to enable the integration
- Configuration will be required in Navigator to enable the integration
The API Token will be used to allow Navigator to create work items in Jira.
Prerequisite(s)
- Creating and using a service account (a user account dedicated to the integration between Navigator and Jira) is recommended.
- Add the service account user to group: jira-software-users
- Optionally, create a new security group, Organization Settings > Security > Create new security group with only the permissions necessary (as identified in the steps to create the token). Then add the user to that group.
- The user must also have permissions to the Space (aka project). See steps below.
- Ensure API Tokens are Allowed for the policy associated with the
service account
- Under administrator settings, go to: Security > Security Guide > User Security > Authentication Policies
- Ensure API Tokens are Allowed for the relevant policy
Steps to Create the API Token
- Log into Jira with the service account
- Go to Manage Profile > Security tab (https://id.atlassian.com/manage-profile/profile-and-visibility)
- Scroll down and click on "Create and manage API tokens"
- Click the "Create API token with scopes"
- Give the token a name (i.e. p2anav_jira_workitem_integration)
- Set expiration date per your security guidelines (recommend 3 to 6 months)
- Click Next
- Select Jira as the app
- Select the following scopes (the search fields are helpful to
finding and selecting):
- 'read:board-scope.admin:jira-software'
- 'read:board-scope:jira-software'
- 'read:issue:jira'
- read:issue-details:jira
- 'read:project:jira'
- 'read:status:jira'
- 'write:issue:jira'
- 'read:jira-work'
- 'write:jira-work'
- Click Next
- Copy API Token to a secure location. This will be needed when configuring the integration in Navigator
- Click Close
Steps to Add Service Account User to Space (aka project)
- Log into Jira with an administrator account (or a user with permissions to manage the space in question)
- Navigate to Spaces
- Find the name of the Space that will be integrated with Path to Agility Navigator in the list
- Select the More Options menu (on the same row as "...") and click Space Settings
- Select People from the left navigation
- Click the Add People button
- Add the service account to the Space
- Give the service account one of the following roles:
- Scrum Master
- Product Owner
- Developer
Web Hook Creation
The Web Hook will be configured so that updates to work items in Jira will be shared with Navigator, thus keeping the information in sync in both systems.
Prerequisite(s)
In order to create a Web Hook, the user creating the web hook must have administrator privileges (this should not be the same user as the service account which was used to create the API Token)
Steps to Create a Web Hook
Ensure the user has the appropriate permissions (see Prerequisites)
In Jira, navigate to the WebHooks admin page
Click the gear icon in the upper right
Under the heading Jira admin settings, click System
In the left side panel, scroll down to the Advanced section and click WebHooks
Creating the WebHook - this step requires values obtained from Navigator
On the right side of the screen, click the "Create a WebHook" button
Enter a descriptive name, such as "P2ANav Jira WebHook"
Set status to Enabled
In the URL field, enter the Webhook URL generated in Navigator
Click the button to generate a secret (and save this somewhere secure)
[Optional] Provide a description
Skip Events section
Under "Issue related events", enter a JQL filter so only updates to Jira items created by the integration will be shared with Navigator
Enter "reporter = "
Enter the first few letters of the name associated with the service account used to create the API Token OR enter the email address associated with that user
A list of selectable options will be displayed
Select the one with the service account info associated with the API Token
It will translate into a sequence of numbers and letters similar to the screenshot below
Under "Issue related events" (same section), check created, updated, and deleted under the "Issue" column (as shown in the screenshot below)
Leave all other fields blank
Click Save to create the WebHook
Update Navigator with the WebHook Secret
- In Navigator, as a Company Admin
- Go to Settings
- Go to the Jira Integration page
- Paste a copy of the secret that was generated and saved during the WebHook creation
- Save the changes
