Skip to main content

IMPORTANT - Product End of Life Statement - IMPORTANT

Request RE, Survey, and Calendar 1.5 Support Ending December 31, 2020
Contact Kinetic Data Support with Questions
Kinetic Community

Using REST to interact with the Task Engine

Note that this article applies to Kinetic Task 1.0/2.0. Please refer to the Kinetic Task 3.0 documentation for that version.   The Kinetic Task Engine has a wide range of handlers available to access and interact with other systems when initiating the integration from Kinetic. There are times, however, when records in those external systems need to interact back to the Task Nodes that created them.  To solve this, Kinetic supplies two interfaces to the Task Engine accessible from either SOAP or REST. Enabling SOAP can sometimes be problematic for some Servlet Engines and requires a fair amount of overhead generating the Soap Envelope. REST, on the other hand, is much more lightweight, is natively supported by a Kinetic Task Engine Servlet, and can be executed by simply calling a URL. Consequently, although a SOAP interface is available, for the purposes of this article we'll concentrate on using REST. Also note that this article is current as of Task Engine versions 1.x and 2.x. The 3.0 version of the Task Engine may provide additional interfaces and a wider range of solutions.


Some Background Information

Calling the REST interface to the Tas Engine to trigger a Deferred Node requires that the deferral token be available to the external system. A good practice when generating some external record via a handler is to map the deferral token from the Task Node generating the record into a field on the target.

The deferral token for that particular Node Instance is available for use in your node.xml using <%=@task['Deferral Token'] %>. Remember to escape the "<>" characters when including that value as a parameter.

Once the external system has the Deferral Token, it must also be able to generate an HTTP Request. This can be as simple as calling a command line to as robust as creating a custom Java class or executing a XMLHTTPRequest from within a web interface.

If those two conditions are met, you're now ready to interact with the Task Engine.

There are two actions available when generating a Trigger (as of version 2.0) - Update and Complete. These actions correlate to what happens in the Task Tree based on how other Task Nodes are connected to the Deferred Node you're triggering.




Using the above Task Tree as an example, if you send an Update Trigger to the "Defer" Node, the "Update Defer" Node will execute (note the dashed line between them signifying an Update Connector).

If you send a Complete Trigger to the "Defer" Node, the "Completed Defer" Node will execute (note the solid line connecting them signifying a Completion Connector).

Interesting Side Note: unlike other Task Nodes which execute only once (to prevent infinte loops) Task Nodes which trigger from an Update can execute multiple times, each time an Update Trigger is generated.

For additional information on using Connectors in Task Trees, please refer to the Deferrals and Connectors section of the Task Engine class materials.

Setting up the URL

In order to use this, you'd create a REST call with this general pattern from your external system:


And then concantenate the following options as needed separated by ampersands in the query string. Token and Action are required, but the others are optional. Additionally, the deferred_variables parameter is only available for a Complete action.

_method=POST (you can use GET as well, but POST seems to be the most direct usage).
trigger[action]=Update or Complete
trigger[deferral_token]= the Token from the deferred node you want to trigger.
trigger[message]= Whatever text you want to return in a message. This will display on the Portal when looking at a submission's Task List.
trigger[deferred_variables]= An XML string in the following format:
  <result name="MyResult">My Result Value</result>


And that's all there is to it. Generating the REST call can be tested by simply typing in the URL on the Location Bar of your favorite browser, so it's also a very simple mechanism to test.

Once executed, the REST interface wil return a small XML document containing the GUID of the Task Trigger record.

Some Additional Information

1. When passing in a "message" parameter, this can be consumed in the Task Tree by using the variable <%=@trigger['Message'] %>. Most commonly this is placed in an Echo node so that it's available in other parts of the Tree. The following article describes this with a bit more detail:

2. When consuming deferred_variables from your REST Trigger in the Task Tree, you'd use the following syntax:
<%= @results['Name of your deferred node being triggered']['Name you gave the Result in your XML string'] %>

Note that unlike results that are defined in a handler's node.xml, Deferred Results will not show up in the Pre-Defined Values menu and must be entered by hand.

So, in the example I gave above, if I was triggering a Complete on the "Defer" Node in order to get the value "This is a result" I'd access it with: <%=@results['Defer']['Web Thing'] %>


Example Update Trigger URL:

your_kinetic_server/kineticTask/api/Trigger?_method=POST&trigger[deferral_token]=ABC123&trigger[action]=Update&trigger[messasge]=This is a message from the REST interface

Example Completion Trigger URL:

your_kinetic_server/kineticTask/api/Trigger?_method=POST&trigger[deferral_token]=ABC123&trigger[action]=Complete&trigger[messasge]=This is a message from the REST interface&trigger[deferred_variables]=<results><result name="Web Thing">This is a result</result></results>

Example return value:

<?xml version="1.0" encoding="utf-8"?>