The Open Integration Manager enables you to create customizable 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

• Modify existing standard integrations
• Create a customized 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
  • Filter Logic

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:

• AppDynamics
• Azure Monitor
• CloudWatch
• Cribl
• Datadog
• Dynatrace APM
• Entuity
• Grafana v8+
• LogicMonitor
• LogScale
• Nagios
• New Relic
• OpsView v6+
• Prometheus
• ScienceLogic
• SCOM (Microsoft System Center Operations Manager)
• SiteScope
• SNMP
• SolarWinds
• Splunk
• SQL Sentry
• Sumo Logic
• ThousandEyes
• Tivoli EIF
• VMware Aria Operations
• Zabbix
• REST API

🚧

After first creating an OIM-enabled integration in the BigPanda UI, ensure that the integration configuration has been saved and wait five minutes before sending alerts via the integration. Alerts sent immediately after saving an integration within the UI may not be successful.

Add OIM to existing Integrations

To use the Open Integration Manager for a standard 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 letters (a-z), numbers (0-9), underscores ( _ ) and hyphens ( - )
• Cannot include spaces

📘

Null Values

OIM automatically removes null values, empty strings, empty objects, and empty arrays from payloads received.

Force Lowercasing

The Lowercase created tag name toggle lets you automatically convert all tag names to lowercase. This keeps tags consistent throughout BigPanda, regardless of the capitalization from ingested tags.

Create Multiple Alerts

The Create multiple alerts using toggle enables you to select a field that is an array of alert JSON or XML 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 test payload with the desired array field to have it appear in the dropdown. Alternatively, you can use one of the 10 events most recently sent to the integration to configure your tag mapping. This applies for both new and existing OIM integrations.

If a tag contains nested JSON or XML objects (one tag contains multiple pieces of relevant information), the user can choose 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.

Tag Normalization Suggestions

📘

The Tag Normalization Suggestions feature is currently only available for organizations who the BigPanda platform onboarded in 2023 or later.

Before low-quality alerts can be turned into high-quality alerts, they all must speak the same language.

Unfortunately, each monitoring tool has a unique format and terminology to describe IT elements. This makes it hard for IT Ops teams to consume their data in a consistent manner, and even harder for them to glean valuable insight from this data.

BigPanda tag normalization standardizes the language tools are speaking, right at ingestion for each individual integration.

To help you find the ideal tag normalization, BigPanda automatically presents standard tag name and mapping suggestions during OIM tag mapping. These recommendations are based on the BigPanda machine learning engine and our deep knowledge of successful Incident Intelligence. Leveraging industry best-practices, these suggestions are geared to maximize correlation and your team’s ability to respond to incidents.

Suggestions will appear automatically in the tag mapping fields and will be marked with a purple icon.

Hover over a suggestion to view a description of the tag.

To reject a tag suggestion, click the X in the right-hand corner of a suggested tag. A confirmation window appears. Select Remove Suggestion to reject the suggested tag, or Cancel to keep the suggested tag.

🚧

Removing a tag suggestion will clear all BigPanda suggested tags for that field. We recommend using one of the suggested tags whenever possible.

Suggested Destination tag names can be changed right in the Integration Manager screen. Select the tag you would like to change, make the edit, and click Save.

When you change the name of a suggested tag, BigPanda will remember your name preference. The next time you configure an integration, BigPanda will suggest the new tag name instead.

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, event 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 select these properties within the Primary and Secondary Properties step in the Integration Manager configuration.

🚧

OIM integration configuration defines Primary and Secondary properties based on Destination tags rather than Source tags.

❗

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.

If all source tag fields are empty, the system will use a default value if defined. See the Open Integration Manager Advanced Configuration documentation for details on how to use the Advanced Tag Mapping Options.

Array Flattening

By default, BigPanda flattens array objects. When flattened, each element within the array is sent as a separate tag in the event payload.

For example, an array like "annotation":["description1","summary1"] would send two tags when flattened: "annotation_0":"description1" and "annotation_1":"summary1".

If you select a tag within Tag Mapping and disable the Array Flattening toggle, the tag value will be sent to BigPanda as an array rather than separate tags.

🚧

Array Flattening UI Toggle

The Array Flattening toggle only appears in the UI if the selected tag is an array object.

All additional array tags that are sent to BigPanda when the Ignore any tag not mapped above box is unchecked will be flattened.

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

Human Readable Timestamp
You also have the option to include the human-readable timestamp tag bp_timestamp. This tag will display as: bp_timestamp: Tue Mar 19 2024 14:53:57 GMT+0000 (Coordinated Universal Time)

This tag is based on an alert payload's "timestamp" tag, as defined in the Event Timestamp step. If there’s no timestamp field in the payload, bp_timestamp will be the received time.

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.

Event Filtering

The Event Filtering section uses the same BigPanda Query Language as the rest of the BigPanda platform. Any events that meet the defined criteria will be dropped upon ingestion and never visible in the Incident feed.

This feature should only be used as a garbage filter for events that can never be actionable and would only add clutter in BigPanda. Below are some examples:

• Misconfiguration (certain tags that are critical for assignment and prioritization are missing)
• Lowest severity (we already know that it won’t be actionable and contains no signal)
• Events from Dev/QA environments
• Non-alerts (info, logs, etc.)

Keep in mind that the syntax used here is based on the tags included in the event payload (Source Tags, not Destination Tags). If two different types of events from your monitoring tool use different tag names, be sure to include both in your filter criteria. The Query Assist feature will provide guidance based on your sample event payloads and recently delivered events.

📘

If you are using an array of alerts, you will need to use the @alert.<tag> syntax. For example, your filter criteria could be something like: @alert.error_code="sdwan-datapath-down".

Preprocessing Functions

Before being ingested into BigPanda, the Open Integration Manager performs preprocessing functions on some complex integrations. This allows the data to be mapped appropriately to tags in BigPanda. Visibility into these functions is available within OIM by clicking the Settings cog icon.

For more information and a full list of these functions, see the Open Integration Manager Preprocessing Functions documentation.

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.

To preview a sample alert using the existing settings:

1. At the top of the Tag Manager, click Test Payload
2. In the window, paste or type to add a sample JSON or XML 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.

Recent Payloads View

BigPanda is able to generate event previews and configure tag mappings based on actual alerts. To generate a sample payload, use the integrated tool to send a test event to BigPanda after integration installation, but before configuration. All payload fields to be referenced in the configuration settings must be included in the sample. The 10 events most recently sent to the integration can be used to configure your tag mapping.

To use this configuration option, go to the Event Preview section and click the Recent Payloads View button to switch from configuring based on the Test Payload to the Recent Payloads View. You will see No recent payloads available if no events have yet been delivered to an integration.

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.

📘

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

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.