Synchronizing incidents with Azure DevOps work items via BMC Helix iPaaS, powered by MuleSoft

As an administrator, you can integrate BMC Helix ITSM with Microsoft Azure DevOps to synchronize BMC Helix ITSM incidents with Azure DevOps work items.

BMC Helix Multi-Cloud Broker, along with BMC Helix iPaaS, powered by MuleSoft, provides an out-of-the-box integration template that you use to integrate BMC Helix ITSM with Azure DevOps. You configure the integration in BMC Helix Multi-Cloud Broker and deploy the integration template to the BMC Helix iPaaS, powered by MuleSoft environment.

The following image gives an overview of the capabilities that this integration supports:

Important

The BMC Helix ITSM incident and Azure DevOps work item integration is available only with the cloud version of Azure DevOps.

This integration provides the following capabilities:

Use case

BMC Helix ITSM to Azure DevOps

Azure DevOps to BMC Helix ITSM

Create tickets

Creates a work item in Azure DevOps for an incident created in BMC Helix ITSM

Creates an incident in BMC Helix ITSM for a work item created in Azure DevOps

Synchronize updates

Updates configured field values in an Azure DevOps work item from updates in the BMC Helix ITSM incident

Updates configured field values in the BMC Helix ITSM incident from an Azure DevOps work item

Synchronize comments

(with attachments)

Adds a comment to an Azure DevOps work item from a worklog in a BMC Helix ITSM incident

Adds a worklog to the BMC Helix ITSM incident from an Azure DevOps work item comment

BMC Helix ITSM to Azure DevOps data flow

The following image gives an overview of the data flow for creating or updating a work order in Azure DevOps from a BMC Helix ITSM incident:

Azure DevOps to BMC Helix ITSM data flow

The following image gives an overview of the data flow for creating or updating a BMC Helix ITSM incident from a work order in Azure DevOps:

Before you begin

You require the following items to successfully set up and use this integration:

Required versions	BMC Helix ITSM version 20.08 and later Azure DevOps cloud version
Authentication and permissions	Administrator access to BMC Helix Innovation Studio, BMC Helix Multi-Cloud Broker, and BMC Helix ITSM to run this integration Administrator access to the Azure DevOps account and the Azure DevOps Personal Access token Access to the Azure DevOps organization Basic Access to the Azure DevOps project
MuleSoft Anypoint platform subscription	A valid MuleSoft Anypoint platform license Important: BMC provides pre-build integration templates for the MuleSoft platform, targeting common integration use cases for BMC products. To obtain a MuleSoft platform license, contact MuleSoft support.
Application registration	Set the Process setting for the project to Agile
Webhooks	Microsoft Azure DevOps webhooks that are created one at a time All the BMC Helix Multi-Cloud Broker webhooks that are created at once or one webhook that is created at a time

Task 1: To configure the integration

Log in to BMC Helix Innovation Studio.
On Workspace, click Multi-Cloud Broker.
To launch BMC Helix Multi-Cloud Broker, click Visit Deployed Application.
Tip

You can access BMC Helix Multi-Cloud Broker directly by entering the URL https://hostName:portNumber/helix/index.html#/com.bmc.dsm.mcsm/login and logging in as a tenant administrator.
Click Settings .
Select Start Here > Quick Configuration Guide.
The Quick Configuration Guide page is displayed.
On the Step 1: Choose configuration tab, perform the following steps:
1. From the Choose configuration list, select Helix iPaaS (powered by MuleSoft).
2. Under DevOps Integration, select Between ITSM Incident and Microsoft Azure DevOps.

In the Step 2: Perform configurations tab, perform the following steps:

Add an operating organization, if you have not already done so.
Add Azure DevOps as the vendor organization, if you have not already done so.

To add vendor metadata for Azure DevOps, click Map vendors, and perform the following steps:

On the Map Vendors page, click Map Vendor.

Complete the fields as described in the following table:

Field	Action
Description	Enter a description for the Azure DevOps vendor metadata configuration.
Ticketing Technology Provider	From the list, select Azure DevOps.
(Optional) Instance Name	If you are using multiple instances of Azure DevOps, enter the instance name that you are using to identify it.
Add Mapping	After you select the ticketing technology provider, click Add Mapping. BMC Helix Multi-Cloud Broker displays the default values in the Instance URL field and the Display Field Mapping section.
InstanceURL	If you have clicked Add Mapping, this field is auto-populated. Update the URL and replace the Azure DevOps server with the correct host name.
Vendor Field Mapping	Do not update the default mappings.
Display Field Mapping	By default, the basic Azure DevOps fields are mapped in this section. If you want to map additional fields to be displayed in the BMC Helix ITSM UI, add the relevant mappings by clicking .
Enable Local ITSM Communication	By default, this toggle key is enabled. If you want to use BMC Helix Integration Service as the underlying integration platform, disable this toggle key.
Resolve Incident Ticket When Vendor Closes It	By default, this toggle key is enabled so that when a Azure DevOps work item is closed, the corresponding BMC Helix ITSM incident is also closed. You can disable the toggle key, if required.
Integration Platform	From the list, select MuleSoft.

Click Save.

To fetch incidents from BMC Helix ITSM, click Define filter criteria to fetch records from ITSM to Helix Multi-Cloud Broker for incident, and perform the following steps:
1. To select the filter criteria, click Advanced filter.
2. Select the filters from the available fields, and click Next.
  The query filter expression is displayed. By default, the AND qualifier is applied when you select multiple filter criteria.
3. To change the qualifier for your filters, update the query, and then click Save.
  Important
  
  Make sure that you enter a valid query with available fields and values.
4. Click Close.
  When an incident matches the operation and filter that you have selected, the system fetches that incident to BMC Helix Multi-Cloud Broker.
In the Configure Azure DevOps integration section, refer to the configuration steps that are listed and select the check boxes as you complete each step.
Click Save.

Task 2: To download and deploy the integration template project

Download the Sync BMC Helix ITSM incident and Azure Devops workitem 2022-03-01 file.
Log in to MuleSoft Anypoint Platform and select Runtime Manager.
To configure your integration template, click Deploy application.

To select the .jar file that you downloaded, and enter project details, on the Runtime tab of the Deploy Application page, select the following values:

Field name	Action
Application Name	Enter a unique name for your application.
Deployment Target	Select the space for deploying the application; for example, CloudHub.
Application File	Select Choose File > Upload file, and select the Integration template .jar file.
Runtime tab
Runtime version	Select the MuleSoft runtime version used to develop the application.
Work size	Select a core size for your application. The core size defines resource allocation for your application and impacts performance. For more information about worker size, see Cloudhub workers .
Workers	Select the number of dedicated instances of Mule for the application. Deploying your application with more than one worker balances incoming load across allocated worker nodes. It also provides a backup if any of the worker nodes is not responding.

To add the template configuration values, on the Properties tab of the Deploy Application page, add the following values:

Key	Action
Anypoint Studio properties
anypoint.platform.config.analytics.agent.enabled	To enable or disable Anypoint Platform analytics data, set this value to true. By default, the value of this key is false.
Kafka properties (Mandatory only if you are using Kafka)
kafka.use	To enable the Kafka queuing mechanism for incoming Webhook requests for fault tolerance, set the value to true. By default this value is set to false.
MuleSoft API webhook properties
api.integrations.name	Enter the name of the API that is created in BMC Helix iPaaS, powered by MuleSoft to receive BMC Helix Multi-Cloud Broker webhook requests. Use the following syntax to enter the API name: `BHIP_<APIName>` For example, BHIP_CreateIncident.
api.integrations.profile.username	Enter the user name for the Basic type of authentication to configure the webhook.
api.integrations.profile.password	Enter the password for the user name that you provided.
Microsoft Azure DevOps properties
vendor.connector.url	Enter the Azure DevOps instance URL in the following format: `[http/https]://[host name and port]/services/Soap/u/[version number].`
vendor.connector.api.version	Enter the Azure DevOps API version. The template supports Azure DevOps API versions 5.0 and later.
vendor.connector.project	Enter the name of the Azure DevOps project, where the work items should be created.
vendor.connector.personal.access.token	Enter the personal access token for Azure DevOps if the user requires it.
vendor.connector.protocol	Enter HTTPS.
vendor.property.project.key	Enter the project key of the Azure DevOps project, where the work items should be created.
vendor.property.webhook.name	Enter the name to be used for the Azure DevOps webhook being created; for example, 'Escalated'.
BMC Helix Multi-Cloud Broker properties
mcb.connector.protocol	Enter HTTP or HTTPS.
mcb.connector.url	Enter the BMC Helix Multi-Cloud Broker URL to which the Azure DevOps work items should be synchronized.
mcb.connector.username	Enter the user name that enables users to interact with BMC Helix Multi-Cloud Broker.
mcb.connector.password	Enter the password for the user name that you provided.
mcb.property.vendor	Enter the AzureDevOps. This is the vendor name configured in the Map Vendor section in BMC Helix Multi-Cloud Broker.
BMC Helix ITSM properties
itsm.property.company.name	Enter the company name for which the integration template needs to be run; for example, Apex Global.
itsm.property.first.name	Enter the first name of the BMC Helix ITSM customer.
itsm.property.last.name	Enter the last name of the BMC Helix ITSM customer.
itsm.property.assigned.group	Enter the name of the support group to which you want to assign the incidents.
itsm.property.assigned.support.organization	Enter the name of the support organization to which you want to assign the incidents.
itsm.property.assigned.support.company	Enter the name of the support company to which you want to assign the incidents.
itsm.property.assigned.company	Enter the name of the company for which you want to create the incidents.
Email properties
email.property.smtp	Enter the SMTP server details in the following format: `[SMTP Server>[:<SMTP Port>]`
email.property.sender	Enter the email address from which you want to send the emails.
email.property.recipients	Enter the email address of the user to whom you want to send the emails. Use comma-separated values to specify multiple email addresses; for example, allen@apexglobal.com, mary@abc.com.

Click Deploy Application.
While the application is being deployed, the log updates are displayed. After the application is successfully deployed, a green circle is displayed next to the template name.

(Optional) Task 3: To verify and update field mappings defined for the template

After you deploy the application in MuleSoft Anypoint Platform, export the project.
Log in to MuleSoft Anypoint Studio and import the project.
Select projectName > src/main/resources > config.
Double-click the mule-mappings.yaml file, update the <app>Field value to modify the mapping for the field, and then save the file.
Select the project name and then select File > Export.
On the Select dialog box, select Mule > Anypoint Studio Project to Mule Deployable Archive (includes Studio metadata), and click Next.
On the Export Mule Project dialog box, click the ellipses (...) and select the location and name for the file.
Select the following options:
- Attach project sources
- Include project modules and dependencies
Click Finish.
Deploy the application on the MuleSoft Anypoint platform.

Task 4: To enable the integration

To enable the integrations, you need to run the webhook creation scripts from your MuleSoft Anypoint Platform. These scripts automatically create the required webhooks for the integration.

Log in to the MuleSoft Anypoint Platform and select Runtime Manager.
On the Applications tab, click the project name.
On the application details page, click Schedules.

From the following list, select an appropriate schedule and click Run Now. The following options are available:

Schedule	Actions performed
Schedules for create operations from BMC Helix ITSM to Azure DevOps
MCB-Create-Integration-Create-VendorTicket_Manual Trigger	Creates the required webhooks to enable creation of work items in Azure DevOps for incidents created in BMC Helix ITSM
MCB-Create-Integration-Tag-VendorTicket_Manual Trigger	Creates the required webhooks to enable tagging the Azure DevOps work item with the BMC Helix ITSM incident details
MCB-Create-Integration-Create-VendorWorklog_Manual Trigger	Creates the required webhooks to enable creation of Azure DevOps work items for incidents created in BMC Helix ITSM
MCB-Create-Integration-Update-VendorTicket_Manual Trigger	Creates required webhooks to enable updating the fields in Azure DevOps work items with changes made in BMC Helix ITSM incident
Schedules for pause operations from BMC Helix ITSM to Azure DevOps
MCB-Pause-Integration-Create-VendorTicket_Manual Trigger	Pauses the webhooks defined to enable creation of Azure DevOps work items for incidents created in BMC Helix ITSM
MCB-Pause-Integration-Create-VendorWorklog_Manual Trigger	Pauses the webhooks defined to enable creation of worklogs in Azure DevOps for comments added in the BMC Helix ITSM incident
MCB-Pause-Integration-Tag-VendorTicket_Manual Trigger	Pauses the webhooks defined to enable tagging the Azure DevOps work item with the BMC Helix ITSM incident details
MCB-Pause-Integration-Update-VendorTicket_Manual Trigger	Purges the existing webhooks defined to enable updating Azure DevOps work items with changes made in BMC Helix ITSM incident
Schedules for resume operations from BMC Helix ITSM to Azure DevOps
MCB-Resume-Integration-Create-VendorTicket_Manual Trigger	Resumes the webhooks defined to enable creation of Azure DevOps work items for incidents created in BMC Helix ITSM
MCB-Resume-Integration-Create-VendorWorklog_Manual Trigger	Resumes the webhooks defined to enable creation of worklogs in Azure DevOps for comments added in the BMC Helix ITSM incident
MCB-Resume-Integration-Tag-VendorTicket_Manual Trigger	Resumes the webhooks defined to enable tagging the Azure DevOps work item with the BMC Helix ITSM incident details
MCB-Resume-Integration-Update-VendorTicket_Manual Trigger	Resumes the webhooks defined to enable updating the fields in Azure DevOps work item with changes made to the incidents in BMC Helix ITSM
Schedules for purge operations from BMC Helix ITSM to Azure DevOps
MCB-Purge-Integration-Create-VendorTicket_Manual Trigger	Purges the existing webhooks defined to enable creation of Azure DevOps work items for incidents created in BMC Helix ITSM
MCB-Purge-Integration-Create-VendorWorklog_Manual Trigger	Purges the existing webhooks defined to enable creation of worklogs in Azure DevOps for comments added in the BMC Helix ITSM incident
MCB-Purge-Integration-Update-VendorTicket_Manual Trigger	Purges the existing webhooks defined to enable updating the fields in Azure DevOps work items with changes made in BMC Helix ITSM incident
MCB-Purge-Integration-Tag-VendorTicket_Manual Trigger	Purges the existing webhooks defined to enable tagging the Azure DevOps work item with the BMC Helix ITSM incident details
Schedules for create operations from Azure DevOps to BMC Helix ITSM
AzureDevops-Create-Integration-Update-WorkItem_Manual Trigger	Creates the required webhooks to enable creation of incidents in BMC Helix ITSM for work items created in Azure DevOps
Schedules for purge operations from Azure DevOps to BMC Helix ITSM
AzureDevops-Purge-Integration-Create-Issue-WorkItem_Manual Trigger	Purges existing webhooks defined to enable creation of incidents in BMC Helix ITSM for work items created in Azure DevOps
AzureDevops-Purge-Integration-Update-Issue-And-Comment-Create-sample_Manual Trigger	Purges existing webhooks defined to enable updating the fields in BMC Helix ITSM with changes made to the work item fields in Azure DevOps.

After you enable the integration, when an incident is created in BMC Helix ITSM, a corresponding work item is created in Azure DevOps, and the converse is true. Any updates made to the BMC Helix ITSM incident are synced with the Azure DevOps work item, and the converse is true.