Creating ServiceNow incidents for BMC Helix Operations Management events by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to create incidents in ServiceNow for all critical BMC Helix Operations Management events. 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 caseBMC Helix Operations Management to ServiceNowServiceNow to BMC Helix Operations Management
Create tickets

Creates a ServiceNow incident from a new BMC Helix Operations Management event.

The event is updated with the corresponding ServiceNow incident number.

NA

Synchronize statusesSynchronizes the status of a BMC Helix Operations Management event with a ServiceNow incidentSynchronizes the status of a ServiceNow incident with a BMC Helix Operations Management event
Synchronize activity notesSynchronizes an activity note from a BMC Helix Operations Management event with a ServiceNow incidentSynchronizes an activity note from a ServiceNow incident with a BMC Helix Operations Management event

BMC Helix Operations Management to ServiceNow data flows

The following image gives an overview of the data flow for creating a ServiceNow incident from a BMC Helix Operations Management event and synchronizing data between them:

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

Before you begin

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

Required versions
  • ServiceNow Paris or later
  • BMC Helix Operations Management 20.08 and later
Authentication and permissions
  • BMC Helix Operations Management
    • Administrator access to BMC Helix Operations Management.

BMC Helix iPaaS subscription

A valid  BMC Helix iPaaS Open link subscription

Application registration
  • 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 that are defined in the project. 
  • Client ID and client secret for BMC Helix iPaaS in ServiceNow
    Generate a client ID and client secret for BMC Helix iPaaS in ServiceNow, and then add the client ID and secret in the client_id and client_secret project variables that are defined in the project.
    For more information about generating an OAuth endpoint, see the ServiceNow documentation Open link to create an endpoint for clients to access the instance.

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 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 key 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 r egister BMC Helix iPaaS with your BMC Helix Operations Management instance. For more information about generating the tenant ID, access key, and secret key, see Setting up user level API keys Open link .

Task 2: To assign roles and ACL permissions to your ServiceNow user

  1. Log in to your ServiceNow instance as an Administrator.
  2. To create a new custom role, and add the roles required by the ServiceNow user defined in the servicenow_user project variable for the integration, perform the following steps:
    1. Click All and select System Security > Users and Roles > Roles.
    2. To create a new role, click New.
    3. Enter a name and description for the role, and click Submit.
    4. To open the roles record, on the Roles page, double-click the name of the role you created.
    5. To add the required roles, on the Contains Roles tab, click Edit..
    6. Select the role to add from the Collection list, click >.
      Add the following roles:

      • itil

      • personalize_dictionary

      • business_rule_admin

      • script_include_admin

    7. Click Save.
      The selected roles are displayed on the Contains Roles tab.

    8. Click Update.
  3. Click the user profile icon and select Elevate Role to get the privileged role to be able to add ACL permissions for users.
  4. When prompted, select security_admin from the list of Available Roles and click Update

    Important

    The  security_admin  elevated role ends when the session times out or when you log out of your ServiceNow instance.

  5. Click All and select System Security > Access Control (ACL).

    Required access permissions
    The following table lists the values required when you configure the access control settings. 

    TypeOperationName
    For creating and updating incidents and creating comments
    recordReadTable [sys_db_object]None
    recordReadField class [sys_glide_object]None
    recordReadDictionary Entry [sys_dictionary]*
    For creating the webhook required for the integration template
    recordReadSystem Property [sys_properties]None
    recordWriteSystem Property [sys_properties]None
    recordExecuteSystem Property [sys_properties]None
    recordCreateSystem Property [sys_properties]None
  6. To add the access control list rules, complete the following steps for each rule listed in the Required access permissions table:

    1. On the Access Controls page, click New.
    2. Configure the following settings for the new record:
      • Type: Select record from the list.
      • Operation: Select a value.
      • Name: Select a value.
      • Requires role: Under Role, double-click Insert a new row, enter the value for role you created in Step 2 and click Save( ).
    3. Click  Submit.
    4. Click  Save.

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

  1. Download the Create ServiceNow Incident from BMC Helix Operations Management Event Update 2023-11-01 Open link project file to your system.

    This file contains the BMC Helix iPaaS Cloud Studio project Create ServiceNow Incident from BMC Helix Operations Management Event Update.

    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 Cloud Studio.
  3. On the projects page, click Import.
  4. Click Browse and then select the Create ServiceNow Incident from BMC Helix Operations Management Event Update 2023-11-01 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 ServiceNow Incident from BMC Helix Operations Management Event Update project, and click View/Edit.

Task 4: To add authentication details to the BMC Helix Operations Management end point configuration

Before you can successfully use the integration template, you must update the BMC Helix Operations Management connector configuration to add the OAuth authentication details.  

  1. To open the project file, select the environment where the integration templates are available, select the Create ServiceNow Incident from BMC Helix Operations Management Event Update project and click View/Edit.
  2. Update the BMC Helix Operations Management endpoint. 

  3. From the Show menu in the Connectors pane, select Endpoints.
  4. Search for and then double-click BMC Helix Operations Management.
    1. On the Configure BMC Helix Operations Management Connection page, click the variable icon and select the following variable values:
      • Server URL—Select hom_server_url
      • Access Key—Select hom_access_key
      • Secret Key—Select hom_sercret_key
      • Tenant ID—Select hom_tenant_id
    2. Click Save Changes.

Task 5: 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 ServiceNow and BMC Helix iPaaS

      Project variableAction
      ServiceNow
      servicenow_EndpointEnter the host URL for ServiceNow.
      servicenow_userEnter the user ID to access ServiceNow.
      servicenow_passwordEnter the password of the user to access ServiceNow.
      servicenow_clientIDEnter the OAUTH API endpoint ID generated in ServiceNow.
      servicenow_secretEnter the OAUTH API endpoint client secret generated in ServiceNow.
      BMC Helix Operations Management
      hom_server_urlEnter the host URL for your instance of BMC Helix Operation Management.
      hom_access_keyEnter the access key of the API user created in Task 1.
      hom_secret_keyEnter the secret key of the API user created in Task 1.
      hom_tenant_idEnter the tenant ID of the API user created in Task 1.
      hom_webhook_name

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

      An API Webhook with this name is created in BMC Helix Operations Managment. 

      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.

      Important


      BMC Helix iPaaS login credentials are required to create the API in BMC Helix iPaaS by using RestAPI because information about the current login status is unavailable during the execution of the template.

    • Webhook API variables

      Project variablesAction
      BHIP_Hom_Webhook_Action
      Enter the action to create or update a webbook for BMC Helix Operations Management.
      Valid values include:
      • CREATE
      • UPDATE
      BHIP_Integration_API_Name_HOM
      Enter a name for the Webhook API to be created in the BMC Helix iPaaS API Manager for BMC Helix Operations Management.

      By default, the value is set to HOMTOSNOWWEBHOOK.

      BHIP_Integration_API_Name_SNOW
      Enter a name for the Webhook API to be created in the BMC Helix iPaaS API Manager for ServiceNow.

      By default, this value is set to SNOWTOHOMWEBHOOK.

      BHIP_Integration_API_Method

      Enter a RestAPI method that is used by the Webhook API created for BMC Helix Operations Management and ServiceNow. This value is added to the BMC Helix iPaaSJitterbit API.

      The following values are valid:

      • POST 
      • GET
      • PUT
      • DELETE

      The default value is POST.

      Do not change the default value.

      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
      • FINAL_TARGET

      The default value is VARIABLE.

      BHIP_Integration_API_Response_Type_SNOW

      Enter the REST API response type used by the Webhook API to handle requests from ServiceNow.

      This value is added in the BMC Helix iPaaS Jitterbit API.

      The following values are valid:

      • VARIABLE
      • FINAL_TARGET

      The default value is VARIABLE.

      BHIP_Integration_API_Security_Profile_Type_HOM
      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC
      • ANONYMOUS

      The default is BASIC.

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

      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 iPaaS does not support OAuth authentication for this application.
      BHIP_Integration_API_Security_Profile_Type_SNOW

      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC 
      • ANONYMOUS

      The default value is BASIC.

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

      Important:

      • For profile types supported by the ServiceNow 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.
      BHIP_Integration_API_Security_Profile_Name_Suffix_HOM

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

      BHIP_Integration_API_Security_Profile_Name_Suffix_SNOWEnter a suffix to be added to the name of security profiles created for ServiceNow.
      BHIP_API_TimeOut

      Enter a value, in seconds, for an API timeout. 

      The API times out if the integration template takes more than the value you define.

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

      BHIP_API_User_Roles

      Enter comma-separated values of the user roles assigned for the BMC Helix iPaaS API. Leave this value blank to restrict access only to administrators.

      Only a user with these roles can access the APIs. 

      BHIP_Integration_API_Security_Profile_BASIC_Auth_Username

      For the BASIC security profile type, enter a user name to be used to create the basic authentication security profile in BMC Helix iPaaS.

      This user name is used for authentication by the Jitterbit API and the Webhook API.

      BHIP_Integration_API_Security_Profile_BASIC_Auth_Password

      For the BASIC security profile type, enter a password to be used to create the basic authentication security profile in BMC Helix iPaaS.

      This password is used for authentication by the Jitterbit API and the Webhook API.

      BHIP_Integration_API_Security_Profile_ApiKey_Name

      For the APIKEY security profile type, enter a name for the API key to set on the security profile.

      This value is used by the RestAPI and Webhook script for authentication.

      BHIP_Webhook_Security_Profile_Type

      Enter a security profile type that the Webhook uses to call the BMC Helix iPaaS Jitterbit API.

      SNOW_Webhook_APIKEY

      Enter the name of the ServiceNow system property to store the apikey for the BMC Helix iPaaS APIKEY authentication profile.

      SNOW_Webhook_Basic_PasswordEnter a password for the ServiceNow Webhook.
      SNOW_Webhook_Basic_User

      Enter the name of the ServiceNow system property to store the BMC Helix iPaaS basic authentication profile user name.

      SNOW_Webhook_Business_Rule_Name

      Enter a name for the business rule created for the ServiceNow Webhook configuration.

      SNOW_Webhook_Property_Name


      Enter the name of the ServiceNow system property to store the BMC Helix iPaaS integration API.

      SNOW_Webhook_Script_Include_Name

      Enter a name for the script include to be used to create the Webhook.

    • (Optional) Email notification configurations 

      Enter the following configuration values to receive email notifications for integration template errors:

      Project variableValue
      BHIP_SMTP_HostnameEnter SMTP host details for email configuration.
      BHIP_To_Email_Address

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

      Leave this value blank if email notifications are disabled.

      BHIP_From_Email_Address

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

      Leave this value blank if email notifications are disabled.

      BHIP_Email_Enabled

      To enable email notifications trigger, change the default value to true.

      By default, the value is set to false

      BHIP_Email_Summary

      To enable email notifications for a summary email of the errors, set the value to true.

      By default, this value is set to false.

      BHIP_Email_Data_Error

      To enable email notifications for integration template errors, set the value to true.

      By default, this value is set to false.

Task 6: To deploy and enable the project

Deployment is a one-time activity that initializes the integration configurations. The UI displays a message for the deployment status.

To deploy the project and then enable the integration:

  1. To deploy the project, next to the project name, click the ellipsis ..., and select Deploy Project.
  2. To enable the integration, next to the Enable Integrations workflow, click the ellipsis ... for the Enable Integration operation, and select Run

The following image shows the steps to deploy the project and enable it by running the operation:

After you enable the integration, when an event is created in BMC Helix Operations Management, a corresponding incident is created in ServiceNow. Any updates made to the BMC Helix Operations Management event are synced with the ServiceNow incident and the converse is true.

Task 7: To map BMC Helix Operations Management fields or custom fields to ServiceNow fields

For any mandatory ServiceNow 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 Helix Operations Management field to a ServiceNow field, complete the following procedure.

  1. Open the BHIP 21.3.04 Create ServiceNow Incident from BMC Helix Operations Management Event Update project.
  2. On the Workflows tab, expand the 4.0 Sync HOM to SNOW operation and select 4.3 Create Incident in ServiceNow.
  3. Click the Mapping for incidents transformation object, and select View/Edit.
  4. 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 ServiceNow field, drag the BMC Helix Operations Management field and map it to the corresponding ServiceNow field displayed in the Target frame on the right.
    • To map a custom field to the ServiceNow field, hover on the ServiceNow 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 <format?>
      • Script: Add the JSON script to add the field mapping.
  5. Click Return to Workflow

    Important

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

    For more information about deploying the project, see Task 5: To deploy and enable the project.

(Optional) Task 8: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode.

To change the time period for the debug mode, perform the following steps:

  1. In BMC Helix iPaaS , powered by Jitterbit, select API Manager > My APIs.
  2. Open the application API created for the integration.
    The API name is the value defined in the BHIP_Integration_API_Name_HOM or the BHIP_Integration_API_Name_SNOW project variable.
  3. Select Enable Debug Mode Until:  and set it for the required date and time.
  4. Save and publish the API.

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

By default, the template is configured to create a ServiceNow incident for all critical events of any Event class type that is 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 ServiceNow 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  Defining event policies for enrichment, correlation, notification, and suppression Open link .

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 required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Operation nameActions performed
Enable integration Creates all the required webhooks for the template and enables the integration
BHIP Login

Logs in to BMC Helix iPaaS by using the credentials provided in the project variables

Check Custom API and Security Profiles existChecks 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 neededDeletes existing APIs or security profiles, if required
Create Webhook in ServiceNowLogs in to ServiceNow by using the credentials provided in the project variables
Check webhook artifact existVerifies if the Webhook API configurations exist in ServiceNow

Create webhook artifact

Creates the Webhook API configuration to ServiceNow

Update webhook artifact

If Webhook API configuration exists in ServiceNow, updates the configuration with the new data
Failure NotificationSends an email notification if the Webhook API configuration is not added to ServiceNow

HOM Webhook

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

Operation nameActions performed
Validate HTTP Status CodeValidates the Webhook operations
Parse JSONValidates the Webhook operations
HOM Webhook OperationsInitiates the Webhook operations based on the operations performed
HOM Get WebhooksGets the BMC Helix Operations Management Webhook
HOM Delete WebhookIf a Webhook with the same name is provided in the hom_webhook_name project variable, deletes that Webhook
HOM Get Refresh TokenGenerates a token for the access key, secret key, and tenant ID and passes it to the HOM Get JWT operation
HOM Get JWT TokenGenerates a JSON web token (JWT) token based on the refreshed token received from HOM Get Refresh Token
HOM Get API KeyGets the BMC Helix Operations Management API Key required to execute Webhook

Flow Controller

This workflow defines the operation to be triggered depending on the application from which the request is received. 

Sync HOM to SNOW

This workflow creates or updates the ServiceNow incident when a BMC Helix Operations Management event is created or status is updated. The following operations are included in this workflow:

Important

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


Operation nameActions performed
Initialization and Driver Script HOMEnables all the API entry points by using the details provided in the project variables
Parse the Source PayloadGets the details of the BMC Helix Operations Management event to create the corresponding incident in ServiceNow
Create Incident in ServiceNowMaps the required BMC Helix Operations Management fields to the ServiceNow incident fields
Query Incident NumberGets the ServiceNow incident ID corresponding to the BMC Helix Operations Management  event
Update Incident Number in HOMUpdates the BMC Helix Operations Management event with the ServiceNow incident URL and number
Update Snow Through API
  • When a BMC Helix Operations Management event is updated, queries ServiceNow for a corresponding incident request
  • Maps the BMC Helix Operations Management fields to ServiceNow fields
  • Updates the existing ServiceNow incident with the updated values

Failure Email

Sends an email notification if incident creation or update fails
HOM Callback ResponseReturns the ServiceNow incident ID to BMC Helix Operations Management

Sync SNOW to HOM

This workflow updates the BMC Helix Operations Management event when a ServiceNow incident status or work note is updated. The following operations are included in this workflow:

Operation nameActions 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 updates the ServiceNow incident status in BMC Helix Operations Management

ValidationValidates the ServiceNow incident
Update incident notes in HOMAdds ServiceNow worknote updates in BMC Helix Operations Management

failure notification snow

Sends an email notification if the update event fails
HOM Generate JWTMaps the required ServiceNow incident fields to the BMC Helix Operations Management event fields
Add Notes
Adds the notes updated in the ServiceNow incident to the BMC Helix Operations Management event
Was this page helpful? Yes No Submitting... Thank you

Comments