Overview

The ADO data connector for WorkBoard allows the user to pull progress based on available queries in ADO and specified issue status.

Once you've created an objective, you can create a key result that pulls data from your Azure DevOps projects; as work items are completed in Azure DevOps, your key result is automatically updated to reflect the progress made.

Configuring a Data Connector

Prior to setting up a new Key Result data connector, your organization’s IT Administrator may need to approve the connector if there is an approval configuration. Once enabled, any user can have their Key Results measure progress from that specific connector. 

1. Create a new Key Result by selecting the kebab menu (3 dots) next to the applicable Objective.
   • If the Objective hasn't been created, simply select Create > Team Objective or Personal Objective, then enter your Key Result name.
2. Select Edit Settings from the dropdown. 
3. Click Add another key result and enter your Key Result name.
4. Select Advanced options, then Pull data from external applications. 
5. Choose the applicable data source from one of the options:
6. Log in to the application by inputting your credentials. 
   • Please note that for some applications, you will also need to create an API key or provide OAuth2 information. This information is Read Only. 
7. Once enabled, your Key Results will automatically update based on the update cadence specified in the Key Result's configuration.
8. If you need to manually sync an update, use the Sync Integration Data option from the kebab menu (three dots) in the upper right-hand corner of the Key Result details page.

Setting up Key Result from Azure DevOps

1. After selecting Azure DevOps from the list of integrations, you'll need to authenticate the instance through OAuth or by providing a PAT (personal access token).
2. Once authenticated, search and select the applicable project.
3. Determine how to source the work item completion from the following options:
   • By Work Item ID
   • By Work Item Name
   • By Saved Query
4. Next, select an option for how you'd like to measure progress on the associated Work Items:
   • Only the specified Work Items: Measures the specific Work Items you include. This is good for measuring progress on a specific subset of Work Items and will not include any hierarchical children.
   • Progress by All Work Items (Rollup): Measure progress similar to the “Measure Progress by all Work Items” “Rollup” column available in an Azure DevOps Backlog Board. This will NOT include the specified Work Item themselves but will include progress on all Work Items hierarchically below the specified Work Item(s). See here for Azure DevOps documentation on Rollups. This works well for any hierarchical relationships between Work Items and progress.
   • Selected Work Items and any children: Measure only the Work Items that you have identified, or both those Work Items and their immediate children (this is the child link relationship in Azure DevOps).
     • Tip: When searching for work item names, make sure to search for entire words within your work item names to populate results.
       
5. When finished, select Save to lock in the settings for your Key Result, then Done to apply these changes to your Objective.

Tips for Saved Queries

• WorkBoard will gather the count of Work Items in the query. The count will be total number of work items slated for completion during the OKR time period.
• You can select the set of statues associated with work items that are considered completed work in your project and workflow. Completion percentage for these key results will be based on the total number of work items in the query, and how many of them are considered "Done" based on your selections. 

It's recommended to select queries that pull items from a single project; especially if you have different custom statuses defined per project. Status selection when configuring a key result is based on the custom statuses defined for the one project you select in the key result creation workflow.  

Synchronizing Data from Azure DevOps

WorkBoard will effortlessly sync Key Result updates directly from the data connector based on the specified update cadence. You can manually sync Key Result updates, if needed, in two ways:

Force a Sync on a Single Key Result:

1. Select Key Result to navigate to the Key Results Details page.
2. Click the kebab menu (3 dots) in the upper right-hand corner of the page.
3. Select Sync Integration Data.
   

Force a Sync for all Key Result Integrations:

1. From the My Objectives Page, select the kebab menu in the upper right-hand corner.
2. Select Sync Integration Data.

Frequently Asked Questions

What are the scopes of access that WorkBoard receives when I integrate a Key Result connector?

The scope of access is Read Only, which is bounded by the user integrating with the service.

Will the Key Result connector pull in historic updates?

No, the connector does not have the automated ability to post historic updates to Key Results. The update always goes to the present interval due for the Key Result.

• Please note that KPI integrations will only deliver updates that are currently due, meaning data pulled in Month X will have the timestamp 'Month X'.
  • As a workaround, multi-target KRs can divide a Key Result into distinct named intervals such as 'August', 'September', 'October', etc. The 'July' interval, for instance, would encompass the start/end dates for data collection (August 1st - August 31st). Despite being named 'July', the data collection would actually occur within the timeframe of August.
  • 

When will the connector update my Key Result?

The integration will update based on the update frequency set up for the Key Result (e.g. weekly updates weekly, daily updates daily, etc.). The integration scheduler operates on a twice-daily basis, offering two opportunities for updates to ensure data accuracy. To optimize efficiency, the scheduler skips updates for Key Results (KRs) that are not due for updates, to prevent redundant data updates and maintaining a streamlined process.