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 Account Settings > 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
Create Jira Integration in Navigator
The following will be needed to create the integration in Navigator: the API Token created previously, the email associated with the service account, and the URL to your Jira instance (i.e. https://COMPANYNAME.atlassian.net).
Creating the Integration
- Log into Navigator
- The user must have the Company Admin role
- Go to Settings > Jira Integration
- Click Add Integration
- Enter the requested information
- Jira Site URL (i.e. https://COMPANYNAME.atlassian.net)
- Service account email
- API Token
- Save
- After saving, a Webhook URL is generated that will be needed to configure the Webhook in Jira. Copy it for use in the next steps.
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
Add & Configure Projects
Once the integration is fully configured, business units can be configured so action items are created on the appropriate boards in Jira.
- In Navigator, as a Company Admin
- Go to Settings
- Go to the Jira Integration page
- Go to the Add and Sync Projects section
- Select a Business Unit
- Paste in the URL to the board for that business unit
- The list of statuses supported for issues on that board will be pulled in to populate the drop downs for First Status and Last Status. Select the status that corresponds to the initial state of issues as the First Status and the final status for issues (i.e. complete, done, released) as the Last Status.
- Click Add
