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.
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
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"?> <trigger> <id>KS123</id> </trigger>