Bubble Docs

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.
Tip: If you would like to access an element inside a repeating group within a workflow, that workflow will need to be triggered by an element inside a repeating group cell.

Execution rules

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.
For efficiency purposes, workflows run in parallel across the server and the front end. Despite the names “Step 1," “Step 2," it is important to note that a given step does not necessarily wait for the previous one to complete before triggering the next one. The following is some information about Bubble workflow logic and general recommendations. Please also note that steps and actions are used interchangeably, but steps may be used in these examples when the order is important to note.
General rules about how workflows run:
  • Frontend workflow actions run in order but the next action does not wait on the previous action to be complete before triggering.
  • Backend workflows are triggered as soon as the workflow is triggered, independently from steps. For example, a "Schedule API Workflow’" action will be triggered as soon as the workflow is triggered even if it is placed last in the workflow action sequence.
  • Custom events run in sequence, not parallel. If Workflow 1 triggers a custom event that starts Workflow 2, Workflow 2 will complete before the remaining actions in Workflow 1 run.
  • Searches aren’t always immediately updated with new data. So if you create a new item, and then try to retrieve it via search, it may or may not work; you should not rely on this.
  • Retrieving a thing from “result of step X” where step X is the “Create…” step should always be safe.
Workarounds to help achieve workflow consistency:
  • When a workflow trigger (e.g. a button) can have multiple results based on conditions, it is safer to create multiple workflows and place the conditions at the workflow level instead of creating one workflow with all possible actions and placing the conditions at the action level.
  • In a workflow with two actions, if Step 2 is using a condition based on a search depending on data manipulated in Step 1, then Step 1 should be implemented into a custom event to make sure it is finished before moving on to Step 2.
  • If a backend workflow should be triggered after other steps in the workflow, then it should be implemented in a custom event placed after the steps that need to come first.
  • The safest way to use data from one step to another is to use the “Result of step X” operators instead of searches.
  • We do not offer the explicit ability for an action to wait for a workflow to be over before moving on to the next step; however, using "add a pause before next action" action is usually an effective workaround.
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. Go to page actions, toggling or scrolling to elements, and setting custom states would be examples of client-side actions. In addition, client-side workflows will not show up in your application's server logs.

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.

Five minute unit of work timeout error

The longer a unit of work takes, the more likely it is to run into unexpected termination. Consequently all units of work have a timeout limit of 300 seconds. If the unit of work has not been completed within five minutes, an error will occur and the work will stop. The most common units of work are http requests and workflows.
In a workflow, any actions completed prior to a timeout error will not be affected because each unit of work starts a new timer. So, if workflow A successfully schedules workflow B, once workflow B starts running it will have a fresh timer. Even if workflow A gets forcefully terminated, workflow B has already been scheduled. If workflow B can be completed in less than five minutes, it will complete. Each workflow happens asynchronously with respect to all others.
If a timeout error occurs on a workflow, restructuring the workflow may be necessary. For example, the “Make changes to a list of things” workflow action works well for a small list of things or a simple action, but can lead to errors on longer lists or complex queries. For example:
  • If you want to do something once per hour, having workflow A schedule workflow B an hour later, as a first action, is probably what you want.
  • However, if you want to perform the same action on a large number of records, workflow A should be configured to run through a small number of records, and then pass a cursor for the last completed item to the next run of workflow A, which can be scheduled immediately.
Workflow timeout errors will appear in the Logs tab of the app editor.