04. Build your first Workflows

Now that we have the basics of working in the Design Canvas out of the way, let's move on to some practical exercises!

When you see a section titled 'exercise', this is a practical exercise that you need to follow along with.

Create a new Workflow for each exercise and name it according to the exercise number so you can easily come back to it later if you want. Follow the steps listed to build the Workflow and then run it to confirm it's working as expected.

Submit the Workflow for grading by clicking Submit Exercise, then select the exercise number that the Workflow represents. You'll receive a message letting you know whether the exercise passed.

If it didn't pass, there will be some error information explaining what was missing.

Workflow Design Shorthand

We're going to be building many different types of Workflows so we'll use these shorthand conventions to describe certain steps. This enables us to provide steps that are shorter and unambiguous.

"Add Loop" means "add the Loop Node to the Workflow".
"Add Loop rename to outer loop" means "add the Node to the Workflow but then rename it by double-clicking the Node Header". This is done when there will be multiple of the same Node in the Workflow and we want to be able to differentiate them. From that point on, the Node will be referred via the name specified and not the Node name.
"Connect outer loop → Formatter" means "create an execution Flow Connector from the Loop Node to the Formatter Node`". This is an Execution Flow Connector because no Property names are referenced and it therefore can't be a Data Flow Connector.
"Connect outer loop.Error → Formatter" means "create an execution Flow Connector from the Error Output of the Loop Node (i.e. the red Flow Socket at the bottom of the Node) to the Formatter Node".
"Connect If.True → Formatter" means "create an Execution Flow Connector from the True Output of the If Node to the Formatter". This is also an Execution Flow Connector because although there is a named output on the If Node (True), there is no Property name specified on the Formatter.
"Connect outer loop.Current → Formatter.Expression" means "create a Data Flow Connector from the Current Property of the Loop Node to the Expression Property of the Formatter Node". This is implicitly a Data Flow Connector because there are Property names for both the source and the destination.
"Set outer loop.Start to 5 " means "assign the value given to the specified Property".
"Add If.someProperty" means "add a Custom Property named someProperty to the If Node". By default, when a Custom Property is added, it will be an input Property (left-hand socket). If the step requires an output Property, this will be noted explicitly.

Exercise 01: Get Employee

In this exercise, we'll call a third-party API that returns details of an employee given an employee id.

Add Web Request 2.

Web Request 2 is our latest connector for making calls to third party APIs or websites.
Set Web Request 2.Url to https://zorkco.flowgear.net/employees/{id}/?auth-key={auth}.

In the URL above, we're using braces to denote identifiers that will be replaced out later. The runtime will look for a Custom Property on the Node that has the same name as the identifier and translate it out before invoking the Node.
Add Custom Properties Web Request 2.id and Web Request 2.auth. These match the brace-encapsulated identifiers in the Url Property.
Add Variable Bar, rename it to Inputs.

This Variable Bar Node will contain the inputs into the Workflow. The best place to position it is just above the Start Node.
Add Inputs.id as an output Property, set its value to 1.
Add Inputs.auth as an output Property. Also change its Property Type from Default Property to Hidden Property.

Marking a Property as hidden ensures its value isn't visible from outside of the Workflow.
Set Inputs.auth to dMFROUiQadVEWaHZe8qTEHM9TieeyGo7PBhY9Ln1TwKCsGu-sfgnJUh4OKIrBZLplNtXKWdcJDdqgHjVScr24Q.
Connect Inputs.id → Web Request 2.id and Inputs.auth → Web Request 2.auth.
Connect Start.RunNow → Web Request 2.

Run the Workflow to check it executing successfully. If you focus the Web Request 2 Workflow Log Entry and scroll to the right, you'll see a column header for ResponseBody.

The document for employee 1 will be shown there but since it's a JSON document you'll only see the first line which is a brace character ({). Click this to view the document in a full screen modal.

We'll now add a Variable Bar to capture specific elements out of the response document.
Add a second Variable Bar Node to the right of Web Request 2, rename it Outputs.
Add Custom Properties Outputs.name, Outputs.salary and Outputs.age.
Connect Web Request 2.ResponseBody → Outputs.name, Web Request 2.ResponseBody → Outputs.salary, Web Request 2.ResponseBody → Outputs.age.

By default, a Data Flow Connector will send the full Property value from the source Property to the target but you can also use Data Flow Expressions to pick a specific element out of a document.

Hover a Data Flow Connector to see the fx icon. When clicked, a tree of the known fields inside the Property will be displayed. You can select the specific field you want or capture a JSONPath expression.

If you don't see a tree view containing fields, this means no example document is available because the Node the Flow Connector connects from has not been run. Run the Workflow, ensuring that specific Node executes, in order to provide sample data that can be used to create the tree view.
Hover each of the Flow Connectors you just created and click the fx icon to choose which field to pick for each Flow Connector. Select employee_name for name, employee_salary for salary and employee_age for age.

Run the Workflow again. This time you should see individual Properties for name, salary and age on the Start Node entry in the Workflow Log.

Save your Workflow, then click Submit Exercise to grade it.

Copying Workflows

To prepare for the next exercise, you'll need to copy the Workflow you created above to a new Workflow. There are two options for doing this - try both so you're familiar with them!

Copying Nodes from a Workflow

While holding CTRL (Windows) or ⌘ (Mac), left-click to drag a rectangle around the Nodes you want to copy. When you release the mouse button, you'll see selection rectangles around all the of the Nodes that were included. Click the Copy button in the toolbar to copy the Nodes.

Create a new Workflow. Note that you can quickly open a new browser tab for the Workflows list by CTRL or ⌘ -clicking the Workflows option in the left-hand menu.

Click the Paste button in the toolbar to paste the Nodes. Note that the Start Node won't paste because it doesn't make sense to have two in a Workflow.

Copying Workflows

From the Workflows Pane, hover the Workflow you want to copy and click the □ (checkbox) icon in the top-right. Click the copy icon in the toolbar.

Navigate to where you want to paste the Workflow or Workflows, click the paste icon in the toolbar.

Exercise 02: Get Employee with Error Handling

In this exercise, we'll add error handling for cases where the requested employee id doesn't exist. Use the copied Workflow you just created as a starting point for this exercise (don't forget to change the Workflow name by clicking the Workflow Settings button).

Set Inputs.id to 999.

Run the Workflow and you'll see it fail with the error Response status code does not indicate success: 404 (Not Found).

We'll now look at two ways to handle errors so that we present a more helpful response.
Add Error, connect Web Request 2.Error to Error.
Set Error.ErrorMessage to Employee not found.

Run the Workflow again. The error still occurs on the Web Request 2 Node but is consumed by the Error Node which now generates a more helpful error message.

Nodes will generate an error for complete failure but many types of errors require that we inspect the response (i.e. output) Properties of a Node to determine success of failure.

We'll look at an example of how this is done by suppressing errors on the Web Request 2 Node.
Hover and then click the Connection Property value on the Web Request 2 Node.
Click the + button in the overlay that appears. A new Connection will be created.
With the overlay still visible, click the ✎ button to open the Connection in a new browser tab.

This is the Connection Pane showing details of a Connection. You can provide a custom name for the Connection in the Name Property and see which Node the Connection is for in the Node Property.

Below the Environment label is a tab strip showing the Environments that are defined for the current Site. We will look at these in more detail later.

Below the Environment name is the list of Properties associated with the Connection for the selected Node.
Turn on the ReturnFailureResponses Property and click save.

ReturnFailureResponses controls what the Web Request 2 Node does when a failure occurs.

When this Property is false (i.e. turned off), any HTTP failure (i.e. a non-200 response) is treated as a Node error. This is the behavior we saw when we ran the Workflow with an invalid employee id.

When this Property is true, the Node will not error and instead the HTTP response information will be returned in the relevant output Properties.

Go back to the Workflow and run it again, the Workflow will no longer error. We are now ready to inspect the output Properties of the Web Request 2 Node to determine whether it failed and take an appropriate action.
Create a space on the canvas by moving the Outputs Node on the right of the Workflow further to the right.
In the space between the two Nodes, add If.
Connect Web Request 2 → If.
Connect Web Request 2.StatusCode → If.Value.
Set If.Expression to Value = 200.

The If Node is now configured to read the status code returned from the web request and determine whether the response is 200. (For an HTTP request, a 200 response means success).

The Node will then fire either the True or False Execution Output. Since we have no further steps in the Workflow, we won't be connecting anything else on to the True output but we will connect our Error Node to the False Output.
Connect If.False → Error.

Run the Workflow. This time no error will be generated by the Web Request 2 Node since we suppressed that behavior by turning on ReturnFailureResponses.

However, the If Node should fire False indicating that the web request was not successful, causing the Workflow execution to route to the Error Node.

Save your Workflow, then click Submit Exercise to grade it.

Exercise 03: Get Weather

In this exercise, we'll create a Workflow that returns the forecast temperature for a specific city, using the same error handling techniques we learned earlier.

Add Web Request 2, Set Web Request 2.Url to http://api.openweathermap.org/data/2.5/weather?q={city}&APPID={appid}&units=metric.
Add Custom Properties Web Request 2.city and Web Request 2.appid.
Add a Connection to the Web Request 2 Node and in the new Connection, set the ReturnFailureResponses Property to true (i.e. toggle it on). Don't forget to save your Connection.
Add a Variable Bar, rename it Inputs.
Add Inputs.city and Inputs.appid as output Properties. Set appid to be a Hidden Property.
Set the Inputs.appid Property value to c95dadb707ef003ac19b0236e63e348a.
Set the Inputs.city to a city name - e.g. atlanta.
Connect Inputs.city → Web Request 2.city and Inputs.auth → Web Request 2.auth.
Add If, connect Web Request 2.StatusCode → If.Value.
Set If.Expression to Value = 200.
Add a second Variable Bar, renamed Outputs to the right of the If Node.
Add Outputs.temperature, connect Web Request 2.ResponseBody → Outputs.temperature.
Add Error, set Error.ErrorMessage to Invalid city..
Connect Start.RunNow → Web Request 2 Node, Web Request 2 → If and If.False → Error.

Run the Workflow at this point. You should see no errors but will also see a full JSON document being returned in the temperature Property instead of just the temperature.

We only want to pick the temperature field out of the response Property but before we ran the Workflow, we couldn't see what the response would look like and therefore couldn't select the temperature field.

Now that the Workflow has run successfully, Flowgear has a record of the response and will use that to generate a tree view of the fields that were returned in the ResponseBody Property.
Hover the Data Flow Connector that is connected to Outputs.temperature and click the fx icon.
Click the temp field nested beneath the main container.

Run the Workflow again and at this point, you should see just the temperature field assigned to the temperature Property in the Workflow Logs.

Save your Workflow, then click Submit Exercise to grade it.