03 Workflow Design Basics

New Workflow

Let’s start by looking at some of the basic design principles of Flowgear Workflows.

From the Console, go to Workflows, then click + to create a new Workflow.

Optionally provide a name for your Workflow, click Save Changes or press Return.

As you hover over the design canvas, you'll see a + icon appear where you are able to drop steps on to it. In Flowgear we refer to these steps as Nodes.

Click + to open the Node Chooser.

Nodes

You'll see a list of all the available Nodes as well as tabs to filter Nodes by their categories. There are four different categories of Nodes in Flowgear:

• Connectors wrap third party apps or services. Salesforce and Microsoft SQL Query are two examples.
• Triggers wait for a condition to be met. For example, File Watch waits for a file to be created in a specific folder while Day Scheduler waits for a specific time of day.
• Processors evaluate or transform data in memory. These include the For Each which is used to iterate through a set of records or QuickMap, our Visual Data Mapper.
• Evaluators allow the Workflow to proceed in a different direction based on an evaluation. For example, If evaluates a condition and allows the Workflow to branch along a true or false route based on its outcome.

At the top of the Pane, you'll also notice Workflows, next to Nodes. In Flowgear, Workflows can reference (call) other Workflows. We'll discuss this in more detail in a later section.

Node Components

Filter the Nodes Chooser for Formatter Node and select it to add it to the Canvas. This Node handles string formatting and we'll use it to get familiar with the basics of Workflow Design.

Node Header

The top section of the Node where its name is displayed is called the Node Header.

• Drag the Node Header to move the Node to a different position on the canvas.

• Click the Node Header to focus the Node (for example in order to copy it).

• Click the Node Header a second time to change its descriptive name.

• Hover the Node Header to see the Node Version.

New Node versions are published to each tenant as they become available. When a Node is added to the Canvas from the Node Chooser, the latest version of the Node is specified. The version of the Node used on a Workflow does not change automatically - this is to ensure its behavior doesn't change.

When a newer version of a Node is available, you'll notice a horizontal red line just under the Node Header.

You can upgrade the Node to the latest version from the Node Context Menu. Click v in the Node Header to access the Node Context Menu.

We will review the other options in the Node Header Context Menu later in the course. For now, also note the Delete Node option to remove the Node from the Canvas.

Node Input & Outputs

To the left and right of the Node Header are the input & output Execution Flow Sockets.

In Flowgear, Execution Flow Sockets are connected together to show the order in which Nodes in a Workflow should execute.

Create a Flow Connector by beginning to drag on the Start Flow Socket of the Start Node. As you do this, a Flow Connector will be added that follows your cursor. Snap the other end of the Flow Connector into the input (left) Flow Socket of the Formatter Node Header.

To remove a Flow Connector, drag it so that it disconnects from its target and then release it.

To move a Flow Connector to a different target, drag it to disconnect it from its current target and then snap it to a new one.

Re-add the Flow Connector from the Start output of the Start Node to the Execution input of the Formatter Node.

Node Properties

Below the Node Header are the Node Properties.

These Properties are different for each Node and configure how it behaves. Some Properties are input Properties so they have a Data Flow Socket on the left-hand side (for example, the Expression Property of the Formatter Node). Other Properties are output Properties so they have a Data Flow Socket on the right-hand side (for example the Result Property of the Formatter Node).

Setting Properties & Custom Properties

The Formatter Node allows us to prepare a string for use later in the Workflow. As an example, we'll configure it to echo back an order quantity.

Hover to the right of the Expression label on the Formatter Node and you'll see a textbox outline appear. Click this to open the Property. When a Property supports a full document or multi-line text, it will open in a popup window.

Type Your order quantity is {quantity} into the textbox and click ✓ to commit the value and go back to the Workflow Design.

In the expression we just provided, the curly braces signal that quantity is the name of a variable that will be translated into the expression.

Click + at the bottom of the Node to add a Custom Property. The default Property name Custom1 appears. Replace it with the text quantity and press Return or click elsewhere on the Workflow to commit the change.

Set the value of the Property quantity to 10 by clicking the textbox to the right of the Property quantity.

Running the Workflow

Click the ▶ Test button at the top of the screen.

A Workflow Log will display showing the steps of the Workflow executing.

You should see a ✓ on each row showing that the step executed successfully. (If you see X, you can hover or click it to see details of the error).

Click a row in the Workflow Log to see the names of the Properties for that row. You can drill in to a Property value by clicking it in the Workflow Log too.

Adding Inputs and Outputs to a Workflow

In the Workflow we created, we hardcoded the number 10 in to the Custom Property quantity on the Formatter but in a real world scenario, we often want to be able to dynamically inject a value into a Property.

Flowgear allows a set of input and output Properties to be defined for a whole Workflow through the Variable Bar Node.

Add a Variable Bar Node to the Canvas (generally it's neatest to add it just above the Start Node).

Click + to add a Property and rename it to quantity. (Note that the name doesn't have to match the Custom Property we added to the Formatter - we're just choosing to give it the same name).

The new Property defaults to an Input Property. In other words, its Flow Socket is on the left-hand side. For our purposes, we need it to be an Output - click the checkbox on top of where the output Flow Socket would be to convert it to an output Property. If you've already closed the overlay that allows you to toggle this, click the Property name to open it again.

Next, create a new Data Flow Connector by dragging from the output Socket of the quantity Property on the Variable Bar to the input Socket of the quantity Property on the Formatter Node.

Data Flow Connectors show how data moves from one step to another whereas the Execution Flow Connector we created earlier (attached to the Start Node), shows how execution proceeds from one Node to another.

Finally, clear the value 10 from the quantity Property of the Formatter Node and instead capture it in to the quantity Property of the Variable Bar Node.

Run the Workflow again to see how the value 10 is injected into the Custom quantity Property on the Formatter Node.

We will cover the Variable Bar in more detail later but to recap, it acts as a way to send Properties into a Workflow as well as read them out of the Workflow.

Conditional Logic

Let's add a conditional step to our Workflow.

Click the + just to the right of the Formatter Node, filter for If and select that Node.

Drag a Data Flow Connector from the quantity Property of the Variable Bar to the Value Property of the If Node. This causes the value that is in the Variable Bar Property to inject into the Value Property when the Workflow runs.

Drag an Execution Flow Connector from the Execution output Flow Socket of the Formatter Node to the Execution input Flow Socket of the If Node. (Remember that the Execution Flow Sockets are location in the Node Header). This causes Flowgear to run the If Node after the Formatter Node.

We're going to evaluate whether the quantity is below a certain threshold. Place the value Value < 100 in the Expression Property of the If Node.

Custom Errors

If more than a quantity of 100 is ordered, we're going to treat that as an error. We want to generate a custom error explaining this constraint.

Add the Error Node to the Canvas and drag an Execution Flow Connector from the False Execution Output of the If Node to the Execution input of the Error Node.

Set the value The quantity ordered is too large to the ErrorMessage Property of the Error Node.

Run the Workflow again and you should see the If Node in the Workflow Logs should show that the output that fired was True (the log will show → True).

Change the value of quantity on the Variable Bar to 100 and run the Workflow. This time, you should see the If Node fires False and that the custom Error Node executes causing the whole Workflow to fail with The quantity ordered is too large.

Handling Errors

We just looked at generating a custom error as part of validating input data but we also need to look at how to handle errors that were generated by the platform or the Connectors.

There are two categories of errors you'll need to take into account when building a solution.

• Runtime errors occur when a Node fails to execute. Examples include a Node that has been misconfigured or where it requires a Connection and an incorrect credential has been provided.

• Application errors occur when a Node executes but the response indicates that there is at least partial failure. For example, you might use the Salesforce Node to push multiple contacts into Salesforce. The response that comes back will show you which of the contacts succeeded and which failed but the Node itself didn't fail to execute.

You can handle runtime errors as part of your Workflow design by connecting a Flow Connector from the red error Flow Socket of a Node to another Node that should be used to handle that error.

To see how this works, let's look at a scenario where we've received a non-numeric value in the quantity Property of the Variable Bar.

Set the value of quantity to abc and run the Workflow.

This time the If Node errors with Invalid statement: Conversion from string....

This is not an error message we necessarily want to report back to a consumer or an end user so we'll handle that error and generate a custom error with a more helpful message instead.

To do this, add another Error Node to the Canvas. Create an Execution Flow Connector from the red Error Socket on the If statement to the new Error Node.

Set the ErrorMessage Property of the new Error Node to Please provide a number.

Run the Workflow again and you'll see the If Node still generates an error but execution is directed to the new Error Node which in turn causes the Workflow to error out with a more helpful error message.

In the example above we used an Error Node as our handler but you can use any Node you like (or any sequence of Nodes). For example, you might trigger a notification via email or DM that an invalid quantity had been captured.

We have also looked at connecting to the error handler on the Node itself but you'll notice that the Start Node has some special error handlers that capture errors anywhere in the Workflow.

• AnyError will fire whenever there is an error in the Workflow regardless of whether the error is handled on the Node by attaching another Node to the Error Output

• UnhandledError will fire whenever there is an error in the Workflow except if the error is handled directly via the Error output of a Node