VSTS/TFS Plugin

This topic describes the VSTS/TFS Plugin in Digital.ai Release, which integrates with Visual Studio Team Services and Team Foundation Server.

Requirements

• Digital.ai Release 6.1.0 or later
• If you are using Digital.ai Release version 8.5.0 or later, you must use the Release VSTS/TFS plugin version 8.5.0.
• Visual Studio Team Services (VSTS) or Team Foundation Server 2015

Supported VSTS/TFS operations

Work item operations:

• Create new work item
• Retrieve work item
• Update work item
• Update work items by Query
• Query work items

Build operations:

• Tag a build
• Queue new build

Triggers:

• Git commit trigger
• TFVC change-set trigger

Supported authentication types

VSTS/TFS versions	Authentication
TFS 2015	Basic and NTLM authentication types
TFS 2017	Basic, NTLM, and PAT authentication types
VSTS	PAT authentication type
Azure Devops Services	PAT authentication type

For more information, see Authenticate access with personal access tokens for VSTS and TFS.

Set up a VSTS/TFS server

To set up a connection to a VSTS service or your TFS collection:

1. In Digital.ai Release, go to Connections under the Configuration group of the navigation pane, and under the TFS Server, click Add server.
2. Specify a name for this connection.
3. The collection URL field must be set to the full URL pointing to your TFS collection (for example: http://my.tfs.address:8080/tfs/DefaultCollection). Make sure that the collection name is included. For VSTS, insert the URL of your account (for example: https://myaccount.visualstudio.com).
4. Select the Azure Devops Services checkbox if cloud offering is used.
5. Select the authentication type. For:
   • Basic: Complete the username and password fields.
   • NTLM: You must also specify your domain name in the Domain field.
   • PAT: Skip the username field and, in the password field, set your personal access token.
6. If your Digital.ai Release server is using a proxy, specify the necessary values.

Using the work item management tasks

The work item management tasks allow you to perform several operations with work items on VSTS/TFS such as creating new work items, updating existing work items, and retrieving or querying work items.

Create a work item task

This task creates any type of VSTS/TFS work item. The following input properties are available:

• Server: The VSTS/TFS instance to be used
• Team Project Name: The name of the project where the work item will be created
• Work Item Type: The type of work item (Examples: Bug, Product Backlog Item)
• Work Item title: The title of the work item
• Tags: Work item tags
• Fields: Additional fields that should be modified. Each work item in VSTS/TFS is based on multiple fields. Custom fields can be added by a custom work item process template (Standard field examples: "System.AreaPath", "Microsoft.VSTS.Common.Priority"). Each of the available fields can be modified by specifying the field name as a key and the desired value as a value in the fields map. For more information, see Work item field index.

Output properties:

• Work Item ID: The ID of the new work item

Retrieve a work item task

This task retrieves any specified work item and returns all of its fields. To manipulate the output property, use the Script Task or the Release Variable Manipulation Community Plugin.

The following properties are available:

• Server: The VSTS/TFS instance to be used
• Work Item ID: The ID of the work item that you want to retrieve

Output properties:

• Fields: All of the retrieved fields of the work item

Query work items

This task allows you to retrieve multiple work items IDs by specifying a WIQL query. for more information about the WIQL, see Syntax for the Work Item Query Language (WIQL).

To customize the output properties, use the Script Task or the Release Variable Manipulation Community Plugin.

The following input properties are available:

• Server: The VSTS/TFS instance to be used
• Query: Specify a query written in WIQL language

Output properties:

• Retrieved IDs: List of work item IDs that are retrieved by the query

Build operations tasks

Queue new build task

The Queue new build task allows you to queue a build on your VSTS/TFS server.

These input properties are available:

• Server: The VSTS/TFS instance to be used
• Team Project Name: The name of the project where the build definition is set
• Build definition name: The name of the build definition from which you want to trigger a build

Output properties:

• Build ID: Unique identifier of the build run
• Build Number: The assigned value from the build engine based on the build number format option in your build definition
• Build Result: Build run result

note

If the queued build fails, the task will also fail.

Tag a build task

The tag a build task allows you do add one or more tags on your build.

The following input properties are available:

• Server: The VSTS/TFS instance to be used
• Team Project Name: The name of the project where the build definition is set
• Build ID: The ID of the build where to apply the tag(s)
• Tags: A list of strings that are added to the build as tags

Using Triggers

The git commit trigger

If you want your release to be created and started by a commit in a VSTS/TFS Git repository, you can setup this trigger.

The following input properties are available:

• Server: The VSTS/TFS instance to be used
• Project: The name of the project where the Git repository is created
• Repository: The name of the Git repository
• Branch: The branch that should be monitored for the changes

The TFVC changeset trigger

If you want your release to be created and started by a new changeset in a TFVC repository, you must setup this trigger.

The following input properties are available:

• Server: The VSTS/TFS instance to be used
• Project: The name of the project where the associated TFVC repository should be monitored