❗

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.

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.

📘

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.

Relevant Permissions

See the Standard Integrations guide for a full explanation of the permissions required to access the Integrations section and the Open Integration Manager.

To learn more about how BigPanda's permissions work, see the Roles Management guide.

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 in BigPanda before configuring OIM rules.

🚧

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.

📘

Rate Limitations

To maintain quality of service, BigPanda APIs are limited to 5 requests per second.
Additional requests will return a 429 response code and the request will need to be retried.

Tag Manager

There are four configurable rules to customize payload processing.

• Tag Mapping
• Status Mapping
• Event Timestamp
• Event Deduplication Tags

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 letters (a-z), numbers (0-9), underscores ( _ ) and hyphens ( - )
• Cannot include spaces

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, normalization, 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.

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 tag 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.

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.

📘

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

Available Objects & Actions

OIM Configuration leverages the following objects: