Edwin AI Integration YAML File

The mappings.yaml file defines how events from third-party systems are mapped to Edwin AI’s Common Event Format (CEF). This configuration ensures that incoming event data is standardized and usable across Edwin AI’s processing pipeline.

While not all third-party integrations require a mapping YAML file, it is necessary for any integration that sends event data in a non-standard format or requires transformation before ingestion by Edwin. Integrations like Splunk and similar platforms benefit from using a mapping file to ensure compatibility and flexibility.

Mapping File Structure

All YAML files must include the following:

• Mappings—Maps fields from third-party events to Edwin’s standardized fields using JSONPath expressions.
  

  event_ci: ["$.configurationItem.name"]
  event_description:
    string_template: "sample text {variable1} {v2}"
    variable1: ["$.alert_name"]
    v2: ["$.not_exist", "$.configurationItem.name", "$.source"]

  Copy
  The mappings block includes the following event fields definitions:

You can define fallback paths using multiple JSONPath strings. The first valid match is used.

• Defaults—Defaults are used when no mapping resolves to a value or the value is invalid.
  The following code block defines fallback values used when mappings cannot extract valid data:

  
  event_ci: "defaultEventCI"
  event_severity: 1
  event_source: "splunk"

  Copy

• Enrichments—Custom fields that supplement the core event with additional metadata.
  Common enrichments include datapoints such as location, environment (for example, development or production), and the business service or application supported by the alerting resource.
  The following code block defines enrichment fields, including a string template:
  

  test_enrichment: ["$.obj[0].name"]
  test_enrichment_template:
    string_template: "enrichment template {v1}"
    v1: ["$.alert_name"]

• Transforms—Transforms map non-standard values (from the source system) to standardized values used by Edwin AI. 
  The following code block defines how raw severity values are normalized into Edwin’s standard severity levels:
  

  event_severity:
    critical: ["crt", "critical", 5]
    major: ["mjr", "major", 4]

  Copy
  
  If a severity doesn’t match a known value, it falls back to the following:
  

  defaults.event_severity

  Copy

• Timestamps—Define how to interpret event_time.
  The following code block specifies the timestamp format and timezone offset interpretation:
  

  type: "datetime"
  day_first: false
  year_first: false
  offset:
    BST: 3600
    PST: -28800
    CST: -21600

Although every block is required for a valid file, each block has its own rules for validity.

The following code block displays a complete YAML file with all required blocks:

mappings:
  event_ci: ["$.configurationItem.name"]
  event_object: ["$.obj[1].name"]
  event_source: ["$.source"]
  event_name: ["$.alert_name"]
  event_description:
    string_template: "sample text {variable1} {v2}"
    variable1: ["$.alert_name"]
    v2: ["$.not_exist", "$.configurationItem.name", "$.source"]
  event_severity: ["$.event_severity"]
  event_time: ["$.timestamp"]
  event_id: ["$.event.identifier"]
 
defaults:
  event_ci: "defaultEventCI"
  event_object: "defaultEventObject"
  event_source: "splunk"
  event_name: "defaultEventName"
  event_description: "default event description"
  event_severity: 1
 
enrichments:
  test_enrichment: ["$.obj[0].name"]
  test_enrichment_template:
    string_template: "enrichment template {v1}"
    v1: ["$.alert_name"]
 
transforms:
  event_severity:
    critical: ["crt", "critical", 5]
    major: ["mjr", "major", 4]
    minor: ["min"]
    warning: ["wrn"]
    indeterminate: ["sdt"]
    clear: [0, 255]
 
 
timestamps:
  type: "datetime"
  day_first: false
  year_first: false
  offset:
    BST: 3600
    PST: -28800