Workflows are small programs created in Sanbox. All Workflows begin with a Start Node. A Start Node dictates the purpose of a Workflow; whether it's an API endpoint, function, or scheduled job. In Sanbox, Workflows are deployed instantly when you save a valid Workflow.
Your Workflows are comprised of Nodes. Every Node in Sanbox serves a small atomic purpose. There are Nodes for executing logic, Nodes for accessing databases, Nodes for communicating with other HTTP APIs, and many more. When a Workflow is executed, the first Node to execute is called the Start Node. The Start Node outputs data through an output, which is connected to another Node's input. When this Node receives the output from the Start Node, this Node executes and does its job, outputs its own data, and the chain continues. This chain is called the execution path.
Outputs can be fanned out and connected to multiple inputs. When this is done, each input will be executed simultaneously. This forms multiple execution paths running at once. The same Nodes can also be ran more than once as part of a different execution path.
Workflows stop when all execution paths have completed. An execution path is completed when the last Node in the chain has no outputs, or has nothing hooked up to the output(s) they have. APIs and Functions in Sanbox require you to have an End Node (API Response Node, and Function End Node respectively). For Workflows with multiple execution paths, these End Nodes must have received input before all execution paths have finished so that Sanbox may conclude an API call and send a response (with the API Response Node), or conclude a call to a function and return a result or null (with the Function End Node).
Important: Consider the example below. An API Workflow is created that returns an array of users in the system. Upon a
GET request, both the Query Node (which obtains data from a database) and the Wait Node are executed at the same time. Although the query executes very quickly, the Wait Node has been configured to wait three seconds. Sanbox waits for all Nodes to finish execution before a workflow finishes. So in this case, a response is not returned until three seconds have passed.
When opening a Workflow in Sanbox Designer, you are presented with Nodes, their outputs and inputs, and their connections to other Nodes residing on a canvas called the Designer Surface. You can pan around on the surface by either holding down
space and dragging with your mouse holding down the
left-click mouse button, or by using the
WSAD keys when focus is on the Surface. When using the
Shift can be held down allowing for faster panning. Zooming is accomplished by using the mouse wheel.
Right-Click anywhere on the surface to access the surface context menu, which allows you to place Nodes, Prefabs, and perform other editor actions.
You can connect Nodes together easily by clicking one input/output of one Node, then clicking the input/output of another Node.
Each Node can be configured by double-clicking it. Configuring a Node opens a new window onto the surface. This window can be dragged, or set to follow you as you navigate the surface. Multiple windows can be opened at one time, and can be zoomed in or out.
The Node Selector allows you to place nodes and function workflows you've made - fundamental elements of your workflow.
The Designer HUD (Heads Up Display) contains everything that is overlaid on top of the Designer Surface. It includes the side menu panels listed below and other HUD elements.
The Universe Panel contains an organized project/folder structure of all of your Projects, Models, Sanbox Files, and Workflows. Here you can create new items in Sanbox, upload and sync files, export and import items, and much more.
With the Model Viewer Panel opened, you can click elements on the Designer Surface to view Models being used for inputs/outputs.
The Debug Workflows panel allows you to debug workflows.
The Object Viewer Panel serves many purposes. When you test a Node, the Object Viewer populates with the result. When debugging Workflows, data is routed to the Object Viewer when Nodes on the surface are clicked. The Object Viewer is used to supply parameters for test data as well. Clicking the plus (+) button will add a new object to the viewer. If you have JSON data in your clipboard, it will automatically be added to the viewer. Clicking the negative (-) button will clear the Object Viewer.
All data is displayed in JSON, Sanbox's primary data format.
The Surface Editor Problems Panel is located at the bottom of the Designer HUD. Errors and warnings pertaining to the development of your Workflow are displayed here.
As your Workflows become more complicated, you may need to reference data that is present towards the beginning of the Workflow, but not available at a Node's input later down the execution path due to Nodes manipulating the data beyond its original structure. This issue is overcome using Workflow Variables. Consider the below Workflow:
In the above example, we have a Query Node accessing the database for an array of users. The Query Node outputs an array containing 4 users. Our Array Operations Node outputs the first user in the array. Afterwards, our File Operation Node creates a file for the one user. Our File Operation Node then outputs its received input data. In this hypothetical Workflow, our Memory Store Node is acting as our cache for the users from the database, so it must receive the entire array of users from earlier, but it only received the first user as input. For the sake of this example, let's say that we must guarantee the file was written successfully before we store the users in cache, thus, we can't change the order of our Nodes. To overcome this issue, we will use a variable. Our Query Node is setting a variable called
allUsers on its output
query finished. Our Memory Store Node in the meantime is configured as follows:
We need to change our Memory Store Node to instead use the aforementioned variable for our
Value field, as we want to store all users in the store, not just the one user we will be receiving input for.
There are two ways to set variables:
You can configure an input or output to set a variable when fired by right-clicking the input/output and selecting Set Variable in the context menu.
The example above demonstrates setting a variable from the data flowing through an output with a specified JSONPath grabbing the first element in an array (you can also get the first element of an array using JSONPath instead of using an Array Operations Node). When 'Done' is pressed, the output will display a purple border – indicating that it has been configured to set a variable.
You can also set variables using the Set Variable Node.
Variables can be recalled by using Conduits, covered below.
Conduits are used everywhere in Sanbox, so it is important to understand how they work.
Conduits are buttons in Sanbox Designer that specify data sourced elsewhere in Sanbox. You configure Conduits by clicking them. Clicking a Conduit opens the Conduit Editor. In the above example, we are configuring a Copy Files Node. We have the
Source Directory Conduit set to provide a
string literal or static text. Below this, we have the
Target Directory Conduit set to provide the value of a variable declared earlier called
In the above example, this Conduit is expecting a
string, so we've set the
Source to be
Text Plain and specified our own
When the above configured Copy Files Node runs, it will process the first Conduit, giving it the
Source Directory of
C:\CustomerInfo\Marketing, the second Conduit for
Target Directory will then be processed yielding the value of the
marketingDumpDirectory variable, which is set to
C:\MarketingBackup. The Copy Files Node will then copy the files from
Conduits sometimes have an
Expected Model which shows what data format the Conduit is expecting. A string in this case would mean this Conduit is expecting text. Learn more about Models
Conduits have a
Source which determines where to obtain the data. Color coding allows you to quickly determine the source of a Conduit without needing to open it. There are a few available sources to choose from:
None: Indicates that null will be returned.
Text Plain: Plain static text.
Text Template: Text using Sanbox's Text Template System.
Input: When configuring Nodes, refers to the input coming into the Node. Can also refer to different things depending on where the Conduit is.
Variable: Refers to a variable.
Static Json Object: JSON that you predefined in the conduit. Remember that JSON can also be a JSON primitive such as just a string, boolean, or number.
Operation: A simple function. There are many operations available to manipulate text, perform math operations, date operations, and more. Operations can open up to Conduit Chaining.
The Variable and Input source allow you to specify a JSONPath to be used to drill down on input or variable data.