General Principles

Building a workflow

You first start by picking the event that will trigger the new workflow. Most of the time, it will be when a button is clicked, and you will have to pick the element this event applies to. If the workflow should only run under specific circumstances, you can add some conditions, this will be covered in the next section.

Once an event is created, the workflow panel shows up, and you can pick the different actions one-by-one. For each one, you will have to define the few fields that are necessary for the execution, for instance, where to find the email for a Sign the user up action.

The sequence of actions matters. If you need to insert an action before another, clicking on the arrow will reveal the action menu and you'll be able to add an action before the current one.

You can copy-paste workflows and actions by right clicking on them and pick the relevant option. If you copy-paste an event, the entire workflow will be copied, while you can copy-paste individual actions. Note that if you paste an action on another action, the action will be inserted before the current action.

Execution rules

When an event is triggered in run mode, it runs a series of actions, as defined in the Workflow Tab of your app for the current page. The execution happens action-by-action. If an action modifies some data, or fetches data from an external service like an API, the following actions will be able to refer to the previous action result (Result of previous action). In other words, the sequence of actions is critical.

When you define two (or more) workflows on the same event (for instance, on page load), each workflow will be run independently from the others, in parallel. If you need to have one workflow run before an other, you probably need to change your design and only have one workflow with more actions. Conditions and custom workflows are use to customize this behavior, if you need to run some actions before some others and only under certain conditions. This will be covered below.

Types of events and actions

Events and actions are sorted by category in the menu, when you click on an empty event or action placeholder.

In general, there are three main types of events:

Element events - these events are the most common as you build on Bubble. They are triggered when the user interacts with an element. For instance, a map's marker is clicked, or a button is clicked. For each event, you have to define which element this applies to. Note that these events will only be shown on the list if the relevant elements are on the page.

General events - these events, such as 'The current is user logged in' or 'Do when a condition...', are triggered as soon as a general property of the app changes, in such a case the user logging in. It is not related to a specific action from the user. These events can be more complex to debug, as they happen when something changes, but not necessarily something that the user has done on the app. The debugger is very useful to debug these situations.

Custom events - this very specific type of events let you define some reusable series of actions, that can used in other workflows. See the relevant section below.

Navigation - these actions let you navigate the user across pages in your application.

Data (things) - this category contains actions that read and write data. The next chapter will cover them in detail.

Email - this category gathers the few actions that send emails to users

Payment & analytics - Bubble built-in actions regarding credit card payment, subscriptions management and analytics are in these two categories. Notes that actions from Community-built plugins may cover these topics, and will be in the Plugin section

Plugins - this category is where most plugins's actions are gathered, for instance the send data to another service. See the Using Plugins chapter for more details.

Elements - these actions are element-specific actions. For instance, display a list in a repeating group, set a custom stage, or scroll to an element. For each action, you will have to pick the relevant element on the page. Note that as it is the case for events, actions will only be visible in the list if the page contains an element of the relevant type.

You can find details in the full Reference for more details for events, in particular the different fields that need to be filled in the Property Editor.

Lastly, some actions can run on the server only, on the client only, or both. This is important as you start running your application in production for pricing purposes (Bubble only charges for server-side runs). In general, actions that write data, connect to external services will run on both enviroments. Element actions, or navigation actions that you can use to show/hide elements, or take the user to another page, will not be run on the server and therefore won't count as a server-side run. Actions that send emails, charge credit cards run only on the server, and therefore are accessible in the API workflow section of your app. This is an advanced feature and is covered in a different chapter. API workflows are in particular useful to schedule workflows in the future or on a recurring basis.

Errors in workflows

If a workflow hits an error, for instance if you are using a Sign the user up action, and the 2 passwords don't match, or if a credit card action fails because the card is declined, the workflow will stop immediately. The actions that got run this far will not be reverted, and data modifications, or emails sent will not change back, but following actions will not run.

It is possible to add custom handling for workflow errors, for instance if you want to change the message or the user experience when an error occurs. See the reference for more details.

Note that it is also possible for workflows to time out - if a workflow has been running for more than ~5 minutes, it will error out by stopping (i.e. any actions that have already happened will have happened). Generally, workflows can be restructured to avoid this. For example, we commonly see issues with the "Make changes to a list of things", which is good for acting on a small list of things, but can quickly lead to timeout errors if the query is complex. To restructure this, we suggest creating an API Workflow and using "Schedule API Workflow on a list" if you can, or perhaps breaking the workflow up some other way. You can see if a workflow has timed out in the Server Logs.

Workflows can also error out if there is not enough capacity to run them. This can happen, for example, if you have many workflows scheduled to kick off at the exact same time. In this event, you will see a corresponding message in the Server Logs. To mitigate this, consider spacing out workflows to the extent possible, upgrading your plan, or purchasing more capacity.