Workflow Troubleshooting

Introduction

Workflow errors are displayed on their own page accessible from the Global Workflow console.

Each error is assigned an integer as an Id. Each error entry in the list displays the error's ID, the source group, the name of the workflow, and the type of the error. Some types include Missing Routine, Connector, Handler, and Node Parameter.

Even though they have their own console, errors are normally referenced from a task in a Run.

From the Details section you can click on the Error # and go directly to the error.

In the sections below we'll describe how to read, and troubleshoot various workflow errors.

Reading a Task Error

Each error is displayed in the same console format:

Along the top of the console is the Error Id and information about the original run (including a link to the tree).

Below that are tabs for the Details (default) and the Resolution (covered later). And on the right side is a button to open the Builder. If you chose to open the builder and the error is based on a node, that node will be highlighted and placed in the middle of the screen.

The section in blue is for resolving errors and recording actions taken. It is covered in a section below.

The Details section contains any specific information about the error from the the Task engine. Normally, this is a stack trace.

In most cases, the details section includes a short sentence describing the error, a short Problem declaration, and then the entire Stack Trace.

Connector Errors

Connector errors are similar, but include a little more information around the two nodes that are the start and end of the connectors.

Also, instead of retry, connector error will ask you if the path should continue down that particular path (whether that connector would have evaluated to true).

Common Task Errors

In the next sections are some common task errors and potential fixes. The desire is to give you some ideas for troubleshooting. So much in Kinetic workflows is personalized to the customer that it is often impossible to give exact solutions.

Unable to retrieve hash value for the key

You can see this error in the connector error description above. It indicates that a reference to a node name is missing, incorrect, or hasn't been executed yet.

For example, in the connector error, ApprovalValue has either not been returned yet, or is incorrectly identified.

nil:NilClass

This error indicates that within either the handler code, or code in a node parameter, a method was called, but no value was provided.

For example in your handler you have the following code to convert a string variable to an integer x.to_i. If x is nil (null for ruby), you will get the nil:NilClass.

The stack trace will often show a line number in the init.rb file that relates to this error.

Invalid Trigger

This error happens when a trigger tries to complete a deferred node that has already been completed.

Normally this is a breakdown in the logic or process that's creating a trigger. It is either happening at the wrong time, or duplicating a trigger it shouldn't.

Because you cannot retry the trigger in this case, the Resolve Error section only allows you to enter notes (required).

SSLError

This error can happen when task cannot connect to the system the handler is trying to connect to. This can be because of untrusted certificates, an error in the SSL code in the handler, or an error in the task handler's configuration.

Resolving Errors

The task engine provides a built-in mechanism for retrying errors in the Resolve Errors section of the error task. In any case where you are able to resolve an error, there is an Additional Actions drop-down with three choices, and a Notes field to record any extra notes (normally for either auditing or future troubleshooting purposes).

All Actions:

• Do Nothing: Marks the error as being resolved, but does not automatically trigger any actions.

Connector Actions:

• Continue Branch: Indicates to the engine that the connector expression that raised an error should have evaluated to true, and tree processing should continue as appropriate.
• Cancel Branch: Indicates to the engine that the connector expression that raised an error should have evaluated to false, and tree processing should continue as appropriate.

Node Actions:

• Retry Task: Restarts processing from the failed node. This may have unintentional side effects if the error is raised after some amount of processing. For example, if an error is thrown after a handler creates a record, and that error is retried, a second record could be created when the task is retried.
• Skip Task: Skips the failing node (assuming that the behavior from the node was manually completed), and processes its connectors as if the node was completed.

Source Actions:

• Retry: Attempts to restart the tree run from where it left off.

Updating Inputs and Results

It may be necessary, after fixing data that caused an error, to also update where that data appears in inputs or results in the workflow run. There are a couple of places on the Run where you can edit the data yourself and then use the Retry Task option to resolve an error.

Inputs

Inputs are available at the top of every Run. If you know that an input values is incorrect or invalid (for example an answer is blank or not what is expected), you can update the inputs and either retry or run the tree again. Be careful re-running the tree, you could duplicate messages or other actions created by the tree.

Make use of the audit message to explain any edits of the input data.

Results

Each node that generates Results has the ability to edit those results.
Example of a Task Result:

Task does not allow you to makeup a new Result value, so you are limited to the results defined in the task.

Here is an example from a Routine:

In this case I selected to audit the deferred results.

Changing the results here will only have an effect on any Task that runs after the change. Completed tasks are not updated.

The Ability to Retry Errors

The platform allows retries of errors that will consistently have the desired behavior after being retried. For example, we know that if a handler raises an exception that the tree has not done any downstream processing and the node can safely be retried. In other cases, such as a malformed tree, it is impossible to know the expected vs actual outcome so the platform can't effectively allow retries.

Errors that can be retried:

• Connector Errors (Continue or Cancel)
• Handler Errors (Retry or Skip)
• Node Parameter Errors (Retry or Skip)
• Missing Handler Errors (Retry or Skip)
• Missing Routine Errors (Retry or Skip)
• Source Errors (Retry)

Errors that can not be retried:

• Invalid Trigger Error
  (these are raised for things like attempting to update/complete a closed task node)
• Node Message Error
  (these are raised for invalid node messages)
• Tree Error
  (these are raised for invalid trees)
• System Error, Unidentified Error, Unknown Variable Error
  (these are unexpected errors and likely should be reported to support)

Available Logs

Logs are available to either view or download from the Admin|Logs page of the Task Console

The following are available:

• Application (Opens in a new tab) – Activities from the Application console. Useful for issues with export/imports, handler configuration, engine issues, and builder errors.
• Engine (Opens in a new tab) – This is a combined log of all the engine activities. This log moves and fills quickly on a busy system and is better used with initial development troubleshooting. Previous 9 logs are kept (1-9) and the default size is 20 MB.
• Download Worker Logs (Downloads a zip file) – This is the engine log separated by thread (worker). Each worker has an archive of the previous nine logs with a default size of 20 MB.
• Download All Logs (Downloads a zip file) – Includes all of the Worker logs, plus the Application logs, Installation log, and an Environment report.
• Install Log (Opens in a new tab) – Records all the actions taken during installation. If there are issues with connecting or configuring the database for Task during installation, this is the best place to look.

Log Settings

Changing the log setting is done on the Admin|Setup console.

Log Level can be set to

• Info (Production)
• Debug (Development) - Default setting
• Trace (Troubleshooting)

Log size can be set to more than 20 MB. Be aware that this is the size of all the files, and setting this to a higher value can cause delays displaying the current log in a new tab, or the All zipped option to be too large to send via email.