Designing a field mapper that engineers and ops teams both love

The field mapper is the part of ZapRail that most users spend the most time in — and historically, the part that caused the most support tickets. Getting it right meant solving a fundamental tension: power users want direct JSONPath access and JavaScript transforms; non-technical ops teams want to click and see their data moving.

We've gone through three major iterations of the mapper. Here's what we learned.

V1: The dropdown mapper

The first version was a simple two-column UI. Left column: source fields from the trigger. Right column: destination fields for the action. You picked values from dropdowns.

It worked for simple one-to-one mappings. It completely fell apart for arrays, nested objects, transforms, and conditional mappings. Support tickets piled up: "How do I map the first item in an array?" "How do I concatenate first name and last name?" "How do I format a date?"

We were making users context-switch out of ZapRail into Excel or a text editor to pre-process their data, then pass it back in. That's the wrong abstraction.

V2: JSONPath + JS transforms

V2 went to the other extreme. Every field mapping was an expression editor. You could write `$.order.line_items[0].price` or a full JavaScript function. Engineers loved it. Everyone else was lost.

The insight we missed: the two audiences don't need different products. They need the same product with different entry points. A click-and-map interface that collapses to a JSONPath expression under the hood satisfies both — the ops user clicks, the engineer edits the expression directly, and they both see the same result.

V3: The visual canvas

The current mapper treats the data flow as a directed graph. Source fields on the left, destination fields on the right, connections drawn as bezier curves between them. Clicking a source field highlights all semantically compatible destination fields. Dragging a connection creates the mapping.

For complex mappings, an expression editor expands in-place — click a field to see its JSONPath, edit the expression, and the canvas updates live. Hovering over any field shows a preview populated with the last real payload from the trigger, so users see their actual data, not schema definitions.

Array fan-out

The hardest mapping problem in integration work is arrays. When a Shopify order has 5 line items and each one needs to become a NetSuite sales order line, you need to iterate over the array and map each element. In V1 and V2, this required a filter step and some JavaScript. In V3, you add `[*]` to the source JSONPath and ZapRail automatically generates a fan-out — one action execution per array element.

AI Auto-Map

In V3 we added AI Auto-Map as a shortcut. Click "Auto-Map" and ZapRail runs a similarity comparison between source and destination field names and types, then draws the connections it's confident about. On a typical integration, it gets 70-80% of fields right on the first pass. The user corrects the rest.

The key UX decision: Auto-Map draws suggestions, not commitments. The connections appear in amber until the user confirms them. This keeps the human in the loop without making them start from scratch.

What's next

The next version of the mapper will support live diff previews — show me what the output payload looks like before I activate the workflow, with a side-by-side comparison of input and output. We're also working on transform libraries: pre-built snippets for common operations (date formatting, currency conversion, address normalisation) that ops users can apply without writing JavaScript.

The goal is a mapper that a logistics coordinator can use without training, and that a platform engineer would choose over writing their own integration script.