OIM Configuration Object v1

Defines the schema for the configuration of OIM settings.

Open Integration Manager v1 Configuration

The Open Integration Manager v1 API Configuration should only be used by customers who onboarded the BigPanda platform prior to 2023.

In the future, we plan to make v2 available to customers that were onboarded prior to 2023. An upgrade will not be required and both configuration versions will continue to be supported.

API Endpointhttps://integrations.bigpanda.io/configurations/alerts/oim/<app_key>
Supported MethodsPOST, GET

OIM Config Object

The OIM Configuration object schema includes the following attributes:

ParameterDescriptionType
is_arrayWhether the payloads sent to the integration should be treated as single alerts, or multipleBoolean
array_sourceDefines which payload property contains the tag values if is_array=true ?String
statusLookup rule to set the event status

Attributes:
source - Array of payload fields to match
default_to - The value to populate if no matches are found
status_map - Array of value matches for each BigPanda status
Object
primary_propertyMapping rule for the primary property

Attributes:
name - (Optional) Set a name for the tag in BigPanda
source - Which payload fields should populate the value
default_to - (Optional) Value if one cannot be extracted
flatten - (Optional) Whether or not to flatten a nested object for improved mapping
Object
secondary_propertyMapping rule for the secondary property

Attributes:
name - (Optional) Set a name for the tag in BigPanda
source - Which payload fields should populate the value
default_to - (Optional) Value if one cannot be extracted
flatten - (Optional) Whether or not to flatten a nested object for improved mapping
Object
timestampObject that defines mapping rules for the timestamp property

Attributes:
source - Which payload fields should populate the value
Object
bp_timestampDefines an optional tag to add a human-readable timestamp.

Attributes:
is_selected - true or false
Object
event_filterA BPQL statement that dictates which events should be dropped upon initial ingestion (using Source Tags)String
additional_attributesArray of payload field objects to set mapping rules for additional tags

Tag Map Attributes:
name - (Optional) Set a name for the tag in BigPanda
source - Which payload fields should populate the value
default_to - (Optional) Value if one cannot be extracted
flatten - (Optional) Whether or not to flatten a nested object for improved mapping
advanced_options - Additional rules to enable variable values based on incoming payload content. Leverages conditions to filter when the values will apply and regex_patterns**** to calculate the value to apply.
Array of Objects
map_remainingWhether to create tags from fields not included in the mapping rules.Boolean
incident_identifierOptional override for the incident identifierArray
force_lowercase(Optional) Automatically converts all destination tag names in payload to lowercase.Boolean

Sample Object:

{
      "config": {
        "is_array": true,
        "array_source": "alerts",
        "status": {
          "source": [
            "@alert.status",
            "@alert.labels.severity"
          ],
          "default_to": "critical",
          "status_map": {
            "critical": [
              "page",
              "critical"
            ],
            "warning": [
              "warn",
              "warning"
            ],
            "acknowledged": [
              "acknowledged"
            ],
            "ok": [
              "resolved"
            ]
          }
        },
        "primary_property": {
          "source": [
            "@alert.labels.instance",
            "@alert.labels.job",
            "@alert.labels.alertname"
          ]
        },
        "secondary_property": {
          "source": [
            "@alert.labels.monitor",
            "@alert.labels.alertname"
          ]
        },
        "timestamp": {
          "source": [
            "@alert.annotations.timestamp",
            "@alert.startsAt",
            "@alert.endsAt"
          ]
        },
        "bp_timestamp": {
            "is_selected": true
        },
        "force_lowercase": true,
        "event_filter": "@alert.search_name = \"OSS -- MINT Core -- *\"",
        "additional_attributes": [
          {
            "source": ["@alert.startsAt"]
          },
          {
            "source": ["@alert.endsAt"]
          },
          {
            "source": ["@alert.generatorURL"]
          },
          {
            "source": ["@alert.annotations"],
            "flatten": true
          },
          {
            "source": ["@alert.labels"],
            "flatten": true
          },
          {
            "source": ["@alert.fingerprint"]
          },
          {
              "name": "region",
              "advanced_options": [
                  {
                      "conditions": "@alert.host = \"abc\"",
                      "source": "@alert.geo",
                      "regex_patterns": [
                          "(^[^-]+)"
                      ]
                  },
                  {
                      "conditions": "@alert.host = \"123\"",
                      "source": "@alert.geo",
                      "regex_patterns": [
                          "([^-]+$)"
                      ]
                  }
              ],
              "source": [
                  "@alert.geo",
                  "@alert.geo"
              ]
          }
        ],
        "map_remaining": false,
        "incident_identifier": [
                "application",
                "cluster"
            ],
      }

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.

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.

Example Sample Object:

"sample_payload": {
        "alerts": [
            {
                "generatorURL": "https://some-url.io",
                "fingerprint": "123456789",
                "annotations": {
                    "description": "This alert is used to check the CPU utilization of this non-existent server",
                    "runbook_url": "https://runbook.io/cpu-check"
                },
                "startsAt": "2022-07-05T19:59:25.661Z",
                "endsAt": "0001-01-01T00:00:00Z",
                "status": "firing",
                "labels": {
                    "severity": "page",
                    "instance": "bigpanda-server",
                    "alertname": "BigPanda Test",
                    "team": "metrics",
                    "env": "test",
                    "job": "CPU Check",
                    "locale": "ca",
                    "timestamp": "1.657051103137505e+09"
                }
            }
        ],
        "commonLabels": {
            "instance": "bigpanda-server",
            "alertname": "BigPanda Test",
            "team": "metrics",
            "env": "test",
            "job": "CPU Check",
            "locale": "ca",
            "timestamp": "1.657051103137505e+09"
        },
        "externalURL": "https://external-url.io",
        "groupLabels": {
            "instance": "bigpanda-server",
            "alertname": "BigPanda Test",
            "team": "metrics",
            "env": "test",
            "job": "CPU Check",
            "locale": "ca",
            "timestamp": "1.657051103137505e+09"
        },
        "receiver": "bigpanda",
        "version": "4",
        "commonAnnotations": {
            "description": "This alert is used to check the CPU utilization of this non-existent server",
            "runbook_url": "https://runbook.io/cpu-check"
        },
        "status": "firing"
    }