Introduction

Now that you know the basics of vocabulary and the consoles, let's start creating workflow.

Goals

The goals for the article are:

• Learn how to Create Trees
• Learn to navigate the Tree Builder
• Be able to place and configure Nodes
• Learn how to connect Nodes with Connectors

Creating a Tree

Similar to Forms, there are three ways to create workflow/trees, clone, create from scratch, and Import.

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 Kinetic Request CE Source. Any Form you created in previous articles can call workflow trees if it is connected and has a corresponding webhook.

NOTE:
If you are using Kinops, you need to add the Custom Submission Workflow Attribute and set the value to "Submitted".

Example Create Tree dialog:

For the Request CE Source there are four required fields:

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

Depending on the Source, you will have either a defined set of choices, or free-form text for the Source Group and the Name fields. Click in the field to see the menu displayed.

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 - For the Kinetic Request CE Source you 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.

Click the Create Workflow button to save 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 the import dialog. There are two options for import:

by File - drag the file into the open field and the xml is extracted

by URL - paste the URL of your XML into the field

When exported, Trees are saved as XML and file names are a combination of the Source, Source Group, Name, and a timestamp. For example:

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

You can export a tree from the dropdown menu for the individual tree on the Tree list dialog or from the Builder.

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.

Clicking Save takes you to the Form Builder.

Features of the Builder

The Builder is where workflow is constructed. First, lets walk through the specific features of the builder and then look at Nodes and Connectors.

Example of the Builder:

Accross the top of the builder:

• Workflow Name - the Name is along the top with the Source and Source Group below separated by a pipe character
• Search Nodes - search for a node on the tree.
• Actions - dropdown list with the following options, Run (run an instance of the tree - see below), Clone, and Export.
• Save - save any changes to the tree

Run lets you run the tree with specific inputs. Inputs depend on the Source. For Request CE, it's a JSON string.

Example Run dialog:

After clicking Run Tree, you have a link to the Run Number - see the next article for more on Runs.

The central area of the Builder is where the Tree is created and maintained.

Nodes

A Node represents a specific use of a Handler in a Tree. 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 add a node to a tree, click the + on the bottom of the existing node you want to be before the new node existing node.

For example, in the example below you want to add an email notification node after the get manager ID node.

Selecting a Handler (Send SMTP Email in our case) starts the process of placing and configuring the node. You need to give the node a Name, and decide what kind of Connector (and if it needs a label and condition).

• Node Names must be unique within the tree

Clicking on Next brings you to the Node Parameters dialog. Any information required for the Node to process is on this dialog. In our example I've completed the From:, To:, and other standard email fields.

Parameters

Parameters are the inputs to your node. They come from three different areas. First, you can enter straight text. Second, you can get values that are passed from the Source. For example, values (answers) from the submission, attributes, and form|kapp|space information (see more below). Third and possibly the most useful is results from other nodes.

Looking at the image above, you can see all three:

• The from Email Address has straight text
• The Subject and Body fields have values
• The To field has a result from a previous node

As you can see in the image, all three options can be combined.

On the right side of each parameter is a </> icon that opens a list of preconfigured options for the node based on the Source. You can also type a $ to get a similar list.

Here is a list the most commonly used options with a short description:

• Kapp Attributes - available attributes applied to the Kapp
• Values - submitted answers
• Submission - common submission values (created by, created at, etc)
• Space Attributes - available attributes applied to the Space
• Form Attributes - available attributes applied to the Form
• Values Previous - tracks previous answers for changes
• Results - outputs from other nodes

There are other options that are not as commonly used.

Deferred Nodes

Most nodes complete their function right away and the workflow process then continues. However, a deferred node completes its function and then waits (defers) for a response (trigger) before continuing on in the tree process. A common example of a deferred node is a Task assignment. Workflow creates a Task request, but then waits for completion (and possibly some returned information) before continuing the workflow process. Deferred nodes are easy to spot, they always have a blue triangle in the upper right corner.

Triggers are used to Complete|Update deferred nodes. Each trigger has the option to Update (pass information, but leave the node deferred) or Complete (pass information, continue the workflow process).

Since there are actions available for Update and Complete, the application provides options to have different messages available. Messages are optional, and the parameters do not change.

Connectors

Nodes are automatically connected when they're created. The process of defining the new node includes steps to name and provide a Condition

Connectors only go one direction. To delete a connector, select it and click Delete from the dialog. You can move either end of a connector by clicking and dragging on either end and dragging it to another node.

By clicking on the icon in the middle of a connector, you can open it to input a qualifications (see below).

Qualifications

Adding a qualification to your connector limits when the connector fires. The qualification is a Ruby expression that needs to evaluate to either True or False. If true the connector fires, otherwise not. This functionality lets you limit what paths different submissions can take on the same tree.

Example simple qualification:

If you add a qualification to a connector, you must add a label.

When creating the qualification, you have access to the same parameters as you would in a node.

In the Next Article

In the next article, you'll Run some of the trees and see if you can generate any Errors

Activity

Create a tree that does the following:

• Checks for a value from your form in a qualification of a connector.
• Retrieves a value from a Datastore form
• Creates a record in another Datastore form