Sanbox Designer

The fundamentals of the Designer.

How To Create Workflows

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.

JSON is Sanbox's primary data format. All well structured data flowing through workflows is presented in JSON with binary support.

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.

First Glance

Sanbox Designer With Workflow Opened
  1. Start Node

  2. Connection

  3. Node

  4. End Node

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 WSAD keys, 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.

Connecting Nodes

You can connect Nodes together easily by clicking one input/output of one Node, then clicking the input/output of another Node.

Selections

Selections can be made by holding down left-click and dragging with the mouse. Selections allow you to perform bulk actions like create Prefabs and Groups.

Selection made on the Surface

Surface Windows

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.

Two surface windows opened on surface

Node Selector

The Node Selector allows you to place nodes and function workflows you've made - fundamental elements of your workflow.

Node Selector Opened

Designer HUD

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.

Universe Panel

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.

Model Viewer Panel

With the Model Viewer Panel opened, you can click elements on the Designer Surface to view Models being used for inputs/outputs.

Debug Workflows Panel

The Debug Workflows panel allows you to debug workflows.

Object Viewer Panel

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.

Opened Object Viewer

All data is displayed in JSON, Sanbox's primary data format.

Surface Editor Problems Panel

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.

Fundamentals

Workflow Variables

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:

Before

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.

After

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.

Setting a Variable from Input/Output

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.

Output border is purple, indicating that a variable is to be set.

Setting a Variable with a Set Variable Node

You can also set variables using the Set Variable Node.

All variable names must be alpha-numeric with no spaces.

Variables can be recalled by using Conduits, covered below.

Conduits

Conduits are used everywhere in Sanbox, so it is important to understand how they work.

Sanbox Conduit
Copy Files Node, with conduits specified.

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

Opened Conduit Editor

In the above example, this Conduit is expecting a string, so we've set the Source to be Text Plain and specified our own string literal.

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 C:\CustomerInfo\Marketing to C:\MarketingBackup.

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

Sanbox does not use strict typing. For example, if you give a Conduit a number when it wants a string, the Conduit will convert the number to a string. Models are used to enforce data integrity, and there is an exception to this rule if a Conduit is being used to populate a property inside a Model (i.e with Builder Node).

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.