Skip to main content
Kinetic Community

Day 4 - Task Handlers

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.

Agenda

  1. 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.
    1. Task Engine architecture
    2. Task Tree overview
    3. Task Handler overview
    4. Terminology
  2. 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.
    1. Configuration console for importing, downloading, and configuring handlers
    2. Test harness for running and testing task handlers locally
  3. 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.
    1. The handler directory (init.rb) contains the code that is run when the engine processes a node.
      1. initialize
      2. execute
      3. xml output
    2. The process directory (node.xml, info.xml) contains XML files for configuring properties of a task handler.
      1. Configuration values
      2. Node options (deferrable, visible, etc.)
      3. Node parameters
      4. Node results definition
      5. Handler XML input
    3. The test directory (input.rb, output.xml) contains test cases run by the test harness.
      1. *_input.rb matches *.output.xml
      2. *_input.rb defines bindings
      3. *_output.xml defined expected results
    4. Naming rules
      1. Handler package name
      2. Handler id in node.xml
      3. Class name in init.rb
  4. 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.
    1. Data types (String, Array, Hash)
    2. Variables (local, instance, class)
    3. Functions
    4. puts
    5. raise
    6. Iterators
  5. The ArsModels Ruby library - In this section we will discuss the ArsModels library, a library written by Kinetic Data for interacting with Remedy data.
    1. CRUD
    2. Context
    3. Form
    4. Entry
    5. Field types

Activities

  1. Download a task handler from Kinetic Community, then import and configure the downloaded task handler.
  2. Create a new task tree and add a node using one of the Kinetic Sample task handlers.  Run the task tree (either by submitting the service item or using the create trigger form) and examine the results of the node.
  3. Download one of the Kinetic Sample handlers from the Kinetic Task Configuration Console and unzip it, then test this task handler with the test harness.
  4. Modify the Kinetic Sample Incident Create handler to set an additional field in the database.
  5. Modify the Kinetic Sample Person Retrieve handler to retrieve an additional field from the database.
  6. Create a Kinetic Sample Incident Update handler that retrieves and updates an existing sample incident record.
  7. Create a Kinetic Sample People Retrieve handler that retrieves a list of records from the sample people form.  The resulting XML should be formatted for the loop head handler.
  8. Modify the Kinetic Sample Person Retrieve task handler to print the query it is making and raise an exception if the query retrieves no results.

​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.

root.png

Unzipped directory of the kinetic_sample_change_create_v2 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.

handler.png

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.

process.png

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.

test.png

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_sample_change_create_v2.zip becomes KineticSampleChangeCreateV2 (as below).

init-classname.png

 

This image shows the initialize function.  This function 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.  In this case we are loading the KS_SAMPLE_Change form definition because this is required before interacting with any data on that form.  

init-intialize.png

 

This image shows the execute function.  This function 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 function.  This function generally performs some kind of API interaction with an external resource, in this case we are creating a record in the KS_SAMPLE_Change form.

Also note that the execute function is responsible for returning the handler's results so that they can be used later in the process. The results are defined immediately before the "end" keyword below.

init-execute.png

 

Finally, this image shows some of the helper functions defined within the kinetic_sample_change_create_v2 task handler.  Note that none of these are required by the task engine, they exist purely to make the rest of the code within the handler cleaner and easier to work with.  The helper functions below can be found in nearly every handler that interacts with Remedy data.

init-helpers.png

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.

info.xml.png

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

handler-configuration.png

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.xml-misc.png

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.xml-parameters.png

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).

node.xml-results.png

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 Remedy 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.

node.xml-handler-template.png

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.

simple-output.png

Additional Resources

Comprehensive ArsModels documentation can be found here ArsModels

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.