Custom events

Custom events are events that can only be triggered by using the Trigger a custom event action. In other words, they have to be triggered by another workflow. They can accept parameters that can be referenced in the action steps inside of the workflow.

You can trigger custom events that are on the same page, or inside of a reusable element that's directly placed on the page you are currently working on by using the Trigger a custom event from a reusable element action.

What are custom events for?

Custom events have several useful usages:

Avoid repeating work

Since custom events can be called from anywhere on the page, you can avoid having to duplicate workflows.

For example, let's say you have an application that handles documents; you have one Save menu option under File - Save, and another as an icon in a toolbar. The two do exactly the same thing; they save the contents of a input field to the database.

Instead of using two identical workflows to save the document, you can place the actions needed to save it in a custom event, and trigger that workflow from both places.

Returning data

You can also return data with custom events. For example, you can:

• Check something in the database or an external service

• Make calculations

• Generate dynamic data

• Validate forms

Maintain consistency and prepare for future changes

Custom events also help you standardize things that happen in your application. Let's say for example that you use a popup container to show messages to your users such as The changes have been saved. By using a custom event to show that popup, you can ensure that it looks and behaves the same no matter what the message is. Should you later decide to move away from a popup and instead use an Alert element you can make that change in just one workflow and it will be replaced all across the page.

Control the order of operations in a workflow

Custom events give you a more fine-grained control over the order of operations in a workflow.

Article section: The order in which actions are triggered Video: Understanding workflow execution rules

Creating a custom event

To create a custom event, first navigate to the Workflow editor, and click Click here to add an event... . From the dropdown menu, pick Custom and Create a new custom event.

Parameters

1. First, we give the event a name. The name doesn't affect how it works, but it's useful to make it descriptive and easy to recognize

2. Then, we'll set up two parameters by clicking the Add a new parameter button. Parameters let you pass any kind of data to the workflow, and use that information in actions inside of that workflow.

   1. First, we'll pass a user: that is the user who's name we want to change

   2. Then, we'll pass a text: this is the new name that the user will be given

Now we have a custom event that accepts two things: a user and a text. Let's reference those in an action:

We'll add a Make changes to a thing action. In the thing to change we choose user, which is the name we gave the first parameter. Then we pick the Name field on the user, and set it to text, which is the name of the second parameter.

This way, we have set up a custom event that can change the name of any user by asking for it as a parameter. By setting up custom events for key workflows in your app, you can make sure they work consistently and are not duplicated across your app.

Return values

You can also set up a custom event to return one or more values of a specific data type. Let's expand our user example. Instead of changing the user's name, we want to start a subscription via the Stripe plugin. The result can be successful, or not succesful, depending on the user's payment credentials, and we want to return the result after the actions in the custom event are finished running.

Adding the return values

First, select the custom event. The event properties will be displayed. Under return values, we'll include two points:

We'll set it up as in the screenshot below:

A few things are worth noting in the image above:

• We are still sending a user parameter, to instruct the custom event to start the subscription on a specific user

• Return values are created under the Return values header (as illustrated with the red rectangle) – not to be confused with parameters

• We have set the subscription value as required, since we'll always return a yes or no

• The error message is set to optional, since we only need to return a value if the subscription is unsuccessful

Setting up the actions

Now, let's set up the actions that will attempt to start a subscription.

1. First, we'll use the Subscribe user to a plan action to start the subscription on the user provided in the parameters.

2. In step 2, we use the return data action to send data back.

3. We'll leave the Error message return value blank, since this action will only run if the subscription is successful

4. We are using the Only when field to only send yes if Stripe returns the status active. This step terminates the workflow – any steps after this will not run if the Only when returns yes.

With that set up, we are returning a yes to the original workflow that triggered the custom event. Now let's look at Step 3, which runs if the subscription was not successful.

1. First, we're return a no instead of a yes

2. This time, we'll also return the error message. The Stripe plugin (which connects to the Stripe API) returns a field called status which lets us know whether is was successful or not.

3. If that field does not contain the text active, then the subscription failed – Stripe will return a string to let us know what went wrong.

Using the returned data

The data will be "returned" to the original workflow. Let's have a look at how you access that data:

In the first step we're triggering the event (see more about this in the section below). We're not returning any data until the next step.

1. We're using the Show message in Alert action to show the error message to the user. Note that you need to place an Alert element on the page before this action is available.

2. In the custom message, we'll use the Result of step 1 data source. Step 1 in this case was the triggering of the custom event, so this lets us access the returned data.

3. In the third step, we're checking whether an error was generated.

In a real-life example, you may take more action than this, but this illustrates how you can use custom events to perform a series of actions and return dynamic data based on those actions.

Running a custom event

Triggering

A custom event can be triggered instantly by using the Trigger a custom event action.

Trigger a workflow in a reusable element

By placing a custom event inside of a reusable element, that workflow can be triggered from the parent of that reusable element. For example, if you have a page called index and you place a reusable element called popup-message on that page, you can trigger any custom event inside of popup-message from the index page (and any other page where you place the reusable element).

Scheduling

A custom event can also be scheduled to run at a specific time by using the Schedule a Custom event action and providing a number of seconds of delay before the event should trigger.

Is there a difference between triggering a custom event and scheduling a custom event to occur with a 0 second delay?

Yes, there is.

Let's say you have a parent workflow that has some actions, then a "Trigger a custom event" action, then some more actions. When the parent runs that Trigger action, the parent will pause and wait for the custom event to complete before running the actions that come after it. This is convenient in part because the custom event will be able to see the context of what happened in the actions before it in the parent workflow.

In contrast, if you schedule the custom event to occur with delay 0, that custom event could end up running in parallel to the rest of the parent workflow.

How are custom events executed?

Whenever a custom event is triggered inside of another workflow, the workflow will stop at that point, run the custom event until it is completed, and then move on to the next action in the "parent" workflow. You can use this to control some aspects of how workflows are triggered. You can read more about how workflows are triggered in the link below.

Article section: The order in which actions are triggered

FAQ: Custom events

I get the Issue Checker error "This workflow must end with a unconditional 'Return Data' action"

You will get this error when one or more of the Return data parameters are required (not set to optional) and the workflow does not have a Return data action, without a condition, as its last step. When a return data field is required, the workflow has to return something.

There are two ways to solve this:

• Add an unconditional action as the last step of the workflow, and return whatever data you need to

• Change the Return data parameter to be optional. This way a condition is accepted.

Can I loop a custom event?

Custom events cannot be looped, and as such a custom event cannot trigger itself. If you want to repeat a workflow more than once on a list of things, you can consider using Schedule API workflow on a list, and set up an API workflow that completes the action.