The real-time integration of Path to Agility Navigator with Azure DevOps (ADO) follows these rules:
- The integration involves Action Items in Navigator
- Only Action Items created in Navigator can be synchronized with ADO
- Work Items created in ADO, will not be synchronized with Navigator
- Navigator will listen for updates to work items it created in ADO. When updates are detected, Navigator will update the corresponding Action Item in Navigator
- If a work item in ADO is deleted, the action item in Navigator will be deleted
- Configuration will be required in ADO to enable the integration
- Configuration will be required in Navigator to enable the integration
The Personal Access Token (PAT) will be used to allow Navigator to create work items in ADO.
Prerequisite(s)
- Creating and using a service account (one dedicated to the PAT to enable the creation of work items in ADO) is recommended.
- Optionally, create a new security group, Organization Settings
> Security > Create new security group with only permissions to
the following and then add the user to that group. Permissions:
- view projects
- view, edit, and create work items
Steps to Create the Personal Access Token in ADO (PAT)
In ADO as the user under which the PAT should be setup, go to https://dev.azure.com/{organization}
Click on User Settings (gear at top right) > Personal Access Tokens
Create the PAT
Name it something clear (i.e. P2A Navigator Work Item Token)
Select the organization or select "all accessible organizations" if there are multiple organizations
Set "Expiration" based on security standards (30/60/90 days, etc.)
Set "Scopes" to "Custom defined"
Under "Project and Team" select "Read"
Under "Work Items" select "Read & write"
Leave all other fields blank
Click "Save"
Copy the token that was generated. This will be needed to configure Navigator.
Create the Integration in Navigator
As a company administrator, the integration can be set up with the PAT created in the previous steps.
Log into Navigator with an account that has the Company Admin role
Go to Settings and select the Azure DevOps Integration option
Click Add Integration to open the modal to create the integration
Enter the Organization Name and the PAT created previously
Saving will run a validation check to ensure the organization exists in ADO
Once verified, the integration will be enabled and the Webhook URL and Webhook Client Secret are accessible. These are required to create the Service Hook.
Service Hook Creation in ADO
The Service Hook will be configured so that updates to work items in ADO will be shared with Navigator, thus keeping the information in sync in both systems.
Prerequisite(s)
In order to create a Service Hook, the user creating them must have the "Edit subscriptions" and "View subscriptions" permissions set to Allow. (Members of the 'Project Administrators' group have these permissions in the relevant project.)
Steps to Create a Service Hook
Ensure the user has the appropriate permissions (see Prerequisites)
In ADO, navigate to the desired project
Go to Project Settings > Service hooks
Add 2 service hooks (repeat these steps a second time, setting the trigger event to "Work item deleted" for the second web hook)
Select "Web Hooks" as the type and click "Next"
Trigger setup
Select "Work item updated" as the event
Set Area path to the current project
Set "Work item type" to "Any"
Set "Tag" to "P2A-Sync" (you may have to create this tag the first time)
Set "Field" to "Any"
Click "Next"
Action setup - this step requires values from Navigator
Enter the URL [the webhook url copied from Navigator]
Under "HTTP headers" enter the values generated from Navigator
Leave all other fields set to their default values
Click "Test" to test the communication
If testing is successful, click "Next" to complete the setup
