Skip to main content
Kinetic Community

System Utilities

Overview

Explanation of the System Handlers included with the builder.

System Controls

The controls included are Create Trigger, Defer, Echo, Join, Junction, Loop Head, Loop Tail, No Operation, and Wait. To access these tasks, click on the name of the category (System Controls) and the tasks are displayed - click again to hide.

Join

Used to bring multiple branches of a task tree together. The three types of joins are: All, Any, and Some. All indicates that all connectors to the Join Node must be complete before continuing. Any means that any single Connector to the join must be completed before continuing. Some means that a certain number of connectors (configured in the node) must complete before the join node continues along the tree.

Example of Join Tree:

system_join_basic.png

Example of Join Node Information:

system_join_parameters.png

Junction

Similar to Join, except all the Connectors in all the branches leading to the Junction do not have to be complete, just execute as completely as possible. The Junction Node is often used when you need to wait for Deferred Nodes in a collection of branches before continuing. A Junction Node does not have any Parameters, it looks at all the branches (not just the Connectors like a Join Node) that feed into it.

system_junction_basic.png

In the example above if a Connector failed (evaluated to false) leading into Process 1, but the branch for Process 2 and 3 completed the Junction would be complete. In fact if all the Process branches leading from the Process A Node failed the Junction will still complete and the tree will continue processing. The only situation where the Junction would not complete and continue is if the Process A Node did not complete (Does the Connector labeled Do Process A? fail).

Loop Begin and Loop End

The two tasks that make up the loop system controls, must be used together. You are able to put any other type of task in the loop. The Loop End Node controls when and how many processes leave the loop. It is similar to a Join Node. The Loop Begin Node controls how many instances of the loop are created when the loop is encountered on the task tree.

Example of a Basic Loop:

system_loop_basic.png

Notice that the Loop Head Node has a Connector to its Loop Tail Node. This Connector closes the loop and identifies the actions that are part of the loop.

Loop Tail Nodes have the following options: All, Some, or Any.

Loop Head Nodes have the following options:  Data Source, Loop Path, and Variable Name.

Example of Loop Head Node:

system_loophead_details.png

Data Source holds an XML string that defines how many instances of the loop are created.

Loop Path is the XPath definition to the particular data for the loop.

Variable Name is a name that can be used in other nodes in the loop to reference the data defined by the Loop Path

All three fields are required.

Example: You want to send a request to a group of approvers. Only 2 of the approvers need to approve for the request to create a ticket. The list of approvers is created by a previous task and placed into the Data Source field. Here is a sample list (approvers email addresses):

<appEmail>

  <i>Bob@acme.com</i>

  <i>Jane@acme.com</i>

  <i>Charles@acme.com</i>

</appEmail>

Here is the Loop Path to identify the names:

//appEmail/i

The Variable Name can be any text that identifies values defined by the XPath as long as it is not the same as the names in the XPath. Example: appNameEmail or approver_email. This value is used with the following syntax in the nodes within the loop - @appNameEmail or @approver_email depending on what you put into the Variable Name.

In many cases you want to use the output of the Loop Head Node instead of the variable name. The following article describes that option.

No Operation (NoOp)

This type of task is used as both a placeholder and label for Nodes within a task tree. It performs no set function, and cannot pass any information. The most common use is as a label.

Wait

This task is used to put a predefined delay into a task tree.

There are two fields that let you configure the wait node.

  • Wait Time is an integer that defines the number of units of time.
  • Time Unit can be set to minute, hour, day, or week.

Both fields are required.

This node is often used to wait for backup approvers or to send messages if an action has not been completed in a certain time frame.

Create Trigger

This task is used to start another Node on a task tree. You identify the task to start, normally a Defer type of task, by its token.

Example of a Create Trigger Node:

task builder create trigger info.JPG

Action Type is the type of action that the Create Trigger node will fire on: Root, Update, or Complete. Complete is the most common choice.

Deferral Token is the token (unique value) value of the instance that the trigger acts on. Tokens are automatically created by deferred nodes.

Deferred Results are values to pass to the Deferred Node that is being acted upon. These values can be used on the messages tab, or as results for Nodes farther down the tree.

Message Text displayed in the console for the Node.

Action Type and Deferral Token are required.

Defer

This Node lets you pause your tree and wait for some other action before it continues. The Node has a token that you can use to identify it and restart the tree (another use for the Create Trigger Node).

Echo

Echo Nodes are used for two different purposes. They are an excellent troubleshooting step to see what values are in your task tree at specific points in the tree. Any answer or result added to the parameter field will be visible in the results of the task.

You can also use Ruby code to manipulate data and have the output used by other nodes.

system_echo_parameters.png

The code in this Echo node finds a specific value in an XML string. The output is then used in the parameter for a connector.