Skip to main content

Alert Enrichment V2

Enrichment is the process of adding contextual information to alerts in BigPanda. Use the Enrichments API to define alert tags and enrichment maps that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans.

The Enrichments API allows you to programmatically create custom enrichment maps that add contextual information to alerts.

Define an enrichment schema using these API resources:

  • Alert Enrichments object, which defines the enrichment technique and configuration details associated with that technique. For example, in a mapping enrichment, the configuration details include a description of the data mapping table.

  • Sub-objects that are specific to the enrichment technique. For mapping enrichment, the Map endpoint allows you to upload and maintain a data mapping table.

The API works by evaluating all incoming alerts to see if they match an active enrichment definition. Matching alerts are enriched with the defined alert tags according to the instructions in the enrichment definition.

https://files.readme.io/e37c858-mappingProcess.png

New API version and additional functionality

The Alert Enrichments V2.1 API adds additional functionality and performance to Alert Enrichment API capabilities. When possible, BigPanda recommends leveraging the V2.1 API instead of the V2.0 functionality.

If you have previously configured API management of Alert Enrichment using the V1 or V2.0 API, you can update those processes to the new version.

No additional steps are necessary to configure a new API call using the V2.1 API.

Alert Enrichment 2.0

Authentication

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

This API uses the User API Key type of Authorization token.

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

Example 1. List all alert tags
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/enrichments-config/tags \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/enrichments-config/tags \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 2. List all enrichment items of a tag
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 3. Retrieve alert tag order
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/enrichments-config/tags/host_tag/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/enrichments-config/tags/host_tag/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 4. Retrieve enrichment item order
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 5. Update tag order
curl --request PUT \
     --url https://api.bigpanda.io/resources/v2.0/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
    "alert_tags_order":["wiki", "tagwith2rules"]
}'
curl --request PUT \
     --url https://eu-api.bigpanda.io/resources/v2.0/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
    "alert_tags_order":["wiki", "tagwith2rules"]
}'


Example 6. Update enrichment item order
curl --request PUT \
     --url https://api.bigpanda.io/resources/v2.0/enrichments-config/tags/devicetype/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"enrichment_order": [
		"05092465-94e5-4766-80a4-e619ef370666",
		"ee345677-5cfa-4b65-ba8b-a7615b998777"
	]
}'
curl --request PUT \
     --url https://eu-api.bigpanda.io/resources/v2.0/enrichments-config/tags/devicetype/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"enrichment_order": [
		"05092465-94e5-4766-80a4-e619ef370666",
		"ee345677-5cfa-4b65-ba8b-a7615b998777"
	]
}'


Example 7. Create alert enrichment item
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"type": "mapping",
	"active": true,
	"when": "discard != true",
	"config": {
		"name": "map-test5",
		"fields": [
			{
				"title": "application",
				"type": "query_tag"
			},
			{
				"title": "application1",
				"type": "query_tag"
			},
			{
				"title": "owner",
				"type": "result_tag",
				"override_existing": false
			},
			{
				"title": "Runbook URL",
				"type": "result_tag",
				"tag_name": "wiki",
				"override_existing": false
			}
		]
	},
	"note": "wiki.com"
}'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"type": "mapping",
	"active": true,
	"when": "discard != true",
	"config": {
		"name": "map-test5",
		"fields": [
			{
				"title": "application",
				"type": "query_tag"
			},
			{
				"title": "application1",
				"type": "query_tag"
			},
			{
				"title": "owner",
				"type": "result_tag",
				"override_existing": false
			},
			{
				"title": "Runbook URL",
				"type": "result_tag",
				"tag_name": "wiki",
				"override_existing": false
			}
		]
	},
	"note": "wiki.com"
}'


Example 8. Retrieve alert enrichment item
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/7a649631-1cf7-4dbc-9c9b-64cdc067c555 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/7a649631-1cf7-4dbc-9c9b-64cdc067c555 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 9. Update alert enrichment item
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/11842229-74ac-467c-919c-ea0050b0a710 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"active": false,
	"note": "this is a result tag in the map"
}'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/11842229-74ac-467c-919c-ea0050b0a710 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
	"active": false,
	"note": "this is a result tag in the map"
}'


Example 10. Delete alert enrichment item
curl --request DELETE \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/85b6d236-1b63-424e-9de8-5a58dd33zzzz \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request DELETE \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/85b6d236-1b63-424e-9de8-5a58dd33zzzz \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 11. Create enrichment map table rows
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: text/csv; charset=utf8' \
     --data 'application,owner,Runbook URL
billing23,Bobo Roko,https://acme-wiki.com/billing+SOP
sale24s,Rick Sanches,https://acme-wiki.com/salesapp+SOP
'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: text/csv; charset=utf8' \
     --data 'application,owner,Runbook URL
billing23,Bobo Roko,https://acme-wiki.com/billing+SOP
sale24s,Rick Sanches,https://acme-wiki.com/salesapp+SOP
'


Example 12. Retrieve mapping enrichment
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893755/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893755/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 13. Check status of upload job
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments-jobs/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments-jobs/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741 \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \


Example 14. Update mapping enrichment table rows
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
  "op": "delete",
  "value": {
  	"application": "billing23"
  }
}'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
  "op": "delete",
  "value": {
  	"application": "billing23"
  }
}'curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.0/alert-enrichments/039b5ed9-fe54-4555-b326-438a64861ae9_1615893741/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: application/json' \
     --data '{
  "op": "delete",
  "value": {
  	"application": "billing23"
  }
}'