Integrate airfocus with Azure DevOps

Benefits of using the Azure DevOps integration

• Import Azure DevOps work items into airfocus.
• Push airfocus items into Azure DevOps (as any work item type).
• Flexible filtering (via Azure DevOps Issue Search).
• Flexible mapping for system and custom fields with configurable sync directions per field.
• Directly map Azure DevOps descriptions to airfocus descriptions.
• Display your iterations (sprints) in airfocus for context around business value and priorities.

Set up the integration

Integrations in airfocus always connects to one specific airfocus Workspace. You can add multiple Azure DevOps integrations to a given workspace (for example, from different Azure DevOps projects or for different work item types).

To set up the Azure DevOps integration, follow these steps:

1. Sign up for airfocus or log into your existing account. 
2. Create a new workspace in airfocus or select the one you want to integrate Azure DevOps with.
3. Click Extensions from the top-right corner of the page.
4. Select Manage integrations.
   
5. Click Connect from the "Azure DevOps" tile.

From here, the steps differ depending on your instance type. Read the sections below for steps on each one.

Connect to your Azure DevOps Cloud account

To continue setting up the integration for an Azure DevOps Cloud account, follow these steps:

1. Select Azure Cloud in the instance type selector.
2. Click Proceed.

You'll be redirected to Azure DevOps to authenticate your access permissions and, after you log in to your account you'll be redirected to the airfocus integrations page of your workspace.

Make sure you have the setting "Third-party application access via OAuth" toggled on in the organization policies screen on Azure DevOps to ensure a successful integration.

Connect to your Azure DevOps Server (on-premise) account

To continue setting up the integration for an Azure DevOps Cloud account, follow these steps:

1. Select Azure On-Premise in the instance type selector.
2. Click Proceed.
3. Enter the details to connect to your Azure DevOps Server instance.
   • Base URL: Enter the first portion of your Azure DevOps Server URL (everything before until the end of your domain / IP address and before the first backslash). For example: https://198.254.533.325. The URL needs to be accessible by our servers, so you can not use locally hosted URLs here.
   • Personal access token: Obtain your personal access token by going to the personal access tokens section of your Azure DevOps users security settings. For more details, see the "Obtain a personal access token" section below.
   • Organization name: Enter the exact name of the Azure DevOps organization you want to sync with airfocus.
4. Click Proceed to connect your airfocus team to your Azure DevOps organization.

Obtain a personal access token

To obtain your personal access token in Azure DevOps, follow these steps:

1. Open your ADO Security settings.
2. Select Personal access tokens from the navigation menu on the left side of the page.
3. Click + New Token from the top of the page.
4. Create a new token with at least the following permissions:
   • Work items (read and write)
   • Project and team (read)
   • The personal access tokens can be configured to be valid for a maximum duration of 1 year. Remember to keep your token's validity up to date to ensure your airfocus integration can work without any interruptions.
5. Click Create.
6. Copy the token and paste it into your integrations settings in airfocus.

Configure your integration filters

To configure your integration filters:

1. Select the Azure DevOps project you want to integrate with. Add the following information so airfocus knows where to push the data to:
   • Organization
   • Project
   • Area
2. Optionally, include work items of all sub-areas of the selected area by checking the box next to "Include work items of all sub-areas of the selected area".

You can further specify which work items you want to sync using the Azure DevOps Issue Search field in the integration settings. It provides fast and flexible search across all your work items over all your projects (e.g. t:epic AND s:new).

Common Filters

• To filter by the Azure DevOps work item type:
  • t:epic
  • t:feature
  • t:story
  • t:task

To pull in items with a specific Azure DevOps tag

• tags:tag abc

To pull in items with a specific Azure DevOps iteration.

• iteration:iteration abc

Read more about advanced searching here.

Configure your field mapping

Use mapping to define how information in Azure DevOps should be mapped to airfocus (and vice versa). Item names (required) and item descriptions (optional) are always mapped by default when setting up a new integration.

How to set mapping directions

Define for each of your fields whether you want to have a one-way synchronization or a two-way synchronization between the field in Azure DevOps and airfocus.

Set the mapping directions for all fields at once with the “Set direction” dropdown.

By default, the mapping direction is set from Azure DevOps to airfocus only and can be changed by the user to whatever is available for mapping.

How to add a new field mapping

When you select a field in the dropdown, only fields that match the field type are displayed in the dropdown on the other end.

After you've selected two fields you want to map, you can select the field options and how they should be mapped:

Auto-mapping fields

When mapping fields with many options, toggle on "Auto-map field options" to save time. This automatically maps fields with the same values in both airfocus and Azure DevOps.

Auto-create field value generation

Toggle on "Auto-create field options" to automatically add new fields created in Azure DevOps to airfocus when they are added to an item. 

Note: The auto-create field generator is not case-sensitive.

Overview of all field mapping options currently available

Notes

1. ⚠️ If description is synchronized in both directions, this may cause airfocus to make slight changes in your Azure DevOps descriptions' content and formatting. This is due to not all Azure DevOps stylings being natively supported in airfocus yet.
2. The mapping in this direction can’t be supported if the target field in ADO is configured as read-only.
3. This includes only custom numeric fields from ADO. While any system numeric fields need to be implemented separately (like for example Priority or Effort). Therefore, if a system numeric field is not explicitly mentioned in this table - it means it’s not supported yet.
4. Picklists with allowed custom values are not suitable for mapping to airfocus select fields, because the amount of select-options in this case is dynamic and can frequently change over time, which would require to reconfigure the integration mapping each time when a new value appears in the picklist. That’s why we map such picklists to regular text or number fields in airfocus, so any new values on the ADO side are always automatically synchronized to the airfocus side.
5. This includes custom date-time fields, as well as system fields Start Date, Target Date, Due Date, Resolved Date and State Change Date.
6. ⚠️ At the moment airfocus does not support date-time fields (with the time part), but only date fields. Therefore, mapping ADO date-time fields into airfocus date fields in both directions results in losing the time part on the ADO side - the time will be reset by airfocus to 00:00:00.
7. At this time, ADO does not have any built-in date-range fields. However it’s possible to map a pair of any supported ADO date-time fields into a date-range airfocus field.
8. Mapping the Stack Rank field from airfocus back to Azure DevOps may lead to unexpected behavior. Microsoft documentation recommends against manually updating this field, as Azure DevOps dynamically calculates stack ranking behind the scenes to maintain backlog priorities. It is best used as a one-way sync from ADO to airfocus.

Hierarchy sync

Hierarchy sync for Azure DevOps allows you to sync the parent-child relations automatically from your Azure DevOps project to airfocus (one-way for now). This allows you to do product management work on airfocus while having the latest Azure DevOps hierarchy in sight without needing to switch between airfocus and Azure DevOps.

To set up/enable the Hierarchy sync for Azure DevOps, you’ll need:

• Two or more workspaces with airfocus hierarchy enabled between them OR a workspace that allows hierarchy relations within the same workspace.
• Two or more Azure DevOps work item types synced to airfocus.
• If you have two integrations in two workspaces, sync a single item type for each workspace.
• If you have two integrations in one workspace, sync a single item type for each of the integrations in that one workspace.

A user needs full access to the workspace in order to change anything in the integration settings.

To set up hierarchy sync, follow these steps:

1. In the workspace settings in airfocus, make sure the airfocus product hierarchy is enabled with another or within your current workspace.
   
2. At the bottom of the Azure DevOps integration settings page, toggle on the “Automatic item linking” widget.
   
3. To ensure the hierarchy is maintained, make sure the workspaces fulfill the following:
   • The other workspace has an integration into the same Azure DevOps organization.
   • The user has full access to the other workspace.
   • The other workspace is in the same airfocus team.

Once you have the Hierarchy sync enabled, you can see the parent-child relationships directly in airfocus.

Note the following when you enable Hierarchy sync for Azure DevOps:

• The integration only adds the relations between synced items, not additional items. This means items have to be synchronized by their respective integration already before hierarchy links are synced.
• Hierarchy sync for Azure DevOps can also be configured within the same workspace, if multiple Azure DevOps work item types are synced to the same airfocus workspace (either through a single or multiple integrations) and has enabled 'Allow hierarchy relations within this workspace' within the Hierarchy tab in the Workspace settings.

A user would require at least read access to the connected Azure DevOps project in order to enable Hierarchy sync for Azure DevOps.

Additional settings

• When "Archive unknown issues" is enabled, previously imported items are archived in airfocus if they are not present in Azure DevOps anymore or they do no longer fall into the filters set for the integration.
• When "Automatic sync" is enabled, your integration automatically syncs every 10 minutes and every time you access the workspace.
• Click View logs to view your Azure DevOps integration activity logs and see what changes were made before the last sync.
  

To save your settings and import your items to airfocus, click Update and synchronize.

Static IP addresses to white-list for your Azure DevOps integration

Teams on https://app.airfocus.com or https://app.us.airfocus.com  use these IP addresses:

• 46.101.71.101
• 46.101.69.142

Teams on https://airfocus.app, use these IP addresses:

• 100.24.176.163
• 34.204.246.112
• 54.227.154.184
• 35.156.253.227
• 18.159.159.136
• 18.199.183.125

Important information

• In order to create/authenticate a new integration with Azure DevOps, the Azure DevOps account used must have admin-level access.
• Modifying an existing integration on airfocus only requires the user to have Full permissions to the workspace.
• Even if the airfocus user does not have access to the Azure DevOps account used for the initial setup, the Azure DevOps account must keep the same permissions to ensure the integration works at all times.
• If a two-way sync was activated before, it will be applied to all mappings where possible. Otherwise it will be set as one way from Azure DevOps to airfocus.
• If "Show Azure DevOps description" was enabled the integration is only going to sync the description to the special read-only field until the 31st of March 2023. Users need to manually migrate to the new description field mapping in the field mapping section of their integrations. From the 1st of April 2023, the special description field (and its toggle) is no longer be available.

Give feedback on this article