Transformation Functions

You can create a Transformation Function from the Segment catalog.

To create a new Transformation Function, follow these steps:

1. Navigate to Connections > Catalog > Functions.
2. Click New Function.
3. Select Transformation Function.
4. Write and test your function code.
5. Optional: Configure function settings.
6. Click Next: Configure & Create.
7. Provide a name, optional description, and optional logo.
8. Click Create Function.

The new function appears in the Functions catalog where it can be managed and reused.

A Transformation Function becomes active after an instance is attached to a journey step. To attach a function to a journey step, navigate to your journey in the Segment app, add or edit a "Run Function" step, and select your Transformation Function from the available functions list.

Transformation Functions expose a single handler:

1
async function onTransform (event, settings) {
2
  // custom logic
3
  // Return Only new fields (do not return 'payload')
4
  return {
5
    // my_computed_field: value
6
  };
7
}

The handler receives the following parameters:

• event: The event payload containing the current journey context.
• settings: The function settings configured for the journey step.

Within the handler you can do the following:

• Modify event fields.
• Make HTTP requests.
• Perform asynchronous operations.
• Compute derived values.
• Filter events.
• Throw supported errors.

Use settings to configure reusable parameters without modifying function code.

To configure settings, follow these steps:

1. Navigate to Connections > Catalog > Functions > Transformation Functions.
2. Open an existing Transformation Function or create a new one.
3. Open the Settings tab.
4. Click Add Setting.
5. Enter a Label, Name, Type and Description for your setting.
6. Save the setting.

Supported setting types include:

• Static Value: a fixed value that the journey passes for every execution. Supported data types include:
  • String
  • Boolean
  • Array
  • Object
• From input data: A dynamic value where you can define the relative path of the key whose value is passed from the event payload.

Settings are available to the function during execution and can be configured for each journey step.

You can test Transformation Functions within the code editor.

To test a function, follow these steps:

1. Open the Test tab.
2. Provide a sample payload or paste your own event.
3. Click Run.
4. Review:
   • Output event
   • Execution result
   • Console logs
   • Error messages

Testing allows you to validate function behavior before deployment.

You can optionally define the output schema from the Transformation Functions Code Editor. The output schema is used in the journey setup workflow to populate the journey context from the Run Function step that can be used in subsequent journey steps.

You can manually enter the JSON payload of the returned event or copy directly from the Test Output using the Generate from Test Output option.

A function execution is successful if it completes without error. You can throw an error to create a failure on purpose. To make sure the function works as expected, use errors to validate event data before processing.

Throw one of the following predefined error types to indicate that the function ran successfully, but the data was not deliverable:

• EventNotSupported
• InvalidEventPayload
• ValidationError
• RetryError
• DropEvent

This is similar to Source, Destination, and Insert Functions.

The errors listed are all permanent errors, except RetryError. When a RetryError is thrown, Segment retries the function with exponential backoff before permanently failing.

Transformation Functions are available in Journeys.

Yes. A single Transformation Function can be attached to multiple journeys and journey steps.

Yes. Transformation Functions can call external APIs to enrich or validate data.

Yes. Each function instance can have its own settings while sharing the same function code.

Yes. The code editor provides a built in testing environment where you can run sample payloads and inspect the output.

The behavior depends on the error type. Permanent errors stop processing, while RetryError causes Segment to retry execution before marking the invocation as failed.

Yes. Transformation Functions maintains version history and supports rolling back to previous deployed versions.