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:
- In Digital.ai Release, go to Connections under the Configuration group of the navigation pane, and under the TFS Server, click Add server.
- Specify a name for this connection.
- 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). - Select the Azure Devops Services checkbox if cloud offering is used.
- 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.
- 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
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
