Basics of Using Kinetic Task
NOTES: This article describes features from Task v3.2. Some of the screenshots may look different on your version. Most of the basic functionality is the same starting with Task v2.x. Notes will be provided, but be aware that your functionality could be slightly different.
If you are going to use Kinetic Task v4 see the configuration instructions here.
Instructions on the legacy task engine (pre v5 of Kinetic Request) are found here. Search the PDF for "Previous Task Creation".
Tasks are used to model the business process that happens after a request is submitted. This process includes notifications, approvals, creating instances in Remedy forms, and many other individual tasks.
Remedy workflow creates the initial record to start processing your task tree. Starting from the "Start" node, the tree is completed by following connectors to nodes down "branches" of the tree. Each connector can have a qualification determining if it is processed, and each node represents task that the tree performs (lookup of data, creation of records, notifications, etc).
Version of the task engine is controlled by the drop-down at the top of the tab. The options are Kinetic Task 4+, KInetic Task 2/3, and (clear). The clear option will use the Legacy task engine.
Example of the Tasks tab:
Create and Modify Task Trees
Add opens the dialog to create a new Task Tree. The same dialog is used to create and modify task trees.
Two options are presented, Add Existing Task (see below) and Copy Existing Task. Copy existing task presents a list of task trees to select.
Example of the Task Tree Dialog:
Tree Name is a descriptive name for the tree.
Tree Type is a list of available types. The following are included with the application:
- Complete - tree is executed when a request is completed (reach the confirmation page).
- Create - tree is executed when the request is created (often used with approvals).
New types can be created. The types are drawn from configuration items. New workflow must be created for new types.
Status is for the task tree. Inactive trees are not executed. Copied trees start as inactive.
Delete button removes the selected task tree.
Accessing the Task Builder
The Task Builder is available by clicking on a tree in the table, then clicking the ‘Launch Builder’ button on the right side of the table on the Task tab.
To access the task builder, you must be authenticated and a member of either the KS_TSK_Manager or Administrator groups.
Example of the Task Builder Dialog:
The name of the tree is listed along the top of the web page.
Find Node will search the tree for a specific node name and place focus on that node.
Plus and Minus magnifying glasses can change the view perspective on the task tree.
Save button saves the current tree.
Logout button used to close the page and logout the current user.
Bread crumb link can take you to the Trees console in the Task Manager.
Search Task field searches available Task handlers.
Active Task Category shows task handlers used in the current tree.
Misconfigured category shows nodes that are not configured correctly.
All available Tasks are under their specified (during setup in the Task Manager) category.
Nodes are created by dragging a Task from the task list onto the main section of the task builder.
There are a variety of different types of tasks, System Control, System Utilities, and your own tasks that you create and add.
NOTE: New tasks are added through the Task Manager Console.
All nodes share some basic information.
The name of the node is displayed in the middle of the outline. All nodes start with the same name as their id.
The x on the left side of the node is used to delete the node.
The v on the bottom of the node is to connect the node to other nodes. Click on the v and drag to another node. A directional connector is created.
Clicking on the i on the right side of the node shows more information about the node.
Nodes that have required fields without values have a dashed outer border.
If the node is deferred, it will have an orange background.
Editing a Node
Clicking on the i will bring up the edit view of a node (see above). The information available depends on the type of node.
The default name along the top of the node is the same as the id, you can click and change to a more descriptive name (must be unique per tree).
Visible option determines whether the instance of the node is included on the web portal information about requests.
Defers option (not shown) determines whether the node instance will complete automatically, or stay in a work in progress status (waiting for another system to create a trigger to process the node).
Parameters tab is shown by default. It includes the parameter fields configured for the node. Reqiured fields are marked with an asterisk (*). If the values for the parameter field can be edited a pencil icon will be to the right of the field (see details below).
Messages tab shows either a field for Complete (non-deferred node) or Create, Update, Complete (deferred node). These fields can be edited to show information on the web portal. If the Visible option is not checked, these fields are not available.
Id: is a unique name for the node that includes the name of the node with an underscore and an integer. The integer is incremented automatically by the task builder system.
Save button saves the information in the node and returns you to the parameters tab.
Cancel button closes the node without saving information.
Editing a Parameter Field
Clicking on the edit icon for a parameter field (pencil) brings up the following dialog:
Along the top of the dialog is a selection of logical operators. Click on one to add it to the edit field.
Click on the Pre-defined Values button to bring up the list of options:
Application Config Values - includes the Default Web Server and the Mid-Tier Server name. Useful for configuring URLs.
Service Item Answers - includes all the questions from the service item.
Service Item Dataset - includes all the dataset values for the service item.
Service Item Template Fields - includes values about the service item.
Task Results - includes all the results option configured for the handler (you are not limited to these options, these are just the pre-configured ones).
In Parameters, values are surrounded by ERB tags <%= %>. This tells the task engine to process and return values. YOu can include ruby syntax within the ERB tags to make complex parameters.
Connectors are what tie nodes together. Connectors have a single direction, and can have different conditions and types. The defaut for a connector is to always fire (move to the next node) when the node it is coming from is completed. However, there are three types of connectors and each connector can have conditions placed upon it.
Example of a Connector:
Clicking on a connector highlights it, reveals an x to delete it, and highlights the node it is attached to. Double clicking opens the editing dialog (see above).
Label is available to add, and should be unique. Label is required if you add a qualification.
Pre-defined values button is the same as editing a parameter field on a node.
Type is a list of available actions for the connector to fire (see below).
Central editing field is checked to see if the connector should fire. If left blank it will fire the connector. If a qualification is added, it must resolve to true for the connector to fire.
Save button saves changes and closes the dialog.
Cancel button closes the dialog without saving the changes.
Types of Connectors
There are three types of connectors
Complete - fires when the starting node is complete.
Create - fires when the node is first created. This is normally only used with deferred nodes.
Update - fires when the node instance for a tree is updated. This is normally only used with deferred nodes.
Tasks for the task builder come from three locations. The System Utility and System Control tasks are included with the application. Sample tasks are available from the Kinetic Community here. You can create task handlers on your own using examples from the task handlers on the Kinetic Community site.
The tasks on our community site have explanations of how to use them included in their articles. Below are explanations of the system utility and control tasks included with Kinetic Task.
The controls included are: Join, Junction, Loop Begin, Loop End, No Operation, and Wait. To access these tasks, click on the name of the category (System Controls) and the tasks are listed - click again to hide.
Used to bring multiple branches of a task tree together. The three types 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 that completes will cause the tree to continue. And 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:
Similar to join, except it only checks that all the branches have executed completely before continuing. Specifically, all the connectors in the branch 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 that feed into it.
Loop Begin and Loop End
The two tasks that make up the loop system controls, must be used together. The Loop End node controls when the loop is complete. It is similar to a Join node (has the same parameters). 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:
Notice that the Loop Begin node has a connector to its Loop End node. This connector closes the loop and identifies the actions that are part of the loop. You can put any number of different tasks inside a loop.
Loop End Nodes have the following options: All, Some, or Any.
Loop Begin Nodes have the following options: Data Source, Loop Path, and Variable Name.
Example of Loop Begin Node:
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):
Here is the Loop Path to identify the names:
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.
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.
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.
The utilities included are, Create Trigger, Defer, Echo, and Eval. To access these tasks, click on the name of the category (System Utilities) and the tasks are listed - click again to hide.
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:
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 affects. 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.
This node lets you pause your tree and wait for some other action to make it continue. The node has a token that you can use to identify it and restart the tree.
The echo task is used most often to place a message in an instance. This node is useful for debugging to check returned results from various nodes. You are able to get inputs and results from all the various tasks and data from the request. Results are then viewed in the Task Manager.
The Eval task lets you execute ruby code and pass the results to the another node in a task tree as a result.
NOTE: This node is being removed in future versions