Skip to main content

Transforms

The Transforms page lets you create and manage named, reusable JSONata transform expressions for your project.

What Are Transforms?​

A Transform is a saved JSONata expression with a name. Once created, a transform can be assigned to any number of endpoint-destination links in your project. This lets you define payload reshaping logic once and reuse it across multiple links without duplicating the expression.

For the conceptual overview of how transforms work, see Payload Transforms.

Creating a Transform​

  1. Navigate to Transforms → Create Transform
  2. Enter a name (e.g., "Extract PR fields")
  3. The editor opens with an empty expression and a live preview panel

Transform Editor​

The editor has two panels:

  • Left: Expression Editor — write your JSONata expression with syntax highlighting and validation
  • Right: Live Preview — paste a sample payload and see the transform output in real time

Expression Editor​

Type your JSONata expression directly. Syntax errors are highlighted inline. Example:

{
  "action": action,
  "repo": repository.full_name,
  "sender": sender.login,
  "pr_title": pull_request.title,
  "pr_url": pull_request.html_url
}

Live Preview​

Paste a JSON payload into the input field and the preview pane shows the transformed output. This lets you verify your expression before saving and assigning it to a link.

Sample Sets​

Alongside the payload you are editing — the active sample, the one the live preview evaluates against — a transform stores a set of up to 10 sample events.

  • Save current payload as sample adds whatever is in the editor to the set.
  • Add from recent events opens a picker of the events your project received in the last 30 days, newest first — each labelled by its event type, or a short id when the source doesn't set one, with events your filters blocked marked filtered. A filter box above the list narrows it as you type; press ↓ to move from the box into the list, then move with the arrow keys (Home and End jump to the ends), press Space to select one or several, and Enter to add them — with nothing selected, Enter adds the highlighted event. Events already in the set are shown as Added.
  • Each stored sample can be loaded back into the editor as the active sample, or removed from the set.

Adding or removing a sample is an unsaved change — it takes effect when you save.

Creating a transform from an event starts the set off with that event, unless the event is unusually large — in which case the transform is still created, just without the first sample. A multi-row selection from the events table seeds one sample per selected event, up to the 10-sample cap — see Create from several events at once.

AI JSONata Generator​

The transform editor includes an AI-powered expression generator. Click the Generate with AI button (or press Ctrl+Alt+P), describe what you want in plain English, and Dispatch produces a JSONata expression for you.

For example: "Extract the PR title, author login, and repository name into a flat object."

Generation considers the samples in your set, not just the payload in the editor, so the expression it writes copes with the shape differences between your events. The prompt bar names what it will read — the payload in the editor, however many samples your set holds, or neither — and trims a very large set to fit the request by dropping whole samples from the end. With the sample box cleared and no stored samples, it tells you generation has nothing but your description to work from. Press Enter to generate (Ctrl/⌘+Enter works too), Shift+Enter for a newline, and Esc to close it.

The generated expression is applied to the editor automatically. Review it in the live preview before saving.

Managing Transforms​

From the Transforms list page you can:

  • Rename a transform by clicking the name inline
  • Edit the expression by opening the transform editor
  • Delete a transform (this removes the reference from any links using it — the link will fall back to no transform)

After creating a transform, assign it to one or more endpoint-destination links, in either direction:

  • From the source: go to Sources and open the routing page for the endpoint-destination link; the transform is one of the link's defaults.
  • From the transform editor: click Attach in the editor header — the same dialog the template editor has, listing every link (arrow-key navigable) with its current transform and a warning when attaching would replace one. It also has the same Scope with a rule… option: open the link's routing editor with a draft rule carrying this transform, so it applies only to matching events while the link's defaults stay untouched.

To remove a transform from a link, open the link's routing page and clear the transform selection.

Routing Rule Overrides​

Individual routing rules on a link can specify a different transform_id, allowing you to use a completely different transform for specific event types without changing the link's default.

Keyboard Shortcuts​

In the transform editor, Ctrl+S (⌘S on macOS) saves and Ctrl+Alt+P (⌘⌥P) opens AI generation. Both are shown in the tooltip of the button they trigger.

Ctrl+K (⌘K) opens the command palette, which lists both — plus everything else available on the page.

These are the default bindings — any shortcut can be rebound or unbound.