Open Integration Manager

The Open Integration Manager enables you to create custom inbound alert integrations through an intuitive UI.

The Open Integration Manager enables you to create custom inbound alert integrations through the configuration of a generic inbound integration rather than creating custom code. The integration manager sets parsing rules for incoming payloads, pre-processing the content to match incoming data requirements before it reaches the BigPanda enrichment engine.

Key Features

Features:

  • Modify existing standard integrations
  • Create custom integration for any incoming tool leveraging the alerts API
  • Tag mapping enables systems to send native payloads, reducing necessary tool configuration
  • Editable fields include:
    • Timestamps
    • Status
    • Deduplication Logic
    • Additional Primary / Secondary Properties
    • Custom tags

Users can map payload fields to BigPanda tags, select fields and tags to populate key values such as Status and Primary tag, and preview sample alerts based on the configuration settings.

Ideal for monitoring tools and systems that do not support customizing REST API payloads, the open integration manager creates integrations that normalize payload data to ready it for the BigPanda enrichment engine.

👍

The Open Integration Manager is able to read multiple alerts from a single payload, as configured in Tag Mapping

For more information about the Open Integration Manager, see the BigPanda University Open Integration Manager and Email Parser Course.

Install the Integration

Administrators can install the integration by following the on-screen instructions in BigPanda.

The Open Integration Manager is available for these integrations:

  • Prometheus
  • SolarWinds
  • ThousandEyes
  • Zabbix
  • REST API
REST API Open Integration Manager logoREST API Open Integration Manager logo

REST API Open Integration Manager logo

Add OIM to existing Integrations

To use the Open Integration Manager for an OOTB integration that is already set up in BigPanda, the endpoint/destination URL must first be updated. Depending on the integration, you will need to either reinstall the integration or adjust the configuration. Updating the endpoint will NOT change the tag keys and values that are sent to BigPanda until you make updates to the configuration.

🚧

Caution While Editing

Changing property names within OIM can cause unintended consequences with Enrichment, Correlation, and Environments.

REST API integrations cannot have OIM enabled after initial configuration. To use OIM with a REST API integration create a new integration using the OIM REST API.

Authentication

The Open Integration Manager offers additional flexibility with authentication parameters. The following syntax can be used for the Token and App Key:

Auth Token:
query string: access_token=<token>
header: Authorization: Bearer <token>
header: x-auth-token: <token>

App Key:
query string: app_key=<app_key>
header: x-app-key: <app_key>
header: app_key: <app_key>
body: { "app_key": "<app_key>" }

This means that an alert can be sent to BigPanda even if the monitoring tool is not able to include any information in the API call's header, like in the example below:

https://integrations.bigpanda.io/oim/api/alerts?access_token=xxx&app_key=xxx

Tag Manager

There are four configurable rules to customize payload processing.

Tag Mapping

Payload fields can be mapped to BigPanda alert tags. Each matched field will be processed into BigPanda tags used for enrichment, normalization, and deduplication.

Additional tag mapping can be added to accommodate the full list of enrichment values to add to the event.

Tag names must:

  • Start with a letter from a to z
  • Max 64 characters
  • Contain only lowercase leters (a-z), numbers (0-9), underscores ( _ ) and hyphens ( - )
  • Cannot include spaces

The Payload contains multiple alerts toggle enables you to select a field that is an array of alert JSON objects. Toggling this feature on will present you with a dropdown list of available fields. Select the field name of the object array. The fields listed will be populated by the sample payload. Add a sample payload with the desired array field to have it appear in the dropdown.

If a tag contains nested JSON objects (one tag contains multiple pieces of relevant information), the user can choose to which properties to include depending on the way the configuration is set up.

The Ignore any tag not mapped above toggle controls whether only the desired fields are included in alerts. Users may click this toggle off to list specific fields that should be ignored. Any fields that do not map to BigPanda tags and are not ignored will be included in the alert.

Primary and Secondary Properties

Two tags are identified as the Primary and Secondary properties within BigPanda. Primary and Secondary properties are key data fields that function as the main name for alerts and drive correlation and deduplication. Ensure that the fields that map to the BigPanda tags marked as primary or secondary are included in all payloads. You can identify any tag as either Primary or Secondary properties by clicking the three dots icon to the right of the BigPanda Tag Name field.

BigPanda cannot receive events without a primary_property.

Add Multiple Source Tags

Multiple source tags can be used for a single BigPanda tag, with the first tag populated defining the value. When listing multiple source tags, the tags run in the order they appear in the editor. Drag and drop source tags in the tag manager fields to rearrange the run order.

For example:

If two source tags, host and device, are listed, the system will first check for the host field in the payload. If there is a value for host, this value will set the BigPanda tag value. If host is empty, the system will then check for the device field.

Example Multiple Source MappingExample Multiple Source Mapping

Example Multiple Source Mapping

If all source tag fields are empty, the system will use a default value if defined.

Status Mapping

BigPanda alert statuses are determined by specific incoming tag values. Alert Incident status determines several system events and is necessary for closing resolved alerts. Read more about alert status in the Alert/Incident Status documentation.

In the Status Mapping fields, list payload values to map to each BigPanda event status. These must be an exact match, meaning that if ‘warn’ is in the value mapping, an alert message with ‘warned’ will not be matched. If there are multiple tags that can determine an alert's status (severity, statusExtended, etc.), tags will be evaluated against all mapping values in listed order until a match is found or all tags rules have run.

One status will be selected as ‘Default’. If an alert payload does not match any listed status values for any of the specified tags, this status will be applied.

Event Timestamp

Event time can be set automatically by BigPanda or by a payload field.

By default, all custom integrations created through the Open Integration Manager use the time the event entered BigPanda.

If the event instead uses a time tag, the source tag and format can be configured to match the event time field.

Event Deduplication Tags

To eliminate redundant data and reduce noise, BigPanda creates an incident identifier for each incoming event.

By default, this identifier is created using the primary and secondary property tags.

📘

We recommend keeping the default setting for the incident identifier. Changing this setting can create a mismatch between alerts reported through different integrations and may result in duplicate incidents or alerts that fail to resolve properly.

Preview Tag Settings

The Preview pane enables you to view sample BigPanda alerts as they would be generated using the configuration settings and an example event payload.

Previewing Tag ResultsPreviewing Tag Results

Previewing Tag Results

To preview a sample alert using the existing settings:

  1. At the top of the Tag Manager, click Manual Payload
  2. In the window, paste or type to add a sample JSON payload
  3. Click Create Sample Alert(s)

In the preview pane, sample alerts appear individually, with values populated based on the tag mapping configuration.

The sample alert values will update automatically whenever you make a change to the configuration in the left panel.

BigPanda will soon add support for generating previews based on actual alerts. For now, if your tool does not generate event previews, we recommend using a third party tool like webhook.site to copy sample events into BigPanda.

Once you are ready to send alerts to BigPanda, send an alert to the endpoint specified in the installation instructions. Alerts sent to BigPanda through the OIM will time out if no response is received in 30 seconds. A failed alert will attempt to retry up to 3 times unless there are payload errors that will prevent it from processing.

Edit the Integration Configuration

Administrators can change the configuration settings of integrations at any time within BigPanda.

To open the Integration Manager:

  1. Navigate to the Integrations Tab
  2. Select the integration from the list
  3. Click Review Instructions
  4. Select the Integration Manager tab
  5. Preview results by clicking View Sample Alerts
  6. Make any desired changes

🚧

We recommend testing configuration changes using test alerts and the preview panel before finalizing changes to an integration configuration.

Delete the Integration

Deleting an integration requires changes to both the integrated system and BigPanda. You must uninstall the integration on the integrated system and then delete the integration from BigPanda.

🚧

When replacing an existing integration with a new tool or system, we recommend configuring the new integration first to ensure no data is lost.

Stop Sending Data to BigPanda

On the integrated system, disable any settings that send data to BigPanda.

Manually resolve any open alerts sent from the integration to remove the associated incidents from your incident feed. These incidents will not automatically resolve without an ok status from the original sending integration.

Delete the Integration from BigPanda

  1. In BigPanda, navigate to the Integrations tab and select the desired integration from the list.
  2. In the integration details on the right, click Delete Integration. A support message opens, pre-populated with a request to delete the selected integration.
  3. Press Enter to send the request.
  4. The BigPanda support team will remove the integration from the UI.