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. 

Important

By default, critical events are brokered in BMC Helix Operations Management.


This integration provides you the following capabilities:

Use caseBMC Helix Operations Management to xMattersxMatters to BMC Helix Operations Management
Create tickets

Creates an xMatters alert from a BMC Helix Operations Management event

NA

Creates an xMatters alert from a BMC Helix Operations Management event without an incident_id that is updated

NA
Synchronize updatesSynchronizes status updates from a BMC Helix Operations Management event with incident_id with an xMatters alert status, along with worknote, if anySynchronizes status updates from an xMatters alert with the status of a BMC Helix Operations Management event with incident_id
Share worknotesCreates a worknote in an xMatters alert from a worknote in a BMC Helix Operations Management eventCreates a worknote in a BMC Helix Operations Management event from a worknote in an xMatters alert

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: 

Required versions
  • BMC Helix Operations Management version 20.08 and later
  • xMatters version 1
Authentication and permissions
  • Administrator access to an xMatters account
  • Administrator access to BMC Helix Operations Management
Jitterbit Harmony subscription

A valid  BMC Helix iPaaS subscription

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 Cloud 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 Cloud Studio.
  3. On the projects page, click Import.
  4. Click Browse to navigate to and select the Create Xmatters Event from BHOM events.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 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. 

    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 variableAction
      xMatters
      xMatters_clientidEnter the Client ID for xMatters.
      xMatters_host_urlEnter the host URL of xMatters that you are using for your integration. 
      xMatters_usernameEnter the user name to access the xMatters instance.
      xMatters_passwordEnter 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_NameEnter 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_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_nameEnter 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_PasswordEnter 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 variablesAction
      BHIP_Integration_API_Name_HOMEnter 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_xMattersEnter 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_HOMEnter a suffix to be added to the name of security profiles created for BMC Helix Operations Management.
      BHIP_Integration_API_Security_Profile_Name_Suffix_xMattersEnter a suffix to be added to the name of security profiles created for xMatters.
      BHIP_API_TimeOutEnter 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 variableAction
      BHIP_SMTP_HostnameEnter SMTP host details for email configuration.
      BHIP_To_Email_AddressEnter the email address to which you want to send the notification emails.
      BHIP_From_Email_AddressEnter the email address from which the notification emails should be sent.
      BHIP_Email_SubjectEnter 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:

BMC Helix Operations Management fieldxMatters field
EventIdincidentID
msgsummary

status

  • Closed
  • Open
  • Acknowledge
  • Assigned
  • Blackout

status

  • Terminate
  • Active
  • Active
  • Active
  • Suspend
work notecomment

Priority

  • Priority_1
  • Priority_2
  • Priority_3
  • Priority_4
  • Priority_5

Priority

  • High
  • High
  • Medium
  • Low
  • Low

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 ..., and select Deploy

The following image shows the steps to deploy the project and enable it by deploying the workflow:

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:

Operation nameActions performed
Enable integrationSets up variables required for the integration
BHIP Login

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

Check Custom API and Security Profiles existVerifies whether any custom APIs or security profiles exist for the xMatters integration
Publish Custom API

Publishes the BMC Helix iPaaS Jitterbit API

Create Security Profiles and Custom API

Creates the security profiles and RestAPIs in BMC Helix iPaaS

Delete API and Security Profile if neededDeletes existing APIs or security profiles, if required
Create Webhook in xMattersLogs in to xMatters by using the credentials provided in the project variables
Check webhook artifact existVerifies whether the Webhook API configurations exist in xMatters

Create webhook artifact

Creates the Webhook API configuration to xMatters

Update webhook artifact

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

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 Register WebhookRegisters a webhook after you enable the integration
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

Sync HOM to XMATTERS

This workflow contains the following operations:

Operation nameActions performed
Initialization and Driver Script HOM

Parses the JSON payload and extracts the following fields to create or update an alert in xMatters:

  • Event Id

  • Status

  • Priority

  • Message

  • Description Detail

Extracts the following fields to add or update comments in an alert:

  • Event ID
  • Notes
Get FormsGets the form Id from a form name defined in the project variable to create an event or an alert for a communication plan's form

Create xMatters Event

Creates an alert with data extracted from the BMC Helix Operations Management payload.

It checks whether the incident_id is blank for any existing alert.

Update Alert IdUpdates the alert_id field with the incident_id field value in BMC Helix Operations Management
Get xMatters DetailFetches the xMatters alert details to update the event status

Update xMatters Event

Updates the status of an xMatters alert
Get xMatters CommentGets a list of comments added to an xMatters alert and also checks whether a comment from a BMC Helix Operations Management event is added to the corresponding alert or not
Add Comment to xMattersAdds a comment to an xMatters alert

Sync XMATTER to HOM

This workflow contains the following operations:

Operation nameActions performed
Initialization and Driver Script xMatters

Parses the JSON payload and extracts the following fields to create or update an event in BMC Helix Operations Management:

  • Alert Id

  • status

  • auditType

  • comment

Get event by incident_idGets the BMC Helix Operations Management event details by using the incident_id (or xMatters alert ID)
Update Event Status in HOMSynchronizes the status of an xMatters alert with the BMC Helix Operations Management event
Add NotesAdds notes from an xMatters alert to a BMC Helix Operations Management event 
Was this page helpful? Yes No Submitting... Thank you

Comments