Creating Jira issues from BMC Helix Digital Workplace requests by using MuleSoft Anypoint Platform

BMC Helix iPaaS, powered by MuleSoft provides a pre-built integration template to create Jira issues for BMC Helix Digital Workplace service requests and the converse. The integration template leverages the Web API available for BMC Helix Digital Workplace to simplify the integration. To use the integration template with the values defined out of the box, you update the project configuration with details of your systems, create the required Webhook registrations, and deploy the integration template. 

The template provides the following capabilities:

BMC Helix Digital Workplace to Jira data flows

The following images give an overview of the data flow to create a Jira issue from a BMC Helix Digital Workplace request:

The following images give an overview of the data flow to add the comment or attachment added to the BMC Helix Digital Workplace request to the corresponding Jira issue:

Jira to BMC Helix Digital Workplace data flow

The following image give an overview of the data flow to add tjhe comment added to a Jira issue to the corresponding BMC Helix Digital Workplace request:

Before you begin

Limitations

The following limitations apply for this integration template:

• 
  
  • Formatted text in Jira comments will be converted to plain text in BMC Digital Workplace.
  • If the BMC Digital Workplace user does not have an account in Jira, the Reporter variable should be mapped to the Automatic or Unassigned user.
  • The vendor.property.reference.field correlation field in Jira can be a string type field.

Task 1: To create the BMC Digital Workplace service for Jira issues

1. Log in to BMC Helix Digital Workplace Catalog.
2. Select Services > Services.
3. On the Service Management page, perform one of the following actions:
   
   • To open an existing service, select the service from the list, and then select Actions > Open.
   • To create a new service:
     1. Select Create New > Service. 
     2. Enter a name and version for the service, for example, Jira integration and 1.0. 
     3. From Template, select the catalog service under which you want to create the service, for example, IT Request. 
     4. Click Create Service. 

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

   Important

   • If you are using an existing service, update the Workflow.

   • For more information about adding and updating a service, see Adding and updating services.

   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. Follow these steps to configure your workflow and then click Save: Under General settings, for Variables, click Add/Remove Variables and 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. Add the Set Service Request Status element, and add the following variables to the Input Map: Request ID—Map the field to the Service Request ID. Status—Set to "Active".  Click here to view field mapping Add the Receive Task element to the workflow. Click here to view the sample processes (Optional) Add the Create Incident element to the workflow and map thei  Click here to view the sample processes
   	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 Jira.

5. Click Save, and then click Close.

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

When you configure the integration template, the names of the services you create or update, are added as values for the bmc.property.service.names key.

Task 2: To download and deploy the integration template project

1. Download theSync DWP Requests to JIRA Issue 2021-06-01 file for the integration template.

2. Log in to the MuleSoft Anypoint Platform and select Runtime Manager. 
3. To configure your integration template, on the Applications tab, click Deploy application.

4. 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.
   Worker 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.

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

   key	value
   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.
   kafka.bootstrap.server	Enter the Kafka server URL in the following format: <hostname>:<port> Important: If the Kafka messaging system is disabled, enter localhost:9092 in this key.
   Mulesoft API Webhook Properties
   api.integrations.name	Enter the BMC Helix Digital Workplace Webhook name.
   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 entered.
   DWP properties
   bmc.connector.protocol	Enter HTTP or HTTPS.
   bmc.connector.url	Enter the URL of BMC Helix Innovation Studio instance.
   bmc.connector.username	Enter the user ID to access BMC Helix Digital Workplace Catalog.
   bmc.connector.password	Enter the password of the user to access BMC Helix Digital Workplace Catalog.
   bmc.property.service.names	Enter comma separated values of the DWP Catalog service names created for creating JIRA issues.
   BMC Helix Innovation Studio properties
   bhp.connector.username	Enter the user ID to access BMC Helix Innovation Studio.
   bhp.connector.password	Enter the password of the user to access BMC Helix Innovation Studio.
   Jira properties
   vendor.connector.protocol	Enter HTTP or HTTPS.
   vendor.connector.url	Enter the Jira instance URL in the following format: [http/https]://[host name and port]
   vendor.connector.username	Enter the user name to access Jira.
   vendor.connector.password	Enter the Jira API token that was created for the user.
   vendor.property.Webhook.name	Enter the Webhook name to create and update the issues.
   vendor.property.Webhook.sync.jql	Enter the JQL query to specify the Jira issues for which BMC Helix Digital Workplace requests should be updated; for example, enter project in (DWP) AND summary ~ 'DWP Issue%'.
   vendor.property.reference.field	Enter the name of the Jira reference field to store the BMC Helix Digital Workplace Service Request ID.

6. Optionally, if you want to enable email notifications, add the following values:

   key	value
   Email notification configurations
   email.property.protocol	Enter the email protocol. You can set the following values for this variable: smtp smtps
   email.property.smtp	If the SMTP or SMTPS server is configured with a non-default port, enter the port number.
   email.property.recipients	Enter a comma separated list of email addresses for recipients who should receive the failure notification, if the request fails.
   email.property.sender	Enter the email address to be used for sending emails.
   email.property.username	Enter the user name to access the email server from which notifications should be sent.
   email.property.password	Enter the password of the user to access the email server from which notification emails should be sent.
   email.property.smtp.starttls	To indicate that communication with the email server should be secured, set this value to true. By default this value is set to false.

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

1. After you deploy the application in MuleSoft Anypoint Platform, export the project. 

2. Log in to MuleSoft Anypoint Studio.

   Important

   For information about downloading and installing the MuleSoft Anypoint Studio, see Downloading and Installing Anypoint Studio.

3. To import the project file, select File > Import.
4. To select the project file, on the Import dialog, select Anypoint studio > Packaged mule application (.jar), and click Next.
5. To browse and select the jar file, on the Mule Import for Deployable Archive dialog, click the ellipses (...), browse for your project jar file, and click Finish.
   The project file is displayed in the Package Explorer section.
6. Select projectName > src/main/resources > config.

7. To view or update the field mappings, double-click the mule-mappings.yaml file. For each JIRA field, the mapping field includes the following fields:

   dwpField	Name of the BMC Helix Digital Workplace field to which the JIRA field is mapped; for example, Project as shown in the example below for the JIRA Project field.
   default	The default value that is used for the JIRA field; for example, BMC as shown in the example below for the JIRA Project field.

   Update the dwpField value to modify the mapping for the field, and then save the file.
   The following image shows the mappings shipped out-of-the-box, and can be modified:

   BMC_VENDOR_MAP:
     Default:
       Project:
         dwpField: Project
        default: BMC
       Issue Type:
         dwpField: Issue Type
        default: Bug
       Priority:
         dwpField: Priority
        default: Low
         mapping:
           High: High
           Medium: Medium
           Low: Low
       Summary:
         dwpField: Summary
        default: New service request created in DWP
       Reporter:
         dwpField: Reporter
        default: Allen Allbrook
   
   # Vendor to BMC Application attributes mapping
   VENDOR_BMC_MAP: ""
          
   # Jira Close Status
   JIRA_CLOSE_STATUS: "Done"
8. Select the project name and then select File > Export.
9. On the Select dialog box, select Mule > Anypoint Studio Project to Mule Deployable Archive (includes Studio metadata), and click Next.
10. On the Export Mule Project dialog box, click the ellipses (...) and select the location and name for the file.
11. Select the following options:
    • Attach project sources
    • Include project modules and dependencies
12. Click Finish.
13. Deploy the application on the MuleSoft Anypoint platform. For details on deploying the application, see Task 2.

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.

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

4. Select the appropriate option from the following list displayed, and click Run Now:

   Name	Description
   BMC-Application-Create-Integration_Manual Trigger	Creates the required integration to enable creation of Jira issues from BMC Helix Digital Workplace requests
   BMC-Application-Purge-Integration_Manual Trigger	Deletes the existing integrations defined for the integration template
   Jira-Create-Integration-Sync-Issue_Manual Trigger	Creates the required integrations to enable sync of work notes and status from the Jira issue to BMC Helix Digital Workplace request
   Jira-Pause-Integration-Sync-Issue_Manual Trigger	Pauses the integration defined to sync work notes and status from the Jira issue to BMC Helix Digital Workplace request
   Jira-Purge-Integration-Sync-Issue_Manual Trigger	Deletes the existing integrations defined to sync work notes and status from the Jira issue to BMC Helix Digital Workplace requests
   Jira-Resume-Integration-Sync-Issue_Manual Trigger	Resumes the integration defined to sync work notes and status from the Jira issue to BMC Helix Digital Workplace requests

After you enable the integration, when a BMC Helix Digital Workplace request is created by using the service created for Jira issues, a corresponding Jira issue is created.