Microsoft Azure DevOps connector powered by MuleSoft

The Azure DevOps connector, powered by MuleSoft provides a connection between the MuleSoft connector engine and Microsoft Azure DevOps. Use the connector to integrate Azure DevOps with any third-party application and perform different activities. You can add activities to create, query, and update work items and create and query work item comment. The activities can be used either as a source or a target within operations defined for the integration. 

Before you begin

• Make sure users have the required permissions to create and modify work items in Azure DevOps.
• You have installed Anypoint Studio version 7.8.0.
• You have the required access to use Anypoint Studio.
• You have the Organization ID and user name and password for your MuleSoft account.
• You have Apache Maven installed and have working knowledge of it.

Supported product versions

Configuring the Azure DevOps connector in Anypoint Studio

Use the Anypoint Studio to configure the connector and then publish it to the cloud platform for distribution. You can design and update your application, properties, and configuration files for the connector. 

Complete the following procedures to configure the connector in Anypoint Studio:

1. Download and add the connector to MuleSoft Anypoint Studio
2. Create a MuleSoft project and add the connector to the project
3. Create the files required for the connector configuration
4. Configure the connector

After you complete the configuration, you define a workflow and add the following activities:

Task 1: To download and add the connector to MuleSoft Anypoint Studio

1. Log in to BMC Support by using your BMC support ID.

2. Download the Azure Devops Connector 2021-06-01 file from the BMC Helix iPaaS for MuleSoft 21.3.00 page on the Electronic Distribution Site.

3. Extract the .jar file to a local directory.

4. From the command prompt, enter the following commands:

   cd <jarFilePath>

   Then, enter:

   mvn install:install-file "-Dfile=mulesoft-ms-azuredevops-connector-1.0.0-mule-plugin.jar" "-DgroupId=org.mule.bmc.connector.ms.azuredevops" "-DartifactId=mulesoft-ms-azuredevops-connector" "-Dversion=1.0.0" "-DgeneratePom=true" "-Dpackaging=mule-extension"
5. Then, navigate to the C:\Users\<userName>\.m2\repository\org\mule\bmc\connector\ms\azuredevops\mulesoft-ms-azuredevops-connector\1.0.0 directory and paste the downloaded .jar file in this directory. 

After you install the connector, it is available in the Mule Palette of MuleSoft Anypoint Studio.

 Task 2: To create a MuleSoft project and add the connector to the project

1. Log in to Anypoint Studio.
2. Select File > New > Mule Project.
3. Enter a name for your project and click Finished. 
4. From the Mule Palette, click Add Modules. 
5. From the list displayed, drag and drop Azure DevOps to the palette.
   The Azure DevOps connector is listed in the Mule Palette for your project. 

6. On the Package Explorer tab, open the pom.xml for your project and verify that the following dependency is included in the file:

   <dependency>
   <groupId>org.mule.bmc.connector.ms.azuredevops</groupId>
   <artifactId>mulesoft-ms-azuredevops-connector</artifactId>
   <version>1.0.0-SNAPSHOT</version>
   <classifier>mule-plugin</classifier>
   </dependency>
7. To save your updates, click the Save icon on the application toolbar.

Task 3: To create the files required for the connector configuration 

1. Create a properties file for the project.
   1. Right-click the src/main/resources branch and select New > File.
   2. Enter a name for the file; for example: project.properties.

   3. Enter the following variable values in the file and save it: 

      • hostName — Enter the URL of the Azure DevOps instance; for example, https://hostname-dsom-platform.trybmc.com/.

      • personalAccessToken — Enter the Personal Access Token generated for the Azure DevOps instance organization. For more information about generating personal access tokens, see Use personal access tokens.

      • organization — Enter a name of the organization defined for the Azure DevOps instance.
      • version — Enter the version of the Azure DevOps instance.

      These variables are used to configure your connector.

2. Create a configuration file to define the connector configuration:
   1. Right-click the src/main/mule branch and select New > Mule Configuration File.
   2. In the General Information dialog box, enter config.xml in the Name and click Finish.
   3. Click Global Elements and then click Create.
   4. Select Global Configurations > Configuration Properties.
   5. On the General tab, select the project.properties file that you created and then click OK.
3. To save your updates, click the Save icon on the application toolbar.

Task 4: To configure the connector 

1. From the Package Explorer pane, double-click the <projectName>.xml file.
2. To run the workflow when specific conditions are met, configure HTTP Listener as the source: 
   
   1. From the Mule Palette, select HTTP > Listener. 

   2. Select the Listener element, and add the following details: 

      Field name	Actions
      Display name	Enter a short display name for the source.
      Connector configuration	Click the + sign to add the connector configuration and add the following details: Name—Enter a name for the configuration. Protocol—Select HTTP or HTTPS. Host—Select the default value. Port—For HTTP, enter 8081 and for HTTPS, enter 8082. Important: If the selected port is in use, enter a different value. Base path—Enter a path for the flow. Listener interceptors—Select None.

   3. To verify the configuration values, click Test Connection. 
3. Define the connector configuration.
   1. From the Mule Palette, select Azure DevOps, and drag an Azure DevOps activity to the Message Flow tab. 
   2. On the Message Flow tab, select the Azure DevOps activity.
   3. To define the connector configuration, in the Basic Settings section, click the + icon for Connector configuration.

   4. Enter the following variables defined in the project.properties file in Task 2:

      Important

      Create a properties file for the proxy configuration and add the variable values instead of the actual values.

      Field name	Value
      Name	Name for the connector configuration.
      General tab
      Host Name	${hostName}
      Personal Access Token	${personalAccessToken}
      Organization	${organization}
      Version	${version}
      Proxy Config
      Host	URL of the proxy server
      Port	Port number for the proxy server
      Username	User name to connect to the proxy server
      Password	User's password to connect to the proxy server
      NTLM Domain	Domain name of the NT LAN Manager (NTLM) active directory server

   5. To verify the defined configuration values, click Test Connection.
   6. Click OK.
   7. To save your updates, click the Save icon on the application toolbar.

The connector configuration is used for all the Azure DevOps activities in your flow. After you set up the project configuration files and configure the Azure DevOps connector for MuleSoft, you can create flows between Azure DevOps and other applications.

Workflow examples

A typical flow requires the source configuration, for example HTTP > Listener, a request Transform Message that writes information to the Azure DevOps operation, the activity configuration, a response Transform Message that receives the information from the activity and a final logger element to write data to your target application. 

After you create the workflow, run the project (right-click project name and select Run Project As > Mule Application), and then run the flow by using an application like Postman.

The following images show sample flows created for the Azure DevOps operations:

Create Work Item activity

The Create Work Item activity gathers the data to create a new work item at the Azure DevOps endpoint. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Create Work Item activity

1. From the Mule Palette, select Azure DevOps > Create Work Item. 
2. Drag the Create Work Item option to the Message Flow tab. 

3. Select the Create Work Item brick and on the Create Work Item tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Input payload	To define specific field mappings for the activity, click and add your payload data. For example: {  "type": "Epic",  "fields": {  "System.Title": "WorkItemEpic"  } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Create Work Item Comment activity

The Create Work Item Comment activity gathers data for a work item at the Azure DevOps endpoint. It is intended to be used as a source in a workflow. 

To configure the Create Work Item Comment activity:

1. From the Mule Palette, select Azure DevOps > Create Work Item Comment. 
2. Drag the Create Work Item Comment option to the Message Flow tab. 

3. Select the Create Work Item Comment brick and on the Get work item tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Projects	Name of the Azure DevOps project where the work item exists
   Work Item ID	ID of the work item record to which the comment has to be added
   Request payload	To define specific field mappings for the activity, click and add your payload data. For example: {  "text": " Create comment in WorkItem" } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Add attachment activity 

The Add attachment activity adds an attachment at the Azure DevOps endpoint.

To configure the Add attachment activity:

1. From the Mule Palette, select Azure DevOps > Add attachment. 
2. Drag the Add attachment option to the Message Flow tab. 

3. Select the Add attachment brick and on the Add attachment tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Projects	Name of the Azure DevOps project where the work item exists
   Work Item ID	ID of the work item record to which you want to add the attachment
   Add attachment payload	To define specific field mappings for the activity, click and add your payload data. For example: { attachments: [{ fileName: "helix.zip", areaPath: "LakshmiMulesoft", uploadType: "Chunked", comment: "Test comment1", fileContent: "UEsDBBQAAAAAAB2J91L5WLEzHgAAAB4AAAAQAAAAaGVsaXgvc2FtcGxlLnR4dC0tLSFAIEhlbGxvIEF6dXJlIERldk9wcyAhQC0tLVBLAQIUABQAAAAAAB2 J91L5WLEzHgAAAB4AAAAQAAAAAAAAAAEAIAAAAAAAAABoZWxpeC9zYW1wbGUudHh0UEsFBgAAAAABAAEAPgAAAEwAAAAAAA==” }, { fileName: "saas.txt", areaPath: "LakshmiMulesoft", uploadType: "Chunked", comment: "Test comment2", fileContent: "IUAxMjMNCkhlbGxvIEJNQyBTb2Z0d2FyZQ==” ]} } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Get attachment activity 

The Get attachment activity retrieves an attachment at the Azure DevOps endpoint.

To configure the Get attachment activity:

1. From the Mule Palette, select Azure DevOps > Get attachment. 
2. Drag the Get attachment option to the Message Flow tab. 

3. Select the Get attachment brick and on the Get attachment tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Projects	Name of the Azure DevOps project where the work item exists
   Payload	To define specific field mappings for the activity, click and add your payload data. For example: {  workItemId: [2,4]  } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Query Work Item activity 

The Query Work Item activity searches work item data at the Azure DevOps endpoint. It is intended to be used as a source in a workflow. 

To configure the Query Work Item activity:

1. From the Mule Palette, select Azure DevOps > Query Work Item. 
2. Drag the Query Work Item option to the Message Flow tab. 

3. Select the Query Work Item brick and on the Query Work Item tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Projects	Name of the Azure DevOps project in which you want to search for the work item
   Input payloads	To define specific field mappings for the activity, click and add your payload data. For example: {  "ids": [22,27]  } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Query Work Item Comments activity 

The Query Work Item Comments activity searches for the work item data at the Azure DevOps endpoint. It is intended to be used as a source in a workflow. 

To configure the Query Work Item activity:

1. From the Mule Palette, select Azure DevOps > Query Work Item Comments. 
2. Drag the Query Work Item Comments option to the Message Flow tab. 

3. Select the Query Work Item Comments brick and on the Query Work Item Comments tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Projects	Name of the Azure DevOps project in which you want to search for the work item
   Work Item ID	ID of the work item record to which the comment has been added
   Input payloads	To define specific field mappings for the activity, click and add your payload data. For example: {  "top": 1,  "includeDeleted": true,  "order": "DESC",  } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.

Update Work Item activity

The  Update Work Item activity searches work item data at the Azure DevOps endpoint. It is intended to be used as a target in a workflow. 

To configure the Update Work Item activity:

1. From the Mule Palette, select Azure DevOps > Update Work Item. 
2. Drag the Update Work Item option to the Message Flow tab. 

3. Select the Update Work Item brick and on the Update Work Item tab, enter the following configuration details:

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Input payload	To define specific field mappings for the activity, click and add your payload data. For example: {  "type": "Epic",  "id": 1,  "fields": {  "System.Title": "LakshmiupdateEpic"  } } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

4. To save your updates, click the Save icon on the application toolbar.