Introduction

Microsoft supports interacting with the Visual Studio Team Services (Azure DevOps Cloud) and TFS (on-premise) servers via the ReST API. Hence, to configure any of these applications Microsoft Common Adapter can be used.

However, the support for TFS in this adapter is only from TFS2015 versions. To configure any lower versions of TFS, customers are requested to use TFS (or Azure DeveOps Server) adapter.

Supported Authentication

PAT (or) Personal Access Token based Authentication (Not applicable with TFS2015 Servers)

Azure Active Directory Authentication

Supported Entity Types

Bug

Task

Feature

User Story

Issue

Epic

 Test Case

 Test Plan

 Custom Entity / Work Item Types

Supported Functionalities

Sync Fields

Sync Comments

Sync Attachments

Sync Issue Links

Attachment Deletion (Available from the version 2.10.22)

Personal Access Token Based Authentication

PAT or Personal Access Token Based Authentication is supported for both Visual Studio Team Services and TFS2017+ servers. In TFS2015, we do not have an option to enable PAT.

To use this authentication, when trying to configure the application, leave the username field blank and provide the PAT in the password field.

Enable Basic Authentication (on-prem TFS2015 & TFS2017 only)

Visual Studio Team Services

In order to configure Visual Studio Team Services adapter, please ensure that the user credentials that are configured in ConnectALL are enabled with the alternate credentials in Visual Studio.

Please follow the below steps to enable:

1. Login to Visual Studio Team Services online and go to My Security (in some applications security information will be available as part of My profile itself).
   
   
2. Enable the check box under the "Alternate Authentication Credentials" and provide a username and password.

Azure Active Directory Authentication

ConnectALL supports Azure AD authentication. The Azure Active Directory authentication integration involves the following steps:

• Registering the application
  • Registering the ConnectALL URI
  • Creating a secret key for the application 
• Creating a connection in ConnectALL

Registering the Application

1. Go to portal.azure.com
2. Navigate to Azure Active Directory and click App registrations on the left panel
3. Click +New registration to create a new application. The Register an application screen will be displayed. Doing this will help you to create a new application with an Application ID (client ID). Make a note of the details that get generated in this step as they will be needed when you create a connection in ConnectALL
4. Provide a name for your application
5. Under the Supported account types, select the ‘Accounts in this organizational directory only (connectall.com only - Single tenant) option

Registering the ConnectALL URI

In this step, you will provide the ConnectALL URL that includes the connection name that you will be creating in ConnectALL for the interaction.

Tip: While creating the connection in ConnectALL, you must use the same connection name that you have provided here on this screen.

1. Click Authentication under the Manage panel.
2. Under the Redirect URI section, provide the ConnectALL callback URL in the following format: <CONNECTALL_BASE_URL>/oauthcallback/msvststfs/<CONNECTION_NAME> 
   In this format, 
   1. CONNECTALL_BASE_URL is ConnectALL URL (http://localhost:8080/connectall)
   2. CONNECTION_NAME is the connection name you will be creating in the ConnectALL application
      
3. Click Register.

Creating a Secret Key 

1. Click the Certificates and Secrets option on the left panel.
2. Click +New client secret under the Client secrets section to create a secret key.

Please make a note of the secret key as it will be needed later and it will not be displayed again.

Configuring Permissions for the Application

1. Click API permissions from the Manage panel
2. Click Add permissions under the Configured permissions The Request API permissions screen will be displayed
3. Click the APIs my organization uses tab and search for ‘Azure DevOps’
4. Select the ‘Azure DevOps’ option
5. Click the User Impersonation permission to select and add it
   
   
   
   
6. Click the ‘Grant admin consent for connectall.com’ option
   
   
   
   
7. Click the ‘Overview’ option in the left panel and copy the Application (client) ID, Object ID, and Directory (tenant) ID. Once you save, it will be displayed as shown below
   
   

Once you have completed the above procedures, the application is ready to be integrated with ConnectALL. The next and final step is to create a connection in ConnectALL.

Creating a Connection

1. Login to ConnectALL. Login to Azure DevOps in the same browser.
2. Click Connections from the top navigation bar
3. Click Add Connection to add a new connection. The below screen will be displayed. 
   
   
   
   
   
4. Select Authentication type as OAuth1.
5. Enter a Connection Name, URL, Time Zone, tenant ID (that you would have noted down while registering the application in the Azure DevOps portal). Make sure that the connection name is the same that you used to configure in the Redirect URI section. 
6. Enter the Client ID and Client Secret (from the AzureDevOps portal) and click Save and Update. The Authorize Connection screen will be displayed. 
7. Click Authorize. When you do, Azure DevOps authorizes the connection and sends the authorization code to ConnectALL. A message to confirm the authorization is displayed. 
8. Click Proceed. When you do, the access token will be received from the application and the confirmation will be displayed as shown below. 

You have integrated Azure DevOps Active Directory services for authentication. 

Configuration

ConnectALL Microsoft Common Adapter will allow configuring both Visual Studio Team Services and TFS2015+.  For Visual Studio Team Services, the "Team Project" field is not a mandatory field for input. For TFS, the user has to provide the Team Project Collection detail. If not provided, by default the team project collection would be considered as "DefaultCollection".

The other configurations like "Metadata" and "Field Configuration" will remain the same.

Description Field

Please note that when images are added as part of the Description / Repro Steps / Comments field, sync of the image will not be supported by ConnectALL and any further update on the record may cause sync issues. Hence, we would advise not to attach images as part of these fields in VSTS/TFS. 

Also, the support for 'block quote' is available only for the 'Description' field and not for the 'Comments' field.

Jira-Visual Studio Team Services / Jira-TFS2015 Epic Link Support

To synchronize Jira-VSTS/TFS Epic, create an application link in ConnectALL by choosing the entity type as Epic. On the Epic application link field mapping, map the "Epic Name" field of Jira with an "Epic Name" custom field of VSTS/TFS as shown in the screenshot below. This is a mandatory field mapping for an Epic to sync successfully.

To synchronize the linked bugs/stories/tasks under the Epic, create a separate application link in ConnectALL for the relevant entity types between Jira and VSTS/TFS. Now map the Jira "Epic Link" field with the "Epic Link" custom field of VSTS/TFS as shown in the screenshot below. This is a required field mapping to create the linking between the Epics and the linked items.

Microsoft Common Adapter - Remedy 8.1 - Release Management Sync

To synchronize the releases from Visual Studio Team Services/TFS <==> Remedy 8.1/9, select the metadata information as displayed below and configure the fields.

Microsoft Common Adapter Email Reconciliation Logic 

The email field which at present received in the JSON response will constitute the DOMAIN NAME and EMAIL ID. Since this retrieval owes to be RAW and doesn't recommend the usage of the same as it is for further processing, ConnectALL application code has introduced a smart logic to segregate the email ID alone. In that case, below are the steps to be configured for apt functioning:

•  Configure the impacted label name in ConnectAll Properties - Say System.AssignedTo is one such impacted field, this would be configured in ConnectAll.properties as
                               
                                       vsts.email.reconcile.fields=System.AssignedTo
  
  
• If there is more than one field impacted, it should be configured with '~' separator.

         Note: The above fix is limited to the on-premise version of ConnectAll for now.

Microsoft Common Adapter Test Management

Test Case

Test Case entity type when mapped, then the adapter can sync Test Cases from any application. To synchronize Test Steps (along with Test Case), then map the following Steps field with the corresponding field on the other application.

Note: Any test step edited will be created as a new test step instead of updating the existing test step

Test Plan

Test Plan entity type when mapped, then the adapter can create a Test Plan in VSTS/TFS2015+. Test Plan can be created for a specific Area and Iteration Path and within a start and end date.

For Test Plan to work, please ensure that ms_testplan_field.json is available under MULE_HOME/conf directory.

PS: Test Suite create/update support is not available.

Test Instance

For ConnectALL to link a Test Case with a Test Plan and to update the Test Run result (outcome) against the Test Case, Test Instance entity type should be mapped and the following field mappings are mandatory.

• test_sequence - if mapped, this will ensure that the test cases are ordered correctly under the Test Plan
• test_id - to identify the test case id (from the Test Case application link mapping) to link to the corresponding plan
• plan_id - to identify the test plan id (from the Test Plan application link mapping) to identify the test plan against which the changes is required
• test_type - source application test case entity type (For example: When the ALM is mapped then the test_type constant should be "test"
• plan_type - source application test plan entity type (For example: When the ALM is mapped then the plan_type constant should be "test-set"
• outcome - if mapped, this will update the test run result/outcome against each Test Cases

Test Instance

• Only uni-direction sync is supported for Test Instance i.e. All the above points mentioned can be supported in VSTS/TFS2015+ applications only from any source application, vice-versa is not supported.
• The minimum application link scheduler configuration recommended is every 3 minutes or higher.

Issue Linking Limitation in Azure DevOps

In an Azure DevOps record, when you are making modifications that involve issue linking settings alone, the changes will not be updated in the other application when ConnectALL synchronizes that record. However, when you modify the issue linking settings along with other changes in an Azure DevOps record, the update will reflect the issue linking settings change when the record is synchronized. This is due to a limitation in the Azure DevOps API, wherein an individual issue linking settings change is not timestamped. Due to this, ConnectALL will not be able to identify the modified record and an update will not reflect the issue linking changes. On the other hand, if any other changes are also done along with the issue linking settings, Azure DevOps timestamps those changes. This enables ConnectALL to read the changes, and the update will reflect the changes (in the issue linking settings) when the record is synchronized.

Time Difference Configuration

To know how to calculate the time difference, and configure it in the ConnectALL UI,  read the topic Time Difference Configuration.