Configuring and Using Handlers

Anne Ramey
Workflow Developers

Handlers, as reviewed in the basics articles, are the components that execute portions of code and can be used by workflow builders to build whatever processes they wish.

Loading and Configuring a Handler

There are only a few handlers that come as system utilities:

  • Join
  • Junction
  • Echo
  • Loop Head
  • Loop Tail
  • Create Trigger
  • Defer
  • No Operation
  • Wait

All other handlers must be either configured or loaded onto the system and then configured. This is a one time process that involves

  1. Loading the handler code onto the system
  2. Setting up the details of
  3. Where that handler will connect, what user it connects with, etc.
  4. What category it appears in in the task builder.

Note that the configuration details will vary by handler, because the connection info required by a Remedy ARS system, for example, is very different than that required by an Amazon EC2 system.

Also, it can be important to note here, that this configuration needs to be done in each environment. It is very possible (even likely) that you will want each environment (development, test, production) to connect to different environment systems for data and workflows.

Using Handlers

Once the handler is configured, it can be used in any number of trees and routines. Handlers are dragged from the task list on the right side of the workflow builder onto the tree or routine being built.

EmptyRoutineExample

Handlers will appear under the configured category(s) or you can search the task list for the desired handler. Once on the workflow, the handler will appear with a dashed line around it and a generic name.

UnconfiguredNode

There is now an unconfigured node on the workflow that is an instance of that handler. You can double click it to configure the node.

UnconfiguredEcho

You name a node by clicking on the current name up in the header (top grey region) of the node and editing the text. Also in the header are either one or two checkboxes, depending on the code of the handler.

The always present checkbox is Visible. This sets a flag on the handler, so if the workflow system is being queried directly to determine which tasks a user can see, this task would be visible. Note that this method of displaying information to the user is not recommended when using the full Kinetic Platform. It is recommended that you use the more flexible Submission Activities.

The not always present checkbox is Defers. This, if checked, makes this a deferred node. That means that when the handler runs its code, it will then wait for a trigger to be returned to it before it will allow the workflow to continue. See this article for more information on deferrals.

Parameters

Note that each handler is going to create nodes with different parameters because the parameters are the inputs needed by the code run by that handler. Text, items from the preconfigured values list, and Ruby code can be used in parameters that have open text elements. If the handler has a drop down field, you must manually select an option from the drop down, and this cannot change in different runs of the workflow. This is one reason you will not see many drop down menus in handlers.

Messages

Handlers also have messages. These can contain parameters and are a primitive way of making a node's information available to the user, eg "Approval Assigned to {Approver Name}", if the system displaying information does not contain a more sophisticated mechanism.

NodeMessages

There are three potential messages: Create, Update, and Complete. Note that Create and Update are only present for nodes that defer.

It is not recommended that the messages functionality be used when leveraging the full Kinetic Platform. It is recommended that messages be created and displayed for the users using the Submission Activity feature instead. This allows for more flexibility and better error handling.

Useful Shortcuts

  • If you hold down ctrl while you double click on a node you will duplicate it. This can save having to find and reconfigure a nearly identical node.
  • If you are changing the name of a node that has results already in use later in the workflow, you will be prompted to see if you want to update these results:

    • If you are NOT replacing the node but genuinely replacing it, say yes.
    • If you are replacing the node, say no. Then give that same (old) name to the new node. Poof, references "updated" to the new node (so long as the outputs are the same). This is useful for versioning situations.