Creating BMC Helix ITSM incidents from BMC Helix Operations Management events by using Jitterbit Harmony

Review note
This topic is for BMC Internal use only and should not be made available to customers.

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template to create incidents in BMC Helix ITSM when BMC Helix Operations Management events are created. To use the integration template with the values defined out of the box, you update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities: 

Use case

BMC Helix ITSM to BMC Helix Operations Management

BMC Helix Operations Management to BMC Helix ITSM

Create tickets

Not applicable

Creates a BMC Helix ITSM incident from a new BMC Helix Operations Management event and create an IncidentInfo event in BMC Helix Operations Management.

The incident ID in the event is updated with the BMC Helix ITSM incident.

Synchronize data updates

Updates the IncidentInfo event from an updated BMC Helix ITSM incident.

Not applicable

Synchronize status updates

Closes the IncidentInfo event when a BMC Helix ITSM incident is closed.

Not applicable

After you deploy the integration template, a BMC Helix ITSM incident is automatically created for an event created in BMC Helix Operations Management. Any updates made to the BMC Helix ITSM incident are reflected in the corresponding BMC Helix Operations Management event. 

BMC Helix Operations Management to BMC Helix ITSM data flow

The following image gives an overview of the data flow for creating a BMC Helix ITSM incident from a BMC Helix Operations Management event:

21304_HOM_ITSM_createITSMIncident.png

Before you begin

You require the following items to successfully set up and use this integration: 

Required versions

  • BMC Helix Operations Management 20.08 and later
  • BMC Helix ITSM 19.11 and later 

Authentication and permissions

Authorized access to the BMC Helix ITSM and BMC Helix Operations Management accounts

Jitterbit Harmony subscription

A valid BMC Helix iPaaS subscription

Application registration

An API access key, secret key, and tenant ID for BMC Helix Operations Management to register BMC Helix iPaaS with your BMC Helix Operations Management instance. 
To do this, create an API user in BMC Helix Portal, and then add the access key, secret key, and tenant ID to the hom_tenant_id, hom_access_key and hom_client_secret project variables you define in the project.

Task 1: To generate the secret key and ID for BMC Helix Operations Management

  1. Log in to BMC Helix Portal.
  2. Select User Access > User Management.
  3. On the API users tab, click Add API User.
  4. Enter the following details required for the API user:
    • API user name
    • Description
    • Key expiry
  5. Click Confirm. 

  6. Copy the secret key, API access key, and tenant ID values.

    Important

    You can copy the access key, and secret only when they are generated. After that they are stored in an encrypted format and cannot be copied. If you do not copy the values when they are generated or if you lose them, you must generate a new one.

These values are required to register BMC Helix iPaaS with your BMC Helix Operations Management instance.  For more information about generating the tenant ID, access key, and secret, see Setting up user level API keys.

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

  1. Download the BHIP 22.1.00 Create ITSM Incident from BMC Helix Operations Management Event.json file to your system.
    This file contains the BMC Helix iPaaS Integration Studio project BHIP 22.1.00 Create ITSM Incident from BMC Helix Operations Management Event.

    Important

    Your ability to access product pages on the EPD website is determined by the license your company purchased.

  2. As a developer, log in to BMC Helix iPaaS and navigate to the Integration Studio.
  3. On the projects page, click Import.

  4. Click Browse and then select the BHIP 22.1.00 Create ITSM Incident from BMC Helix Operations Management Event.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 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_ITSM_Incident_from_BMC_Helix_Operations_Management_Event_Update project. and click View/Edit.

Task 3: To update the project variables for the integration template

  1. Next to the Environment name, click ... and select Project Variables.
  2. Update the following project variables:

    • Access points and authentication details for BMC Helix Operations Management and BMC Helix iPaaS

      Project variable

      Action

      BMC Helix ITSM

      ITSM_Company

      Enter the company name for which the integration template needs to be run.

      This company name is displayed in an incident that is created in BMC Helix ITSM; for example, Apex Global.

      ITSM_First_Name

      Enter the first name of the BMC Helix ITSM customer.

      ITSM_Last_Name

      Enter the last name of the BMC Helix ITSM customer.

      ITSM_Url

      Enter the rest API URL of the BMC Helix ITSM instance that you are using.

      ITSM_User

      Enter the username to access the BMC Helix ITSM instance.

      ITSM_User_Password

      Enter the password of the username provided earlier.

      BMC Helix Operations Management

      hom_server_url

      Enter the host URL for your instance of BMC Helix Operation Management.

      hom_access_key

      Enter the access key of the API user created in Task 1.

      hom_secret_key

      Enter the secret key of the API user created in Task 1.

      hom_tenant_id

      Enter the tenant ID of the API user created in Task 1.

      hom_webhook_name

      Enter the name of the API Webhook for BMC Helix Operations Management.

      BMC Helix iPaaS

      BHIP_Url

      Enter the URL to access BMC BMC Helix iPaaS.

      BHIP_User

      Enter the user ID to access BMC Helix iPaaS.

      BHIP_User_Password

      Enter the password of the user to access BMC Helix iPaaS.

    • Webhook API variables

      Project variables

      Action

      BHIP_Integration_API_Name_HOM

      Enter a suffix to be added to the name of the Webhook API that is created in BMC Helix iPaaS to handle requests from BMC Helix ITSM and BMC Helix Operations Management.

      By default, this value is set to HOMTOITSMWEBHOOK.

      BHIP_API_Security_Profile_BASIC_Auth_Username_ITSM

      Enter the username that has access to BMC Helix ITSM.

      BHIP_API_Security_Profile_BASIC_Auth_Password_ITSM

      Enter the password for the provided username to authenticate access to BMC Helix ITSM.

      BHIP_API_TimeOut

      Enter the value in seconds for an API timeout.

      The minimum value must range between 30-180. By default, the value is set to 55.

      BHIP_API_User_Roles

      Enter comma-separated values of the user roles assigned for the BMC Helix iPaaS API.

      Only a user with these roles can access the APIs. Leave this value blank to restrict access only to administrators.

      BHIP_Hom_Webhook_Action

      Enter the actions to create or update a Webhook in BMC Helix Operations Management.

      The following values are valid:

      • CREATE
      • UPDATE

      BHIP_Integration_API_Name_HOM

      Enter the name for the Webhook API that is created in the BMC Helix iPaaS API Manager for BMC Helix Operations Management.
      By default, this value is set to HOMTOITSMWEBHOOK.

      BHIP_Integration_API_Name_ITSM

      Enter the name for the Webhook API that is created in the BMC Helix iPaaS API Manager for BMC Helix ITSM.By default, this value is set to ITSMTOHOMWEBHOOK.

      BHIP_Integration_API_Response_Type_HOM

      Enter the REST API response type used by the Webhook API to handle requests from BMC Helix Operations Management. This value is added in the BMC Helix iPaaS Jitterbit API.
      The following values are valid:

      • VARIABLE (Default)
      • FINAL_TARGET

      BHIP_Integration_API_Response_Type_ITSM

      Enter the REST API response type used by the Webhook API to handle requests from BMC Helix ITSM. This value is added in the BMC Helix iPaaS Jitterbit API.  

      The following values are valid:

      • VARIABLE (Default)
      • FINAL_TARGET

      BHIP_Integration_API_Security_Profile_ApiKey_Name

      For security profile type APIKEY, enter the name of the API key to be used for the security profile.
      The Jitterbit API and the Webhook API use this APIKEY name for authentication.

      BHIP_Integration_API_Security_Profile_BASIC_Auth_Username

      For security profile type BASIC, enter the user name to be used to be used for the security profile.
      The Jitterbit API and the Webhook API use this username for authentication.

      BHIP_Integration_API_Security_Profile_BASIC_Auth_Password

      For security profile type BASIC, enter the password for the security profile created. 
      The Jitterbit API and the Webhook API use this password for authentication while.

      BHIP_Integration_API_Security_Profile_Name_Suffix_HOM

      Enter the suffix to be added to the name of security profiles created for BMC Helix Operations Management.

      BHIP_Integration_API_Security_Profile_Name_Suffix_ITSM

      Enter the suffix to be added to the name of security profiles created for BMC Helix ITSM.

      BHIP_Integration_API_Security_Profile_Type_HOM

      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC 
      • ANONYMOUS
      • APIKEY

      The default value is BASIC.

      Enter comma separated values to select multiple profile types; for example, APIKEY,BASIC.

      A security profile type defines the authentication type to be used by the Webhook API. This value is added in the BMC Helix iPaaS Jitterbit API.

      Important:

      • For profile types supported by the BMC Helix Operations Management application, the security profiles are automatically created by the integration template when you enable the integration. 
      • BMC Helix iPaaSdoes not support OAuth authentication for this application.

      BHIP_Integration_API_Security_Profile_Type_ITSM

      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC 
      • ANONYMOUS
      • APIKEY

      The default value is BASIC.

      Enter comma separated values to select multiple profile types; for example, APIKEY,BASIC.

      A security profile type defines the authentication type to be used by the Webhook API. This value is added in the BMC Helix iPaaS Jitterbit API.

      Important:

      • For profile types supported by the ITSM application, the security profiles are automatically created by the integration template when you enable the integration. 
      • BMC Helix iPaaSdoes not support OAuth authentication for this application.

    • Email notification configurations

      Project variable

      Action

      BHIP_SMTP_Hostname

      Enter SMTP host details for email configuration.

      BHIP_To_Email_Address

      Enter the email address to which you want to send the notification emails.

      BHIP_From_Email_Address

      Enter the email address from which the notification emails must be sent.

      BHIP_Email_Subject

      Enter the default subject line for the notification email.

      BHIP_Email_Enabled

      To disable email notifications, change the default value to false.

      By default, the value is set to true. 

      BHIP_Email_Summary

      Enter a summary for the email.

      BHIP_Email_Data_Error

      To disable email notifications for errors during data migration, set the value to false.

      By default, this value is set to true.

Task 4: To map BMC Helix Operations Management fields or custom fields to BMC Helix ITSM fields

For any mandatory BMC Helix ITSM fields that are not mapped to an existing BMC Helix Operations Management field, or a custom field, you have to add the mapping manually. To add a mapping of a BMC Helix Operations Management field to a BMC Helix ITSM field, complete the following procedure:

  1. On the Workflows tab, expand the 4.0 Sync BHOM to ITSM operation and select 4.4 Create ITSM Incident.
  2. Click the Auto Map Response transformation object, and select View/Edit.
  3. Select the Variables tab and enter BHOM in the search box. 
    The search displays a list of global variables available for BMC Helix Operations Management. 
    • To map an existing BMC Helix Operations Management field to a BMC Helix ITSM field, drag the BMC Helix Operations Management field and map it to the corresponding BMC Helix ITSM field displayed in the Target frame on the right.
    • To map a custom field to the BMC Helix ITSM field, hover on the BMC Helix ITSM field displayed in the Target frame on the right, and click the + icon, and select one of the following options:
      • Custom value: Add the value of the custom field 
      • Script: Add the JSON script to add the field mapping.

  4. Click Return to Workflow Return to workflow icon_Jitterbit project.png. 

    Important

    If the integration template is already deployed, you must deploy it again after you make changes to the mappings.

    To deploy the integration, on the project page, click icon_Deploy.pngselect Deploy.

Task 5: To deploy and enable the project

(Optional) Task 6: To update the default trigger conditions for the Create ITSM Incident from BMC Helix Operations Management Event project

By default, the template is configured to create a BMC Helix ITSM incident for all critical events of any Event class type created in BMC Helix Operations Management. When you deploy the integration template, BMC Helix iPaaS creates a notification event policy in the BMC Helix Operations Management Event Policies section. 

To change the events for which you want to create corresponding BMC Helix ITSM incidents, update the selection criteria in the Predefined Policy for Incident notification event policy.

For more information about event policies and defining the criteria, see Configuring event policies.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. Refer to the following details for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.

Enable Integration

This workflow defines the operations to control the sync between BMC Helix Operations Management and BMC Helix ITSM. The following operations are included in this workflow:

Operation name

Actions performed

Enable integration

Creates all the required webhooks for the template and enables the integration

Create single API in Jitterbit

Creates an API in BMC Helix iPaaS after enabling the integration

Login into Jitterbit

Logs in to Jitterbit by using the credentials provided in the project variables

Check Custom API and Security Profiles exist

Checks if the Custom API and security profiles exist

Publish Custom API

Publishes the custom APIs to BMC Helix iPaaS

Create Security Profiles and Custom API

Creates security profiles and Rest APIs in BMC Helix iPaaS

Delete API and Security Profile if needed

Deletes existing APIs or security profiles, if required.

Failure Notification

Sends an email notification if the Webhook API configuration is not added to BMC Helix Operations Management.

HOM Webhook

This workflow defines the Create HOM Webhook operation required to generate the Webhook API for BMC Helix Operations Management. 

Operation name

Actions performed

Validate HTTP Status Code

Validates the Webhook operations

Parse JSON

Validates the Webhook operations

HOM Webhook Operations

Initiates the Webhook operations based on the operations performed

HOM Register Webhook

Registers a webhook in BMC Helix Operations Management.

HOM Get Webhooks

Gets the BMC Helix Operations Management Webhook

HOM Delete Webhook

If a Webhook with the same name is provided in the hom_webhook_name project variable, deletes that Webhook

HOM Get Refresh Token

Generates a token for the access key, secret key, and tenant ID and passes it to the HOM Get JWT operation

HOM Get JWT Token

Generates a JSON web token (JWT) token based on the refreshed token received from HOM Get Refresh Token

HOM Get API Key

Gets the BMC Helix Operations Management API Key required to execute Webhook

Sync BHOM to ITSM

This workflow creates the BMC Helix ITSM incident when a BMC Helix Operations Management event is created. The following operations are included in this workflow:

Important

 Incident ID created in BMC Helix ITSM is populated in the Incident ID field on the Others tab of the BMC Helix Operations Management event. 


Operation name

Actions performed

Initialization and Driver Script HOM

Enables all the API entry points by using the details provided in the project variables

BHOM Driver

Decides if it needs to create an incident or update an incident

Query Incidents by Vendor Ticket ID

Gets the BMC Helix ITSM incidents corresponding to the events based on the event ID

Query Worklogs

Gets the BMC Helix ITSM incident worklog corresponding to the events

Create ITSM Incident

Creates a BMC Helix ITSM incident corresponding to the BMC Helix Operations Management event

Update Incident Number in HOM

Updates the BMC Helix Operations Management event with the BMC Helix ITSM incident URL and number

Add Worknotes to ITSM Incident

Adds worknotes to a BMC Helix ITSM incident corresponding to an event

Failure Email

Sends an email notification if incident creation or update fails

HOM Callback Response

Returns the BMC Helix ITSM incident ID and the status of an operation to BMC Helix Operations Management

BHOM ITSM Mapping

Maps the fields in BMC Helix Operations Management with BMC Helix ITSM fields

Update Incident

Updates the BMC Helix ITSM incident

Create Incident Info Event

Creates an Incidentinfo event in BMC Helix Operations Management corresponding to the BMC Helix ITSM incident with its details

Sync ITSM to BHOM

This workflow updates the BMC Helix Operations Management event with the BMC Helix ITSM incident ID. The following operations are included in this workflow:

Operation name

Actions performed

Initialization and Driver Script HOM

Enables all the API entry points by using the details provided in the project variables

Update incident status in HOM

Uses the update event activity to get details of the BMC Helix Operations Management event and update the BMC Helix ITSM incident status in BMC Helix Operations Management

Get event details

Gets the BMC Helix Operations Management event details to synchronize the incident updates.

failure notification itsm

Sends an email notification if the update event fails

HOM Generate JWT

Generates the JSON Web Token of the BMC Helix Operations Management user

Add Notes

Adds the notes updated in the BMC Helix ITSM incident to the BMC Helix Operations Management event

Query Worklog for Incident ID

Gets the BMC Helix ITSM incident ID based on incident worklogs

Query Incident with Incident Number

Gets a BMC Helix ITSM incident based on an incident number

Query Incident with Request ID

Gets a BMC Helix ITSM incident based on a request ID

ITSM BHOM Mapping

Maps the BMC Helix ITSM and BMC Helix Operations Management fields

Update Incident Info Event

Updates the Incidentinfo event with the BMC Helix ITSM incident details

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*