Open Integration Manager v2

Use the Open Integration Manager Configuration API to create and manage integration configuration rules for inbound OIM integrations.

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.

Install integration

You must first install an OIM compatible integration before the configuration can be managed. Read more about which integrations can leverage OIM in the Open Integration Manager documentation.

Pre-Configuration

Before leveraging the Integration Configuration API, the integration must be created within the UI. For OIM-enabled integrations, follow the full installation instructions before configuring OIM rules.

Initial delay

After first creating an OIM-enabled integration in the BigPanda UI, wait ten minutes before attempting to create or update rules using the API. POST requests sent immediately after saving an integration within the UI may not be successful.

Make note of the app key as you’ll need it for the API.

Authentication

All BigPanda APIs require Bearer Token Authorization in the call headers.

This API uses the Org Token type of Authorization token.

BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.

Integration Manager

There are four configurable rules to customize payload processing.

Tag Mapping
Status Mapping
Event Timestamp
Event Deduplication Tags

OIM v2 Config Object

The OIM v2 Configuration object schema includes the following attributes:

Parameter	Description	Type
additional_attributes	Array of payload mapping rules for additional tags. See the additional_attributes table for more information.	Object
array_source	Defines which payload property contains the tag values if `is_array=true`	String
is_array	Whether the payloads sent to the integration should be treated as single alerts, or multiple	Boolean
map_remaining	Whether to create tags from fields not included in the mapping rules	Boolean
primary_property	Mapping rule for the primary property Attributes: name - (Optional) Set a name for the tag in BigPanda	Object
secondary_property	Mapping rule for the secondary property Attributes: name - (Optional) Set a name for the tag in BigPanda	Object
status	Lookup rule to set the event status Attributes: default_to - The value to populate if no matches are found source - Array of payload fields to match status_map - Array of value matches for each BigPanda status	Object
bp_timestamp	Defines an optional tag to add a human-readable timestamp. Attributes: is_selected - true or false	Object
event_filter	A BPQL statement that dictates which events should be dropped upon initial ingestion (using Source Tags)	String
timestamp	Object that defines mapping rules for the timestamp property Attributes: source - Which payload fields should populate the value	Object
incident_identifier	Optional override for the incident identifier	Array
version	The version of the OIM API.	String

additional_attributes Object

The additional_attributes object contains the following parameters:

Parameter	Description	Type
isDestinationAccepted	(Optional) Whether the destination tag was accepted	Boolean
isSourceAccepted	(Optional) Whether the source tag was accepted	Boolean
isSuggestion	(Optional) Whether the tag was suggested by BigPanda Tag Normalization	Boolean
name	(Optional) Set a name for the tag in BigPanda	String
source	Array of payload fields to match.	Array of strings
suggestedDestination	Suggested Destination tag name	String
suggestedSources	Array of payload fields to match, for suggested tags	Object
flatten	(Optional) Whether or not to flatten a nested object for improved mapping	Boolean

Default change

As of October 2024, new OIM integrations will not flatten arrays by default. Existing integrations will not be affected by this change. If you would like to turn off array flattening for an integration created before October 2024, please reach out to support to update the array flattening setting.

Example Config Object

    {
      "config": {
        "additional_attributes": [
          {
            "isDestinationAccepted": true,
            "isSourceAccepted": true,
            "isSuggestion": true,
            "name": "check",
            "source": [
             "@alert.labels.alertname",
             "@alert.labels.check",
             "@alert.labels.alert",
             "@alert.labels.sdesc",
             "@alert.labels.short_desc",
             "@alert.labels.title"
            ],
            "suggestedDestination": "check",
            "suggestedSources": [
             "@alert.labels.alertname",
             "@alert.labels.check",
             "@alert.labels.alert",
             "@alert.labels.sdesc",
             "@alert.labels.short_desc",
             "@alert.labels.title"
            ]
           },
           {
            "isDestinationAccepted": true,
            "isSourceAccepted": true,
            "isSuggestion": true,
            "name": "application",
            "source": [
             "@alert.labels.app_name",
             "@alert.labels.application",
             "@alert.labels.app",
             "@alert.labels.impacted_app"
            ],
            "suggestedDestination": "application",
            "suggestedSources": [
             "@alert.labels.app_name",
             "@alert.labels.application",
             "@alert.labels.app",
             "@alert.labels.impacted_app"
            ]
           }
         ],
        "array_source": "alerts",
        "is_array": true,
        "map_remaining": false,
        "primary_property": [
         {
          "name": "host"
         },
         {
          "name": "application"
         },
         {
          "name": "service"
         }
        ],
        "secondary_property": [
         {
          "name": "check"
         },
         {
          "name": "description"
         }
        ],
        "status": {
         "default_to": "critical",
         "source": [
          "@alert.status",
          "@alert.labels.severity"
         ],
         "status_map": {
          "acknowledged": [
           "acknowledged"
          ],
          "critical": [
           "page",
           "critical"
          ],
          "ok": [
           "resolved"
          ],
          "warning": [
           "warn",
           "warning"
          ]
         }
        },
        "bp_timestamp": {
            "is_selected": true
        },
         "timestamp": {
         "source": [
          "@alert.annotations.timestamp",
          "@alert.startsat",
          "@alert.endsat"
         ]
        },
        "event_filter": "@alert.search_name = \"OSS -- MINT Core -- *\"",
        "incident_identifier": [
                "application",
                "cluster"
            ],
    "version": "2.0"
       },

Sample Payload

For field validation, BigPanda checks against an existing sample JSON payload from the integration. For all create calls to the API, a sample must be included in the body of all calls. For update calls to the API, the sample payload field must be included, but can be blank.

All payload fields referenced in configuration settings must be included in the sample.

To generate a sample payload:

Send a test or sample event to BigPanda after integration installation, but before configuration
Generate an event preview in your tool
Manually enter payload field values into the interactive code generator on the BigPanda docs site

When included in the API body, the sample payload should be JSON formatted with double quotes. The payload can include nested objects.

Payload size limit

The payload size limit that OIM can accept is 6 MB.

Sample Payload Object

For field validation, BigPanda checks against an existing sample JSON payload from the integration. For all create and update calls to the API, a sample must be included in the body of all calls.