Manage Mapping Enrichments

Mapping enrichment lets you upload a CSV table that maps tag values to enrichment results. When an incoming alert matches a value in a query column, BigPanda writes the corresponding result column value to the alert. You configure and maintain mapping enrichment through the v2.1 Alert Enrichment API.

Use the v2.1 routes
The v2.1 mapping-enrichment routes replace the earlier /enrichments (v2.0) paths. Use v2.1 for all new mapping enrichment work.

How mapping enrichment works

A mapping enrichment is made up of two parts:

Mapping schema: Defines how BigPanda interprets the table — the map name, the condition that controls when the map runs, which columns are lookups, which columns are results, and override behavior.

Mapping table: The CSV data that populates tag values. The table does not have to be fully populated on first upload, but it must include headers for every column.

Each column is either a query_tag (matched against the incoming alert) or a result_tag (written to the alert when a row matches). Mapping items are added automatically to existing tags when a result_tag column name matches an existing tag. If no tag matches, BigPanda creates a new tag for the enrichment item.

Before you start

All Alert Enrichment routes require User API Key authorization. Pass the key in the Authorization header as Bearer <your_user_api_key>.

The base URL for US instances is https://api.bigpanda.io.The base URL for EU instances is https://eu-api.bigpanda.io.

Map reuploads must match the existing schema, with the same column headers used on the first upload.

Endpoint reference

All routes require User API Key authorization.

Method	Route	Purpose
`POST`	`/resources/v2.1/mapping-enrichment`	Create a mapping schema
`GET`	`/resources/v2.1/mapping-enrichment`	List all mapping schemas
`GET`	`/resources/v2.1/mapping-enrichment/<mapschema_id>`	Retrieve one mapping schema
`PATCH`	`/resources/v2.1/mapping-enrichment/<mapschema_id>`	Update schema status, condition, or description
`DELETE`	`/resources/v2.1/mapping-enrichment/<mapschema_id>`	Delete a mapping schema
`POST`	`/resources/v2.1/mapping-enrichment/<mapschema_id>/map`	Upload the map table as CSV
`GET`	`/resources/v2.1/mapping-enrichment/<mapschema_id>/map`	Retrieve the map table (paginated)
`PATCH`	`/resources/v2.1/mapping-enrichment/<mapschema_id>/map`	Create, update, or delete individual rows
`GET`	`/resources/v2.1/alert-enrichments-jobs/<job_id>`	Check the status of an upload or update job

Step 1: Define the mapping schema

Create the schema that describes your table structure. For each CSV column, set type to query_tag or result_tag and name the BigPanda tag it reads from or writes to.

Send a POST request to /resources/v2.1/mapping-enrichment:

Schema fields

Field	Type	Description
`type`	string	Set to `mapping` for a mapping enrichment.
`active`	boolean	Whether the schema is enabled.
`when`	object	A BigPanda Query Language (BPQL) object that controls when the map runs.
`config.name`	string	The map name.
`config.fields`	array	One object per CSV column.
`config.fields[].title`	string	The column header as it appears in the CSV.
`config.fields[].type`	string	`query_tag` to match incoming alerts, or `result_tag` to enrich them.
`config.fields[].tag_name`	string	The BigPanda tag the column reads from or writes to.
`config.fields[].override_existing`	boolean	Whether a result value overwrites an existing tag value.
`config.case_insensitive`	boolean	Match query values without case sensitivity.
`config.id_generation_function`	string	Row identity function, for example `use_md5`.

Copy the id value from the response body. You use it as <mapschema_id> to upload and maintain the table.

Step 2: Upload the mapping table

Upload the table as a CSV file. The CSV must follow the structure you defined in Step 1 and use the same column headers.

Send a POST request to /resources/v2.1/mapping-enrichment/<mapschema_id>/map with a text/csv body:

The request starts an asynchronous job and returns a job object so you can track progress. Copy the trigger_uri value from the response to check the status in Step 3.

End the payload with an empty new line
The CSV payload must end with an empty new line, and there must be no spaces before the closing quotation marks on the last line.

Add enrichment flag columns for analytics
To visualize enrichment rates accurately in Unified Analytics (UA), include two enrichment flag columns in the CSV: an enriched column with true or false in each row, and a <map name> column with enriched in each row to apply the enriched quality to any alert matched on the map.

Step 3: Verify the job

Confirm the upload finished before relying on the map.

Send a GET request to the trigger_uri you copied, which resolves to /resources/v2.1/alert-enrichments-jobs/<job_id>.

Confirm the response status shows the job completed successfully. The job object returns status, job_id, and trigger_uri.

(Recommended) Send test alerts through the Alert API to confirm the enrichment works as expected.

Resolve any test alerts as needed.

Step 4: Maintain the mapping table

How you update a map depends on what you need to change.

Replace the entire table

To replace all rows but keep the same structure, repeat Step 2. The new upload overwrites the existing table.

Change individual rows

To add, update, or remove specific rows, send a PATCH request to /resources/v2.1/mapping-enrichment/<mapschema_id>/map. Set op to the operation and value to the row data:

`op`	Effect	`value` requirement
`create`	Adds a new row. Fails if the row already exists.	Every column in the row.
`update`	Modifies an existing row.	Every column in the row.
`delete`	Removes an existing row.	Only the query or key fields.

Each row change starts an asynchronous job. Verify it with Step 3.

Change the table structure

After a schema is created, you can edit only its status (active), condition (when), and description (note). To change mapping fields, create a new schema.

Deactivate the existing schema by sending a PATCH request to /resources/v2.1/mapping-enrichment/<mapschema_id> with active set to false:

Create a new mapping enrichment, starting from Step 1.

Dependencies and run order

When one tag or enrichment item depends on the result of another, order matters. BigPanda runs tags and enrichment items in the order they appear in the UI, so a dependent item must sit below its source item in the enrichment order.

Results can vary between runs in some dependency cases. For example, if a tag value arrives in the original payload, a dependent tag uses that original value rather than a value produced during enrichment.

Normalize values with overrides
Map overrides keep tag values consistent even across systems with different data models. Set override_existing to true on a result_tag column to normalize its value on every match.

Best practices

Keep query columns minimal and specific so matches stay predictable.

Test with sample alerts after every upload or row change before relying on the map in production.

Use a separate schema per logical data source rather than overloading one map.

Include the enrichment flag columns from the start if your team tracks enrichment rates in Unified Analytics (UA).

How mapping enrichment works#

Before you start#

Endpoint reference#

Step 1: Define the mapping schema#

Schema fields#

Step 2: Upload the mapping table#

Step 3: Verify the job#

Step 4: Maintain the mapping table#

Replace the entire table#

Change individual rows#

Change the table structure#

Dependencies and run order#

Best practices#