Skip to Content
This is the latest documentation for BMC Helix Network Management (formerly known as Netreo).

 

OpsGenie Integration for Incident Alert and Acknowledgement

For BMC Helix Network Management to receive API-based incident acknowledgements from OpsGenie, users must send the OpsGenie payloads to BMC Helix Network Management's OpsGenie ITSM Integration API rather than the normal Acknowledgement API. This requires several setup steps beforehand.

  • Configuring OpsGenie
  • Configuring BMC Helix Network Management

Note: BMC Helix Network Management incidents cannot currently be unacknowledged from OpsGenie. De-acknowledging BMC Helix Network Management incidents will need to be done manually, on an as-needed basis.

For API documentation, see OpsGenie ITSM Integration API

OpsGenie Setup

For BMC Helix Network Management to be able to send incident alerts to -- and receive incident acknowledgements from -- OpsGenie, your OpsGenie account must have a team configured for this purpose. This can be an existing team or one specifically dedicated to BMC Helix Network Management.

The team will require two integrations be added to it to work with BMC Helix Network Management.

  • BMC Helix Network Management to OpsGenie - To allow OpsGenie to receive incident alerts from BMC Helix Network Management
  • OpsGenie to BMC Helix Network Management - To allow OpsGenie to send incident acknowledgements to BMC Helix Network Management

Follow the steps below to add these integrations to your OpsGenie team.

  1. Log in to your OpsGenie account.
  2. Select Teams at the top of the page to open the Teams page.
  3. Select the team you wish to use for BMC Helix Network Management integration to configure that team. (If you have not already created a team to use with BMC Helix Network Management, you may do so now by selecting Add Team.)
  4. In the team configuration, select Integrations from the menu on the left.
  5. Add a "BMC Helix Network Management to OpsGenie" integration:
    1. On your team's Integrations page, select the Add Integration button.
    2. Select the API integration type to add it.
      1. Name the integration. (We suggest something easily identifiable like "BMC Helix Network Management to OpsGenie")
      2. Ensure the correct team is selected.
      3. Select Continue.
      4. Select Turn On Integration.
    3. On your team's Integrations page, select the newly added integration to edit it.
      1. In the Integration settings section, select the Edit button.
      2. Ensure the following options are checked:
        • Allow Read Access
        • Allow Create and Update Access
        • Allow Delete Access
        • Allow Configuration Access
      3. Copy the provided API key. (You will need this to configure BMC Helix Network Management later.)
      4. Save your integration.
        • You may leave all other settings at the default or configure as required for your organization.
  6. Now, add an "OpsGenie to BMC Helix Network Management" integration:
    1. On your team's Integrations page, select the Add Integration button.
    2. Select the Webhook type to add it.
      1. Name the integration. (We suggest something easily identifiable like "OpsGenie to BMC Helix Network Management")
      2. Ensure the correct team is selected.
      3. Select Continue.
      4. Select Turn On Integration.
    3. On your team's Integrations page, select the newly added integration to edit it.
      1. Ensure the following alert options are checked:
        • Post to Webhook URL for OpsGenie alerts
        • Alert is acknowledged
      2. In the Integration settings section, select the Edit button.
      3. Ensure the following options are checked:
        • Authenticate with a Webhook account
          • Under webhook URL enter the public-facing URL of your BMC Helix Network Management instance pointing to the BMC Helix Network Management OpsGenie ITSM Integration API (e.g., instanceURL/api/webhook/opsgenie_itsm.php). (The URL to use for a BMC Helix Network Management SaaS deployment is https://netreo.cloud/api/webhook/opsgenie_itsm.php)
          • Under custom headers select Add extra property
            • In the first field, enter Authorization
            • In the second field, enter the base64 encoded hash of your BMC Helix Network Management API credentials (consisting of a username and your BMC Helix Network Management API key for the password) using the basic authorization type (e.g., Basic cGFzc3dvcmRoZXJl'). The username used in the hash is ignored by the API, so it can be anything. Only the BMC Helix Network Management API key is important. (This hash can be created using any API client, such as Postman. Remember to use the basic authorization type when creating the hash.)
            • Select the checkmark to add the header.
          • (If you are using a BMC Helix Network Management SaaS deployment) Under custom headers select Add extra property
      4. Save your integration.
        • You may leave all other settings at the default or configure as required for your organization.

Your OpsGenie account is now set up for incident acknowledgement integration with BMC Helix Network Management using the default OpsGenie webhook payload mapping for incident history display. If you wish to use custom mapping for the OpsGenie payload, see the next section Custom Mapping.

Custom Mapping

This section includes instructions for customizing the incident acknowledgement API call that OpsGenie makes to BMC Helix Network Management's OpsGenie ITSM Integration API to acknowledge an incident.

There are three internal fields in BMC Helix Network Management that are used to display acknowledgement information:

  • incident_id - The ID of the BMC Helix Network Management incident being acknowledged. (By default, BMC Helix Network Management maps the alert.alias value of the OpsGenie webhook payload to this field.)
  • ack_user - The username used to show who acknowledged an incident. (By default, BMC Helix Network Management maps the alert.username value of the OpsGenie webhook payload to this field.)
  • ack_comment - The text to display for an incident acknowledgement comment.  (By default, BMC Helix Network Management maps the alert.message value of the OpsGenie webhook payload to this field.)

If you would like BMC Helix Network Management to use other values from the OpsGenie webhook payload for these fields, the API call made by OpsGenie to BMC Helix Network Management when acknowledging an incident may include additional headers to customize the mapping of these fields. (Customizing these fields requires knowledge of the OpsGenie payload structure. For an example of the OpsGenie payload structure go to https://support.atlassian.com/opsgenie/docs/opsgenie-edge-connector-alert-action-data/)

To customize the mapping for any or all of these fields, follow the steps below.

  1. Log in to your OpsGenie account.
  2. Select Teams at the top of the page to open the Teams page.
  3. Select the team used for BMC Helix Network Management incident acknowledgement to configure the team.
  4. In the team configuration, select Integrations from the menu on the left.
  5. On your team's Integrations page, select the OpsGenie to BMC Helix Network Management integration you created to edit it.
  6. In the Integration settings section, select the Edit button.
  7. For each field you wish to custom map (steps a-d below must be repeated for each field to be remapped):
    1. Under custom headers select Add extra property
    2. In the first field, enter "X-BMC Helix Network Management-FieldRemap"
    3. In the second field, enter the field name (in quotes) you would like to remap and the payload source you would like to map it to (also in quotes) in JSON format (e.g., {"ack_comment" : "$.alert.userId"})
    4. Select the checkmark to add the header.
  8. Save your integration.

The fields you have included headers for will now use the payload source specified as their value in BMC Helix Network Management.

BMC Helix Network Management Setup

First, make sure API access is enabled in BMC Helix Network Management - How to Enable BMC Helix Network Management API Access

To set up BMC Helix Network Management for OpsGenie incident acknowledgement, follow these steps.

  1. Log in to BMC Helix Network Management as a user with the SuperAdmin access level.
  2. Install the OpsGenieAlert action group  from the BMC Helix Network Management cloud library:
    1. From the main menu select Administration >> Alerts >> Actions to navigate to the Actions Administration page.
    2. Select the Actions Cloud Library button to navigate to the Actions Cloud Library page.
    3. Using the search box, search for OpsGenieAlert.
    4. Once located, select the download icon in its ACTIONS column to download and install the OpsGenieAlert action group.
  3. Edit the OpsGenieAlert action group to work with your OpsGenie account:
    1. On the Actions Cloud Library page select the Actions Administration button to navigate to the Actions Administration page.
    2. Locate the OpsGenieAlert action group.
    3. Within the action group, locate the OpsGenie Alert action.
    4. Within the action, locate the "api.opsgenie.com/v2/alerts" webhook method.
    5. Select the Edit Method icon in the method's ACTIONS column to edit the webhook.
      1. In the PAYLOAD field, after "Authorization" replace the text "INSERT CUSTOMER API KEY HERE" with your OpsGenie API key. (Retrieved when creating the BMC Helix Network Management to OpsGenie team integration in the OpsGenie Setup section above.) Do not delete the "GenieKey " part of the text. (The final result should similar to this: "Authorization" : "GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'")
      2. Select the Edit Method button to save the method.

BMC Helix Network Management is now set up to send alerts to your OpsGenie account.

After completing both the OpsGenie setup steps and the BMC Helix Network Management setup steps, BMC Helix Network Management will send incident alert notifications to your OpsGenie account and allow you to acknowledge those incidents from within OpsGenie.

 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Helix Network Management