Run Custom Code (JS)

The Basics

The custom code step is an advanced tool for processing data in Relay.app. It can be used to build complex logic that goes beyond the capabilities of Relay.app's Transform data steps.

Custom code is written in JavaScript, and some familiarity with programming is required to use it.

When to use

Common scenarios that work well are:

• Data from Step Outputs need to be converted into another format.

• Complex logic is required to decide what the workflow should do.

Custom code steps are limited to working with local data. Communicating with external services within a custom code step is not possible.

JavaScript support

Code can use all ES2023 language features.

Built in objects

• All transformations that are available in a Transform data step are also accessible from custom code. They can be accessed under the global object $.

  • For example, the Format text -> Uppercase transformation in a Transform data step can be invoked in a custom code step as $.text.upper.

• The global console object implements console.log to record messages during execution.

Date and time data

Custom code uses the luxon library to handle date and time data. Input data with the corresponding type is passed to the function as a DateTime or Duration value. If returning the output of a Luxon call, those values should be typed accordingly in Relay.app (e.g., using Relay.app's Date/DateTime/Duration variable types).

The luxon documentation offers a good overview of formatting and math capabilities. The complete API can be viewed in the API reference.

Working with data

Steps in Relay.app define their interface ahead of time. For custom code this requires configuring both inputs and outputs:

• Configure the Inputs by selecting data produced by earlier steps of the workflow.

• Configure the shape of the Outputs returned by your code block. Your code must return a value whose structure matches the Outputs configuration.

Anything configured in Outputs is accessible in later steps of the workflow.

Inputs

The inputs section defines what data from the workflow can be used from the custom code step. Inputs are typed according to the source data. All inputs are passed to the function together as a single object, keyed by their name.

In addition to regular fields the custom code step also supports picking whole data objects. These give access to the underlying raw data used throughout Relay.app.

Use the Interface section in the Inputs tab of the code editor to see the structure of the raw data objects.

Outputs

The output schema defines what data the step will produce when executed. This is required to enable later steps to work with the data.

There are two main recommended patterns for using the custom code step that allow automatic configuration of the output schema:

1. If the goal is to produce data in a format defined by another step, first build out the full workflow. Next, add the custom code step in the middle. Now the outputs can be configured to match these inputs, which guarantees a perfect fit and full support by the compiler when working on the code.

2. If the step is used to implement custom logic, first configure the inputs, and then build the code. Running the code via the Test tab will produce an inferred output schema that can be automatically applied to your step. Make sure to test with a variety of inputs, to build confidence that your schema covers all potential outputs.

Using one of these two approaches enables automatic configuration of output schema for the vast majority of use cases. While possible, it should rarely be necessary to configure schemas manually.

Debugging

The Test tab in the code editor offers the best way to quickly verify that code is working correctly. To provide additional visibility into the execution beyond input and output values, use console.log. Anything logged during code execution is displayed in Relay.app alongside your output.