Building Basic Workflow (105)

Derick Larson
Administrators and Developers New to Kinetic
V5

Introduction

The workflow process takes over after the front-end form is submitted. Workflow (using the Task Engine) has the ability to update and retrieve from numerous other systems, perform calculations (using Ruby), and dynamically determine process steps.

Goals

Learn the basics of nodes and connectors. Learn about a Run of a tree.

Basic Workflow Video

Basic Run Example

Trees

In the video we go over creating and adding some basic elements in a tree. More specific details are included below.

Creating a Tree

Similar to Forms, there are three ways to create workflow/trees, clone, create from scratch, and import. New trees are normally created from scratch.

Create from Scratch

Creating a new tree is normally defined by the Source, the application that calls and passes information to the tree. For this class, all the trees will use the Request CE Source. Any Form you created in previous articles can call workflow trees if it has a corresponding webhook.

NOTE: If you are using kinops, you need to add the Custom Submission Workflow Attribute to your form and set the value to "Submitted". This allows your form to call a custom tree, and not the default kinops process.

Example Create Tree dialog:

V5 New Tree Dialog

For the Request CE Source there are four required fields:

Source - defined on the Admin tab, it normally relates to the application that is calling and getting the results back from the tree.

Source Group - categorization of the trees within the Source.

For Request CE it's the combination of the type (submission of form), Kapp Slug and the Form Slug separated by a greater than sign ( > )

Example: Submissions > services > onboarding

Name - Select from Closed, Created, Deleted, Submitted, Updated (Submitted is the most common)

Status - Active (default), Inactive, Paused

You cannot create a tree with the same Source, Source Group and Name as another tree.

The last field, Process Owner Email, is used for notification of errors during a Run on the tree.

Import

Importing a Tree is normally done when moving a process from one environment to another (Dev to QA for example).

Clicking on the Import Tree button opens a dialog for you to drag a tree export file into. The XML of the tree is extraced and viewable. There is also an option to import with a URL. Once you've identified your tree, click the Import button to complete the process.

You can export a tree from the dropdown menu for the individual tree on the Tree list dialog. Trees are saved as XML, and file names are a combination of the Source, Source Group, Name, and a timestamp. For example:

KineticRequestCE.Submissions-services-requesttocancel.Submitted.20190814164938.xml

Clone

Cloning a tree creates an exact duplicate of the tree, except for the Source > Source Group > Name combination. The option to Clone is available on the dropdown menu for each Tree on the trees console. Selecting Clone opens a dialog similar to Creating a Tree, except all the options are filled with the source trees information. From here you need to select new information so that you can save the tree.

Tree Elements

A tree is the basic element of workflow. In Task, a tree has two elements, Nodes and Connectors.

Nodes

A Node represents a specific use of a Handler in a Tree (often also called a Task). For example, you have a Handler that is used to retrieve Users based on a search string. When you place a Node of that Handler in a Tree, you will configure that search string specific to that Tree.

To create a Node, click the plus on the node that comes directly before it in your tree. The following dialog appears:

V5 New Node Dialog

Since this example is going to notify the Submitor, I searched for SMTP and selected the Send SMTP Email handler.

NOTE: You may need to go to the Plugin|Handlers console and update the Send SMTP Handler to be able to see it on a tree. Just add it to a Category if it is not already part of one.

Label and Connector

After placing the Node on the Tree you are asked to give it a Name, and decide on the type of Connector and if it requires a Condition.

V5 Node Name and Connector

Each Node must have a name (unique to the Tree).

Parameters

Clicking Next takes you to the Parameters section of the Node (Task). There are a few different options for values.

Plain Text - You can simply type a value into the field. The From field in the screenshot is an example of this.

Variables - Click on the </> icon opens a list of variables that are available to use. For the Kinetic Request CE source, you have access to everything about the submission including answers (values), attributes, kapp and space information, etc. Selecting one of these values from the dropdown lists appears like this - <%= @values['Email'] %>

The <%= => enclose the values to tel

In Task Engine what to replace. The @values tells the Task Engine where to get the values, and the vlaue inside the square brackets, identifies the specific value. thBesides values, the most useful variable option is a Result. It is the output of a previous node. Those variable look like this - <%= @results['Trees Needed']['output'] =>. The first value in square brackets is the name of node providing the result and the second value is the name of the result.

Combination You can also combine static text and variables. There is no need to concatenate with a + sign or place extra quotes, just add the variables as needed into the text.

Examples are shown below:

V5 Task Parameters

Deferred Nodes

Most nodes complete their function right away and the workflow process then continues. However, a deferred node while it still completes its function, will wait (defer) for a response before continuing on in the tree process. A common example of a deferred node is an Approval.

In addition to waiting for a response to Complete the deferred node, it can also accept periodic Updates.

The Update and Complete actions are done with Triggers which are covered later.

Connectors

Connectors link two nodes (tasks) together. They are normally created when a node is added to the tree. Connectors only go one direction. You can move either end of a connector by clicking and dragging to another node.

To modify a connector, click the "funnel" icon.

V5 Connector Update

You can Update the Type, Label, and Qualification from this dialog.

Types of Connectors

The default Connector type is Complete. If you create a connector between two nodes and don't make any changes, that connector will only fire when the starting node is complete. Complete connectors have solid lines.

Because of the different options for deferred nodes. There are two different options for connectors, Create and Update. If a node is not deferred, the different types of connectors can be used, but do not offer any additional functionality

Create connectors (dotted lines) fire as sson as a deferred node completes its function. Update connectors (dashed lines) only fire when an Update trigger is processed for the deferred node.

For a deferred node, a Complete connector only fires when a complete trigger is processed for the node.

Example of different connectors:

V5 Deferred Node

In the Next Article

Next we look at some of the System Controls included with Task.

Story for the Class

As a new Kinetic Admin, you have been tasked with cloning an existing Facilities form to collect more information. You also need to construct a basic notification after it's submitted.