Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Transformer step takes the output from previous steps and reshapes it using AI. Instead of writing code to parse, map, and restructure data, you write a natural language prompt describing the transformation you want — and the AI produces the result as structured JSON. This is useful when you need to:
  • Extract specific fields from a large API response
  • Rename and restructure data to match a target format
  • Merge or flatten nested objects
  • Filter an array down to matching items
  • Convert between data formats (e.g. CSV-style rows to nested JSON)

​
How It Works

At runtime, the Transformer step resolves any template variables in your prompt before sending it to the AI. Data from previous steps, trigger payloads, variables, and databases must be explicitly referenced in the prompt using {{...}} syntax — the AI only sees what you include. The AI returns the result as a JSON object in the result output field, which downstream steps can reference. Because the output is always JSON, the Transformer works best when your prompt is specific about the structure you expect back.
Prompt:
From the following API response:
{{step.fetch-articles.output.body}}

Extract each article's id, title, and author name. Return an array of
objects with the keys: articleId, title, authorName.
Output (result):
[
  { "articleId": 1, "title": "First Post", "authorName": "Alice" },
  { "articleId": 2, "title": "Second Post", "authorName": "Bob" }
]

​
Configuration

FieldDescription
PromptNatural language instructions describing the transformation to apply. Use template variables to reference specific data from previous steps.
Output SchemaOptional visual schema that defines the exact shape of the result object the model should return.

​
Writing Good Prompts

  • Be specific about output structure — tell the AI exactly what keys and shape you expect back
  • Reference input paths explicitly — e.g. “from the body.data array” rather than “from the data”
  • Keep it focused — one transformation per step is easier to debug than a complex multi-part prompt

​
Using Libraries

The prompt editor has built-in library integration. Click Library above the editor to load a saved prompt, or click Save to store the current prompt as a reusable library item. This is useful when the same transformation logic is shared across multiple automations.

​
Output Schema

The Output Schema builder lets you define the exact structure you expect back from the Transformer, rather than relying solely on the prompt to describe it. When a schema is defined, it is compiled into a strict Zod schema at runtime and passed to the model — constraining its response to the shape you specify. This removes the need to describe the output format in the prompt itself and makes it easier to access nested fields in downstream steps, because all defined paths appear automatically in the template picker.

​
Adding Fields

In the Output schema section of the Transformer panel, click Add field to add a top-level field to the result object. Each field has:
SettingDescription
NameThe key name in the result object (e.g. title, amount, items)
TypeThe data type for this field (see table below)
NullableWhether the field is allowed to be null (toggle in the field settings popover)
DescriptionAn optional hint for the model describing what this field should contain

​
Supported Field Types

TypeDescription
stringA text value
numberA numeric value (integer or decimal)
booleantrue or false
nullAlways null — useful for placeholder fields
enumOne of a fixed set of string values. Enter the allowed values as a comma-separated list below the field row.
objectA nested object. Expand to add child fields.
arrayA list of items. Choose the item type (including object for arrays of objects).

​
Nested Types

  • Objects — add child fields inside the object field row to define the nested structure.
  • Arrays of objects — set the item type to object, then add child fields to define each item’s shape.
  • Arrays of enums — set the item type to enum and enter the allowed values.
Schema definition:
  • tracks (array, item type: object)
    • title (string)
    • status (enum: active, inactive, pending)
    • plays (number)
The model will return:
{
  "tracks": [
    { "title": "Song A", "status": "active", "plays": 14200 },
    { "title": "Song B", "status": "inactive", "plays": 830 }
  ]
}
Downstream steps can reference {{step.transform.output.result.tracks}} or individual fields like {{step.transform.output.result.tracks[0].title}}.
If no schema is defined, the Transformer falls back to open-ended JSON output — the model returns whatever structure the prompt describes. Defining a schema is optional but recommended when the result feeds into downstream steps that depend on specific field paths.

​
Output

FieldTypeDescription
resultobjectThe transformed data, shaped according to the Output Schema if defined
errorbooleanWhether an error occurred
error_messagestringError description if failed
Downstream steps access the result via {{step.your-step-name.output.result}}. If you defined an Output Schema, all nested field paths (e.g. result.tracks, result.tracks[0].title) appear automatically in the template picker. If the result is an array, you can feed it into a Loop step to process each item.