The Basics

Bubble is built around a workflow-based programming system. A workflow is an event that runs a series of actions when triggered. For instance, when a user clicks on button 'save' (the event), 'something' should happen (the series of actions).

Our Academy course includes a walkthrough of the Workflow tab

Building a workflow

A workflow is composed of an event, which is what triggers the workflow and the series of actions that run. The combination of the event and the series of actions is what defines a workflow. An example of a workflow is 'When the button Signup is clicked, sign the user up, send an email, and then change the page.' Workflows are specific to a page in the app and are modified in the Workflow tab. If an action returns information, you can access this information as 'Result of previous step.'

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.

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.

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; 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.

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.

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.

Note: Although a workflow is created as a linear set of actions, there is a lot going on behind-the-scenes when a workflow executes. This can sometimes lead to some steps firing before other, earlier steps in rare cases.

More technical explanation: some workflow actions can happen on the client's browser, while others have to happen on the Bubble server and some even have to happen on both browser and server! If a workflow has a mix of actions from these three categories, the ordering of the actions fired might be different from the linear design because of what's firing on the browser versus the server.

Tip: If an end-user does something that kicks off the same workflow many times within a short window of time (e.g. clicking on a button repeatedly very quickly), Bubble tries to be smart about executing that workflow: any actions that make sense to repeat (e.g. changing a thing) will be repeated and any actions that don't make sense to repeat (e.g. navigating to another page) should not be repeated.

Types of events & 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 event lets you define some reusable series of actions, that can be used in other workflows.

Similarly, actions can be separated in a few categories:

  • Account management - these actions let you sign a user up, log in, log out, etc.

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

  • Data (things) - this category contains actions that read and write data

  • 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. Note 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

  • Elements - these actions are element-specific actions. For instance, display a list in a repeating group, set a custom state, 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.

Client versus server-side actions

Some actions can run on the server only, on the client only, or both. In general, actions that write data or connect to external services will run on both environments. 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.

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.

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.