Function

A simple summary on how to use the Function step to execute code within a Flow

Overview

Buildable's Functions are built-in cloud functions that provide a powerful way to add custom logic to your Flows. You can use functions to transform or compute data, or even to perform more complex operations within Flows that you might otherwise need to write server-side code for. Buildable functions support Javascript (ES7) and provide access to select npm modules.

If you know how to write Javascript, you'll know how to build a function in Buildable. In this section, we'll go over the following short concepts:

Defining function parameters

To illustrate how to create a function using Buildable, we're going to use an example function of Generating a Random Code that is 5 characters in length using JavaScript. To start, we're going to define our Generate Random Code function's parameters.

To define parameters, you can pass any data from upstream steps into your Function as parameters using the key-value table under "What data should be passed in as an input?". Under "Key", you can give your variable a name and under "Value" you can insert a variable from the variable menu in a few different ways.

To add your function parameters, add a Key name (i.e., length) and use the drop-down selector in the Value column to assign data from a previous step (i.e., to find $steps.trigger.length). Keep in mind, you can also manually type $steps in the Value field to assign your data faster. You can also simply type the value statically (i.e., 5).

Keep in mind, in each given step you only have access to the data generated from steps before. If you're using the dropdown selector and select a step that is AFTER the step you're currently in, then the key's value will be null.

Writing function code

You can write your custom code in the onRun() function, which accepts any valid Javascript. The values defined in the input table would be passed as the first argument to the onRun()function, which can be destructured or accessed directly. Any data that you return from this function can then accessed by downstream steps in your Recipe.

For example, a parameter that includes the key number can be accessed in the function by destructuring the first arg {number}.

Functions can only be synchronous and a function's maximum execution time is 1,000 ms. Functions that take longer than 1,000 ms to execute will timeout with error code 500.

Using NPM modules

Buildable provides access to certain npm modules that can be used within functions.

Here's an example of how you can access the lodash npm module within a function. You'd simply add this snippet above the onRun( ) function:

const _ = require("lodash");

Using our Greater than 5 Function example from earlier, here's how it'd look in the Function step editor:

You can find the full list of supported npm modules in our Javascript Libraries Catalog. If you don't see the module that you're looking for, let us know and we can usually add it for you.

Understanding global variables

The function editor exposes two global variables, which are $steps and input.

As you may expect, $steps gives you easy access to the output data from previous steps in your Flow that exist before your function step. Input gives you access to the params added to the key-value table above the function.

Keep in mind, setTimeout, setInterval, setImmediate and eval are not available in the function editor.

Using console logs

Buildable functions give you access to console.log , which is used to log text values and console.dir, which is used for logging objects and arrays.

Using Buildable Libraries

Buildable functions give you access to endRecipe , which is used to terminate the Flow with an error and endCall, which is used to terminate the Recipe with data.

endRecipe

When endRecipe is executed, it will end the Flow call and return a response with the following keys: message, code, data and hasError. Keep in mind, the code is the http code of the response. Any code that is 400 and above will raise an error.

Here's an example of how you can access the endRecipe Buildable library within a function. You'd simply add this snippet above the onRun( ) function:

const { endRecipe } = require("@buildable/recipes");

Here's how it would look in the function editor:

endCall

When endCall is executed, it will end the Recipe call and return a response with the destructured data alone. With endCall, the code is optional and the default is 200.

Here's an example of how you can access the endCall Buildable library within a function. You'd simply add this snippet above the onRun( ) function:

const { endCall } = require("@buildable/recipes");

Throwing errors

If your function throws any form of error, whether syntax or otherwise, the Flow will terminate. Throwing an error inside a function step by usingthrow new Error() terminates the Flow, exactly as you'd expect.

In most cases, it's recommended to use endRecipe and endCall instead.

Executing the function only when a condition is met

You can set a rule which will dictate if and when the Function step will execute. To do this, simply use the operators in the "Add your condition(s)" section found below the function editor.

If you set a condition for the function to execute and it isn't met, the function will be skipped and return the following output:

{
"__skipped": true,
}