Using Output Mappers

Overview

Every node in the Workflow Builder produces a raw output — the full response from an API call, a gaiia node, or a TypeScript function. By default, that entire response is written to the workflow state and passed to the next node. An output mapper lets you intercept that response and reshape it before it reaches state: renaming fields, extracting only what you need, transforming values, or combining data from multiple sources.

In this article, we'll be covering what output mappers are, where they appear, how to write them, and the patterns where they add the most value.

Understanding what output mappers do

When a node runs, its raw output is whatever the underlying API or function returned — often a deeply nested object containing far more data than the next step needs. Without an output mapper, that entire object lands in state under state.steps['node-slug'].output, and every downstream node that references it has to navigate the full structure.

An output mapper runs immediately after the node completes and before anything is written to state. It receives the raw output and returns a new object — whatever shape you define. That shaped object is what gets stored in state and made available to downstream nodes.

Output mappers don't change what the node does or what the API returns. They only change what gets stored in state. The raw response is never visible to downstream nodes once a mapper is configured.

Finding output mappers in the builder

Output mappers are configured on a node's Configure tab. Select any action node in the builder, open its Configure tab, and locate the Output mapper section. The section opens a TypeScript editor where you write a function that receives output and returns the reshaped value. Output mappers are always optional — if none is configured, the node's full raw response is written to state as-is.

Output mappers are available on:

• All gaiia API nodes
• HTTP REST and SOAP request nodes
• TypeScript code nodes
• The workflow-level End node (see Workflow output mapper below)

While Loop nodes also have their own output mapper and iteration output mapper. Those are covered in While Loop Node.

Writing an output mapper

An output mapper is a TypeScript function that receives output — the node's raw response — and must return a value. It also has access to state, variables, secrets, and utils.

Basic structure

    return {
      fieldName: output.path.to.value
    };

Whatever you return becomes the node's output in state, accessible to downstream nodes as state.steps['node-slug'].output.

The structure of output depends on the node type:

Maping output from gaiia API nodes

gaiia API nodes return GraphQL responses under output.response.

Extract a single field

    return {
      mostRecentWorkOrderCreatedAt:
      output.response.workOrders.nodes[0].createdAt
    };

Validate and reshape with optional chaining

Use optional chaining (?.) to safely traverse nested GraphQL responses. This avoids hard failures when optional fields are absent.

const category = output.response?.billingSubscription?.productVersion?.product?.
  productCategory?.name;
return {
  productCategory: category,
  isInternet: category === 'Internet'
};

Maping output from HTTP nodes

HTTP REST and SOAP nodes expose the response body under output.data and the HTTP status code under output.status.

Check status and return a graceful fallback

Rather than failing hard on a bad response, this mapper returns undefined values so downstream nodes can handle the missing data conditionally.

    if (output.status !== 200 || output.data.length === 0) {
      return {
        uploadDataUsageDaily: undefined,
        downloadDataUsageDaily: undefined
      };
    }
    const lastEntry = output.data[output.data.length - 1];
    return {
      uploadDataUsageDaily: lastEntry.upload,
      downloadDataUsageDaily: lastEntry.download
    };

Inspect the response body for errors

Some APIs return a 2xx status even when an error occurred. In those cases, inspect the response body directly rather than relying on the HTTP status code.

    const error = output.data.items.find((item: any) = item.error);
    if (error) {
      return utils.fail(error.message, 'API_ERROR', JSON.stringify(error));
    }
    return output.data;

Combining output with earlier steps

Any output mapper can read previously executed steps via state.steps. This lets you merge the current node's result with data from earlier in the workflow.

    return {
      accountId: state.input.accountId,
      newStatus: output.data.status,
      previousStatus: state.steps['get-account'].output.status
    };

Failing intentionally from an output mapper

If the response indicates an error or a required field is missing, use utils.fail() to stop execution cleanly rather than letting a malformed value propagate to downstream nodes.

    if (!output.response?.account) {
      return utils.fail(
        'Account not found in response.',
        'ACCOUNT_NOT_FOUND',
        { response: output.response }
      );
    }
    return {
      accountId: output.response.account.id,
      status: output.response.account.status
    };

See Using utils in Workflow Functions for the full reference on utils.fail() and other available helpers.

Defining a workflow output mapper

The workflow-level output mapper runs when the workflow reaches its End node. It defines what the workflow returns as a whole — useful when the workflow is called by another workflow via the Start Workflow node, or when you want a clean summary of the execution's results available in the execution log.

The workflow output mapper receives state rather than output, since it summarizes the full execution rather than a single node's response. It also has access to variables, secrets, and utils.

If this workflow is called by a parent workflow using the Start Workflow node, the parent can access this output via state.steps['start-workflow-node-slug'].output.

Knowing when to use an output mapper

Output mappers are most valuable when:

• The raw response is large or deeply nested — mapping to a flat, named structure makes downstream references simpler and less brittle
• Multiple downstream nodes need the same derived value — compute it once in the mapper rather than repeating the expression in every node
• You want to validate the response before it reaches state — use utils.fail() in the mapper to catch bad responses at the source
• This workflow is called by another workflow — a workflow output mapper gives the parent a clean, predictable interface to work with

If a node's output is simple and used by only one downstream node, an output mapper may not add much. The tradeoff is worth it when the raw response is complex or when the shaped output is reused across multiple steps.