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:

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: 

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.

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. 

   Type	Operation	Name
   For creating and updating incidents and creating comments
   record	Read	Table [sys_db_object]	None
   record	Read	Field class [sys_glide_object]	None
   record	Read	Dictionary Entry [sys_dictionary]	*
   For creating the webhook required for the integration template
   record	Read	System Property [sys_properties]	None
   record	Write	System Property [sys_properties]	None
   record	Execute	System Property [sys_properties]	None
   record	Create	System 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 project file to your system.
   This file contains the BMC Helix iPaaS Integration 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 Integration 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 variable	Action
     ServiceNow
     servicenow_Endpoint	Enter the host URL for ServiceNow.
     servicenow_user	Enter the user ID to access ServiceNow.
     servicenow_password	Enter the password of the user to access ServiceNow.
     servicenow_clientID	Enter the OAUTH API endpoint ID generated in ServiceNow.
     servicenow_secret	Enter the OAUTH API endpoint client secret generated in ServiceNow.
     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 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 variables	Action
     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_SNOW	Enter 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_Password	Enter 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 variable	Value
     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. 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.

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:

Disable Integration

This workflow defines the operation required to disable the integration. The following operation is included in this workflow:

HOM Webhook

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

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:

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: