Creating known errors from Jira issues via BMC Helix Integration Service

BMC Helix Multi-Cloud Broker helps facilitate DevOps practices in organizations that use multiple tools. You can integrate BMC Helix ITSM with Jira to create known error requests in BMC Helix ITSM from Jira issues. With this integration, you can track Jira defects in BMC Helix ITSM in the form of known errors. You can also synchronize data between a BMC Helix ITSM known error request and a Jira issue. The BMC Helix ITSM: Smart IT agents can view BMC Helix ITSM known errors in the Smart IT console. An issue ID is also added to a Smart IT ticket, and agents can click the ID to directly open the issue in Jira.

Jira to BMC Helix ITSM data flow

The following image illustrates how BMC Helix Multi-Cloud Broker creates a known error in BMC Helix ITSM from a Jira issue:

Before you begin

Complete all preconfiguration tasks before you enable the integration.

To select the integration option for DevOps between Jira and BMC Helix ITSM

1. Log in to BMC Helix Innovation Suite.
2. On Workspace, click Multi-Cloud Broker.

3. To launch BMC Helix Multi-Cloud Broker, click Visit Deployed Application.

   Tip

   You can access BMC Helix Multi-Cloud Broker directly by entering the URL https://hostName:portNumber/helix/index.html#/com.bmc.dsm.mcsm/login and logging in as a tenant administrator.

4. To open the configuration page, click Settings .
5. Select Start Here > Quick Configuration Guide.
6. In the Step 1: Choose configuration tab, perform the following steps:
   1. From the Choose configuration list, select the Helix integration service.

  b. To enable the DevOps Integration feature for Jira and BMC Helix ITSM, under DevOps Integration, select Jira Issue to ITSM Known Error, and click Next.

The Perform configurations tab displays a list of common configurations, connectors, and flows that you need to configure as described in the next tasks.

To map Jira vendor data to BMC Helix ITSM or BMC Helix ITSM: Smart IT

Configuring vendor data includes setting up a vendor organization and defining vendor mappings for the technology provider. Vendor mapping is the metadata of the vendor that is used to define dynamic field mapping between BMC Helix ITSM and Vendor application fields. Vendor mapping metadata is required to send ITSM ticket to the vendor application. Vendor mapping ensures that notifications about changes made to the BMC Helix ITSM fields are added as a comment to the corresponding vendor application ticket. If you are integrating with multiple instances of Jira, create a vendor mapping for each instance of Jira.

1. If required, to create or modify a vendor organization, in the Perform configurations tab, click  Manage Vendor Organizations  under Configure JIRA.
2. To add or update the vendor mapping, in the Perform configurations tab, click Manage Vendor Metadata under Configure JIRA.
   1. On the Configure Vendor Metadata page, click . 
      
   2. Enter a Description that makes it easy for you to identify the vendor metadata configuration.
   3. Select the Ticketing Technology Provider. 
      The technology provider is the organization that develops the vendor application. For example, Amazon is the Ticketing Technology Provider for AWS.

   4. If you have multiple Jira instances, enter a Instance Name that BMC Helix Multi-Cloud Broker can use to identify each Jira instance.

      The recommended format for an instance name is  instanceName instance instanceNumber

   5. Click Add Mapping.
      BMC Helix Multi-Cloud Broker displays the default Instance URL, Vendor Field Mapping, and Display Field Mapping.
   6. Update the Instance URL with the server name and the port number for the Jira instance that you are mapping. 
      This URL represents the URL for connecting with your Jira server.
   7. Click  { }  to open the JSON editor, and modify Vendor Field Mapping and Display Field Mapping to add or delete values. 

      • Vendor Field Mapping — Defines how BMC Helix Multi-Cloud Broker maps ITSM fields to vendor application ticket fields.

        Update the value of fields.project.name with the name of your Jira project for ticket-brokering-lib:Known Error .

        

      • Display Field Mapping — Defines how Jira ticket fields are displayed on the Smart IT console.

        

   8. From the Integration Platform list, select Integration Service.

To configure connectors for integrating BMC Helix ITSM and Jira with BMC Helix Multi-Cloud Broker

For the Jira Issue to ITSM Known Error feature that you selected, complete the following procedure for the connectors listed on the Configuration Links page:

1. To navigate to BMC Helix Integration Service, on the Configuration Links page, click Configure connectors in Integration Studio under Required Common Configurations.
   You must configure the connectors listed for each feature, in addition to the connectors listed under Required Common Configuration.
2. To enter field values, select a connector, such as ITSM, and click Configuration.
   You might need to click the arrow on the ribbon in the lower section of the screen to open the Configuration pane.
3. To update the configuration defaults, enter the appropriate field values by referring to the list of connectors at the end of this procedure.
4. To add or update the user account that is used to access the vendor application, click Accounts.

List of connectors for integration with Jira

• Multi-Cloud
  
  • Configuration
    While activating BMC Helix Multi-Cloud Broker, BMC configures the Multi-Cloud connector. Do not modify the default Multi-Cloud connector configuration.
  • Account
    BMC sets up the account for the Multi-Cloud connector.
    Click to re-authenticate after you have changed the password for your tenant administrator user account in BMC Helix Innovation Studio.
    For information about changing the user password, see Creating or modifying People data.
• Jira
  • Configuration

    • If you are integrating with an on-premises instance of BMC Helix ITSM, enter values for the following fields:

      Field	Value
      Name	Enter a name for the connector configuration
      Site	For each on-premises Jira instance, select the site that you created. For Jira instances in the cloud, select Cloud as the site.
      Jira Server Hostname	Enter the name of your Jira server.
      Jira server Port	Enter the port number of the Jira server. Enter 443 if your Jira server is SSL enabled.
      Protocol	Enter the protocol used by the Jira server.
      Certificate Authority	Copy the contents of a self-signed certificate.

    • If you need to integrate with multiple instances of Jira, add a Connector Configuration for each instance.
  • Account
    • Add the account of a Jira user who can view and update Jira issues.
    • If you need to integrate with multiple Jira instances, add an account for each of the Jira instances.

• AR system
  
  The following definition is provided as internal forms configuration in the connector in the out-of-the-box schema:

  [
     {
         "label": "Known Error",
         "name": "PBM:Known Error",
         "trigger": "PBM:Known Error",
         "create": "PBM:ProblemInterface_Create",
         "update": "PBM:KnownErrorInterface",
         "query": "PBM:Known Error",
         "resultKeyField": "1000000979",
         "keyField":"1000000979"
     },
     {
         "label": "Known Error WorkLog",
         "name": "PBM:Known Error WorkLog_People",
         "trigger": "PBM:Known Error WorkLog_People",
         "create": "PBM:Known Error WorkLog"
     }
  ]

  
  

List of flows for integration with Jira

Create flows

• Create Known Error from Jira Issue

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Project is	NA
    Labels not matches	(INC|CRQ|PBI|WO|PKE)\d+

  • Field mapping
    The following mappings are provided out-of-the-box:

    • Flow Target 1 (BMC Helix Multi-Cloud Broker)

      Field	Value
      Description	Issue description
      Impact	Priority
      Summary	Issue Summary
      Urgency	Priority
      View Access Note: The value of this field is set to Internal.	NA
      Known Error Status	Status
      Target Date	Due date
      Vendor Note: The value of this field is set to JIRA.	NA
      Vendor Ticket Id	Issue Key
      Vendor Ticket Properties fields.assignee.displayName fields.status.name fields.issuetype.name key	Assignee Status Issue Type Issue Key
      Webhook Condition Parameter Note: The value of this field is set to Remedy.	NA
      Action Note: The value of this field is set to CREATE KNOWN ERROR.	NA

• Create ITSM Known Error from Multi-Cloud Known Error

  • Triggerconditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Condition is	${webhookContext.466000271} = "Remedy" AND ${webhookContext.466000048} = "CREATE KNOWN ERROR" AND ($ webhookContext.466000257} = $NULL$ OR ${webhookContext.466000257} = "")
    Include All Fields is	true
    is New	is true

  • Field mappings
    

    • Flow Target 1 (AR System)

      The following mappings are provided out-of-the-box:

      Field	Value
      Status* (Known Error Status) Note: The value of this field is set to Known Error Status.	NA
      Notes (Detailed description)	Description
      Urgency* (Urgency) Note: The value of this field is set to Urgency.	NA
      Impact* (Impact) Note: The value of this field is set to Impact.	NA
      Description* (Description)	Summary
      Target Date (Target Resolution Date)	Target Date
      Broker Vendor Name Note: The value of this field is set to JIRA.	NA

    • Flow Target 2 (BMC Helix Multi-Cloud Broker)
      The following mappings are provided out-of-the-box:

      Field	Value
      Known Error ID	Target 1 Known Error ID* + (Known Error ID)
      ID	ID

    • Flow Target 3 (BMC Helix Multi-Cloud Broker)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Parent Ticket Id	ID

    • Flow Target 4 (BMC Helix Multi-Cloud Broker)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      text	TICKET_CREATED_MESSAGE
      post_type Note: The value of this field is set to comment#remedy.	NA
      ticket_type Note: The value of this field is set to knownerror.	NA
      vendorTicketId	Vendor Ticket Id
      Parent_GUID	Target 1 Known Error ID* + (Known Error ID)
      WorkLogTypeId Note: The value of this field is set to 44000.	NA

    • Flow Target 5 (JIRA)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Issue Key	Target 3 Vendor Ticket Id
      Labels	Target 1 Known Error ID* + (Known Error ID)

Worklog flows

• Sync Jira Issue Comment

  • Trigger

    Retain the values that are available out-of-the-box.

  • Field mapping

    Do not change the following out-of-the-box field mappings.

    Field	Value
    text	Retain the prefix Comment Body
    post_type	comment#remedy
    Vendor	JIRA
    Vendor Ticket Id	Issue Key
    commentId	Comment ID
    Attachment Object 1	Attachment Object 1
    Attachment Object 2	Attachment Object 2
    Attachment Object 3	Attachment Object 3

• Multi-Cloud Worklog to ITSM Known Error Activity Note

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Mapping
    Condition is	${webhookContext.304411991} = "knownerror" AND ${webhookContext.304412011} = "comment#remedy"
    Include All Fields is	true

  • Field mappings
    

    • Flow Target 1 (AR System)
      The following mappings are provided out-of-the-box:

      Field	Value
      Work Info Type* (Work Log Type)	WorkLogTypeId
      Known Error ID* (Known Error ID)	Parent_GUID
      Notes* (Detailed Description)	CommentText

• Create Known Error Activity Note with Author

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Is New Known Error Worklog	is true
    Broker Vendor Name	is not empty

  • Field mappings

    • Flow Target 1 (BMC Helix Multi-Cloud Broker)
      The following mappings are provided out-of-the-box:

      Field	Value
      text	Notes (Detailed Description)
      post_type Note: The value of this field is set to comment#vendor.	NA
      ticket_type Note: The value of this field is set to knownerror.	NA
      ticketNumber	Known Error ID
      vendorTicketId	Broker Vendor Ticket Id
      Author	Full Name
      Webhook Condition Parameter	Broker Vendor Name

• Multi-Cloud Worklog to Jira Issue Comment

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Condition is	${webhookContext.466000228} = "JIRA" AND ${webhookContext.304412011} = "comment#vendor" AND ${webhookContext.304411991} = "knownerror"
    Include All Fields is	true
    Attachment Group Id is empty	NA

  • Field mappings

    • Flow Target 1 (JIRA)
      The following mappings are provided out-of-the-box:

      Field	Value
      Comment Body	CommentText
      Issue Key	associatedGUID

• Multi-Cloud Worklog with Attachment to Jira Issue comment
  • Trigger condition

    • The following trigger conditions are provided out-of-the-box:

      Field	Value
      Condition is	${webhookContext.466000228} = "JIRA" AND ${webhookContext.304412011} = "comment#vendor" AND ${webhookContext.304411991} = "knownerror"
      Include All Fields is	true
      Attachment Group Id is not empty	NA

    • Field mappings

      • Flow Target 1 (JIRA)
        The following mappings are provided out-of-the-box:

        Field	Value
        Comment Body	CommentText
        Issue Key	associatedGUID

      • Flow Target 2 (JIRA)
        

        The following mappings are provided out-of-the-box:

        Field	Value
        Issue Key	associatedGUID
        Attachment	Attachment Object 1

        
        

Sync flows

• Sync Jira Issue to Multi-Cloud Known Error

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Project is	NA
    Labels matches	PKE\d+

  • Field mappings

    • Flow Target 1 (BMC Helix Multi-Cloud Broker)
      The following mappings are provided out-of-the-box:

      Field	Value
      Status	Status
      Vendor Note: The value of this field is set to JIRA.	NA
      Vendor Ticket Id	Issue Key
      Vendor Ticket Properties fields.assignee.displayName fields.status.name fields.issuetype.name fields.fixVersions key	Assignee Status Issue Type Fix versions Issue Key

    • Flow Target 2 (BMC Helix Multi-Cloud Broker)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Description	Issue Description
      Impact Note: The value of this field is set to Impact.	NA
      Known Error Id	Target 1 Parent Ticket Id
      Summary	Issue Summary
      Urgency Note: The value of this field is set to Urgency.	NA

• Update ITSM Known Error from Multi-Cloud Known Error

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Condition is	${webhookContext.466000278} = "true"
    Include All Fields is	true
    Record Event equals	update

  • Field mappings

    • Flow Target 1 (AR System)
      The following mappings are provided out-of-the-box:

      Field	Value
      Known Error ID	Known Error ID
      Summary (Description)	Summary
      Notes (Detailed Description)	Description
      Urgency Note: The value of this field is set to Urgency.	NA
      Impact Note: The value of this field is set to Impact.	NA

    • Flow Target 2 (BMC Helix Multi-Cloud Broker)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Known Error ID	Known Error ID
      Sync Remedy Ticket	false

• Sync ITSM Known Error

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Broker Vendor Name	is not empty

  • Field mappings

    • Flow Target 1 (BMC Helix Multi-Cloud Broker)
      The following mappings are provided out-of-the-box:

      Field	Value
      Company	Company
      Description	Notes (Detailed Description)
      Impact Note: The value of this field is set to Impact* (Impact).	NA
      Known Error ID	Known Error ID* + (Known Error ID)
      Known Error Status	Status* (Known Error Status)
      Last Corrected Date	Last Corrected Date
      Priority	Priority* (Priority)
      Sync Vendor Ticket	true

• Update Jira Issue from Multi-Cloud Known Error

  • Trigger conditions
    The following conditions are provided out-of-the-box:

    Field	Value
    Condition is	${webhookContext.466000279} = "true"
    Include All Fields is	true
    Record Event equals	update

  • Field mappings

    • Flow Target 1 (BMC Helix Multi-Cloud Broker)
      The following mappings are provided out-of-the-box:

      Field	Value
      Parent Ticket Id	ID

    • Flow Target 2 (JIRA)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Issue Key	Vendor Ticket Id
      Issue Description	Description
      Issue Summary	Summary

    • Flow Target 3 (BMC Helix Multi-Cloud Broker)
      

      The following mappings are provided out-of-the-box:

      Field	Value
      Known Error ID	Known Error ID
      Sync Vendor Ticket	false

To enable mapping between BMC Helix ITSM fields and custom fields created in Jira

When integrating with Jira, you can send and receive the value of custom fields created in Jira to a field in BMC Helix ITSM by specifying the appropriate mapping for the fields. After you create the custom field, you need to update the Jira connector, flow, and vendor data configuration.

1. Create the custom field in Jira.
   1. Log in to Jira and add the custom fields that you need. 
   2. Ensure that the custom fields are available on all the screens and issue types that you want to integrate with. 
      For information on adding custom fields, see the documentation for Jira.
2. Synchronize the Jira connector.
   1. Log in to BMC Helix Integration Studio.
   2. Navigate to Catalog and click Connectors.
   3. Select the Jira connector and click Custom Fields in the Configuration pane.
      You might need to click the arrow on the ribbon in the lower section of the screen to open the Configuration pane.
   4. Select the connector configuration that you want to update for custom fields and click Generate or Re-Generate.
      
3. Update the Sync Jira Issue flow to synchronize the new field. 

   1. (Optional) Get the internal ID from Jira for your custom fields: 

      Important

      You must install a utility for non-interactive download of files like wget and then run the commands using the command line prompt.

      
      

      1. Run echo -n username:password| base64
         to generate base64 encoded string for subsequent requests.

      2. Run wget --no-check-certificate --header='X-Requested-With: XMLHttpRequest' --header='Authorization: Basic [base64 encoded username:password]' --output-document applications.json 'https://[host]/api/v1.0/apps/search?lower_case_name=[connector name]'

         This command creates applications.json file that contains response from the BMC Helix Integration Service. Copy value from id field from the json file. This is application Id field that you can use in the next command. Find from the list of appConfig your  configuration by name and copy value from Id field. This is configuration Id value that you can use in next command.

      3. Run wget --no-check-certificate --header='X-Requested-With: XMLHttpRequest' --header='Authorization: Basic [base64 encoded username:password]' --output-document app_triggers.json 'https://[host]/api/v1.0/apps/[application Id]/configs/[configuration Id]/triggers'

         This request creates  app_triggers.json file with available triggers. Each trigger object contains a fields field that is an array of available fields. Copy value from systemName field. Use this value in step f.

      4. Run wget --no-check-certificate --header='X-Requested-With: XMLHttpRequest' --header='Authorization: Basic [base64 encoded username:password]' --output-document app_actions.json 'https://[host]/api/v1.0/apps/[application Id]/configs/[configuration Id]/actions'

         This request creates  app_actions.json  file with available actions. Each action object contains a fields field that is an array of available fields. Copy the value of systemName field. These fields can be used as Vendor field mapping properties.

      
      

   2. Log in to BMC Helix Integration Studio.
   3. Navigate to My Flows and select the Sync Jira Issue flow.
   4. On the Details tab, click .  
   5. Select the Edit Field Mapping tab. 
   6. In the Vendor Ticket Properties section, click Add Property for each custom field that you want to use. 
      
      
   7. Enter the systemName field and select the field in which the value of the custom field needs to be populated.
      
4. To display the custom field, update Display Mapping in Vendor Data configuration.
   1. Log in to BMC Helix Multi-Cloud Broker and click Settings .
   2. Navigate to Configure Vendors > Map Vendors.
   3. Select the Jira metadata that you want to update and click Edit.
      
      
   4. Add new vendor specific values for the custom fields that you need.

      • Vendor Field Mapping defines how BMC Helix Multi-Cloud Broker maps BMC Helix ITSM fields to vendor ticket fields. 

        

      • Display Field Mapping defines how vendor ticket fields map to the fields on the Smart IT console.

        

        
        

The configuration enables you to send data from the custom Jira field to the BMC Helix ITSM field mapped in the Vendor Field Mapping.

To sync the values of mapped fields between Jira and BMC Helix ITSM

You can configure the prebuilt DevOps integration between JIRA Software and BMC Helix ITSM to automatically update the values of fields mapped between Jira and BMC Helix ITSM in the applications, instead of adding them as a comment. If you update the value of a mapped field in one application, the value is automatically updated in the other application. For example, after creating a known error request, the initial value of the Status field in Jira and ITSM ticket is In Progress. Now, when you update the status of the Jira defect to Closed, the status of the ITSM known error request is automatically updated to Closed.

To update the Jira field value when BMC Helix ITSM field value is changed

To automatically update the value of a Jira field when the BMC Helix ITSM field value is changed, you must first map the BMC Helix ITSM and Jira fields that you want to keep in sync in the Jira Vendor Field Mapping.  Then, configure the flows required to update the value of the Jira fields. 

The following table lists the steps that you must perform to update a Jira field value when a BMC Helix ITSM field value is changed:

To update the BMC Helix ITSM field value when Jira field value is changed

To automatically update the value of a BMC Helix ITSM field when the Jira field value is changed, you must first map the Jira and BMC Helix ITSM fields that you want to keep in sync in the Jira Vendor Field Mapping.  Then, configure the flows required to update the value of the BMC Helix ITSM fields. 

The following table lists the steps that you must perform to update a BMC Helix ITSM field value when a Jira field value is changed:

To map a custom field in BMC Helix ITSM with Jira

You can create a custom field in BMC Helix ITSM and map it with a field in the Jira ticket. To learn more, see Updating-configurations-to-send-and-receive-data-from-custom-BMC-Helix-ITSM-fields.

Related topic

Configuring-BMC-Helix-Multi-Cloud-Broker