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: 

Use caseBMC Helix Digital Workplace to Azure DevOpsAzure DevOps to BMC Helix Digital Workplace
Create Work Items

Creates a Azure DevOps work item from a BMC Helix Digital Workplace service request

NA
Synchronize comments or attachments Synchronizes an activity note or an attachment from a BMC Helix Digital Workplace service request with the corresponding Azure DevOps work itemSynchronizes an activity note from an Azure DevOps work item to with the corresponding BMC Helix Digital Workplace service request
Synchronize statusesNAUpdates the status of the BMC Helix Digital Workplace service request when the Azure DevOps work item is resolved

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: 

Required versions
  • BMC Helix Digital Workplace version 21.02 and later
Authentication and permissions
  • Access to create service requests in BMC Helix Digital Workplace
Jitterbit Harmony subscription
  • A valid BMC Helix iPaaS subscription

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

Important

Repeat this procedure for each service for which you want to perform an action in Azure DevOps.

For a detailed description of the procedure to create a service, see Adding and updating services .

  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:

    ConfigurationDescription
    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 .

    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 variableValue
    BMC Helix Digital Workplace
    DWPC_URLEnter the BMC Helix Digital Workplace Catalog host URL.
    DWPC_UserEnter the User ID to access BMC Helix Digital Workplace Catalog.
    DWPC_PasswordEnter the password for the user to access BMC Helix Digital Workplace.
    DWPC_Service_NameEnter the name of the BMC Helix Digital Workplace Catalog service created for Azure DevOps work items.
    dwpCommentPrefixEnter a prefix to add to the comments from the corresponding Azure DevOps work item.
    BMC Helix Innovation Studio
    Helix_Platform_API_PrefixEnter 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_UrlEnter the BMC Helix Innovation Studio URL.
    Helix_Platform_UserEnter the User ID to access BMC Helix Innovation Studio.
    Helix_Platform_PasswordEnter the password for the user to access BMC Helix Innovation Studio.
    Azure DevOps
    adoAttachmentCommentAttachment shared from the corresponding BMC Helix Digital Workplace service request.
    adoCommentPrefixComment 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_HostEnter https://dev.azure.com.
    AzureDevOps_OrganizationEnter the name of the organization using the Azure DevOps instance.
    AzureDevOps_ProjectEnter the project name based on which the Azure DevOps webhook events are filtered.
    AzureDevOps_User_NameEnter the user name to access Azure DevOps.
    AzureDevOps_User_Personal_Access_TokenEnter 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 URL to access BMC Helix iPaaS.

    BHIP_Username

    Enter the User ID to access 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 API that is created in BMC Helix iPaaS.

    This API receives 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.

    BHIP_API_User_Roles

    Enter comma separated values for the BMC Helix iPaaS user roles to be assigned to the new API; for example: Admin, User.

    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 Jitterbit API and the Webhook API use this APIKEY for authentication while accessing Azure DevOps.

    BHIP_Vendor_API_Profile_Type

    Enter a security profile type.

    You can set 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 ServiceNow. This value is added in the BMC Helix iPaaS Jitterbit API.

    Important:

    • For profile types supported by the Azure DevOps application, the security profiles are automatically created by the integration template when you enable the integration. 
    • BMC Helix iPaaS does not support OAuth authentication for this application.
    Email
    Email_From_AddressEnter 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_SMTPEnter 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.

    <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

Deployment is a one-time activity that initializes the integration configurations. The UI displays a message for the deployment status.

To deploy the project and then enable the integration:

  1. To deploy the project, next to the project name, click the ellipsis ..., and select Deploy Project.
  2. To enable the integration, next to the Enable Integrations workflow, click the ellipsis ..., and select Deploy

The following image shows the steps to deploy the project and enable it by deploying the workflow:

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.

Operation nameAction
Enable Integrations

Sets up variables required 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:

Operation nameActions performed
BHIP Login

Logs in to BMC Helix iPaaS by using the credentials provided in the project variables

BHIP Get API DetailsVerifies if any custom APIs or security profiles exist for the integration
BHIP Delete APIDeletes existing APIs, if required
BHIP Delete API ProfileDeletes existing security profiles, if required
BHIP Create API Profile

Creates the security profiles and Rest APIs in BMC Helix iPaaS

BHIP Get Operation IDVerifies if an operation ID exists for the integration
BHIP Get User Roles

Verifies the roles of the users accessing BMC Helix iPaaS

BHIP Create API

Creates the API configuration in BMC Helix iPaaS

BHIP Publish API

Publishes the API configuration to BMC Helix iPaaS

BHIP Rest API Variables

If a Webhook API configuration exists, updates the configuration with the new data

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:

Operation nameAction
Helix Platform Login

Logs in to BMC Helix Innovation Studio to create the required artifacts

Helix Platform Get Web API ConnectionVerifies if a Web API connection is defined for the integration
Helix Platform Delete Web API ConnectionDeletes any existing Web API connections defined for the integration
Helix Platform Create Web API ConnectionCreates the Web API connection for the integration
Helix Platform Get Documents

Verifies if documents are defined for the integration

Helix Platform Delete DocumentsDeletes any existing documents defined for the integration
Helix Platform Create DocumentsCreates the ocuments required for the integration
Helix Platform Get Web API CollectionsVerifies if Web API collections are defined for the integration
Helix Platform Delete Web API CollectionsDeletes any existing Web API collections defined for the integration
Helix Platform Create Web API CollectionsCreates the Web API collections for the integration
Helix Platform Get ProcessesVerifies if processes are defined for the integration
Helix Platform Delete ProcessesDeletes any existing processes defined for the integration
Helix Platform Create ProcessesCreates the required processes defined for the integration
Helix Platform Get RulesVerifies if rules are defined for the integration

Helix Platform Delete Rules

Deletes existing rules defined for the integration

Helix Platform Create Rules

Creates the required rules for the integration
Helix Platform Get Alias MappingVerifies if alias mappings are defined for the integration
Helix Platform Update Alias MappingUpdates any existing alias mappings defined for the integration

Field Mappings

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

Operation nameAction
DWP to Azure DevOps Mapping

Maps 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.

Operation nameAction
DWP Flow Controller

Accepts the request from BMC Helix Digital Workplace and sends it to the DWP Wrapper operation for asynchronous processing, and then responds back to the webhook request

DWP Wrapper

Interface between the DWP Flow Controller and DWP Driver operations.

Manages the processing of the Azure DevOps work item and update of the work item details in the comments section of the BMC Helix Digital Workplace request.

DWP Driver

Defines the sequence in which operations need to be called to create the Azure DevOps work item

DWP LoginLogs in to BMC Helix Digital Workplace
DWP Get Request DetailsRetrieves the details of the BMC Helix Digital Workplace request
DWP Create CommentAdds the comment from the Azure DevOps work item to the BMC Helix Digital Workplace request
Create Work ItemCreates a work item in Azure DevOps when a request is created in BMC Helix Digital Workplace

ADO Webhook

Operation nameAction
ADO Sync Webhook OperationsUpdates the webhook with the work item updates
ADO Webhook WrapperManages the processing of Azure DevOps webhooks
ADO List Service HooksLists the Azure DevOps webhooks
ADO Delete Service HookDeletes an Azure DevOps webhook if a duplicate webhook exists
ADO Create WebhookCreates an Azure DevOps 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.

Operation nameAction
ADO Flow Controller

Accepts the request from Azure DevOps and sends it to the ADO Wrapper operation for asynchronous processing, and then responds back to the webhook request

ADO Wrapper

Interface between the ADO Flow Controller and ADO Driver operations.

Manages the processing of the BMC Helix Digital Workplace request and update of the service request details in the comments section of the work item.

ADO Driver

Defines the sequence in which operations need to be called to create the BMC Helix Digital Workplace service request

DWP Sync Comments from ADOSynchronizes the comment from the BMC Helix Digital Workplace request to the work item
ADO_DWP_MAPMaps the Azure DevOps and BMC Helix Digital Workplace fields
DWP Update Service Request StatusUpdates the status of the service request when the work item is resolved
Was this page helpful? Yes No Submitting... Thank you

Comments