Skip to main content

Load Enrichment Data

To set up use Enrichment API in Moogsoft Onprem, upload your enrichment data using the endpoint from the Enrichment API Integration. This topic covers the second step in the Enrichment API example Enrich Alerts Using the Enrichment API.

The Enrichment API stores a static set of enrichment values that you want to add to an alert based upon the data in a corresponding alert field. The API stores data in the following keys:

  • attribute: any attribute name. Wherever possible, it makes sense to use the corresponding alert field name. For example, if you want to match on the source field from alerts, set the attribute to "source".

  • value: the data to correlate the enrichment data to the alert. If you want to match on hostnames in the source field, you could set the value to a specific hostname. For example "sflinux101".

  • enrichment: a JSON object representing the enrichment data. When the enrichment API finds a data match, it adds the enrichment data as-is to the alert. For example, if you want to store location and responsible support group based upon hardware name: {"location":"1265 Battery Street, San Francisco, CA", "support_group":"SF NOC"}.

The JSON representation of a single enrichment record looks like the following:

{"attribute":"source",
"value":"sflinux101",
"enrichment":{support_group":"SF NOC"}}

The following diagram illustrates the process to enrich alert data using the Enrichment API:

load_enrichment_data.png

The Enrichment API integration enables the enrichment Graze API endpoint that lets you store and maintain enrichment data:

https://<server>/graze/v1/integrations/enrichment

The enrichment endpoint only accepts POST methods. You control the behavior of the api with an "action" value in the request body. A "post" action creates or updates enrichment records. A "delete" action deletes enrichment records. A sample payload to create enrichment records looks like the following:

{"action":"post",
 "data":[{
    "attribute":"source",
    "value":"SFlinux101",
    "enrichment": {
        "location":"1265 Battery St., San Francisco, CA",
        "support_group":"SF NOC"} 
       },
    {
    "attribute":"source",
    "value":"DENlinux102",
    "enrichment": {
        "location":"1700 Lincoln Street, Denver, CO",
        "support_group":"DENVER NOC"}
    }]
}

For a full description of the enrichment endpoint, see /enrichment.

Step 2 example: Load enrichment data

In the example scenario, you want to enrich all alerts with location and support group data from the Enrichment API. This means that you need to create and maintain your data using the /enrichment Graze API endpoint. The following example shows how to load sample data records into the enrichment data store so you can see how the Enrichment Workflow Engine getEnrichment function works.

curl -k -X POST 'https://localhost/graze/v1/integrations/enrichment' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u graze:graze \
-d '{"action":"post", "data":[ {"attribute":"source", 
"value":"SFlinux101", "enrichment": { "location":"1265 Battery St., San 
Francisco, CA", "support_group":"SF NOC"} }, {"attribute":"source", 
"value":"DENlinux102", "enrichment": { "location":"1700 Lincoln Street, 
Denver, CO", "support_group":"DENVER NOC"} }]}'

Use the Enrichment Utility to load data

The Moogsoft Add-ons come with a node.js-based utility called the Enrichment Utility (moog_enrichment_util). You can use the Enrichment Utility to load data from JSON, CSV, or TSV formatted files.

If you completed the steps to install the node.js utilities in Install Moogsoft Add-ons, you can use the node.js version of the Enrichment Utility to load data into your enrichment data store. Otherwise, you can use the Bash version of the script moog_enrichment_util.sh which is slower, but provides the same functionality.

Tip

You can run the node.js-based Enrichment API utilities on any machine with node.js version 12.6.x or later and with with HTTPS access to Moogsoft Onprem.

For example, to load some sample records included with the utility:

$MOOGSOFT_HOME/contrib/moog_enrichment_utils/bin/moog_enrichment_util \
-u 'https://localhost/graze/v1/integrations/enrichment' \
-p graze:graze \
-n 5

If you had the following data the file $MOOGSOFT_HOME/contrib/moog_enrichment_utils/data/location.json:

[
{"attribute":"source", 
"value":"SFlinux101", 
"enrichment": { "location":"1265 Battery St., San Francisco, CA","support_group":"SF NOC"}
},
{"attribute":"source",
"value":"DENlinux102",
"enrichment": {"location":"1700 Lincoln Street, Denver, CO", "support_group":"DENVER NOC"}
}
]

You could run the following command to load it into the enrichment data store:

$MOOGSOFT_HOME/contrib/moog_enrichment_utils/bin/moog_enrichment_util \
-u 'https://localhost/graze/v1/integrations/enrichment' \
-p graze:graze \
-f $MOOGSOFT_HOME/contrib/moog_enrichment_utils/data/location.json 
\-T json

The Enrichment Utility data directory ($MOOGSOFT_HOME/contrib/moog_enrichment_utils/data) has samples to help you get started. For the syntax for the utility, run the following command:

$MOOGSOFT_HOME/contrib/moog_enrichment_utils/bin/moog_enrichment_util -h

Learn more

To continue with the Enrichment API example, go to step 3: Create an Enrichment Workflow.

To read about the Enrichment API, see /enrichment.

In this section: