Skip to main content

How do I integrate Entuity with BMC Helix?

Stuart Hill
Updated

Applicable to Entuity v23.0 P01 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

 

 

To send events and data from Entuity to BMC:

  1. Obtain the Helix user account API Key and Tenant ID.
    The API Key and Tenant ID let you create Helix custom classes and authorize connections from the Helix server.
  2. Obtain the Access Key and Secret Access Key.
    With these access keys, you can 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 uses..
  3. Create the Helix custom classes to be used by the Entuity integration.
  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. Navigate to the BMC Helix server where you can retrieve the API Key.
  2. From Administration, go to Repository, and 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, and then click API keys.

    h1.png

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

    h2.png
     

  4. Use the Access Key and Secret Access Key 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. In this example, the Helix server is 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.

You must use curl to create these Helix custom classes before Entuity is configured to forward data. Once the Helix custom classes for ENA_EV, ENA_INC and CHANGE_EV are 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 must provide the Helix server, the JWT authorization token, and the class name as parameters.

~!/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 starts 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 must provide the Helix server, the JWT authorization token, and the class name as parameters.

#!/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 need to specify the BHOM host and path under which the JSON objects will live on BHOM.

Navigate to the Helix.cfg file, located in the entuity_home/etc directory, 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 an earlier 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:

As of Entuity v23.0 P01, there are two EMS actions for sending data to BMC Helix: 'Send to BMC Helix' and 'Send to Helix Queue'

The 'Send to BMC Helix' action forwards data directly to BMC Helix, while the 'Send to Helix Queue' action forwards data to BMC Helix through a queue from the Message Broker. Sending through a queue helps prevent communication or connection errors during the forwarding process, as messages remain in the queue until successfully acknowledged by the target endpoint. A dedicated message queue log file is also created when using the 'Send to Helix Queue' action. For more information on message queues, see this article.

  1. From the entuity_home/etc directory, locate the file Helix-example.cfg, and copy it to the file Helix.cfg (also in the entuity_home/etc directory).
  2. Edit the Helix.cfg file to configure the connection parameters for your environment.
    You can do this by either editing the [default] section, or by creating a new section as a copy of the default one. Next, 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 enter the section name in the 'cname' parameter of the EMS 'Send to BMC Helix' or, from Entuity v23.0 P01 upwards, 'Send to Helix Queue' action.  

  3. Restart the eventEngine process.
    You can do this by stopping and starting Entuity, or by using the following command at the entuity_home/bin directory:
     

    ./stop eventEngine
  4. To forward the content of Entuity events to Helix, go to the Rules tab of the Event Administration page, and create a new rule that contains the action step 'Send to BMC Helix' or, from Entuity v23.0 P01 upwards, 'Send to Helix Queue'.

    rules_tab.png

    adding a rule

    send_to_helix_queue_add_rule.png
     
    1. If you edited the Helix.cfg file in step 2 with a section name other than [default], set the value of the 'cname' parameter to that section name (without [] brackets). 

      setting cname parameter
       
    2. Set the value of the 'apiKey' parameter to that of the API Key retrieved from the Helix server (see To obtain the Helix user account API Key and Tenant ID).

      rule4.png

      rule5.png
       
  5. If you selected the 'Send to Helix Queue' action step (Entuity v23.0 P01 upwards), choose whether to execute callback actions by optionally using the 'Response Callback' action. Do one of the following:
    • If you want a 'Response Callback' action executed when event and incident data is sent to the Helix server:
      1.  Keep the 'callback' parameter in the 'Send to Helix Queue' action step.
      2. Create a Helix-specific 'Response Callback' action from the Actions tab of the Event Administration page, and define which action to execute upon receiving a response from the Helix server.
      3. Return to the 'Send to Helix Queue' action step in the new rule from the Rules tab (for events) or in the new trigger from the Incidents tab (for incidents) of the Event Administration page.
      4. Enter the name of the newly created 'Response Callback' action as the value of the action step 'callback' parameter.
    • If no 'Response Callback' action is required, go to the Actions tab of the Event Administration page, and remove the 'callback' parameter from the 'Send to Helix Queue' action.

      Note, if events are forwarded through message queues, the 'Set Attribute' option cannot be used as a 'Response Callback' action. However, you can use other options in the 'Response Callback' action, such as 'Create Event'.  

      Keeping the callback parameter

      define_helix_callback.png

      Helix_callback_parameter.png

      If no callback action is required:

      delete_callback_parameter.png
       
  6. To forward the content of Entuity incidents to Helix, navigate to the Incidents tab of the Event Administration page, and create a new trigger that contains the action step 'Send to BMC Helix' or, from Entuity v23.0 P01 upwards, 'Send to Helix Queue':

    incidents_tab.png

    rule7.png
     
    1. Select either the 'Send to BMC Helix' or 'Send to Helix Queue' action step.

      add_action_send_to_helix_queue.png
       
    2. If you edited the Helix.cfg file in step 2 with a section name other than [default], set the value of the 'cname' parameter to that section name (without [] brackets).

      helix_cname_parameter.png
       
    3. As with the event process (from step 4), edit the action step by setting the value of the 'apiKey' parameter to that of the API Key retrieved from the Helix server. 
    4. If you selected 'Send to Helix Queue' in step i, choose whether to invoke callback actions by completing step 5 for the new trigger.

Was this article helpful?

0 out of 1 found this helpful
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.