Trees

Trees are the Parent process for workflow. Each Tree is dependent on a source for its input. Forms, submissions, spaces, kapps, and Users call trees through a webhook that creates a trigger for the Tree.

Trees contain handlers and routines, global and local. Trees can only be called by triggers.

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 on the Build console.

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.

Source

The list of Sources is normally set during configuration/installation of Kinetic Task. All of the examples in this documentation are specific for Request CE.

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 available:

• Closed
• Created
• Deleted
• Submitted
• Updated

Status

Status 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 (XXX - link?).

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 opens the Builder.

Features

The name of the tree is displayed along the upper left of the builder. Click on the links to take you back to other consoles (Tree Details and Tree list).

There are two search options. The first, called Find Node is located along the top of the builder and is used to find nodes on the displayed tree. The second, called Search Task List is used to find tasks in the task list.

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

Save and Logout buttons are 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 Task List is available as a categorized list along the right side of the builder. Click the Category name to see the individual tasks. More on tasks later in this article.

The main builder window has two features that don't involve nodes or connectors. The first is a small chevron next to the task list. It allows you to close the task list to make more room for the builder. Related to this are controls on the upper right corner of the builder that allow you to zoom in and out on your tree.

Creating a Node

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

1. Click the category that the task is in to reveal the individual tasks
2. Click and drag the task to your tree to create a node

The x on the left side of the node is used to delete the node from the tree. The i on the right side of the node is used to configure (add parameter values - see below). The triangle on the bottom of the node is used to connect this node to other nodes (click and drag).

The text in the middle of the node is a unique identifier for the node that consists of the id (snake case name plus version) with an integer added. This value cannot be changed. You can set a friendly name for a node from the configuration view of a node.

If the outline of the node is a dashed line, it means that there is a required parameter for the node that does not have a value. You will also see an indicator for Required Field Missing under the "Misconfigured" category on the Task List.

The name is set along the top of the view, click on the unique Id and enter a friendly name. This name must be unique on the tree.

A link to the original Task or Routine is available below the Id. Clicking on the link takes you to the relevant configuration screen.

If the background of a node is orange, the node is set to defer.

Deferred nodes wait to complete (move farther down the tree) until they receive a trigger from another process.

Parameters

A parameters is how information is passed into tasks for processing. You have the option of typing in plain text, or using Ruby code. However, there are drop-down list 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. Connectors are one-way arrows that direct processing from one node to another. To create a connector, click on the triangle from the node you want to start from and drag the arrow into the destination node.

A single node can have more than one connector coming from it. Unless the node is a Join or Junction, (System Controls Nodes - add link XXX) you should never have more than one connector coming into a node.

As you can see in the screenshot, nodes can also have names. Double clicking on the connector opens a view with the options for adding a qualification and a name (required if you add a qualification).

If the qualification resolves to true the connector is processed, if it fails, the process stops. Ruby code is used in the connector.

How to Examine a Tree

You may, during processes of development, oversight, or upgrade want to examine a tree for connector content, routines used, or handlers leveraged. This is most simply done by leveraging the tree JSON available via the API. This has all the tree information available in the export, but in an easier-to-work-with JSON format.

This example service is one way of implementing this type of review. You could also use the SDK to do the same thing via the command line.