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

Getting Started with Source Roots

Starting in version 3.0, Kinetic Task extended support for the automation of workflow for any application, and is no longer restricted to providing task processing for Kinetic Request.  The term source root refers to an application that initiatiates task processing.  This article will cover some of the background knowledge and strategies necessary to integrate an application with Kinetic Task.

Possible Source Roots

  • ITSM systems
  • Salesforce
  • Oracle Identity Management
  • Kinetic Request
  • Kinetic Survey

Getting Started

Prepare Source Application

The first step in preparing a source root is to determine what circumstances should cause a task tree to execute.  Most systems provide some method for configuring an action to take place when the desired circumstances are met.  The method will vary between source applications, but the action will always be to call the Kinetic Task API and create a start trigger, which indicates to the Task Engine that a new process is ready to be executed.

Kinetic Request includes a Remedy filter that fires when a request is submitted.  This filter pushes the necessary values into the KS_TSK_Seed form (one of the three API mechanism options), which initiates the task processes associated to the service item.  In this case, the Remedy filter defines the circumstances that should trigger a task tree to execute and the push fields action is calling the Kinetic Task API which creates the start trigger.

Source roots that do not run on the Remedy platform will likely call the Kientic Task API via one of the available web service mechanisms.  For source roots that are not capable of registering event hooks, or not capable of consuming the Kinetic Task API, a secondary polling application can be used to check for changes and call the the Kinetic Task API on behalf of the source root.

When a source root creates a start trigger, there are four parameters that will always be passed:

  • The Source Name references the name of the source root that is initiating the task process.
  • The Source Group is a value used to group task trees to a similar resource.  For example, Kinetic Request uses a concatenation of the catalog and template names for the source group value.  This allows two trees to have the same name, provided they are associated to different templates.
  • The Source Id represents an Id that will be used to retrieve information.  In almost all cases, this will the the unique identifier associated to a record that exists in the source system, but it could also be a transaction id or other key.
  • The Tree Name is used to specify which task process should be executed.

For more information about how to integrate external source applications with Kinetic Task, see the API Reference developer guide.

Prepare Handler or Consumer

After the source application has been configured to initiate a task process, the next step is to prepare a strategy for retrieving information from the source system.  In almost all cases, a task tree will need to leverage the information associated to whatever triggered it to executed.  For example, if a Kinetic Request task tree didn't have access to information about the request, it would be extremely limited in what it can accomplish.

In most situations, the easiest way to expose source data to the task tree is to use one or more task handlers to retrieve the information.  A source root that uses this approach is called a standard source root.  A standard source root uses the source group and source id passed by the source system to determine what data to retrieve.  The results of the task handler are then made available to the rest of the tree.

However, in some situations the desired data is too dynamic or too complex to make a task handler practical.  For example, a Kinetic Request submission has many attributes and answers and the names of these are not static.  This makes it very difficult to map to the task handler results (which are simple name/value pairs).  In this case, a consumer can be used.  A consumer is a small Ruby module, similar to a task handler, that can look up dynamic relationships ahead of time and expose additional variables within a task tree.  A source root that uses this approach is called a dynamic source root.  Kinetic Request is an example of a dynamic source root.  Given a source group (catalog and template) of a tree, the Kinetic Request consumer can build a list of available variables (which are shown in the Task Builder pre-defined variables menu) and given the source group and source id, the Kinetic Request consumer can build up the values of those variables (such as @answers, @template, etc).

Register the Source Root

Source roots need to be registered in the Kinetic Task source configuration console (shown below).  Dynamic source roots will require additional configuration, such as the source system server name, a username/password, etc.  Standard source roots do not  require much configuration, because the values such as server name and username/password will be configured as task info properties when importing the associated data retrieval handler.


Sometimes it may be desireable to add an additional layer of security to the creation of start triggers.  This can be done by restricting API access and is configurable on a per-source root basis.  For more information about API access control, see the Getting Started with KSL article here in the Kinetic Task 3.0 User Guide.

Create A Task Tree

Once the source application has been prepared, and there is a task handler (or consumer) ready to expose the necessary data, we are ready to build our first task tree.  Some dynamic source roots will provide tree management as part of the source application (such as Kinetic Request), but most of the time a tree will be created in the Kinetic Task Tree Configuration Console.

Standard Source Tree

Below is a simple task tree for a standard source root.  After the process is started, the Retrieve Incident node immediately retrieves information about the corresponding incident record.  This node is a configured instance of the prepared Task Handler, and is configured to lookup the KS_SAMPLE_Incident record using the @source['id'] pre-defined variable, which will be the source id value passed by the source application when the start trigger is created.  The Echo Submitter node represents what would normally be your full task tree process.  Is is configured to output the submitter, which is a return value of the Retrieve Incident node.  In a full task tree process, it is likely that many of the incident field values returned by the Retrieve Incident node would be used as parameters for other nodes or in connectors to specify process logic.


Dynamic Source Tree

Below is an example of a tree for a dynamic source root.  Just like the above standard source root tree example, it is echoing the name of the submitter.  However, rather than using a return value from a lookup handler (like the Retrieve Incident handler above), it is using a pre-defined variable that was automatically looked up by the consumer.  In this case, the Echo Submitter node is outputting the value of the @dataset['Submitter'] pre-defined variable.  In a full task tree process, there would be many nodes after the start, and any of the variables listed by the pre-defined variables menu could be used in connectors or as task parameters.



As you can see, in just four steps you can prepare any external application to utilize Kinetic Task for workflow automation.

  • Prepare the source application.
  • Prepare a method for retrieving data from the source application.
  • Register the source root with Task.
  • Start building trees!