API Reference

Last updated
Save as PDF

The Kinetic Task API exposes the functionality necessary for external applications to initiate and control the execution of task trees. The two primary use cases for consuming the Kinetic Task API are source roots (applications that initiate task processing), and delegate systems (applications that have task handlers to initiate a process and defer, waiting for the application to complete the process and respond that the process is complete).

Summary

In Kinetic Task, task tree process flow is controlled by triggers, which represent steps that need to be taken. To start a task tree process, a Start trigger is created with information about the task tree and the source root and source record that initiated the execution. Similarly, when a task tree encounters a deferring node (such as an Approval, which requires human interaction before completing), it executing the task handler associated to the node and then stops processing and waits for a trigger with the completion information to be created.

The Kinetic Task API provides three possible mechanisms that applications can consume to create these triggers, and all three mechanisms utilize the same common API methods and parameters.

Information specific to the use of each of the API mechanisms is available at the above links, but the general definition of API methods and parameters is documented below.

API Methods

createStart

The createStart method us used to create a new start trigger, initiating a new task tree execution.

Parameters in bold indicate that they are required and parameters in italics indicate that they are not.

Example

Start the task process to handle a new network outage incident

Source Name	Remedy
Source Group	KS_SAMPLE_Incident
Source Id	INC00000001
Tree Name	Network Outage
Results
Message

Parameter Reference

Source Name	The name of the source root that the desired task tree is associated to. This value is used by the task engine to look up the task tree, and may be used within the task tree using the Source Information -> Source Name variable (@source['name']) in the Task Builder pre-defined values menu.
Source Group	The name of the source group that the desired task tree is associated to. This value is used by the task engine to look up the task tree, and may be used within the task tree using the Source Information -> Source Group variable (@source['group']) in the Task Builder pre-defined values menu.
Source Id	The Id of the record that the task tree is being executed on behalf of. For dynamic source roots, this value is used to automatically look up the necessary dynamic variables (IE the @base or @answers information for Kinetic Request). For standard source roots, this value is used in the task tree to look up the associated record information using the Source Information -> Source Id variable (@source['id']) in the Task Builder pre-defined values menu.
Tree Name	The name of the tree that will be executed.
Results	An optional XML string of "results" that will be passed to the start node. These results will be available in the Task Builder using the @results['Start']['NAME'] variable (these variables will not be available in the Task Builder pre-defined values menu, but can be manually entered). Format: <results> <result name="NAME">VALUE</result> ... <result name="NAME">VALUE</result> <results>
Message	An optional trigger message. This value is not used by the task engine. Trigger message are not typically used when creating a start trigger, but can be referenced in a task tree using the @trigger['Message'] variable (this variable is not available in the Task Builder pre-defined values menu, but can be manually entered).

createDeferred

The createDeferred method is used to create a new deferral trigger.

Parameters in bold indicate that they are required and parameters in italics indicate that they are not.

Example

Completes a deferred approval node

Action	Complete
Token	AG005056960051rJQmUQPmxIWAUXYJ
Results	<results><result name=“Status”>Approved</result></results>
Message	Request approved by Ben Christenson on March 1st.

Parameter Reference

Action	The type of deferral trigger that should be created (Complete or Update). The task engine uses the deferral trigger action to determine what processing should be executed. The creation of a Complete deferral trigger will indicates that the associated deferring task has been completed, and task processing can continue past the deferring node. The creation of an Update deferral trigger indicates that the task is still in progress, but any update connectors leaving the deferring node should be evaluated an the appropriate branches should be processed.
Token	The deferral token that was generated when the deferring task instance was first executed. This value is used by the task engine to look up information about the deferring node (such as the source name, source id, tree, etc). This value is made available within the task handler and often "pushed" as a piece of data to the delegate system (so that the delegate system can pass it back to the API to complete the deferred task).
Results	An optional XML string of "results" that will be passed to the deferring node. It is important to note that results can only be passed to Complete triggers. The results will be available in the Task Builder using the @results['NODE_NAME']['VARIABLE_NAME'] variable. Whether these variables are available in the Task Builder pre-defined values menu is dependent on the task handler node.xml configuration. Format: <results> <result name="NAME">VALUE</result> ... <result name="NAME">VALUE</result> <results>
Message	An optional trigger message. This value is not used by the task engine. Trigger message are typically used to populate node mesages, which are often made visible to the end user, and can be referenced in a task tree using the @trigger['Message'] variable (this variable is not available in the Task Builder pre-defined values menu, but can be manually entered). Other usages include passing formatted input that can be used in processing stemming from update branches off of the deferring node (since results can't be passed in update triggers).