Building a Basic Workflow

Derick Larson
Workflow Developers
5.x

Building a workflow is done in the Builder in the workflow (Task) part of the platform. Getting to the Builder happens in a few different ways; directly from scratch, cloning an existing workflow, or importing a workflow from another environment.

Creating a Workflow

Creating a workflow tree from scratch starts in the Space|Global Workflow console.

GlobalWorkflow

Two of the options are available from buttons near the upper right corner of the screen, Import Tree and Create Tree.

For this article the focus is on creating from scratch.

Selecting the +Add New Tree button takes you to the New Tree console.

NewTree

Source

The list of Sources is normally set during configuration of Workflow. All of the examples in this documentation are specific for the platform.

Source Group

Source group categorizes the element that is used with the tree. For example, if your tree fires when a form is submitted your source group is Submissions > services > equipment-move for a form in the Services kapp with the slug equipment-move.

Name

Values for the name field are determined by the specific Source. For Requst CE, the following values are availble:

  • Closed
  • Created
  • Deleted
  • Submitted
  • Updated

Status

Staus values are the same for every tree and source. Active is the default value on creation and indicates the tree is available to be called by the API. Inactive indicates the tree is not available for processing Paused indicates that three is not currently available, and triggers for that tree will go into a Staged status

Process Owner Email

Use this field to notify someone via email of errors during a run of the tree. This value is used in the Notify on Run Error tree in the Kinetic Task source. This tree must be configured with your email information for the notifications to process.

Workflow Builder

Once the tree settings are in place, you can use the Builder to add nodes and connectors.

Clicking the Save Button for a newly created tree updates the tree and then you can select the Builder button.

Below is an example workflow:

V5-Example Tree

Features

The name of the tree is displayed along the upper left of the builder. Click on the links to take you back to Tree Details console.

There is a search option Search Node located along the top of the builder and is used to find nodes on the displayed tree.

The Actions drop-down list has three options.

  • Run - start a run of the displayed tree with inputs you provide
  • Clone - makes a copy of the existing tree. You must name and configure the clone.
  • Export - creates an xml file of the tree ready to download and loaded in another environment

A Save button is available on the far upper right corner. Save should be used as often as you are comfortable, and is only available if there has been a change to the tree.

The main builder window has a set of controls that let you zoom in and out, move back and forth through saves, and open a key to the various types of nodes.

Creating a Node

A node is a representation of a task on a tree. To add a node to a tree:

  1. Click the + on the node you want it to come after
  2. search for it using the Search Task field by name

V5-Select Handler

Once the task is selected, you move to naming the Node, and configuring the connector. Both of these can be redone later as needed.

V5-Name Node and Connector

Clicking Next takes you to the dialog to complete the Parameters for the Node.

V5-Set Parameters

Parameters

A parameter is how information is passed into tasks (an instance of a node for a Run of a tree) for processing. You have the option of typing in plain text, or using Ruby code. However, there are pre-configured options that are always available in every tree.

The Source contains the generic information that is always available. It includes the tree name (Source Group and Source Name), the Id of the source, and all of the data that is provided with the source. In this case it is a json string of the submission.

The System option contains an option to get the Run ID and any Message from a trigger (normally just for a deferred node).

Task Results is always included. Options available in this list depend on the other nodes in the tree.

Other parameter options depend on whether you're in a tree or routine, and what source is being used. The Values and Submissions are the most popular options from the list in the above link.

All of the values have the same format. For example here is what a value (answer to a question) looks like, <%= @values['First Name']%>

ERB tags <%= %> enclose the options and tell the engine that it will be replacing them with a value from the source input.

The first half of the value between the ERB tags begins with an @ symbol and defines where the value is coming from. Options include, values, results, submission, space, kapp, and form.

The value in the square brackets normally identifies a specific item for the first value. For the example, <%= @values['First Name']%>, tells the task engine to return the answer to the First Name question.

Kinetic Platform Parameters

The following parameters are specific to the front end of the Kinetic Platform.

  • Event. Action that prompted the run. For a submission it includes the date/time of the submission
  • Form. Information about the form
  • Form Attributes. Access to the attribute of the form
  • Kapp. Name and slug of the kapp
  • Kapp Attributes. Access to the attributes of the kapp
  • Space. Name and slug of the space
  • Space Attributes. Access to the attributes of the space
  • Submission. Information about the submission including dates and times
  • Submission Previous. If there is a previous submission information about that
  • Values. Answers from the submission
  • Values Previous. If there is a previous submission, answers from that submission

Connecting Nodes

Nodes are connected by Connectors. They are one-way arrows that direct processing from one node to another. Connectors are configered in the same dialog as the node when it is first created, or you can click on the "funnel" symbol to update an existing Connector. To create a connector, click on the plus symbol on the node you want to start from and drag the arrow into the destination node.

V5 Connector Dialog

A single node can have more than one connector coming from it. Unless the node is a Join or Junction, you should never have more than one connector coming into a node.

Nodes can also have qualifications. The qualification is a Ruby expression that resolves to either True or False. True means the connector processes.

V5-Connector Expression