Integrating BMC Digital Workplace requests with Jira issues

As an administrator, you can integrate BMC Digital Workplace with Jira so that whenever a service request is created in BMC Digital Workplace, a corresponding issue is created in Jira. This helps your users to search for any Digital Workplace service requests directly in Jira, and also synchronize comments between a Jira issue and Digital Workplace service request.

BMC Helix iPaaS, powered by Jitterbit, provides a pre-built integration template that you can use:

• to create Jira Issues for Digital Workplace service requests 
• to add Jira issue comments to Digital Workplace service requests 

Before you begin

Make sure you have the following subscriptions and files to successfully set up and use this integration:

• A valid BMC Helix iPaaS subscription

• A BMC Digital Workplace Advanced license with Admin access to the BMC Digital Workplace Catalog
• A valid Atlassian Jira subscription

• The Cloud Studio project file and BMC Helix Digital Workplace service API—Download the BMC Helix Integration Platform 20.02.00 Create Jira Issue from DWP Request Update 2020-09-01 file for the integration template from the BMC Electronic Product Distribution (EPD) website. Your ability to access product pages on the EPD website is determined by the license your company purchased. This compressed package contains the following files:

  • BMC Helix Integration Platform 20.02.00 Create Jira Issue from DWP Request Update 2020-08-01.json —Contains the BMC Helix iPaaS Cloud Studio project Sync DWP Service Request to Jira Issue.
  • ServiceExport_DWPHelixIntegrationPlatform.zip —Contains the BMC Digital Workplace service Call Helix Integration Platform API. 

Limitations

The following limitations apply to this integration template:

• Attachments that are added in Digital Workplace service requests will not be available in Jira.
• Attachments that are added to comments in a Jira issue will not be available in the Digital Workplace service request.
• Formatted text in Jira issue comments will be converted to plain text in the Digital Workplace service request.
• If the Digital Workplace user does not have an account in Jira, the Reporter variable should be mapped to the Automatic or Unassigned user.
• The JIRA_Reference_Field_To_DWP correlation field in Jira can be a string type field.

BMC Digital Workplace to Jira data flow

The following image describes the flow of data between BMC Digital Workplace and Jira defined in the integration template:

Configuration overview

Complete the required BMC Digital Workplace and BMC Helix iPaaS configurations for this integration to work.

Task 1: To add the Helix Integration Platform connector to BMC Digital Workplace Catalog

1. Log in to BMC Digital Workplace Catalog.
2. Select Services > Connectors.
3. Click New Connection and add the following details:
   1. Connection Name: Type Helix Integration Platform
   2. Connector: Select REST
4. Open the connector and add a URL to your BMC Helix iPaaS Cloud Studio instance.

Task 2: To import the required service request to BMC Digital Workplace Catalog

1. Log in to BMC Digital Workplace Catalog.
2. Select Services > Services.
3. Click Import From File to navigate to the location where you extracted the BMCHelixIntePlat_20.02.00_CreateJiraIssueFromDWPRequestUpdate_2020-08-01.zip file you downloaded.
4. Select the ServiceExport_DWPHelixIntegrationPlatform.zip file.
   Verify that the Call Helix Integration Platform API is displayed in the list.

Task 3: To set up individual BMC Digital Workplace service requests

1. Select Actions > Open or double-click the service for which you want to create an issue in Jira.
2. To view the Workflows and Questions, click Edit next to the Workflow.
3. Identify a place in the workflow where you want to create a Jira issue and add a Call Activity action.

4. From the Called Process list, select Call Helix Integration Platform API.
   
   

   Click here to view the expanded process.

   

5. Add values for the following input parameters.

   Important

   • The security fields must be populated according to the authentication mechanism used with Helix Integration Platform.
     To view the security profile, log in to BMC Helix iPaaS and click API Manager > My APIs, and select Security Profiles from the list. For more information, see Security Profiles.

   • The Jira Project and Issue Type values specified here will override the mapping configuration specified in the BMC Helix iPaaS mapping script. Do not enter values for these parameters if you want to use the mapping configuration.

   Input parameter	Description
   Jitterbit Security Profile Type	The authentication method used. For example, type "APIKEY" if you use API key based authentication.
   Jitterbit Security Profile Basic Auth Token	If you are using the basic authentication method, type the authentication token.
   Jitterbit Security Profile ApiKey Name	If you are using API authentication, type the name of the API key.
   Jitterbit Security Profile ApiKey Value	If you are using API authentication, type the value of the API key.
   Jitterbit URI	Path for the BMC Helix iPaaS environment and project. For example, [http/https]://<hostName:Port>.
   Jitterbit method	The API method used. For example, POST.
   Project	The Jira project in which an issue will be created.
   Issue type	The Jira issue type that will be used for creating the issue.
   sb-context	Type 'context' to set it to the BMC Digital Workplace context.

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

1. As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
2. On the projects page, click Import.
3. Click Browse to navigate to the location where you extracted the downloaded file and select the BMC Helix Integration Platform 20.02.00 Create Jira Issue from DWP Request Update 2020-08-01.json file. 
   The Project Name and Organization are automatically populated depending on the values defined. 
4. From the Environment list, select the environment to which you want to import this integration template, and click Import.
   The project opens after the integration template is imported. 
   To open the project file at a later time, select the environment where the integration templates are available, select the Sync DWP Service Request to Jira Issue project and click View/Edit. 

Task 5: To update the project variables for the integration

1. As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
2. Select the environment where the integration templates are available.
3. Select the Sync DWP Service Request to Jira Issue project and click View/Edit. 
4. Click ... next to the Environment name and select Project Variables.
5. Update the required project variables. 
   You must update the following project variables:

   • Access points and authentication details for BMC Digital Workplace, Jira, and BMC Helix iPaaS applications

     Project variable	Description
     BMC Digital Workplace
     DWP_User_Password	Password of the user to access BMC Digital Workplace.
     DWP_User_Login	User ID of a user with access to create requests in the BMC Digital Workplace end user console.
     DWP_Host	BMC Digital Workplace host URL. For example, [protocol]://[HostName]:[PortNumber].
     DWP_comment_visibility	Visibility settings for the comment added to BMC Digital Workplace.
     DWP_comment_login_id	The account used to add Jira comments to the BMC Digital Workplace Business Request.
     Jira
     JIRA_UserName	User ID of a user with access to create issues in Jira.
     JIRA_Reference_Field_To_DWP	Define a field name in Jira to store the reference values of the DWP Service Request. Only text type fields are currently supported.
     JIRA_Host	Jira host URL. For example, https://jira.example.com.
     JIRA_API_Token	The authentication token for the Jira server.
     BMC Helix iPaaS
     Jitterbit_User_Password	Password of the user to access BMC Helix iPaaS.
     Jitterbit_User	User ID to access BMC Helix iPaaS.
     Jitterbit_Url	URL to access BMC Helix iPaaS.
     Jitterbit_API_Security_Profile_BASIC_Auth_Username	User ID to access BMC Digital Workplace.
     Jitterbit_API_Security_Profile_BASIC_Auth_Username	Password to access BMC Digital Workplace.
     Jitterbit_API_Security_Profile_ApiKey_Name	Name of the API authentication key apiKey.
     Jitterbit_API_Jira_To_DWP_Security_Profile_Type	The security profile type. For example, APIKEY. Use comma-separated values to specify multiple security profile types.Important: For profile types supported by the source 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.
     Jitterbit_API_Jira_To_DWP_Security_Profile_Name_Suffix	The Jira to BMC Digital Workplace profile name. This value is added as a suffix to the new security profile name.
     Jitterbit_API_Jira_To_DWP_Name	The Jira to BMC Digital Workplace comment name.
     Jitterbit_API_DWP_To_Jira_Security_Profile_Types	The authentication method used. For example, APIKEY. Use comma-separated values to specify multiple authentication methods.
     Jitterbit_API_DWP_To_Jira_Security_Profile_Name_Suffix	The BMC Digital Workplace to Jira Profile name. This value is added as a suffix to the new security profile name.
     Jitterbit_API_DWP_To_Jira_Name	The API endpoint used for creating issues in Jira.
     Jitterbit_API_DWP_To_Jira_Method	The API method used for creating issues in Jira.

   • Email notification configurations

     Project variable	Value
     Jitterbit_Email_Data_Error	Set to true if you want to send data error logs through email.
     Jitterbit_SMTP_HOSTNAME	SMTP host details for emails configuration.
     Jitterbit_To_Email_Address	Enter the email address to which you want to send the notification emails.
     Jitterbit_From_Email_Address	Enter the email address from which the notification emails should be sent.
     Jitterbit_Email_Enabled	Defines if notification emails should be sent.By default, the value is set to true. To disable email notifications, update the Default Value to false.
     Jitterbit_Email_Summary	Defines if notification emails with a summary log should be sent if workflow is successful.By default, this value is set to true. To disable email notifications for successful operations, set the value to false.
     Jitterbit_Email_Data_Error	Defines if emails should be sent if an error occurs in the data migration. By default, the value is set to true. By default, set to true. To disable email notifications for errors, set the value to false.

Task 6: To review and update out of the box field mappings

1. Open the Sync DWP Service Request to Jira Issue project.
2. Select the Components tab and expand the Scripts list.
3. Scroll through the list and find DWP to Jira mapping, and click ... and select View/Edit.

4. For each service, you must map the fields in BMC Digital Workplace to the fields in Jira.

   Important

   The Jira Project and Issue Type values can be specified in the workflow for individual BMC Digital Workplace service requests and will override the mapping configuration.

   For the question response field mappings, add questions to the question name.

   <javascript>
   var $dwpToJiraMapping = {
      "<Service Request 1>": {(
          "Project": {
              "default": "<JIRA Project Name>"
           },
          "Reporter": {
              "dwpfield": "<JIRA reporter user name>"
   "default": "<John Doe>"
           },
          "Issue Type": {
              "dwpfield": "<DWP question - Is this a new request?>",
              "mapping": {
                 "<Yes>": "<Task>",
                 "<No>": "<Bug>"
               },
              "default": "<Task>"
           },
          "Priority": {
              "dwpfield": "<DWP question - How urgent is this request?>",
              "mapping": {
                 "<Urgent>": "<P1>",
                 "<High priority>": "<P2>",
                 "<Medium priority>": "<P3>",
                 "<Low priority>": "<P4>",
               },
              "default": "P3"
           },
          "Summary":  {
              "dwpfield": "<Provide a summary>"
           },
          "Description": {
              "dwpfield": "<Provide a description>"
           },
          "Labels": {
              "default": []
           }
       },
      "<Service Request 2>": {
          "Project": {
           },
          "Reporter": {
           },
          "Issue Type": {
           },
          "Summary":  {
           }
       },
      "<Service Request 3>": {
          "Project": {
           },
          "Reporter": {
           },
          "Issue Type": {
           },
          "Summary":  {
           }
       }
   };
   </javascript>

Task 7: To deploy and enable the integration

1. To deploy the integration, on the project page, click on the project page, click , and select Deploy.
   Deployment is a one-time activity that initializes the integration configurations. After the deployment is complete, you receive an email notification about the deployment success or failure.
2. After successfully deploying the integration, select the Enable Integration workflows.
3. Click the 3.0 Enable Integration workflow.
4. Click ... next to the Enable Integration element and select Run.

Workflows included in the integration template

The following workflows are included in the integration template:

Related topics

Integrating

Orientation