# mapEvent

A Workflow Engine function that allows you to map an event in the Event Workflow engine using a configured Payload map. Entries in the configured Payload map will be evaluated using macro based substitution and will replace the existing values in the triggering event.

While this function is not designed to replace the standard mapping from the LAM configuration, it can be used to conditionally map an event. An example of this is a scenario in which an event source presents more than one format and the mapping needs to be different for each one.

This function uses the standard Payload mapping configuration to build a JSON object from the triggering event (allowing macros, default values, etc. to be used) and replaces the existing values in the event with the newly mapped values.

This function is available as a feature of the Add-ons v2.4 download and later.

This function is available for event workflows only.

## Using Overflow Data in the Payload Map

Previously unmapped data in the event is held by default in the "overflow" key. However, this data is held as a string, meaning that it cannot be directly accessed in the Payload map. To use keys from "overflow" in the mapping, perform the following steps:

1. Ensure that the Lambot does not remove "overflow" as part of its processing (some LAMs may do this to limit event sizes).

2. In the workflow, precede the mapEvent action with the parseOverflow action. This will convert the event’s overflow data to a JSON object and copy this to the WorkflowContext.

3. Reference any overflow data you want to use in the Payload map as: $(workflowContext.overflow.<key>) ### Note Overflow data cannot be used in the entry filter for workflows. If you need to filter on an overflow value, perform the above steps (parseOverflow) and use a suitable intermediate action (contextFilter, compareFields, etc.) before the mapEvent action. ## Arguments Workflow Engine function mapEvent takes the following arguments: Name Required Type Description mapName yes string The Payload map name that will be used. ## Example The following example demonstrates typical use of Workflow Engine function mapEvent. An event source sends two formats for events - one representing a fail condition, and another representing a clear condition. Each format contains different keys. Traditionally, this would be handled using JavaScript logic in the Lambot. Fail event: { "manager": "monitorOne", "check": "availability", "alias": "host001", "source": "host001", "time": 1639497307, "class": "monitorOne", "description": "Host Down", "severity": 2, "type" : "fail" } Clear event: { "manager": "monitorOne", "monitor" : "availability", "alias": "host001", "source": "host001", "time": 1639497307, "class": "monitorOne", "summary": "Host Available", "severity": 0, "type" : "clear" } In this case, two fields that need inclusion, check/monitor and description/summary need to be mapped: check/monitor in the signature and description/summary as the event description. You do not need to create Payload maps for both formats. Instead, create a default mapping in the LAM for one format and a Payload map which will override the default for the other format. 1. Create a standard map in the LAM configuration (either UI or backend) for the “fail” event. • Set the signature to: $source::$check • Set the description to: $description

2. Create a Payload map for the “clear” event, called “monitorOne Clear”.

• Set the signature to: $(source)::$(workflowContext.overflow.monitor)

• Set the description to: \$(workflowContext.overflow.summary)

3. Create a workflow using a suitable entry filter. Example: manager : “monitorOne” and type : “clear”.

• Use the parseOverflow action to copy the unmapped fields in overflow to the workflow context. Note that monitor and summary will have been unmapped by the LAM mapping and will therefore appear in overflow.

• Use the mapEvent action.

• mapName : “monitorOne Clear”

When the entry filter is met, the event will be remapped using the output of the Payload map.