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:

Use case

BMC Helix Digital Workplace to Jira

Jira to BMC Helix Digtial Workplace

Create Jira issues

Creates a Jira issue from a BMC Helix Digital Workplace service request

NA

Synchronize attachments

Synchronizes comments and attachments added to the service request with the Jira issue

Synchronizes comments added to the Jira issues with the service request

Close service request

Updates the status of the service request to Closed when the Jira ticket status is updated to Resolved

NA

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

Required versions
  • BMC Helix Digital Workplace version 21.3 and later
  • Atlassian Jira version 4.11.3 and later
Authentication and permissions
  • A BMC Digital Workplace Advanced license with Administrator access to the BMC Digital Workplace Catalog
  • Administrator access to BMC Helix Platform to create workflows
  • A valid Atlassian Jira Software subscription
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.

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

Important

Follow this procedure for each service for which you want to perform an action in Jira. You can perform an action in Jira for an existing BMC Helix Digital Workplace service or create a new service. 

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

    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 IDMap the field to the Service Request ID.

      • StatusSet to "Active"


    • Add the Receive Task element to the workflow.

    • (Optional) Add the Create Incident element to the workflow and map thei 


    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 the Sync 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 nameAction
    Application NameEnter a unique name for your application.
    Deployment TargetSelect the space for deploying the application, for example, CloudHub.
    Application FileSelect 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:

    keyvalue
    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.passwordEnter 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.usernameEnter the user name to access Jira.
    vendor.connector.passwordEnter the Jira API token that was created for the user.
    vendor.property.Webhook.nameEnter 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:

    keyvalue
    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.passwordEnter 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:

    dwpFieldName 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.
    defaultThe 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 TriggerCreates the required integration to enable creation of Jira issues from BMC Helix Digital Workplace requests
    BMC-Application-Purge-Integration_Manual TriggerDeletes the existing integrations defined for the integration template
    Jira-Create-Integration-Sync-Issue_Manual TriggerCreates 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 TriggerPauses 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.

Was this page helpful? Yes No Submitting... Thank you

Comments