Articles in this section

How do I integrate Entuity with BMC Helix?

Avatar
Stuart Hill
  • Updated
Follow

Applicable to Entuity v19.0 P03 upwards. If you are using an earlier version of Entuity, please see this article.

 

 

1. To obtain the Helix user account API Key and Tenant ID

2. To obtain the JSON Web Token (JWT)

3. To create the Helix classes that the Entuity integration will use

To list (GET) the Helix class properties
To delete (DELETE) a Helix class property

4. To specify the Entuity configuration file Helix.cfg

5. To configure Entuity to send data to BMC Helix

 

 

From Entuity v19.0 P03 upwards, to send events and data from Entuity to BMC, you will need to do the following:

  1. Obtain the Helix user account API Key and Tenant ID, which will allow you to create Helix custom classes and authorize connections from the Helix server.
  2. Obtain the Access Key and Secret Access Key, which will then allow you to obtain a JSON Web Token. The JSON Web Token (JWT) is required to authorize the CURL class creation and curl command that the Entuity integration will use.
  3. Create the Helix custom classes that the Entuity integration will use.
  4. Specify the Entuity configuration file Helix.cfg.
  5. Configure Entuity to send data to BMC Helix.

 

 

1. To obtain the Helix user account API Key and Tenant ID:

  1. The API Key can be retretireved from the BMC Helix server. Navigate to the BMC Helix server.
  2. Click Administration, then click Repository, then click Copy API Key.

    i2.png

 

 

2. To obtain the JSON Web Token (JWT):

  1. Log in to the BMCOM interface.
  2. Click your account icon in the top right of the window, then click API keys.

    h1.png


  3. Using the API keys menu, create the API key.

    h2.png

  4. The Access Key and Secret Access Key can then be used to obtain the JWT that will last for 15 minutes. The following example script is used to log in to the Helix server and return a JSON Web Token. It is for the example Helix server helixtrial-emea-8-dev-ir1.onbmc.com.
    #!/bin/bash
    LB=helixtrial-emea-8-dev-ir1.onbmc.com
    ACCESSKEY=myAccessKey
    SECRETKEY=mySecretAccessKey
    curl --insecure --header "Content-Type: application/json" --request POST --data '{"access_key": "'$ACCESSKEY'", "access_secret_key": "'$SECRETKEY'"}' https://$LB:443/ims/api/v1/access_keys/login
    The following is the response, and the JWT is in bold:
    {"user_id":"495942095729265","principal_id":"IOV722VD3ZIX8XY6E85557AJHVUEXI","tenant_id":"1692610049","tenant_name":"helixtrial-emea-8","token":"eyJraWQiOiI3OWVlYjdmMy04M2UxLTRkM2YtODQ2MC1hOGJlMDNkODMzMmMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiIxNjkyNjEwMDQ5Ojo0OTU5NDIwOTU3MjkyNjUiLCJhdWQiOiJibWNfYWRlX2Nsb3VkX3NlcnZpY2VzIiwiYW1yIjpbImV5SjFjMlZ5WDJsa0lqb2lORGsxT1RReU1EazFOekk1TWpZMUlpd2lZV05qWlhOelgydGxlU0k2SWtsUFZqY3lNbFpFTTFwSldEaFlXVFpGT0RVMU5UZEJTa2hXVlVWWVNTSXNJblI1Y0dVaU9pSkJVRWtpTENKMFpXNWhiblJmYVdRaU9pSXhOamt5TmpFd01EUTVJbjA9Il0sImlzcyI6Imh0dHBzOi8vaGVsaXh0cmlhbC1lbWVhLTgtZGV2LWlyMS5vbmJtYy5jb20iLCJ0eXBlIjoiUkVGX1RPS0VOIiwiZXhwIjoxNjI3MDUyMjk3LCJpYXQiOjE2MjY5NjU4OTcsImp0aSI6ImM3NWY2MTEwLTc4YWMtNDVhYi05ZjUxLWJlNWUzMzdkMWEwOSJ9.LYfVbk_dyGUuGcwGzlHXSL71sFc5H_wXK2xXT5uDNHamN6p-qwHkRqHvjjboDYleBGBp8O8AMGNYP765xYDy-wWXOLLeKFv3TTL-Gcui5xPuGNx6T4EnNwho0D4_uM4mnWNJ-8uxI5Y7cectzwtlH5J6aHABUetRoE6Wquk9PnurqCdOpyPgOUTR2FVGbD3LvrTzAHpmoCpJyxJYGFR1HMT9FKv6QQTl5uDCIGZDkDc88YpL45-fFo8cswRUVeTIhRBByTlv1-6X5ZS9wfuej37FTatgtV13uOIpdjymWW-OhyqjXZEZwoCpKUYvG2toM-gG-UZyEFF8lYKQteKuQw","json_web_token":"eyJraWQiOiI3OWVlYjdmMy04M2UxLTRkM2YtODQ2MC1hOGJlMDNkODMzMmMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiIxNjkyNjEwMDQ5Ojo0OTU5NDIwOTU3MjkyNjUiLCJhdWQiOiJibWNfYWRlX2Nsb3VkX3NlcnZpY2VzIiwiYW1yIjpbImV5SjFjMlZ5WDJsa0lqb2lORGsxT1RReU1EazFOekk1TWpZMUlpd2lZV05qWlhOelgydGxlU0k2SWtsUFZqY3lNbFpFTTFwSldEaFlXVFpGT0RVMU5UZEJTa2hXVlVWWVNTSXNJbkJ5YVc1amFYQmhiRjlwWkNJNklrbFBWamN5TWxaRU0xcEpXRGhZV1RaRk9EVTFOVGRCU2toV1ZVVllTU0lzSW5WelpYSmZjM1JoZEhWeklqb2lSVTVCUWt4Rklpd2lkSGx3WlNJNklrRlFTU0lzSW5SbGJtRnVkRjlwWkNJNklqRTJPVEkyTVRBd05Ea2lMQ0p5YjJ4bGN5STZXeUk0T1RBNE5ERTVNVFk1TWpFMU5qa2lYU3dpWjNKdmRYQnpJanBiSWpNd05ESTFOVFkxTURVMU1qa3pOaUpkTENKd1pYSnRhWE56YVc5dWN5STZXeUlxSWwxOSJdLCJpc3MiOiJodHRwczovL2hlbGl4dHJpYWwtZW1lYS04LWRldi1pcjEub25ibWMuY29tIiwidHlwZSI6IkFDQ0VTU19UT0tFTiIsImV4cCI6MTYyNjk2Njc5NywiaWF0IjoxNjI2OTY1ODk3LCJqdGkiOiJlNTY2NmI2My03Y2RjLTQwMmQtYjM4My02MGNlMGM4NmZhMmYifQ.P3kSxxCHDPoCC-rhd9nvmIvXeVE4eEtwpHonwmP9eF2Ja1S2_NHgIcXv50kSwmXHqKNWBSFeLRVI72SlRYuebPRuQO3wWxXczhi0lIKDHjj9FrIlOyDjfiUnen_-GGdXnK1uL3myIZAw6LjqJor-hNLu24VMM4g0mT6wI1njXbaF8PwtAWaMDyxe9kOl6nHVjZxvgEkRUsyeGptGE2Udl_Vl3oLMcYaft_5zy-J46QjFEzsuXCqZ_knYEDtLeJBNo4IpXv_eWTfkITZOdu3xxMREbl2YMS0oaJQkfU02WqkI6TCCbxdecSoxdyFvJBsaSAFi8A3Hh-_Z2PLMtjnMlg"}

 

 

3. To create the Helix classes that the Entuity integration will use:

The Entuity integration uses the following Helix custom classes:

  • ENA_EV for events.
  • ENA_INC for incidents.
  • CHANGE_EV for configuration monitoring/management events.

These classes must be created before Entutiy is configured to forward data, and class creation is currently undertaken using curl. Once the Helix custom classes for ENA_EV, ENA_INC and CHANGE_EV have been created, they do not need to be created again.

The following example script is used to POST a class creation definition to Helix for ENA_EV. To create the class definition for ENA_INC or CHANGE_EV, simply replace ENA_EV in the script as appropriate.

#!/bin/bash

LB=$1
jwtToken=$2

curl --insecure --header "Content-Type: application/json" --header "Authorization: Bearer $jwtToken" --request POST --data '{"name": "ENA_EV", "parentClassName": "EVENT", "attributes": [ { "name": "ENA_description", "dataType": "STRING", "default": "Unknown", "enum": false, "allFacet":[ ] }, { "name": "ENA_details", "dataType": "STRING", "default": "", "enum": false, "allFacet":[ ] }, { "name": "ENA_event_key", "dataType": "STRING", "default": "", "enum": false, "allFacet":[ ] }, { "name":"ENA_timestamp", "dataType":"DATE", "default":"0", "enum":false, "allFacet":[ ] }, { "name":"ENA_severity", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, { "name":"ENA_state", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, { "name":"ENA_object", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, { "name":"ENA_object_type", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, { "name":"ENA_object_id", "dataType":"STRING", "default":"0", "enum":false, "allFacet":[ ] }, { "name":"ENA_object_source", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, { "name":"ENA_event_source", "dataType":"STRING", "default":"", "enum":false, "allFacet":[ ] }, {"name":"object","dataType":"STRING","default":"","allFacet":[],"enumElements":[],"enum":false}, {"name":"object_class","dataType":"STRING","default":"","allFacet":[],"enumElements":[],"enum":false}, {"name":"object_id","dataType":"STRING","default":"","allFacet":[{"name":"read_only","value":"true"}],"enumElements":[],"enum":false} ] }' https://$LB:443/events-service/api/v1.0/events/classes

 

To list (GET) the Helix class properties:

You can use a GET script to list the properties of a Helix class. You will need to provide as parameters the Helix server, the JWT authorization token, and the class name.

~!/bin/bash
LB=$1
jwtToken=$2
className=$3

curl --insecure --header "Content-Type: application/json" --header "Authorization: Bearer $jwtToken" --request GET https://$LB:443/events-service/api/v1.0/events/classes/$className?idType=name

A successful response will start as follows, with the class ID being useful (highlighted here in bold):

{"responseTimeStamp":1627895824584,"statusCode":"200","statusMsg":"[Event Class found successfully for specified ID or Name.]","eventClass":{"id":"14bf54a1-f05d-11eb-a632-816591350d7d","name":"ENA_INC","parentClassName":"EVENT","childClassNames": ..........

 

To delete (DELETE) a Helix class property:

You can use a DELETE script to delete a Helix class. You will need to provide as parameters the Helix server, the JWT authorization token, and the class name.

#!/bin/bash
LB=$1
jwtToken=$2
classId=$3
curl --insecure --header "Content-Type: application/json" --request DELETE --header "Authorization: Bearer $jwtToken" https://$LB:443/events-service/api/v1.0/events/classes/$classId

 

 

4. To specify the Entuity configuration file Helix.cfg:

You will need to specify the BHOM host and path under which the JSON objects will live on BHOM.

Navigate to the Helix.cfg file and enter the following (this is for the example Helix server helixtrial-emea-8-dev-ir1-onbmc.com):

[default]
port=443
proto=https
trust=0
host=helixtrial-emea-8-dev-ir1.onbmc.com
path=/events-service/api/v1.0/events

If you are using the previous version of the Entuity integration with BMC Helix, the specification is as follows:

[default_v1]
port=443
proto=https
trust=0
host=hmbeta.bmcclm.com
path=/tsws/api/v1.0/events

 

 

5. To configure Entuity to send data to BMC Helix:

  1. Within the Entuity installation etc directory, locate the file Helix-example.cfg, and copy it to the file Helix.cfg (which is also in the Entuity installation etc directory).
  2. Edit the Helix.cfg file to configure the desired connection parameters. You can do this by either editing the [default] section, or creating a new section as a copy of the default one. Next you will need to complete its values (in particular, the required change to the example is to provide the name of the Helix server as the value of the host variable), and then name it in the EMS Send to BMC Helix Action parameter 'cname'.
  3. The eventEngine process must then be restarted. You can do this by stopping and starting Entuity, or from the ENA_INSTALL/bin directory, using the following command: 
    ./stop eventEngine
  4. To forward the content of Entuity events to Helix, you will need to navigate to the Rules tab of the Event Administration page, and create a new rule that contains the action step 'Send to BMC Helix':

    rule1.png

    rule2.png

    rule3.png

    Edit the action step by setting the value of the apiKey parameter to that of the API Key retrieved from the Helix server (see section 1 above - To obtain the Helix user account API Key and Tenant ID).

    rule4.png

    rule5.png

  5. To forward the content of Entuity incidents to Helix, you will need to navigate to the Incidents tab of the Event Administration page, and create a new trigger that contains the action step 'Send to BMC Helix':

    rule8.png

    rule7.png

    rule6.png

    As with the event process above, you will need to edit the action step by setting the value of the apiKey parameter to that of the API Key retrieved from the Helix server.

Related articles

Comments

0 comments

Please sign in to leave a comment.