Implementing this feature requires creating a record in the KS_RQT_TaskSeed form that corresponds to the Task Node that is to be completed. In Task 3 only the Token was required. However, since Task 4 is a stand-alone application some additional information is required. Note that unless otherwise noted, all fields are required.
- Task Server - the name used by Kinetic Request to identify which Task Instance to use. This is defined in the Task 4 Management console.
- Task Source - the Source used to parse and manage any results from the Trigger. Can be an AdHoc Source, but to have a pre-parsed Result set use the "Kinetic Request" Source/Consumer.
- Integration Name - An arbitrary name to be given to the inbound integration. Can be anything but a descriptive name helps when troubleshooting records in the KS_RQT_TaskApiCall form.
- Integration Record ID - An identifier to be used to track the particular transaction into the source system. Typically a Record ID. For our purposes, AR System Field "1" (Request ID) will be used.
Additionally, the following fields are common to a Task 3 integration:
- Deferral Token - the GUID of the particular deferred transaction. This is available from Kinetic Task in the @task['Deferral Token'] bind variable, as an output of a Defers system utility node, or in the @dataset['Token'] bind variable of a request created in Kinetic Request/Survey.
- Deferral Action - the action to be taken on the deferred node. Can be either "Update" or "Complete". Note that only a "Complete" action can send back Deferred Results.
- Message - an arbitrary string of data or a message to be used when displaying Task information in a Portal. This is an optional parameter.
- Deferral Results - a formatted string of XML to be used as a Result in the originating Task Tree for the deferred node. Note that a value is required but it need not contain any additional information.
To create the integration, first determine the method for passing in all the required information. This can be done by hard-coding in the Filter but some information may be better supplied more dynamically. In this example, we have updated the Sample Incident Create handler to take additional parameters for Task Server and Task Source.
Note that the Task Server and Task Source values can also be supplied via attributes available in the service item or catalog.
Note that supplying fields on the target ARS Form is done in a separate step using the Developer Studio tool to create those fields.
Next, define the Filter that will be used to create the KS_RQT_TaskSeed record to generate the Task Trigger.
First, supply a qualification that will execute the Filter selectively. To support mixed integration with Task 3, you may want to differentiate by determining if the Task Source and/or Task Server values have been supplied. These are unnecessary in Task 3, but required in Task 4, so this creates a useful hook to fire the appropriate Filter depending on the source of the integration.
Next, create a Push Fields action to insert the appropriate fields into a KS_RQT_TaskSeed record.
Note that leaving the qualification blank will always create a record in the form. This is the desired behavior but it is worth noting that should the filter fire a second time (for example, changing the Status of the Incident from Closed to Open and then back to Closed) it will generate an error in the Task Engine as nodes can only be processed once. The better practice would be to qualify the entire filter to fire more specifically so that this condition does not occur.
Next, supply the Push Field mappings.
The 'Link Id' field was defined on the sample incident form to hold the deferral token. This step was performed in the field mapping of the kinetic_sample_incident_create Handler. For ITSM integration, check the "fields" mapping in the node.xml of the handler you will be using to verify the ITSM field in use. Typically it is 'SROAId' or some other SRM-specific field.
A note about the Deferral Results
When sending deferred results back in a completion trigger, a value has to be provided in a specific format and be valid XML:
<results> <result name='Some Name'>Some Value</result> </results>
However, you need not send deferred results back to the originating node. Simply supply "<results/>" in the mapping and it will be valid.
Additionally, make note of the quotation mechanism used in the Push Field's field mapping:
Make sure to provide escaped double-quotes around the entire string (this is done by using a sequence of 4 double-quote characters). When this value is retrieved by the Task 4 engine, it is put into a JSON format. Without the outside double-quotes, the Task Engine will use the literal results XML without quotes and it will cause an error when it is parsed.