Defines the schema for the v2 configuration of OIM settings.
Open Integration Manager v2 Configuration
The Open Integration Manager v2 API Configuration should only be used by customers who onboarded the BigPanda platform in 2023 and after.
In the future, we plan to make this available to other customers that were onboarded prior to 2023. An upgrade will not be required and both configuration versions will continue to be supported.
| API Endpoint | https://integrations.bigpanda.io/configurations/alerts/oim/ |
| Supported Methods | POST, GET |
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 |
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 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 Payload
"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"
}