Configure and activate Azure DevOps integration

You should configure Azure DevOps settings in Jira Align (ADO) for the correct data synchronization. You can customize many settings according to your needs.

To configure and turn on integration:

• Set up connector information
• Configure your projects
• Configure work item sync
• View logs

Prerequisites:

1. In Jira Align, set up portfolios and programs.
2. Create the PI dates you identified in Step 8 in the Azure DevOps Integration Prerequisites section.
3. For each Jira Align PI, create sync sprints for Azure DevOps iterations.

Set up connector information

1. Select the Settings gear in the top navigation bar.
   
2. On the left side of the page, select Azure DevOps Settings in the Connectors section.
3. Click Add Connector. The New Azure DevOps Connector slide-out appears. 
   
   
4. Type the connection name and the URL to connect to Azure DevOps.
   Note: This configuration supports both the https://visualstudio.com and https://dev.azure.com.
5. Select the authentication method you want to use: PAT (personal access token), NTLM (NT LAN manager), or OAuth (only available for Cloud instances), and then enter the necessary credentials. Read more on authentication methods here.
6. In the Item Link Back URL Template box, type the URL template used when you want to present a link in Jira Align in the upper-right corner of an item that will take you to the linked item in Azure DevOps.
7. Enter a value between 60 and 1440 minutes in the Project sync timer field. This value controls how often the connector syncs mapped program area paths, team area paths, and iteration paths.
8. Enter a value between 3 and 60 minutes in the Work item sync timer field. This value controls how often the connector runs to sync new and updated work items.
9. Enter a value between 240 and 1440 minutes in the Recycle bin sync timer field. This value controls how often the connector syncs items in the ADO recycle bin with the Jira Align recycle bin.
10. Switch on the Update on Link Change toggle to allow the connector to perform a separate search to identify and sync items in AzureDevOps for which the only change was the identity of the item's parent. ADO’s standard query for changed items only provides items that were directly changed; changing or removing an item's parent does not update the timestamp of the item and the standard query will not find these changes. However, the separate search enabled by this setting is an extra step in the sync process and connector performance may be improved by disabling the setting.
11. In the Default Jira Align system role for ADO users dropdown, select a system role. All users added to Jira Align through the connector will receive this system role.
    
12. Enter a value between 1 and 30 days in the Logs Retain Days Limit field. This value controls how long Jira Align should save information in the error log on the Jira Align page.
    
    Note: This setting does not change the internal log retention for server-side and Atlassian-visible logs.
13. Select Save. The connector information updates and is deactivated by default; additional Projects and Items tabs display at the top of the slide-out.
14. Activate the connector by selecting Activate on the right of the connector slide-out. When active, the Activate option will change to Deactivate so that the connector can be disabled if desired.

Remove the connector permanently by selecting Delete on the right of the slide-out.

 Configure your projects

1. On the connector slide-out, select the Projects tab.
   
   
2. Switch on the Support Multiple Projects toggle if you would like to map multiple Azure DevOps projects with this single connector. We recommend enabling this option when first setting up the connector, even if you have only one project. This makes future expansion easier.

Important: When this toggle is switched on or off, the connector’s previous project setup is cleared.

If mapping a single project with the connector:

1. Enter the Azure DevOps Project Name for the project you’d like to map.
2. Select a Jira Align program to use as a Default Program if a program cannot be found in the mapping for an item’s area path.

If mapping multiple projects with the connector:

1. Enter a Process Template Name.
   Note: All projects using the same connector must have the same process template name.
2. Add Azure DevOps projects to be synced by entering the project name and then selecting the plus (+) icon to add it to a list of projects to sync.
3. Remove a path from the list by selecting the X icon next to its name.

Regardless of how many projects you’re mapping, continue to configure your projects:

1. In the Program Mapping section, enter the Azure DevOps Value that you wish to map, and select its corresponding Jira Align Program.
2. Add additional programs for mapping by selecting the Add button. You can also delete program mappings by clicking the X icon next to the mapping.
3. In the Work Code Field Name text field, enter the name of the Azure DevOps custom field you’d like to use to set Jira Align work codes for features.
4. Under Team Area Setup, set up your Team Level Mapping by selecting the minimum and maximum team area hierarchy levels in the Minimum Level and Maximum Level drop-downs, respectively.
5. If you’re only mapping a single project with this connector, set a Scope Path. Enter an Azure DevOps Path to define the team sync scope in the text field, and then select a Matching Method in the drop-down:
   1. Begins with - all paths that starts with the specified value will be synced as teams.
   2. Includes - all paths that includes the specified value will be synced as teams.
   3. Exact only - only the path with the specified value will be synced as a team.
      
      If you’re mapping multiple projects, leave the scope path blank.
6. Optionally, add Exclude Paths to denote team area paths, including children, that will not be synced. All items with paths set in the Exclude Paths section will not be synced. For each path you’d like to exclude, enter the name of the path to exclude, and then select the plus (+) icon to add it to a list of excluded paths.
   • If you’re mapping a single project, list every path in the project that you do not want to synchronize (unless using scope path).
   • If you’re mapping multiple projects, it is only necessary to list paths that you want to exclude that are also under paths mapped to programs.
     
     
7. Remove a path from the Excluded Path list by selecting the X icon next to its name.

Note: When syncing a single-project, exclude paths should be within the team area scope set in Scope Path.

1. Under Iteration Area Setup, set up your Release Level Mapping by selecting the minimum and maximum release area hierarchy levels in the Minimum Level and Maximum Level drop-downs, respectively.
2. Set up your Iteration Level Mapping electing the minimum and maximum number of iteration area hierarchy levels in the Minimum Level and Maximum Level drop-downs, respectively.
3. If desired, set a Scope Path. Enter an Azure DevOps Path to define the sync scope in the text field, and then select a Matching Method in the drop-down:
1. Begins with - items associated with all paths that starts with the specified value will be synced.
2. Includes - items associated with all paths that includes the specified value will be synced.
3. Exact only - items associated with the path with the specified value will be synced.
4. Optionally, set a number of Buffer Days to automatically map Azure DevOps iteration paths that have end dates to Jira Align sprints and PIs on a day range.
5. Optionally, add Exclude Paths to denote iteration area paths that will not be synced. All items with paths set in the Exclude Paths section will not be synced. For each path you’d like to exclude, enter the name of the path to exclude, and then select the plus (+) icon to add it to a list of excluded paths.
6. Remove a path from the Excluded Path list by selecting the X icon next to its name.
7. Select Save to save your changes to the connector.

Configure work item sync

A variety of work items can be synced between Azure DevOps and Jira Align, including tasks, defects, stories, and features. On the Items tab, you can toggle syncing of each work item type on and off, as well as configure a variety of other settings.

Defects, stories, and features can be synced forward from Azure DevOps to Jira Align or bi-directionally; tasks can only be synced forward (from Azure DevOps to Jira Align).

Start by configuring general work item settings:

1. Expand the General section at the top of the Items tab.
2. From the Default Sync User drop-down menu, select the user name that will be used by default to synchronize the unassigned items in Jira Align. If you don’t select anyone from the list, the item will stay unassigned.
3. The Add Hyperlink to ADO toggle controls whether Azure DevOps items will contain web links back to their corresponding Jira Align work items. Switch off the toggle to turn off these links in Azure DevOps.
   Note: Jira Align work items will always contain links to their corresponding Azure DevOps item.
4. Switch on the Enable Removed State toggle to assign objects in the Recycle Bin in Jira Align to the Removed state in Azure DevOps, and vice-versa. When the toggle is switched off, the connector will attempt to use ADO’s recycle bin when an item is moved to the recycle bin in Jira Align. If the toggle is switched on, ensure that the Removed state is enabled for all record types that are synchronizing in both directions.
   
5. Optionally, in the Initial Sync Date from ADO field, select a date. The initial connector run will search for items in Azure DevOps that have changed since this date.
   
   Note: This setting applies to combinations of record types and projects individually.  There is a separate timestamp maintained for each item type in each project so that issues encountered with one project or type do not affect other item types in other projects. For example, the search timestamp for a product backlog item in Project X might be this morning, and a product backlog item in Project Y might still be in 2020. This setting can be useful after additional projects and record types are added to the connector configuration after the initial run. Otherwise, changing this setting will not affect the connector unless no items were found in the initial sync.

Next, determine which work items will be synced. To sync a work item:

1. 1. Switch on the toggle next to the work item’s type to turn sync on.
   2. Enter the Azure DevOps work item types to be synced:
      a. For stories, use the Story type mappings section to map Jira Align story types to Azure DevOps work item types. Map Jira Align values on the left to Azure DevOps work items on the right. You can add additional mappings by selecting Add story type mapping at the bottom of the table. Each Jira Align value can only be mapped once.
      If needed, you can remove a mapping by selecting the X icon to the right of a row.
      Notes:
      • When editing story type mappings, keep in mind that any unmapped Jira Align story types will stop syncing with Azure DevOps. This may result in stories remaining in Jira Align, but not updating in Azure DevOps because the mapping was removed.
      • If the connector has been syncing before setting up or making changes to story type mappings, and work items previously only existed in one product (e.g. work items only existed in Azure DevOps), those work items won’t immediately display in the other product. You’ll need to make a change to the relevant work items in either Jira Align or Azure DevOps to trigger a sync. A quick way to do this is to go to Azure DevOps, run a query on all relevant work items, then perform a mass action (e.g. add a tag) to the results. Any action that causes the Azure DevOps last updated date to change will suffice. This will cause those Azure DevOps work items affected to sync to Jira Align.
        b. For all other work item types, enter a single Azure DevOps work item type in the Azure DevOps Item Type field.
   3. Select a Delete Action to determine what will happen to the work items in Jira Align when the associated work items are deleted in Azure DevOps.
   4. For features and stories, enter the name of the Azure DevOps field that syncs with Jira Align acceptance criteria in Acceptance criteria field name.
      Note: In programs that sync with ADO, you’ll be limited to a single acceptance criteria text field in Jira Align since the default ADO acceptance criteria is a text field. If you already have multiple acceptance criteria in Jira Align for work items in these programs, the connector will automatically merge them into a single, formatted text field.
      
   5. For features and stories, fields to map Jira Align custom text input, text area, and single-select dropdown fields will display. Enter the names of the equivalent Azure DevOps fields in the corresponding fields.
      
   6. In the State Mapping (Azure DevOps to Jira Align) section, enter the Azure DevOps Value that you wish to map, and select its corresponding Jira Align State. Optionally, add one or more Other Allowed States in Jira Align for the mapping.
   7. For all items except tasks, in the State Mapping (Jira Align to Azure DevOps) section, enter the Jira Align State that you wish to map. Then, set its corresponding Azure DevOps Value. Optionally, add one or more Other Allowed States in AzureDevOps for the mapping.
      1. Add additional states for mapping by selecting the Add button. You can also delete state mappings by clicking the X icon next to the mapping.
   8. For defects, in the Severity Mapping section, enter the Jira Align Severity that you wish to map. Then set its corresponding Azure DevOps Value.
   9. For stories and features, in the Type Mapping section, enter the Jira Align type that you wish to map to a Azure DevOps Value Area.  Optionally, add one or more Other Allowed Types for the mapping.
   10. For stories, features, and bugs where the sync direction is bidirectional, in the Azure DevOps Field Defaults (Jira Align to Azure DevOps) section, type the Azure DevOps Field you’d like to set a default value for. Then, set the Default Value. If there’s no value already set on the field in Azure DevOps, and no value supplied from Jira Align, the connector will set the Azure DevOps field to the default value.
       1. Add additional field default values by selecting the Add button. You can also delete field default values by clicking the X icon next to the mapping.
          

Authentication methods

PAT (personal access token)

For PAT authentication, you need to generate an access token for the appropriate organization in Azure DevOps first. Read the Authenticate access with personal access tokens for Azure DevOps Services and TFS article to learn how to create personal access tokens to authenticate access. For proper functioning of the connector, select Project and team (read, write, and manage), Work item (full), and Identity (manage) as scopes. Finally, enter your user name (email) and password (your access token) in Jira Align.

NTLM (NT LAN manager)

NTL is used for server authentication. Type a user name, which is a domain name/the user added to the Azure DevOps server, for example, {local/admin}, and a password, which is a password of this user.

OAuth

OAuth is an authentication method that Cloud users can use. First, click Register to register your application with Visual Studio Online. Read more on how to register your app here.

Required fields to fill in are your Company name, Application name, Application website, and Authorization callback URL. For authorization callback URL, use https://{yourinstancename}/privateapi/tfsConfig/oauth/callback/. For proper functioning of the connector, select Project and team (read, write, and manage), Work item (full), Identity (manage), and MemberEntitlement Management (read) as authorization scopes.

After the registration, you will get a generated App ID, Client Secret, Authorized Scopes, and Callback URL. Copy and transfer them to Jira Align. Click Authorize and Get Token.

View logs

On the right of the table on the Azure DevOps Settings page, select the View Logs button to view error logs on the synchronization process. The log captures information on issues that occurred during the sync processes, specifically:

• ID: A unique identification number for the entry.
• Level: The type of issue. Warnings are issues that don’t stop items from copying. Errors are issues that prevent items from copying.
• Message: Detailed information about the warning or error.
• Item type: Name of the type of item where the issue occurred. The name varies based on the direction of the sync process.
• Jira Align Item ID: The work item ID in Jira Align. This may be blank if the item does not exist in Jira Align yet, and the sync fails completely.
• ADO ID: The work item ID in Jira Align. This may be blank if the item does not exist in Azure DevOps yet, and the sync fails completely.
• Date: The date and time when the issue occurred.

Note: In addition to filtering by date and message contents, the table can be filtered by one or more values in the Level, Item Type, Jira Align Item ID, or ADO ID fields. To filter the table:

1. Click the column name.
2. In the list of items, select the checkbox next to one or more options to narrow the filter.
3. The filter criteria appear above the list of items, and the table filters to display items that meet the filter criteria.

To remove a filter:

1. Select the column that contains the filter you want to remove.
2. In the list of items, select the option or options to remove from the filter criteria.

From the Azure DevOps Settings page, you can also view a queue report of recent connector activity. Select the View Queue button to access the Queue Report. This report captures connector processes as it synchronizes batches of 100-200 items, up to 25 batches (6,000 items) per connector run. On the queue report, you can view the following information:

• ADO Project: The Azure DevOps project being synchronized. In multi-project mode, a single connector can synchronize data from more than one Azure DevOps project as long as they are in the same Azure DevOps organization and have the same process template.
• Item Type: The Jira Align work item type being synchronized.
• Last Modified: The date that the connector uses to determine which items to synchronize from Azure DevOps. This is not the timestamp of the last run. Instead, it is the timestamp of the item that was last successfully copied, so it may be earlier than the Sync End timestamp. This timestamp is updated at the end of each batch of 100-200 items.
• Sync Start: The date and time that the connector started the most recent set of batches for the project and work item type.
• Sync End: The date and time that the connector last finished a set of batches for the project and work item type. In the vast majority of instances, if this is blank, it means that this is the record type and project that is currently being synchronized. However, it also can be blank if there was an error during processing and the cycle didn’t complete.
• Initial Count: The count of work items that were found to need synchronization from Azure DevOps, captured at the beginning of the connector run cycle.
• Last Count: The count of the work items that were found to need synchronization from Azure DevOps that was captured at the beginning of the most recent batch of items:
  • If the number is less than 100, then the cycle has likely completed and all of the items have been synchronized.
  • If the number is greater than 200, then the cycle likely included over 25 batches and didn’t finish copying all the items that were ready. This can happen because the cycle started with a large number of items or because additional items were changed by users in Azure DevOps during the cycle. The items will be synced the next time the connector runs.
  • If the number is between 100 and 200, then either of the above could be in play (or both).