Map Events to Columns

A mapping tells Engage what to do when an event arrives: the value in this schema field goes into that column. Each event in the manifest needs one. Engage builds a first mapping by matching names, so for most events the work is confirming it rather than drawing it.

Before you begin

• The report columns are settled. See Define report columns. Changing a field name afterwards means revisiting the mapping that used it.
• You know which workflow step reports each event, so you can judge whether a field should land in a column at all. The Send to Engage activity is the other half of this mapping.

What Engage seeds for you

Once the integration has columns, the Event Mapping table gains one row per event in the manifest, each with an automatic mapping that connects schema fields to columns whose names match, ignoring case. An event whose schema fields all share names with columns is fully mapped before you open it.

The rows in the table are the events Engage will accept for this integration. An event in the manifest with no row here is not recorded.

Add an event row

If an event is missing from the table:

1. In the Event Mapping section, select Add new event. The link is disabled once every manifest event already has a row.
2. In the new row's Event cell, select the event from Select an event. Only events not yet in the table are offered.

To remove an event from the integration, select the delete control at the end of its row. Its mapping is discarded with it.

Check or change a mapping

1. Select Map Fields on the event's row. The link is disabled until an event is selected.

The Define fields drawer opens with the source schema on the left and the target on the right.

• The source tree is the event's schema, wrapped in two groups: data, holding the fields the workflow maps in Send to Engage, and headers, holding batchId, batchPosition, correlationId, and transactionId, which Engage attaches to every event.
• The target tree is the integration's report columns, listed under a records node.

2. Drag a source field onto a target column to connect them. Connect a header field the same way if a column should hold it.
3. Use Transform to write an expression where a value needs reshaping before it is stored. Undo and redo controls sit beside it.
4. Select Save. The button stays disabled until at least one connection exists and every connection is valid.

Save here stores the mapping in the form. Nothing reaches Engage until the integration's own Save or Update, as described in Configure an integration.

Use the AI auto-mapper

The generate control at the right of the Transform row opens a prompt panel at the bottom of the drawer and locks the trees while it is open.

1. Select a quick prompt, Map similar fields or Clear all mappings, or describe what you want in Explain how the mapping should be and send it.
2. Wait for Mappings generated successfully. The proposed connections appear in the trees.
3. Select Accept to keep them. Engage confirms with Generated mappings applied successfully. Select Reset to return to the mapping as it was before generation, or Regenerate to try the same prompt again.
4. Close the panel to unlock the trees, then select Save.

The auto-mapper is most useful when column names and schema field names differ, which is exactly the case the automatic name matching cannot handle.

How you know it worked

Reopening Map Fields on the event shows its connections drawn between the two trees, and after the integration is saved and the workflow runs, the mapped columns of that event's records are populated in the view. See Validate the data flow.

When it does not work

Symptom	Cause	What to do
Map Fields is disabled	The row has no event selected	Select an event in the row's Event cell
Add new event is disabled	Every manifest event already has a row	Nothing to add; edit the existing rows
The event you need is not in Select an event	It was added to the manifest after the application was synced	Sync the application from the Configuration > Integrations tab, then reopen the form
Save stays disabled in Define fields	No connection exists, or one is invalid	Draw at least one connection and clear any connection shown as invalid
Sorry! We couldn’t generate the mapping. Please try again.	The auto-mapper request failed	Send the prompt again, or map the fields by hand
Failed to generate mappings	An inline expression suggestion failed	Write the expression by hand in Transform

Next steps

Configure views.