Create and use custom functions in Flow Builder

Flow Builder offers a great amount of flexibility. Sometimes, you might come across a niche scenario where the best solution is to write some custom code!

We created Flow Builder functions to give you the flexibility to parse semi-structured JSON information, connect with legacy systems, compute output values based on bespoke custom rules and solve other problems.

To start using functions, go to your Dashboard, navigate to the Developers area and click Functions. Here, you will be able to create new functions and view, edit and delete existing functions.

What is a flow function?

A function is a custom piece of javascript (Node.js version 12) that runs in our cloud and performs an automatic operation: given an input, it will return an output.

Components of a function

When you create your own function, you'll need to specify the following components.

Function name

Choose a descriptive and recognizable name for your function. This will help you to easily identify it when you're working in Flow Builder.

Input parameters

To make your function easier to use, you can specify the expected input parameters. This is similar to defining parameters for a webhook-type trigger.

When you or your team use your function in Flow Builder, the parameters that you define here will appear as input fields.

You can access the input parameters inside the code editor, via the following variables parameter:

variables.inputParameterName

Function code

The functions code editor will accept Node.js version 12 Javascript code, and will allow you to code complex flows and interactions.

The code editor offers:

Typeahead support
Code validation via JSHint
Code formatting (JS)
Keyboard shortcuts for power editing (see the top right-hand side of the code editor)

If there are errors in your code, the code editor will notify you of the error, and you won't be able to save and deploy the function until you fix the error.

Inside the code, you'll be able to use various helper libraries, as long as you make sure to include them in the Dependencies tab. You'll also be able to use environment variables (security keys, for example), as long as you define them in the Environment variables tab.

Dependencies

In the Dependencies tab, you'll be able to include a large variety of helper libraries by loading them up directly from the npm repository.

Inside the editor, you'll have to ensure that these dependencies are loaded via the following require clause:

const thirdPartyFunction = require("my-dependency")

or, depending on how that dependency exports its code:

const { thirdPartyFunction } = require("my-dependency")

This information can typically be found in the README of the dependency that you're using, via the following URL: https://npmjs.com/package/my-dependency

When using this, replace my-dependency with the actual name of your dependency.

For more general information about importing dependencies in Node.js, take a look at this guide.

Environment variables

If you would like to use security-sensitive information, like API keys or passwords, then we recommend configuring these as environmental variables, then referencing them inside the code via the context parameter.

Logs

Once a function is deployed, you will be able to view the execution logs inside the Logs page.

Testing a function

Once a function is deployed, you will be able to "test" that function from the function list page.

Inside the test screen, you will be able to provide values for your input parameters and test to check that the result it gives is the one expected.

Deploying a function

As a new function is deployed, or if a new version of an existing function is deployed, you'll be able to monitor the deployment status on the Functions list page.

Once the function is deployed, or if the function fails, the status on the list will be automatically updated.

When you publish a new version of an existing function, the previous version of the function will continue to execute until publishing is complete, when the new function will take over.

Calling the function inside a flow

You can add the Call my function step anywhere inside the flow, and specify which function to call. You can use the same function in multiple flows, but be mindful that any changes you make to your function will affect every flow that includes it.

When calling a function, you'll be able to do the following:

Pass a variable as an input parameter
Specify which variable the function's output will be stored in

If your function outputs an object, you can individually access object variables via variable dot notation.

// Function code 
exports.handler = function (context, variables) { 
return { MY_OBJECT_KEY: "my value", anotherKey: "another value"} 
};

When using this in Flow Builder, the following will happen:

{{result.MY_OBJECT_KEY}} will result in "my value"
{{result.anotherKey}} will result in "another value"

To handle the instances where the function will fail to execute or the result of executing the function would be different from "success" (when an HTTP code = 200 response), add a failure branch to this step.

Making 3rd party API calls from within your function

In Node.js, all 3rd party calls are asynchronous. These are the two options you have for making 3rd party API calls with your function:

Option one (with Promises) + axios lib for HTTP requests

const axios = require('axios');
exports.handler = function (context, variables) { 
 return axios.get('https://api.exchangeratesapi.io/latest') 
  .then(function (response) { 
   return {USD_RATE: response.data.rates.USD} 
}) 
};

Option 2 (with async/await API) + axios lib for http requests:

const axios = require('axios');
exports.handler = async function (context, variables) {
 const response = await axios.get('https://api.exchangeratesapi.io/latest');
 return {USD_RATE: response.data.rates.USD} 
};

In case the API you connect to requires authentication, this has to be added to the function call.

Deleting a function

You can delete functions from the Functions list page.

Deleting a function will cause any flows that use that function to stop working. Double-check to see that any flows that use that function are no longer needed before you delete anything!