A workflow is the automation and advanced-logic tool in Buttons. Use it to automate behavior that does not begin with a person pressing a button, or when a button press needs more logic than a direct sequence of actions can provide.
You connect nodes to receive events, read current values, make decisions, transform data, run actions, or exchange data with another system. A workflow can start from a connection-state change, timer, schedule, NFC read, incoming network request, or another event. It can also start from a button when the result depends on conditions, branching, retained values, timing, or communication with other systems.
For example, a workflow can watch a connection and respond when its state changes, run scheduled housekeeping, act only when several conditions are satisfied, retain a shared value, or provide an authenticated HTTP endpoint. Use a direct button action when a press should run a straightforward action. Use a Cuelist when actions should advance in a determined show order.
A workflow is a canvas containing nodes and the connections between them.
A node performs one focused job. It might read a connection variable, compare two values, wait for an event, or run an action.
A connection carries either a value or an event from one node to another.
Connections on the left side of a node are inputs. Connections on the right side are outputs.
Some nodes add inputs or outputs after you choose an action, feedback, endpoint, case, or named variable.
Follow a workflow from left to right to understand how information and events reach their result. A workflow does not have to be one uninterrupted chain: one output can support several branches, and separate branches can serve different purposes.
A value carries the latest piece of information available at that point in the workflow. It can be text, a number, a true-or-false condition, a structured object, or another supported type.
Examples include:
the current connection state
the active source name Camera 2
an audio level of -12
whether automation is enabled
the latest HTTP response
When an upstream value changes, nodes that depend on it can calculate new outputs. If the value does not change, it continues to represent the current state; it does not represent another occurrence.
Use values to answer questions such as:
What is the current level?
Is this condition true?
Which mode is selected?
What text should be displayed?
Values are the normal choice for calculations, comparisons, labels, conditions, and live status.
An event represents an occurrence at a particular moment. Examples include:
a Button node was pressed
a timer finished
an NFC tag was read
an HTTP request arrived
a connection action succeeded or failed
Each event is handled separately. Two identical button presses are still two events, because the occurrence matters, not whether a stored value changed.
An event can also carry a payload. For example, an incoming message event can include the received message, and an HTTP completion event can include response information. The event tells downstream nodes when to respond; its payload can tell them what arrived.
Calculate, compare, display, or hold current state
Trigger an action or advance a sequence
A node can provide both. The Button node, for example, emits an Event for every press and provides a Timestamp value showing when the latest press occurred. Connect Event when every press should trigger work. Connect Timestamp when another node needs the latest press time as data.
A changing value and an event are not interchangeable: the editor enforces this directly: dragging a connection from an event output to a value input (or the reverse) is simply refused, so a value and an event can never be connected to each other by mistake.
Suppose a connection feedback outputs true while a device is connected and false when it disconnects. Connecting that Boolean directly to behavior that reacts to every change can respond both when it becomes true and when it becomes false.
Use Change Switch when the workflow needs separate events for those transitions:
Connection Feedback → Change Switch → True Result → connected behavior └→ False Result → disconnected behavior
This pattern is useful when a current condition should trigger an action only as it enters a particular state. It preserves the feedback value as the source of truth while making the transitions explicit.
Choose between a card value and a connected value#
Many nodes let you enter a setting directly on the node card or supply it through a value connection.
Use the card when the setting is fixed for this workflow. For example, enter 100 as a fixed maximum on Clamp.
Use a connection when another node should determine the setting while the workflow runs. For example, connect a Workflow Variable to the maximum so an operator-facing control can change it.
When you connect a value to a setting, the connected value normally becomes the working value. What happens to the card field itself varies by node: on most nodes (for example Math's Value A/Value B, or the open/closed switch on State Gate/Event Gate) the field stays visible and simply displays the incoming value instead of its configured default; it's still clickable, but a connection takes priority whenever one is present. On a few nodes (for example HTTP Request's URL) the field disappears entirely once connected. And a small number of inputs are connection-only from the start, with no card field at all regardless of connection state: Case Switch's Select and Default, and several of Counter's inputs, work this way. Dynamic nodes can also change their available connections after you select an action, feedback, or endpoint.
automation starts from something other than a button press
a button press must branch according to current conditions
several values must be compared, transformed, combined, or retained
events must be delayed, ordered, gated, scheduled, or handled differently on success and failure
Buttons must receive data from or send data to another system
A workflow is usually unnecessary when one button can run the required action directly. Avoid hiding a straightforward control behind extra workflow logic.
Start with the outcome, then identify the information and occurrences needed to reach it:
Choose what should happen, such as displaying a warning or running an action.
Identify the event that should start it, or the value that should control it.
Add only the comparisons, transformations, and gates needed between the input and outcome.
Use Display nodes to inspect important values while building the workflow.
Keep success and error events separate where recovery differs.
For example, an automation that reacts when a calendar activity becomes active might use this flow:
Calendar event name → Logic Operation → Change Switch → True Result → Connection Action
The calendar name is a value. Logic Operation turns the comparison into a Boolean value. Change Switch emits an event only when that result becomes true. The event then runs the action once, rather than running it again when the condition later becomes false.
Node cards show their configuration and, where useful, their current output. A red outline or warning indicator means the node has a configuration or connection problem that needs attention.
Use Display to expose an important value directly on the canvas. It is useful for tracing a workflow from input to result and finding the first point where the value differs from what you expected.
Changes on the canvas are not committed until you select Apply. A disabled workflow shows This workflow is disabled. The state of the nodes will not be updated. at the top of the editor. Review event-triggered actions before enabling or applying a workflow, especially when they can affect production equipment or external systems.
