AI Transform

Transform data using OpenAI and natural language instructions.

Overview

AI Transform uses OpenAI models to transform workflow data based on natural language instructions. Two modes are available: “Generate Code” sends a sample of items to the LLM which generates JavaScript code that is then executed in an isolated JavaScript sandbox against all items; “Direct Transform” sends each item individually to the LLM for transformation. Supports GPT-5.2, GPT-5, GPT-5 Mini, GPT-5 Nano, GPT-4.1, GPT-4.1 Mini, and GPT-4.1 Nano models.

Category: AI
Tool Name: ai_transform
Version: 1

Appearance: Icon: lucide-Brain | Color: #8B5CF6

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires OpenAI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Instructions	string	Yes	—	Natural language instructions describing how to transform the data. Supports {{ }} expressions in Direct Transform mode.
Model	options	No	gpt-4.1-mini	The OpenAI model to use for transformation.
				Options: gpt-5.2, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
Transform Mode	options	No	generateCode	Generate Code: LLM writes JS executed in sandbox against all items. Direct Transform: LLM transforms each item individually.
				Options: generateCode, directTransform
Sample Size	number	No	3	Number of items to sample for the code generation prompt (1-10). (shown when Transform Mode is generateCode)
Max Concurrency	number	No	10	Maximum number of concurrent OpenAI API calls for direct transform mode (1-50). (shown when Transform Mode is directTransform)
Include Input	boolean	No	true	When true, original input fields are merged into the transformed output. Applies to Direct Transform mode; in Generate Code mode the generated code controls the output shape directly.
Schema Hint	string	No	—	Optional description of the expected output schema to guide the AI transformation. Supports {{ }} expressions in Direct Transform mode.

Output Data

The transformed data becomes the output item’s JSON, and every output item carries an _meta.aiTransform block describing the run. Binary data from the input item is forwarded unchanged.

In Direct Transform mode there is exactly one output item per input item, and Include Input decides whether the original fields are merged underneath the transformed ones. In Generate Code mode the generated code returns the item array, so the node can emit fewer or more items than it received — for example when the instructions ask it to filter.

{
  "_meta": {
    "aiTransform": {
      "model": "gpt-4.1-mini",
      "mode": "generateCode",
      "tokensUsed": { "prompt_tokens": 412, "completion_tokens": 96, "total_tokens": 508 },
      "generatedCode": "return items.map(item => ({ ...item }));",
      "sampleSize": 3,
      "totalItems": 25,
      "resultIndex": 0
    }
  }
}

• model, mode and tokensUsed are present in both modes. mode is the Transform Mode that produced the item.
• Generate Code mode adds generatedCode (the JavaScript the model wrote), sampleSize (how many items were actually sampled), totalItems (how many items the code ran against) and resultIndex (the item’s position in the returned array).
• Direct Transform mode adds itemIndex instead — the position of the input item the call was made for.

Reference the metadata downstream by expression, e.g. {{ $json._meta.aiTransform.model }}.

Usage Examples

• Add a fullName field by combining firstName and lastName
• Filter items where status is active
• Convert all date strings to ISO 8601 format
• Summarize the description field into one sentence
• Restructure nested objects into flat key-value pairs
• Classify items by sentiment using AI

Example Configuration

Generate Code mode (the default):

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Extract the first and last name from the 'fullName' field and return them as separate 'firstName' and 'lastName' fields.",
    "model": "gpt-4.1-mini",
    "transformMode": "generateCode",
    "sampleSize": 5,
    "includeInput": false,
    "schemaHint": "Output fields: firstName (string), lastName (string)"
  }
}

Direct Transform mode:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Analyze the 'reviewText' field and classify the sentiment as 'positive', 'neutral', or 'negative'. Add a 'sentiment' field with the result.",
    "model": "gpt-4.1",
    "transformMode": "directTransform",
    "maxConcurrency": 10,
    "includeInput": true,
    "schemaHint": "Output field: sentiment (string, one of: positive, neutral, negative)"
  }
}

Minimal required configuration:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Summarize the 'description' field in one sentence and store it in a 'summary' field."
  }
}

All omitted fields fall back to their defaults: model = "gpt-4.1-mini", transformMode = "generateCode", includeInput = true, schemaHint = "".

Batch field normalization — use generateCode when applying a consistent transformation to all records, which is faster and cheaper than per-item calls:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Normalize the 'phone' field to E.164 format (e.g., +14155552671). Remove any existing formatting characters.",
    "model": "gpt-4.1-mini",
    "transformMode": "generateCode",
    "sampleSize": 3,
    "includeInput": true,
    "schemaHint": "Output field: phone (string in E.164 format)"
  }
}

Per-item AI classification — use directTransform when each item requires independent reasoning by the model:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Read the 'supportTicket' field and assign a priority level of 'low', 'medium', 'high', or 'critical' based on urgency and impact. Store the result in a 'priority' field.",
    "model": "gpt-4.1",
    "transformMode": "directTransform",
    "maxConcurrency": 5,
    "includeInput": true,
    "schemaHint": "Output field: priority (string, one of: low, medium, high, critical)"
  }
}

Schema-guided data extraction — use schemaHint with includeInput: false when you want a clean, reshaped output without the original fields:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "From each record, extract the product name, price as a number, and whether it is in stock as a boolean from the 'rawListing' field.",
    "model": "gpt-4.1-mini",
    "transformMode": "generateCode",
    "sampleSize": 5,
    "includeInput": false,
    "schemaHint": "Output fields: productName (string), price (number), inStock (boolean)"
  }
}

High-throughput direct transform — for large datasets requiring nuanced per-item reasoning, raise maxConcurrency and use a more capable model:

{
  "type": "ai_transform",
  "parameters": {
    "instructions": "Translate the 'body' field from its detected language into English. Preserve formatting and tone.",
    "model": "gpt-5-mini",
    "transformMode": "directTransform",
    "maxConcurrency": 25,
    "includeInput": true,
    "schemaHint": "Output field: bodyEnglish (string)"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Transforms workflow data using OpenAI models guided by natural language instructions, via code generation or direct per-item transformation. Use when you need flexible data reshaping described in plain English rather than explicit field mapping or code. Produces transformed items with optional original field preservation and AI metadata.

Behavioral notes

• Retry (generateCode only): If the generated code fails execution, the tool automatically retries once — sending the error message and failed code back to the LLM for correction.
• Expression support (directTransform only): The instructions and schemaHint fields support {{ $json.field }} expressions in directTransform mode, resolved per-item before sending to the LLM.
• Sample size vs concurrency: sampleSize only applies in generateCode mode and maxConcurrency only applies in directTransform mode — set the one that matches the mode you selected.
• Output metadata: All output items include _meta.aiTransform with model, mode, and tokensUsed. generateCode mode adds generatedCode, sampleSize, totalItems, and resultIndex; directTransform mode adds itemIndex (the item’s zero-based position in the node’s input).