API Reference
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> |
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> |
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). |