Quick Start

The mapping enrichment technique creates custom tags by looking up values in a data mapping table. You define a mapping enrichment with the Enrichments API by using these resources:

Mapping Enrichment Overview

• Enrichments object—defines the schema for your data mapping table. The schema determines how the information in each column of the table will be used in the enrichment process—as a query field, to match a value in the incoming alert, or as a result field, to enrich the alert.

• Map endpoint—allows you to upload and maintain a data mapping table that follows a given Enrichments schema.

The API works by evaluating all incoming alerts to see if they match an active mapping enrichment. When an alert matches the values in the query fields, it is enriched with the values in the result fields.

Prerequisites

• Obtain the BigPanda token for your organization.
  Administrators can find the token by clicking the Integrations tab, and then opening the instructions for the Alerts API

• Obtain the mapping data that you want to leverage (such as a CMDB, registry, or team spreadsheet).

• (Recommended) Review the overview of enrichment.

Step 1: Define The Mapping Structure

For a mapping enrichment, the Enrichments object defines how the information in each column of the table will be used in the enrichment process:

Query field—to match a value in the incoming alert.

Result field—to enrich the alert.

For example, suppose that certain applications have an owner on the operations team and a standard runbook for remediating common problems. You would create an enrichment schema that maps the application names (query field) to their owners and runbook URLs (result fields).

To define the mapping structure for a new enrichment:

1. Send a POST request to /enrichments.

• Specify the type as mapping.

• For each column in your data table, specify the name and whether to use the values as a query_tag or a result_tag.

• For more information, see Create Enrichment.

• The request creates a new Enrichments object for this mapping enrichment schema.

❗️

This mapping schema is defined for a hypothetical sample environment. You can adapt the values as necessary to meet your infrastructure conventions and the needs of your teams.
Be sure to replace ${token} with the corresponding value for your organization.

2. Copy the id value from the response body. You will use it to identify this schema when you upload and update the mapping data.

Step 2: Upload The Mapping Data

After you create an Enrichments object that defines its structure, you can upload the table of the mapping data. For example, suppose that the Billing and Sales applications both have owners and remediation procedures. You can upload a table with three rows—one row for the column names and one row for each application.

To upload the mapping data for an enrichment:

1. Send a POST request to /enrichments/${id}/map.

• Send the mapping data as comma-separated values (CSV) in the body of the request or in a CSV file.

• Ensure the data follows the structure you defined in Step 1 and has the same column names.

• For more information, see Create Mapping Enrichment Table.

• The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

❗️

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

The payload must end with an empty new line. Make sure there are no spaces before the closing quotation marks on the last line.

2. Copy the trigger_uri value from the response body.
   You will use it to check the status of the upload.

3. Send a GET request to the ${trigger_uri} to verify that the upload has completed successfully.
   For more information, see Check Status of Upload Job.

❗️

Replace ${trigger_uri} with the value you copied from the response body and ${token} with the corresponding value for your organization.

4. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.
   For example, you can run the following command to send matching test alerts via the Alert API. For more information, see POST alerts.

❗️

Replace ${token} and ${app_key} with the corresponding values for your organization.

5. Resolve any test alerts, as necessary.

Step 3. Maintain the Mapping Data

As your team and infrastructure changes, you may need to update the values for your mapping enrichment. For example, suppose the Accounts application has just come online, the Payroll application has a new owner, and the Sales application is no longer being used. Depending on what changes you want to make, you can either completely replace the existing table, change only specific rows in the table, or create a new enrichment to change the structure.

To completely replace the existing table but keep the same structure, repeat Step 2. Upload the Mapping Data, above.

To change only specific rows in the existing table:

1. Send a PATCH request to /enrichments/${id}/map.

• For each row, specify the operation to perform (create, update, delete, upsert) and the data required to perform the operation.

• For more information, see Update Mapping Enrichment Table Rows.

• The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

❗️

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

2. Copy the trigger_uri value from the response body.
   You will use it to check the status of the update.

3. Send a GET request to the ${trigger_uri} to verify that the update has completed successfully.
   For more information, see Check Status of Upload Job.

❗️

Replace ${trigger_uri} with the value you copied from the response body and ${token} with the corresponding value for your organization.

4. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.

5. Resolve any test alerts, as necessary.

To change the structure of your mapping data:

1. Deactivate the existing enrichment by sending a POST request to /enrichments/${id}.
   Set active to false.
   For more information, see Update Enrichment.

❗️

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

2. Create a new mapping enrichment, starting from Step 1: Define The Mapping Structure, above.

Post-Requisites

• Continue to maintain the mapping data as team assignments change.

• (Optional) Define Environments based on the custom tags.

• (Optional) Define additional mapping enrichments.