Azure DevOps Integration: Setup Guide

Useful Links For Azure DevOps Integration Setup

• Automation Rules Library
• JS mappings Library
• Additional Feature Toggles List
• Dev Portal: Work Sharing API documentation, how to write JS mappings, comparators and dynamic routings
• How to validate the data quality
• How snapshot service work for integrations
• Azure DevOps Integration End User Guide
• Tips & Tricks

POC / Setup Pre-requisites

Enable Azure DevOps integration for account with feature toggles: WorkSharing:AzureDevOps:UI and  WorkSharing:UI (ask Targetprocess Technical Support for assistance)

For a basic test from a customer side we need

1. Azure DevOps Service User and his personal access token to authorize all actions from Targetprocess in Azure DevOps projects. This user name will show in History as an author of all changes applied by Targetprocess.
   It's recommended to have a dedicated service user for Targetprocess integration that will not be used by other actiors to modify Azure DevOps data. Updates, applied by service user will not be synced back to Targetprocess to avoid unwanted data loss.
2. Test Project in Azure DevOps instance and URL to its organization
3. Azure DevOps APIs must be available for Targetprocess.
4. Whitelisting of Targetprocess IPs may be required on the customer side. The general process is the following:
   The range is available at https://community.ibm.com/community/user/apptio/blogs/apptio-community-member/2023/01/16/targetprocess-public-ips-range?CommunityKey=55a3712d-1835-4ec2-bcd7-603e88cd9dd2
   If a customer doesn’t have access to the community yet, they request access here: https://community.apptio.com/home/request-community-access A customer whitelists the entire IP range. Single IPs are no longer provided. A customer is subscribed to this page (Follow button) When IP is about to be changed - the support team modifies the IP range on the community page Subscribed customers receive notification and add this new IP as well

Important To Know Before Integration Setup

1. Initial import from/to Azure DevOps can be a reason of email spam, which could be avoided. During the import integration creates a comment in Azure DevOps work item with the back link to a related Targetprocess entity. If Azure DevOps is configured to send email notifications on new comment or new issue, consider disabling either temporarily notifications in Azure DevOps or the feature toggle that adds a link to Targetprocess entity as a comment in Azure DevOps during the import. Enable this function after import, or map Targetprocess entity link into Azure DevOps custom field. WorkSharing:Linking:SkipComment
2. Delete operation sync is disabled by default on all clusters and feature toggle WorkSharing:DisableDeleteOppositeEntity is turned ON. The same toggle works for both integrations, Jira and Azure DevOps. If you have Jira with custom delete behavior implemented using Automation Rules, then for Azure DevOps integration it causes a problem.
   Delete can be customized with a separate automation rule reacting on a delete event webhook. In Azure DevOps integration this is possible if only webhooks setup is in manual mode, otherwise on each profile update webhooks for integration will be updated to listen to ‘delete issue’ even. And separate webhook will not help to customize entities delete in Targetprocess.
3. Some fields can not be synced one way only

• Actions like Delete and Convert sync bidirectionally when feature toggle WorkSharing:DisableDeleteOppositeEntity is enabled. Delete customization for Azure DevOps integration is not possible in case of multiple projects in sync and automatical webhooks setup. It means, Jira integration for that account will also sync delete bidirectionally with no way to customize it in 2023.
• Mapped and linked collections and relations sync bidirectionally and that could not be set up to sync one way yet. For example, Azure DevOps Features mapped to Features, Stories to User Stories (child collections) and all other types as regular Relations. It is currently not possible to limit relations sync direction and sync only stories from Targetprocess and bugs only from Azure DevOps Relations sync both ways as soon as they pass filter in project routings.

4. Batch actions “Pull from Azure DevOps”, “Push to Azure DevOps”, and “Unlink” are not available from Targetprocess UI. Batch pull/push for the whole profile is supported in profile settings available for Admins only. Also batch pull and push is supported in “Data validation report”.

5. “Create Date” of Azure DevOps issues cannot be synced into “Creation date” field of Targetprocess entities.

Integration setup is available for Targetprocess Administrators in Settings > Integrations
Integration profile defines all rules for synchronization:
• Target projects
• Work item types,
• Fields and sync direction
• Additional transformations (JS mappings), when needed

Project Routings

Routings define conditions which must be fulfilled to enable the import from Azure DevOps or Targetprocess. Here you match projects and add filters to define when the work must be imported and if this must be an automatic or manual operation.
Simply saying Routings define if you see ‘Push to Azure DevOps’ button in an entity view ‘Synced Work’ tab and can push or pull item from Azure DevOps. As soon as issue is imported, routings do not affect further synchronization. Sync is regulated by Mappings.
If an issue was pushed to Azure DevOps to a Project A, and then routings were updated to exclude Project A from further synchronization, it means that you will not be able to import new work items to/from this project. But those issues that were linked with the previous routing configuration will proceed to sync as long as types and fields mappings are valid.

Static Routings

Static routings are used in simple and straight forward cases when we can map Targetprocess project to Azure DevOps project with some filter and define the rules of data import.

Auto-Push / Auto-Pull

Auto-push

Enables automatic push of Targetprocess entities as soon as they are created or modified and pass the filter in routings. Entity is pushed to Azure DevOps as a new work item.
If you want to link Targetprocess entity to an existing Azure DevOps issue, then in order to see the ‘Push to Azure DevOps’ > ‘Link to existing’ menu auto-push must be disabled in routings.

Auto-pull

We recommend to have auto-pull always enabled. Considering you have corresponding webhooks added and enabled in Azure Devops, then all issues that pass filters will be added to Targetprocess within several minutes.

Dynamic Routings

This is a JS code for setting conditions for more complicated cases, when target project can be different depending on the values of certain fields or you want to pull from Azure DevOps only those entities whose parent is shared with Targetproces. See code example

Entity Types And Fields Mapping

Entity Types Mappings

Synchronization of such Targetproccess entities as QA Area (Test Cases, Test Run), Project, Team, Team Iteration is not supported.
Azure DevOps like Area Path, Iteration Path, Team can be synced as fields, but not as objects including their additional properties. New value of this field can be created in TArgetprocess if missing, but update cannot be synchronized. It means, if you rename area path node that renames some team, then for Targetprocess it will be totally new value and new team will be created automatically on the next sync.

Entity Fields Mappings

1. Effort. Effort field is a calculated field in Targeprocess. Without disabling effort calculation and redefining its calculation with metric, it will regularly update automatically to match Effort Completed and ToDo. Therefore, Effort could be mapped one-way only, to Azure DevOps. But it is not recommended to pull any numbers from Azure DevOps to Targetprocess Effort field. To calculate Effort, use Role Efforts fields and total effort will be calculated automatically and correctly based on the effort of the responsible assignees.
2. Created Date in Targetprocess cannot be mapped and set for issues pulled from Azure DevOps. First, integration creates an empty issue, and then applies fields values. Created Date can be applied only at the moment of creation, not later. Such change would affect performance, so we suggest mapping Azure DevOps Creation Date to Targetprocess date custom field.

• ID to Custom Field
• Custom mapping of drop-downs with different values.
  You can find all JS samples in our public repository

We add new generic mappings as soon as they appear.

See an example of advised fields mapping.

Red color just grabs an attention that some field is selected several times. It supposes that JS mapping must be added to extend default behavior. Multiple mapping of the same field to different fields using only default mappings most likely mean logical error and must be revisioned.

Note: Constanta ‘Set value as default’

It’s possible to set up profile so that one field was populated always with a constant value. That value overwrites on every full entity sync of all its fields – ‘Pull Updates’. It will not work for the use cases, when value needs to be sent only once during the initial import.

Relations

It is possible to map and sync relations between two Azure DevOps issues to Targetprocess.
If you navigate to Relations tab of the profile and match the relations, they will start syncing and appear in Relations tab in any shared entity

For example, with relations mapping as above, zure DevOps Feature has a ‘Duplicate Of’ type link to another Feature:

In that case ‘Duplicate’ outbound relation will be added between corresponding Targetprocess items:

Delete & Convert

Current limitations:

1. For now it is impossible to customize delete in some profiles or tools and some leave to use default logic.
2. Delete customization in Azure DevOps with auto-webhooks setup is not possible.
   In case you want to customize delete for Azure DevOps integration profile, you need to switch profile’s webhooks to manual setup mode.

To customize delete you disable delete event webhook for integration profile; and set up new webhook with a different Targetprocess callback URL that you will use in automation rule.

Automation Rule can customize delete (and convert) performed in Azure DevOps.
Example of the rule in the public repository.

Area Path and Iteration Path Sync

Read here how we suggest mapping and syncing Area and Iteration Paths to Targetprocess.
Library of JS mappings for Azure DevOps Integration

Import from Azure DevOps

Initial Import

Initial import from Azure DevOps to Targetprocess can be done by Targetprocess Administrator only as he has access integration profile.
Import from Azure DevOps brings all issues, selected with the provided WIQL filter, if they match profile setup, to Targetprocess. As soon as the issue is imported, all its mapped fields, collections and relation start to import to Targetprocess automatically then. And that is how you can import the work hierarchy starting from the top parent item imported.

When WIQL query is ready, you can test it with the ‘Preview’ button and see how many issues were detected and will be imported.

In such case you can change the integration profile settings in a new tab and then retry the import from this screen.

Import as batch ‘Pull Updates’

Integration User Type

Users with enabled property ‘IsIntegration’ are available for all operations as regular Targetprocess users: assign to work, filter work by users, etc. The difference between regular and integration users is that the last cannot log in to Targetprocess.
Integration users are created automatically by integratio, when a user email in the assignments is met and no match is found among existing Targetprocess users.
This type of users, if not added by Integration services, then can be added by Targetprocess technical support upon request and user license agreement.
License counts Integration users separately from regular users. Currently a total of integration users can be found in the Account > Licenses page.