Skip to main content
Kinetic Community

Task Handler Creation and Modification

Kinetic Task, is an easy to use, highly flexible, advanced automation engine. In this full day class, learn how to modify and build Task Handlers to accommodate your unique needs. Kinetic Data will show you how to import predefined and custom task handlers. Lastly, learn how Kinetic Task allows you speed up your development by allowing you to test your Task Handlers on your local workstation by using the Task Engine Test Harness.

Topics

  • Introduction - In the introduction we review the basics of the Kinetic Task product and its architecture to provide context for a discussion about task handlers.
    • Task Engine architecture
    • Task Tree overview
    • Task Handler overview
    • Terminology
  • Handler fundamentals - Before diving into the task handler code we review the test harness and some of the consoles that will be used in class.
    • Configuration console for importing, downloading, and configuring handlers
    • Test harness for running and testing task handlers locally
  • Opening the Task Handler package - In this section we unzip up a task handler and look at the various files and content within and discuss the purpose of these contents.
    • The handler directory (init.rb) contains the code that is run when the engine processes a node.
      • initialize
      • execute
      • xml output
    • The process directory (node.xml, info.xml) contains XML files for configuring properties of a task handler.
      • Configuration values
      • Node options (deferrable, visible, etc.)
      • Node parameters
      • Node results definition
      • Handler XML input
    • The test directory (input.rb, output.xml) contains test cases run by the test harness.
      • *_input.rb matches *.output.xml
      • *_input.rb defines bindings
      • *_output.xml defined expected results
    • Naming rules
      • Handler package name
      • Handler id in node.xml
      • Class name in init.rb
  • The Ruby programming language - In this section we will go over some of the basics of Ruby that will be helpful when looking at and modifying task handlers.
    • Data types (String, Array, Hash)
    • Variables (local, instance, class)
    • Methods
    • puts
    • raise
    • Working with JSON
    • Iterators
  • REST API - Like most modern applications Kinetic Request CE exposes a REST API.  Working with the API will not only get us familiar with the Kinetic Request CE API but also given valuable experience with REST which has very broad applications for other applications.
    • HTTP communication
    • Resource URLs
    • HTTP methods
    • JSON data

Activities

  1. Download the Kinetic Training Team Retrieve handler from Kinetic Community.  Import and configure the task handler.  Then create a task tree using that handler, run it, and examine the results.
  2. Download the Kinetic Training Team Retrieve handler from the Kinetic Task Configuration Console and unzip it, then test this task handler with the test harness.
  3. Modify the Kinetic Training Team Retrieve handler to return the Description property from the retrieved team.
  4. Modify the Kinetic Training Team Create handler to set the Description property.
  5. Create a Kinetic Training Team Update handler that updates an existing team.
  6. Use the Ruby interactive shell to work with Ruby data structures and define a method.
  7. Create a Kinetic Training Team Members Retrieve handler that retrieves a list of users that belong to a team.
  8. Use the Kinetic Request CE Reference Documentation to retrieve and create forms.  Be sure to make a note of the URL, HTTP method, and JSON data.
  9. Download the Kinetic Training Form Clone handler and complete the implementation in the init.rb.
  10. Modify the Kinetic Training Team Retrieve handler to catch Resource Not Found exceptions and return empty results instead.
  11. Update the Kinetic Training Form Clone handler to overwrite an existing form if necessary.

​Visual Guide

Handler Package

The following images show the standard contents of a task handler package.  The root of the handler directory should contain the three following subdirectories:  handler, process, and test.

Unzipped directory of the kinetic_request_ce_user_retrieve_v1 task handler
 

The handler directory contains the Ruby code that runs when the node is evaluated as well as any libraries that are used for integrations.

Contents of the handler directory
 

The process directory should contain the info.xml and node.xml files.  These are used for configuring various properties of the task handler such as its name, description, parameters, results, etc.


Contents of the process directory
 

The test directory contains pairs of test files *_input.rb and *_output.xml, each of which represents a test case when running the test harness.

Contents of the test directory

init.rb

The following images show some of the key pieces of code found within the init.rb file.

This image shows the class name of the handler, it is found at the very top of the init.rb file.  This class name is important to the naming scheme of the handler.  To derive the class name from the handler package name remove the underscores from the zip file name and capitalize the first letter of each word (including the v).  For example kinetic_request_ce_user_retrieve_v1.zip becomes KineticRequestCeUserRetrieveV1 (as below).


 

This image shows the initialize method.  The initialize method is required to exist within the init.rb file and it is automatically called by the task engine when the node is processed.  It is generally used to perform some kind of setup or staging for the rest of the handler's action.  Here, we can see it is getting information from the node.xml file and assigning to @info_values and @parameters.


 

This image shows the execute method.  The execute method is also required to exist within the init.rb file and is also automatically called by the task engine when the node is processed.  Note that it is called after the initialize method.  This method generally performs some kind of API interaction with an external resource. In this example, we:

  1. Build up the URL of the API to call
  2. Make the request to the API
  3. Get information from the results of the data that is returned

This method is responsible for returning the handler's results so they can be used later in the process. The results are defined immediately before the "end" keyword below.


 

Finally, this image shows the escape helper method.

info.xml

This image shows the contents of the info.xml file.  This file configures the task handler's configuration properties that are set when importing the task handler.  Note that these are properties are defined system wide.

Here is an image of the configuration console showing how the values defined above are displayed when importing and configuring the task handler.

node.xml

Basic Handler Configuration

This image shows the top section of the node.xml file.  Here basic properties of the task handler are defined like its name, description, whether it is deferrable or not, etc.

Node Parameters

This piece of XML found within the node.xml file shows how the parameters of the node are defined.  Each of the XML elements represents a single parameter that is displayed when configuring the node in the task builder.  Within the elements there are several attributes that can be defined: id, label, tooltip, required, etc.

Node Results

This piece of XML shows how the results of the node are defined.  Each of the results simply needs a name to be defined.  Note that these result definitions should match the structure of the result XML being returned in the task handler ruby code (shown above).

Handler XML Template

Finally, this image shows the XML data that the engine will pass to the task handler ruby code when the node is being processed.  The XML structure shown is common for handlers interacting with Kinetic Request CE data but there are no constraints on how this XML should be organized.  It is common for handlers of similar types to share the same XML structure so that code can be reused and simplified.

simple_input.rb

This image shows the contents of the simple_input.rb file.  This file is one of the two pieces necessary for defining a test case for the test harness.  The purpose of this file is to essentially define all of the variables (bindings) that the task engine builds during normal processing.  To determine which bindings to define in the simple input, simply look at the handler template in the node.xml (shown above).  Anything with an @ symbol before the name is considered a binding variable.

simple_input.png

simple_output.xml

This image shows the contents of the simple_output.xml file.  This file is the second part of defining a test case.  It is simply a chunk of XML data that defines what the test harness should expect a handler to return after running it.  Note that this will look very similar to the results definition found in the node.xml but it will contain values within each of the result elements instead of being empty.

Additional Resources

The Test Harness can be downloaded here Test Harness

This page contains an index of all of our posted task handlers Task Handlers

The Task Handlers that are used throughout the training.  They are already present on the training VMs but if they are needed for some reason you can download them from below.