Creating xMatters alerts from BMC Helix Operations Management events by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit, provides a pre built integration template to create alerts in xMatters for 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. 

This integration provides you the following capabilities:

BMC Helix Operations Management to xMatters data flows

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

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

xMatters to BMC Helix Operations Management data flow

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

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 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 at the time 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 new ones.

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 import the integration template project file

1. Download the Create Xmatters Event from BHOM Events 2022-07-01 file.
   This file contains the BMC Helix iPaaS Integration Studio project Create Xmatters Events from BHOM Events. 

   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 to navigate to and select the Create Xmatters Event from BHOM Events 2022-07-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 Xmatters Event from BHOM Events project, and click Edit.

Task 3: 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 Xmatters Event from BHOM events  project and click View/Edit.

2. Update the BMC Helix Operations Management endpoint. 

   Click here to view the procedure

   1. From the Show menu in the Connectors pane, select Endpoints.
   2. Search for and then double-click BMC Helix Operations Management.
   3. On the Configure Microsoft Endpoint Configuration Manager page, update the following configurations for the endpoint:
      • Server URL—Enter the BMC Helix Operations Management server URL. 
      • Access Key—Enter the access key for the API user created in Task 1. 
      • Secret Key—Enter the secret key for the API user created in Task 1. 
      • Tenant ID—Enter the tenant ID of the API user created in Task 1. 
   4. To save your changes and close the configuration window, click Save Changes.

Task 4: To create a workflow and form in xMatters

1. Log in to xMatters.
2. Navigate to Workflows.
3. Select Create > Create Custom Worfklow, as shown in the following image:
   
4. Enter the name and description of the workflow, and save it.
5. After the workflow is created, mark it as Enabled so that you can use the workflow in your integration, as shown in the following image:
   
6. Open the workflow that you created and click Create Form, as shown in the following image:
   
7. Enter the name and description of the form, specify the form type, and save the form.
8. To specify the message and description that you want to give in the alert, on the workflows page, click PROPERTIES, and perform the following steps:
   1. Click Create Property.
      
   2. On the Select the type of property you wish to create dialog box, click Text, and then click Next.
      
   3. Enter the property details and click Create Property.

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

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

   • Access points and authentication details for xMatters and BMC Helix iPaaS

     Project variable	Action
     xMatters
     xMatters_clientid	Enter the Client ID for xMatters.
     xMatters_host_url	Enter the host URL of xMatters that you are using for your integration.
     xMatters_username	Enter the user name to access the xMatters instance.
     xMatters_password	Enter the password for the provided user name.
     xMatters_Form_Name	Enter the name of the form that contains the message that you want to display in an alert.
     xMatters_Workflow_Name	Enter the name of the workflow that contains the series of events or actions that you want to take to create an alert.
     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 Helix iPaaS.
     BHIP_User	Enter the user ID to access BMC Helix iPaaS.
     BHIP_User_Password	Enter the password of the user ID that you provided earlier.
     BHIP_API_Name	Enter the name of the API that is created in BMC Helix iPaaS. This API receives the webhook requests from BMC Helix Multi-Cloud Broker.

   • Webhook API variables

     Project variables	Action
     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 HOMTOxMATTERSWEBHOOK.
     BHIP_Integration_API_Name_xMatters	Enter the name for the Webhook API that is created in the BMC Helix iPaaS API Manager for xMatters.By default, this value is set to xMATTERSTOHOMWEBHOOK.
     BHIP_Integration_API_Method	Enter the RestAPI method used by the Webhook API. This value is added to the BMC Helix iPaaS Jitterbit API. Valid values include: POST (Default) GET PUT DELETE
     BHIP_Integration_API_Response_Type_HOM	Enter the RestAPI response type used the Webhook API created for BMC Helix Operations Management. This value is added in the  BMC Helix iPaaS  Jitterbit API.  Valid values include: VARIABLE (Default) FINAL_TARGET
     BHIP_Integration_API_Response_Type_xMatters	Enter the RestAPI response type used by the Webhook API created for xMatters.  This value is added in the  BMC Helix iPaaS  Jitterbit API.  Valid values include: VARIABLE (Default) FINAL_TARGET
     BHIP_Integration_API_Security_Profile_Type_HOM	Enter a security profile type.  Valid values include: BASIC (Default) ANONYMOUS APIKEY Enter comma-separated values to select multiple profile types (APIKEY,BASIC). A security profile type defines the authentication type to be used to access the Webhook API. This value is added in the BMC Helix iPaaS Jitterbit API for the BMC Helix Operations Management API. Important: For profile types supported by the source application, the security profiles are automatically created by the integration template when you enable the integration.  BMC Helix iPaaS does not support OAuth authentication to access the API.
     BHIP_Integration_API_Security_Profile_Type_xMatters	Enter a security profile type. Valid values include: BASIC (Default) ANONYMOUS APIKEY Enter comma-separated values to select multiple profile types (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 for the xMatters. Important: For profile types supported by the source application, the security profiles are automatically created by the integration template when you enable the integration.  BMC Helix iPaaS does not support OAuth authentication to access the API.
     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_xMatters	Enter a suffix to be added to the name of security profiles created for xMatters.
     BHIP_API_TimeOut	Enter a value, in seconds, for an API timeout. The minimum value must range between 30 and 180. By default, the value is set to 90.
     BHIP_API_User_Roles	Enter the BMC Helix iPaaS user roles to be assigned to the xMatters API. Enter comma-separated values to assign multiple roles; for example, Admin, User.
     BHIP_Integration_API_Security_Profile_BASIC_Auth_user name	For the BASIC security profile type, enter the user name to be used to create the security profile. 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 the password for the security profile created. 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 the name of the API key to set on the security profile. This value is used by the Rest API and Webhook script for authentication.
     BHIP_Webhook_Security_Profile_Type	Enter a security profile type used by Webhook to call the BMC Helix iPaaS Jitterbit API.

   • 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 should be sent.
     BHIP_Email_Subject	Enter the default subject line for the notification email.
     BHIP_Email_Enabled	Define whether the notification emails should be sent. By default, the value is set to true. If you want to disable email notifications, update the default value to false.
     BHIP_Email_Summary	Define whether emails should be sent when the workflow is successful. By default, this value is set to true. To disable email notifications for successful operations, set the value to false.
     BHIP_Email_Data_Error	Define whether emails should be sent when an error occurs in the data migration. By default, this value is set to true. To disable email notifications for errors, set the value to false.

(Optional) Task 6: To map BMC Helix Operations Management fields or custom fields to xMatters fields

Out of the box, the following fields in BMC Helix Operations Management and xMatters are mapped:

For any mandatory xMatters 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 an xMatters field, complete the following procedure.

1. On the Workflows tab, expand the 3.0 Sync HOM to xMatters operation and select 3.4 Create XMATTERS Event.
2. Click the Mapping for incidents 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 xMatters field, drag the BMC Helix Operations Management field and map it to the corresponding xMatters field displayed in the Target frame on the right.
   • To map a custom field to the xMatters field, hover on the xMatters 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. 

   Important

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

Task 7: 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, a corresponding incident is created in xMatters when an event is created in BMC Helix Operations Management. Updates made to the xMatters incident status or work note are synced with the Helix Operations Management event.

(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 increase the debug mode for a longer period of time, perform the following steps:

1. In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.
2. Open the API created for the integration.
   The API name is the value defined in the BHIP_API_Name 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 BMC Helix Operations Management events to xMatters alerts project

By default, the template is configured to create an xMatters 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 xMatters 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 integration template includes workflows for the basic configuration and each integration use case. The following tables describe the operations defined in 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:

HOM Webhook

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

Sync HOM to XMATTERS

This workflow contains the following operations:

Sync XMATTER to HOM

This workflow contains the following operations: