Creating Azure DevOps work items from BMC Helix Digital Workplace requests by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template to create Microsoft Azure DevOps work items from a BMC Helix Digital Workplace request. Use this integration template to create a work item from a BMC Helix Digital Workplace request and update the BMC Helix Digital Workplace request when the work item is resolved.

To use the integration template with the values defined out of the box, perform the following tasks:

1. In BMC Helix Digital Workplace Catalog, create a service with the required questions to gather the data required to create an Azure DevOps work item.
2. Update the project variables with details of your systems.
3. Map the catalog service fields with the work item fields.
4. Deploy the integration template.

After you deploy the integration, a work item is created from a BMC Helix Digital Workplace request. You can also share comments between the work item and service request, and synchronize attachments from the service request to the work item. When the work item is resolved, the corresponding request is also updated. 

The template provides the following capabilities: 

BMC Helix Digital Workplace to Azure DevOps data flows 

The following image gives an overview of the data flow for creating an Azure DevOps work item from a BMC Helix Digital Workplace service request:

The following image gives an overview of the data flow for adding an attachment or activity note to an Azure DevOps work item from a BMC Helix Digital Workplace service request:

Azure DevOps to BMC Helix Digital Workplace data flows

The following image gives an overview of the data flow for adding an activity note to a BMC Helix Digital Workplace service request from an Azure DevOps work item:

The following image gives an overview of the data flow for updating the status of a BMC Helix Digital Workplace service request when an Azure DevOps work item is resolved:

Before you begin

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

Task 1: To create the BMC Digital Workplace service for Azure DevOps work items

1. Log in to BMC Helix Digital Workplace Catalog.
2. Select Services > Services.
3. Select Create New > Service.
4. Enter a name and version for the service, for example, Azure DevOps work items and 1.0. 

5. From Template, select the catalog service under which you want to create the service, for example, IT Request. 

6. Click Create Service.

7. Under Service Options, click Edit for the following options and provide the details to create the service:

   Configuration	Description
   Catalog Profile	Define the profile to be displayed in the BMC Helix Digital Workplace Catalog. For more information about creating the catalog profile, see Adding catalog profile details to a service .
   Workflow	Define a basic workflow for the service. For more information about defining a workflow, see Workflows for service fulfillment .  Click here to view the sample process Complete the following tasks to configure your workflow and then click Save: Under the General settings, for Input Variables, enter the following values: Name—Enter a unique name for your variable. Variable ID—Add a unique variable ID. Variable Type—Select Input/Output Variable > Input. Data Type—Select Service Broker Context. In the Set Service Request Status element, perform the following actions: Map the Service ID field to the SB Context > Service Request > Service Request ID field. Set the Status field to Active. Add the Receive Task element to the workflow.
   	Add a questionnaire for the service. For more information about adding a questionnaire, see Adding a questionnaire to a service . Important: The values you define in the questionnaire must be defined in Azure DevOps.

8. Click Save, and then click Close.

9. Publish the service. 
   For details about publishing a service, see Approving and publishing services .

Task 2: To download and import the integration template project file

1. Download the Create Azure DevOps Work Item from BMC Helix DWP Request 2022-07-01  project file to your system.
   This file contains the BMC Helix iPaaS Cloud Studio project Create Azure DevOps Work Item from BMC Helix DWP Request.

   Important

   Your ability to access product pages on the EPD website is determined by the license your company purchased.

2. As an administrator, log in to BMC Helix iPaaS Cloud Studio. 
3. On the projects page, click Import.
4. Click Browse and then select the Create Azure DevOps Work Items from BMC Helix DWP Request.json file you downloaded.
   The Project Name and Organization fields are automatically populated depending on the values defined. 
5. From the Environment list, select the environment to which you want to import this integration template, and then click Import.
   The project opens after the integration template is imported. 
6. To open the project file at a later time, select the environment where the integration templates are available, select the Create Azure DevOps Work Items from BMC Helix DWP Request project, and click View/Edit.

Task 3: To update the project variables for the integration template

1. Next to the Environment name, click the ellipsis ... and select Project Variables.

2. Update the following project variables:

   Project variable	Value
   BMC Helix Digital Workplace
   DWPC_URL	Enter the BMC Helix Digital Workplace Catalog host URL.
   DWPC_User	Enter the User ID to access BMC Helix Digital Workplace Catalog.
   DWPC_Password	Enter the password for the user to access BMC Helix Digital Workplace.
   DWPC_Service_Name	Enter the name of the BMC Helix Digital Workplace Catalog service created for Azure DevOps work items.
   dwpCommentPrefix	Enter a prefix to add to the comments from the corresponding Azure DevOps work item.
   BMC Helix Innovation Studio
   Helix_Platform_API_Prefix	Enter a predefined prefix to be used for the names of the WebAPI, Process, Document, and Rules created for BMC Helix Digital Workplace in BMC Helix Innovation Studio.
   Helix_Platform_Url	Enter the BMC Helix Innovation Studio URL.
   Helix_Platform_User	Enter the User ID to access BMC Helix Innovation Studio.
   Helix_Platform_Password	Enter the password for the user to access BMC Helix Innovation Studio.
   Azure DevOps
   adoAttachmentComment	Attachment shared from the corresponding BMC Helix Digital Workplace service request.
   adoCommentPrefix	Comment from the corresponding BMC Helix Digital Workplace service request.
   adoWorkItemCloseStatus	Default value is Done. The variable identifies if the work item is closed and accordingly closes the corresponding BMC Helix Digital Workplace request.
   AzureDevOps_Host	Enter https://dev.azure.com.
   AzureDevOps_Organization	Enter the name of the organization using the Azure DevOps instance.
   AzureDevOps_Project	Enter the project name based on which the Azure DevOps webhook events are filtered.
   AzureDevOps_User_Name	Enter the user name to access Azure DevOps.
   AzureDevOps_User_Personal_Access_Token	Enter the personal access token to access Azure DevOps.
   AzureDevOps_Webhook_Area_Path	Enter the area path name based on which the Azure DevOps webhook events are filtered. By default, this variable is blank.
   AzureDevOps_Webhook_Tag	Enter a tag name based on which the Azure DevOps webhook events are filtered. By default, this variable is blank.
   AzureDevOps_Webhook_Work_Item_Type	Enter the type of work item based on which the Azure DevOps webhook events are filtered. The following types of work items are valid: Bug Epic Feature Issue Task Test Case User Story By default, this variable is blank.
   BMC Helix iPaaS
   BHIP_Host	Enter the BMC Helix iPaaS instance URL where you want to run this project. Important: Make sure that you do not enter any leading and trailing spaces in the URL.
   BHIP_Username	Enter the user ID to access the BMC Helix iPaaS instance. Important: BMC Helix iPaaS login credentials are required to create the API in BMC Helix iPaaS by using RestAPI. This is due to a limitation that BMC Helix iPaaS does not enable access to information about being logged in to BMC Helix iPaaS.
   BHIP_Password	Enter the password of the user ID to access BMC Helix iPaaS.
   BHIP_API_Name	Enter the name of the Webhook API that is created in the BMC Helix iPaaS API Manager to receive the webhook requests from BMC Helix Digital Workplace.
   BHIP_ADO_Api_Name	Enter the name of the API that is created in BMC Helix iPaaS. This API receives the webhook requests from Azure DevOps.
   (Optional) BHIP_API_User_Roles	Enter comma-separated values of the organization roles assigned for the BMC Helix iPaaS API; for example: Admin, User. Important: If you do not specify any value, all the organization roles get access to the API.
   BHIP_Vendor_API_Profile_Username	For the BASIC security profile type, enter the user name to create the API Profile.
   BHIP_Vendor_API_Profile_Password	For the BASIC security profile type, enter the password for the security profile created. This password is used for authentication by the Jitterbit API and the Webhook API.
   BHIP_Vendor_API_Profile_ApiKey_Name	For security profile type APIKEY, enter the name of the APIKEY to be used when creating the Azure DevOps profile.  The BMC Helix iPaaS API and the Webhook API use this APIKEY for authentication while accessing Azure DevOps. The default value is apiKey. Important: Provide a value for this variable, only if you select the APIKEY option in BHIP_Vendor_API_Profile_Type.
   BHIP_Vendor_API_Profile_Type	Enter the name of the security profile type. You can set one of the following values for this variable: BASIC APIKEY ANONYMOUS The default value is BASIC. Security Profile Type defines the authentication type to be used by the Webhook API while accessing Azure DevOps. This value is added in the BMC Helix iPaaS API. Important: For profile types supported by the Azure DevOps application, the integration template automatically creates the security profiles when you enable the integration.  BMC Helix iPaaS does not support OAuth authentication for this application.
   Email
   Email_From_Address	Enter the email address from which a mail is sent to notify about integration failure.
   Email_Recipients	Enter comma separated values of the email address of a recipients who receive the integration failure mail notification; for example, email1@abc.com, email2@abc.com.
   Email_SMTP	Enter the details of the SMTP server.
   Enable integration
   Enable_DWP_To_ADO_Integration	Enable the creation of work items from a service request, and addition of attachments from a service request to a work item.
   Enable_ADO_To_DWP_Integration	Enable the sharing of comments between a work item and a service request.

Task 4: To update out-of-the-box mappings

1. Open the Create Azure DevOps Work Items from BMC Helix DWP Request project.
   Out-of-the-box field mappings are defined in the script element of the DWP to ADO Mapping operation in the 5.0 Field Mappings workflow. You must update the payload to map the fields you defined in the BMC Helix Digital Workplace service with corresponding Azure DevOps fields.
   For additional information about the workflow, see Workflows.

2. In the Field Mappings workflow, select the DWP to Azure DevOps script element, click the ellipses ... and select View/Edit.

3. Update the required mappings in the javascript. 

   Important

   You can create multiple mappings for each BMC Helix Digital Workplace service. If a field mapping is unavailable for a service, the default field mapping is used.

    Click here to view the sample code

   <javascript> 
   $DWP_ADO_MAP = {
       "Default": {
          "Priority": {
          		"dwpField": "Priority",
             "default": "4",
             "mapping": {
               "Critical": "1",
               "High": "2",
               "Medium":"3",
               "Low":"4"
             }
          },
          "Severity": {
          		"dwpField": "Priority",
             "default": "4 - Low",
             "mapping": {
               "Critical": "1 - Critical",
               "High": "2 - High",
               "Medium":"3 - Medium",
               "Low":"4 - Low"
             }
          },
           "WorkItemType": {
          		"dwpField": "Type",
             "default": "Issue",
             "mapping": {
               "User Story": "User Story",
               "Bug": "Bug",
               "Issue": "Issue"
             }
          },
          "Title": {
          	"dwpField": "Summary",
           "default": "DWP to ADO Request"
          },
          "Description": {
          	"dwpField": "Summary",
           "default": ""
          }
       }
   };  </javascript>

4. To validate the script, click Test, and then to return to the workflow, click the x mark.
5. Define the json output schema for the updated javascript. 

6. In the Azure DevOps Create Work Items workflow, add the json output to the Azure DevOps Read variable.

   1. Click the ellipsis ... on the Azure DevOps Read variable, and click View/Edit.
   2. On the first screen of the Read dialog, select Yes, Provide New Schema and paste the json output schema in the text area.
   3. Click Next.
   4. Validate the schema and then click Finished.
7. In the Transformation element of the Azure DevOps Read workflow, map the fields updated or modified in the schema.
   1. Click the ellipsis ... on the Transformation element, and click View/Edit.
   2. From the variable list, drag the variable to the field mapping you want to update in the Mappings section.

   3. Click Return to Workflow.

8. (Optional) If you update the field mappings after the integration template is already deployed, to enable the updated mappings, deploy the integration template again. To deploy the integration template, see Task 5: To deploy and enable the project. 

Task 5: To deploy and enable the project

After enabling the integration, when you create a service request in BMC Helix Digital Workplace, a corresponding work item is created in Azure DevOps.

(Optional) Task 6: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

1. In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.
2. Open the API created for the integration. The API name is the value defined in the BHIP_API_Name project variable.
3. Select Enable Debug Mode Until: and set it for the required date and time.
4. Save and publish the API.

Workflows included in the integration template

The integration template includes workflows for the basic configuration and each integration use case. The following tables describe the operations defined in each workflow:

Integrations

This workflow defines the required details for the integration.

BHIP Operations

This workflow defines the operations required to be performed for BMC Helix iPaaS. The following operations are included in this workflow:

Helix Platform Operations

This workflow logs in to BMC Helix Innovation Studio, and creates the required WebAPI, Process, Document, and Rules created for BMC Helix Digital Workplace. The following operations are included in this workflow:

Field Mappings

This workflow includes the script to map the BMC Helix Digital Workplace request fields to the Azure DevOps Work Item fields.

DWP Workflow 

This workflow logs in to BMC Helix Digital Workplace and processes the data from the BMC Helix Digital Workplace request to create the Azure DevOps work item and update the BMC Helix Digital Workplace request.

ADO Webhook

ADO Workflow

This workflow logs in to Azure DevOps, processes the data from the Azure DevOps work item to the BMC Helix Digital Workplace request, and updates the service request when the work item is resolved.