Workflows: Custom Functions

Overview

While Persona provides built-in functions for manipulating data in your workflows, Custom Functions allow you to create your own functions to fill in any gaps for evaluating code. You write a JavaScript function once, publish it, and reuse it anywhere in your Workflows without copying the same logic into every step. Custom Functions are currently supported for Workflows, and the supported language is JavaScript.

Once published, Custom Functions surface anywhere you want to set a dynamic value in the Workflow editor, including action step parameters, conditional steps, and loop settings.

Functions tab and function editing window

The Functions tab shows every Custom Function your organization has published, along with its Inputs, Outputs, and current revision. From this tab you can open the function editing window for an existing function or start a new one.

The function editing window has four elements:

• Name: a short label that identifies the function in the list.
• Inputs: a set of Input arguments the function receives from the caller.
• Outputs: a single Output value the function returns.
• Code: the JavaScript that transforms the Inputs into the Output.

Using a Custom Function inline

Anywhere you set a dynamic value in the Workflow editor, such as an action step parameter, a conditional branch, or a loop setting, you can draw on a Custom Function without leaving the editor. Type @ at the end of the path to open the function menu.

The function menu lists the Custom Functions your organization has published alongside the built-in options. Each Custom Function appears with an @ name, such as @isGmailAddress, and selecting one appends it to the path you are building. If you type a name that no published function matches, the menu offers Create custom chain, which opens the function editing window in place. Write and test the function there. When you publish it, the new function is added to the path and becomes available anywhere you set a dynamic value.

Creating a Custom Function from the Functions tab works the same way, and the tab keeps every function your organization has published in one place for review and revision.

Creating a Custom Function

1. Navigate to the Functions tab in Workflows.
2. Click Create a function.
3. Write or paste your JavaScript in the Code editor.
4. Set your Input and Output types.
5. Set a Description of your function.
6. Test your function using the Test run settings section.
7. Save your edits and needed using the Save button at the top right.
8. When ready, use the Publish button at the top right.

You can test the function right in the editing window before you publish it, so you can iterate on the code while the Inputs, Outputs, and errors are visible.

When you save a draft, the function is saved for later. When you publish it, the function becomes available to use across your Workflows and Workflow Actions.

Inputs and Outputs

A Custom Function receives its Inputs as the argument object passed to the function. The example below defines a function that receives a value under the previous key, so the code reads previous off the argument object:

// Uppercases the first character of the incoming string.
export default function ({ previous }) {
  if (typeof previous !== 'string' || previous.length === 0) {
    return '';
  }

  return previous.charAt(0).toUpperCase() + previous.slice(1);
}

The Outputs are what the function returns. The Input schema and Output schema describe the shape of the values the function accepts and returns. You define them in the function editing window, and Workflows uses them to validate the arguments you pass and the value the function produces.

Example Custom Function

Here is a complete working example of a Custom Function called cap_first_letter. It expects its Input to be a string and uppercases the first character:

// Uppercases the first character of the incoming string.
export default function ({ previous }) {
  if (typeof previous !== 'string' || previous.length === 0) {
    return '';
  }

  return previous.charAt(0).toUpperCase() + previous.slice(1);
}

Example usage: if you pass the string "hello world" as the previous Input, the function returns "Hello world". If you pass an empty string, the function returns an empty string.

Testing in Production vs Sandbox

You can test a Custom Function on the page while you are writing it. Once satified, you can save and Publish it to begin using it within your Workflows. Testing behaves differently depending on the environment:

• Sandbox: functions run with the sandbox limits in place. The sandbox catches runtime errors, missing Inputs and Outputs, and schema mismatches before you ever publish the function, which is a good reason to create and test your Custom Functions in Sandbox first.
• Production: your function receives production data. Any error the function raises also surfaces in the Workflow that runs it, so a Custom Function that works in Sandbox can still fail in Production if it was published before the code it depends on, or if the production data does not match what the Input schema expects.

Important limits

• Revisions: a Custom Function has a draft revision and a published revision. The published revision is what runs inside your Workflows and Workflow Actions. Creating a new draft does not change what is published, so a published function keeps running the behavior it had when you last published.
• Context: Custom Functions receive the context relevant to where they run. You cannot call the same function with context it was not written for.
• Environment: test in Sandbox before you publish, and verify the published revision in Production before you rely on it. Refer to the Well-Architected Workflow Framework and the client SDK guides in the Workflows developer documentation for the limits that govern the code you write.

Publishing and revising a Custom Function

1. Click Publish in the function editing window to publish the draft as the new revision. Once published, the function is available across your Workflows and Workflow Actions.
2. To revise a published function, open it in the function editing window and edit the code, Inputs, or Outputs. The edits create a new draft revision, and the previously published revision continues to run until you publish the new draft.
3. If a function is published with Inputs and Outputs and you subsequently change them in a new draft, the already-published revision keeps its original Input and Output configuration until you publish the new draft.

Plans Explained

Custom Functions by plan

Learn more about pricing and plans.