Create a new ALM Connection
Before you are able to sync a PI session with ADO, you will need to first create a new ALM Connection.
For this, you need to do the following in the RTE Cockpit:
Navigate to the ALM Connections on the left side navigation.
Click the Add new ALM Connection button on the ALM Connections page.
In the Select ALM Tool dropdown field, select Azure DevOps. Click Next.
[ADO] Connection tab
On the Connection tab you need to do the following:
Enter a Connection name: name reference to the ADO instance being connected
Enter the Instance URL: Base URL to your ADO instance
Enter a Username + PAT: For the designated ADO Service User Account.
Note: Authentication to ADO is currently via a Personal Access Token (PAT). It requires the ADO User Account to have Read, Write & Manage permission on Work Items (PBIs).
🔑 We recommend that you create a ADO Service Account for the sole purpose to manage the integration to piplanning.io.
🟢 IF you are looking for guidance on how to generate a PAT for the ADO Service User Account being used to authenticate, follow the link below. 🟢
How to obtain the PAT for your ADO account: Obtain PAT
Note: There are more options which you can access when clicking on the checkbox Advanced Settings. Check Connection advanced settings for more information.
[ADO] Project tab
Select the main ADO Project to connect to.
The purpose of this ADO Project selection is so we can fetch the metadata for the ADO Project, such as the Backlog Item types, the Workflows, Statuses etc.
Note: You can link to Area Paths and Iteration Paths in other ADO Projects for the Team / ART Mappings, as long as those ADO Projects are in the same ADO instance.
ADO Area Path and Iteration Path mappings are done later when completing the Team Mapping or ART Mapping tabs.
[ADO] WebHook tab
To establish a real time sync from ADO to piplanning.io, you will need to setup WebHooks in ADO.
You need to be a ADO Project Admin in ADO to do this. It is a very simple task, so please ensure you set up the ADO WebHooks for the best possible experience.
ADO WebHooks allow for automatic data updates to flow from ADO > to > piplanning.io.
You need to take the information displayed in this WebHook tab in the ALM Connection setup, and create the corresponding ADO WebHooks in your ADO Project/s or Organization with that information.
Checkout this guide on how to setup WebHooks in ADO: Setup WebHooks
The URL you need to enter for the WebHook in ADO is displayed on the WebHook screen and is unique per ALM Connection.
🟢 ADO WebHook lag - Delay in ADO WebHook triggers 🟢
IMPORTANT: Observations have shown that ADO triggers the WebHook with a lag of approximately 5-10 seconds.
Keep that in mind that you will have to wait for this time to pass until you see an update in the app.
Next: [ADO] Team Mapping tab.
Next: [ADO] ART Mapping tab for Solution Train set up.
ADO ALM Connection Prerequisites
Requirements
Minimal version of TFS / ADO: >= TFS 2020
Authentications against ADO (REST API): Personal Access Token/PAT with Read, Write and Manage permission on Work Items (PBIs)
Technical details related to the ADO ALM Connection
The following data is stored in piplanning.io
ADO Work Item Title
ADO Work Item ID
ADO Work Item Story-points (optional)
ADO Work Item WSJF (optional for ART-level Feature work items only)
ADO Work Item Area and Iteration Path
Links or relations from and to synced ADO Work Items
piplanning.io → ADO: ADO REST API (accessible on Port 80/443)
Requests to the ADO REST API from a single IP
ADO REST API Authentication with ADO PAT
Optional 2Way TLS (client certificate)
ADO → piplanning app: WebHooks using three (3x) different trigger events: Work item Created, Work item Deleted, Work item Updated)
Other
We strongly recommend an ADO Service User account which will be used for the authentication of the ADO REST API connection.
This ADO Service User account needs to have access to the Area Paths, Iteration Paths, Workflow metadata etc. ADO Projects/Teams. In addition it needs to C.R.U.D. permissions to backlog items in the ADO Projects.