Create a new connection
Before you are able to sync a PI session with ADO, you will need to create a new ALM connection first.
For this, you need to click "Add new ALM Connection" on the "ALM Connections" page.
Connection
On the connection screen you need to enter the URL to your ADO instance.
The authentication against ADO is currently done via a PAT (Personal Access Token). It requires the Read, Write & Manage permission on Work Items.
We recommend that you create a service-account which only purpose is to be used with piplanning.io.
Check this page on how to obtain the PAT of an ADO account: Obtain PAT
There are more options which you can access when clicking on the checkbox "Advanced Settings". Check Connection advanced settings for more information.
ADO Project
We only support one ADO project / alm-connection. You can therefore not use multiple ADO projects in one PI session.
Webhook
To be able to use the realtime sync from ADO into the piplanning app, you will need to setup a webhook in ADO. You need to be a project Admin in ado to do this.
Take the information on in the "Webhook" screen in the Cockpit to setup the webhook in ADO. 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 setup in the cockpit.
Lag between ADO->piplanning app
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.
Prerequisites
Requirements
Minimal version of TFS / ADO: >= TFS 2020
Authentications against ADO (REST API): Personal Access Token with Read, Write & Manage permission on Work Items
The following data is stored in piplanning.io
Workitem Title
Workitem ID
Workitem Story-points (optional)
Workitem WSJF (optional)
Workitem Area and Iteration path
Relations from and to synced workitems
Connections used for the synchronization
piplanning app → ADO: REST-API of ADO (access on Port 80/443)
Requests to the ADO API from a single IP
API Authentication with ADO PAT
Optional 2Way TLS (client certificate)
ADO → piplanning app: Webhooks (Work item created, Work item deleted, Work item updated)
Other
We recommend a service-user account which will be used for the connection to ADO
The user needs to have access to the Area-paths of the used Teams in the app (needs to create, change and delete work-items in ADO)