Skip to main content
Kinetic Community

Task Handler Modifications and Naming Conventions

Kinetic Task offers a comprehensive strategy for controlling which Task Handlers are shown in the Kinetic Task Builder task list.  This strategy can help to provide a good framework for applying updates to your Kinetic Task environment.  When a Task Handler is modified, it can either maintain the same name, have the version incremented, or be changed to a completely new name.  This article outlines the implications of each of these approaches, and makes suggestions as to when each of the options should be used.   The highlevel approach to naming is to be System_Object_Function_Version.

Samples of good names

Kinetic_Incident_Create_V1

BMC_User_Add_V1

Salesforce_Contact_Create_V1

Remedy_Group_Create_V1

 

Samples of bad names

Incident_Create_V1

Create_User_V1
 

 

Basic Naming Conventions

Kinetic Task Handlers are typically named by concatenating each of the following items (that are appropriate):
 

  Item   Example
    A prefix corresponding to the name of the company the handler was customized for     ACME
    The manufacturer of the platform or application that the task handler corresponds to      BMC
    The platform or application that task handler corresponds to     Remedy
    The object or model that the task handler corresponds to     User
    The action that the task handler corresponds to     Retrieve
    The version of the task handler     v2

The above example would generate a Task Handler with a "display name" of ACME BMC Remedy User Retrieve v2 and the Task Handler class name would be ACME_BMC_Remedy_User_Retrieve_V2.  From this name, we can easily identify that the handler is likely retrieving data from the Remedy User form.  We can also deduce that ACME has customized the Task Handler, and that this is the second version of that customization.

Naming Options After Modification

Maintain the same name, including version

The first option for the naming of a modified Task Handler naming is to keep the same name.  If a modified Task Handler is uploaded to a Kinetic Task server, all future executions of Task Nodes that reference that handler will use the most recent modification (as long as the Cache Handlers setting is set to Disabled on the Kinetic Task Admin Console; if the Cache Handlers setting is set to Enabled then the server will need to be restarted to pick up the modifications).  This can be very advantageous if the modification is intended to fix a bug or make a modification that does not change the Task Handler parameters or results.  If the modification did change the Task Handler parameters or results, it is possible that overwriting the original handler will break existing Trees.

Maintain the same name, but increment the version

The second option for the naming of a modified Task Handler naming is to keep the same name, but increment the version.  A Task Handler with a different version is treated as an entirely different Task Handler once it is uploaded to the Kinetic Task server.  This is very advantageous when old, presumably fully working and tested, Task Trees don't need to be changed.  Additionally, the incrementing of a version is recommended when the Task Handler parameters or results change.  

If a Task Handler parameter is removed or renamed and the version is not incremented, Task Trees with nodes corresponding to that Task Handler will pass incorrect parameters to the Task Handler.  If a Task Handler parameter is added, then that parameter will not show up in previously existing Task Nodes until the Node is deleted and re-added using the updated Task Handler.

Similarly, if a Task Handler result is removed or renamed and the version is not incremented, Task Trees with child Nodes that reference the removed or renamed result will no longer be able to access the value.  If a Task Handler result is added, then that result will not show up in the Task Builder results menus for Nodes associated to the Task Handler until the Nodes are removed and re-added using the updated Task Handler.

Change the name

The third option for the naming of a modified Task Handler is to change the name completely.  This can be beneficial if the logic of the Handler was modified enough to indicate that the behavior has been modified.  Adding a company name as a prefix to a generic handler (such as renaming the KineticRequest_Submission_Close_V1 to ACME_KineticRequest_Submission_Close_V1) can also help to identify that modification or customizations were made.

Common Modifications

Customizing a Task Handler provided by the Kinetic Task Community

When customizing a "Generic" Task Handler that was provided via the Kinetic Task Community, it is recommended that a prefix corresponding to the name of the company the Task Handler was modified for be added.  This way, it is apparent that the behavior is different from the standard out of the box Task Handlers.

Modifying a Task Handler and changing the Handler parameters or results

Whenever the Task Handler parameters or results are changed, it is recommended that the Task Handler's version number be incremented.  This ensures that existing Task Trees that reference the old task handler will continue to work without modification.  If the new functionality is desired for existing Task Trees, the Trees should be modified and re-tested accordingly.  If the older versions of the Task Handler should no longer be used in new Task Trees, they can be "deprecated" in such as way that existing Task Trees that utilized the older versions continue to work, but the Task Builder no longer shows the Task Handler as a selectable option.  For more information on deprecating handlers, see the Removing Deprecated Handlers from the Kinetic Task Builder section below.

Modifying a Task Handler without changing the Handler parameters or results

If a Task Handler is modified without changing the parameters or results, the Task Handler version can either be incremented or not.  If there are existing Task Trees that utilize the old Task Handler and don't require any changes in behavior, then it may be beneficial to increment the Task Handler version (since the existing Trees will continue to use the older version, their behavior will not change, and additional testing can be avoided).  If there are multiple Task Trees that require the changes in Handler behavior, it may be beneficial to maintain the same Task Handler version so that the enhancements will be propagated to all of the existing Trees.

Removing Deprecated Handlers from the Kinetic Task Builder

To "hide" a deprecated handler, the Kinetic Task Configuration Console can be used to remove the deprecated handler from any categories it is associated to.  This will prevent it from being displayed in the Task Builder, but the Task Engine will still be able to retrieve and execute the handler for any Task Trees that reference the older, deprecated handler.  There is no way to "hide" a handler from the Configuration Console at this point.

Behind the Scenes

The KS_TSK_Def form includes multiple status field values that are intended for future use.  Manually changing the value between the statuses (Active, Inactive, Obsolete, and Future) has no effect in the current version of Kinetic Task, v1.0.3 as of this writing.  The one exception is the status of Delete, which will trigger workflow to delete the KS_TSK_Def record and the associated KS_TSK_DefInfo records.

As a reminder, all KS_TSK forms should be considered "internal" forms and are not intended to be used directly.  The Kinetic Task Admin, Configuration, and Management consoles should be used whenever possible.