Administration Guide

Troubleshoot Workflow

On this page

This page describes the ways a workflow run can fail, the messages a failed run shows, and the workflow log that records workflow runs. For the other logs, including the system log, see Logs. Actions and triggers themselves are introduced in Workflow Overview.

How a workflow run can fail

The workflow engine distinguishes four ways a run can fail:

What happened Caused by What the user sees What is logged
Aborted The Abort operation Depends on the calling application and preceding Message Box; see Return and Abort results. Pending changes are discarded. Workflow-log and job statuses differ; see below.
Error Any step that fails "Error while executing the workflow function. Workflow Item # n.", with "Function 'name'." for a named function, and the underlying message. A SQL error adds the statement text. The failure goes to the system log and, when enabled, the workflow log, with the Scheduled Task and global-function exceptions described below.
Trigger limit exceeded A cascade of triggers that goes past ten passes The error message followed by "The maximum number (10) of recursive calls for triggers is exceeded. Please simplify your workflow definition." As for an error.
Skipped silently A step that calls a function that is already running, an iteration over a script object that cannot be resolved, or a client-side external command reached when a service runs the item Nothing, or a line in the service's log Nothing in the workflow log

See Operations Reference for what each operation does.

Return and Abort results

Saving changes, a job's status, and the message shown to a user are separate results. A successful status alone does not mean that changes were saved.

How execution ends Pending changes Scheduled Task result
Return Saved when the program finishes normally. Succeeded.
Return with Discard all changes Not saved. Succeeded; the workflow log records the discard.
Abort Not saved. An After-Save trigger cannot undo the save that already completed. Failed; the session log records Execution aborted. ... as an error, and the System Log receives a job-failure entry.

In the Web App, Abort without a preceding Message Box shows an Error dialog with "Execution aborted. Workflow Item # n." A named function also adds "Function 'name'." If a Message Box precedes Abort, only its supplied message is shown, without a second standard Abort error. A normal Return shows any queued messages after saving. In Scheduled Tasks, messages are written to the session log.

An aborted Action has no result message in its workflow-log entry; with all executions logged, the Web App entry displays Succeed. An Abort in a Scheduled Task's own program creates no workflow-log entry. If a trigger fired by the task's save aborts, its entry is written without a result message. Use the task's session log and job status to check the failure.

An engine error in a Scheduled Task's own program or a global-function run also creates no workflow-log entry. The Scheduled Task Agent records the error in its session log and the System Log; a global function's caller receives the exception.

Other callers report Abort differently. For the REST API response, see Run Workflow Actions. The Mail Connector records an aborted rule as a rejected message; see Mail Connector.

Find the item behind an error message

In "Error while executing the workflow function. Workflow Item # n.", n is the number of the workflow item, the action or trigger, whose run failed. It is not the number of a function: a named function appears separately, in "Function 'name'.". The underlying message that follows says what went wrong. For example, when a step uses a placeholder that cannot be resolved, it reads: Could not resolve placeholder "<placeholder>".

The failure is recorded with the same message and item number in the system log and, when the workflow log keeps the run, in the workflow log.

An item's functions are corrected in the Settings App. The Admin Center has no command that opens a workflow item by its number.

In the Settings App

To open the item by the number in the message:

  1. On the Search menu, click Go To..., or press Ctrl+G.
  2. In the Go To dialog, enter the number in Workflow Item #: and click OK.

The item opens in its editor, and the navigation tree moves to the item's place in the workflow of its class, with the item selected. For more on Go To..., see Go to an item by its number.

From the workflow log, select the failed run's entry and click Go to Item, or open the entry and use Go to Item in its Log Entry Details window (see Log Entry Details). The window's Error Message: shows the whole message.

In the Admin Center

  • In the workflow log (the Workflow tile of Logs), open the entry with View log. In its Log Entry Details window, Item Name shows the item's name followed by its number, as (#n). The window has no command that goes to the item.
  • In the Error Log (the All Errors tile of Logs, then Error Log), open the entry for the failure with View log. When an action failed with this error, its details name the action and its number, followed by the error message and the underlying message.

The trigger limit

Saving an object starts a loop: the engine finds the triggers that match each modified object and runs them, and anything they modify joins the queue for the next pass. The loop allows ten passes. If a trigger's condition still matches on the eleventh pass, the engine raises the error above instead of stopping quietly. This happens before the save is written, so nothing of the save is stored, and the trigger's run is logged as failed.

Functions that skip their work

When an Execute Function, Update Field, variable, Create Object, Act on Related Object, or iteration step names a function that is already running, the engine skips the call. Nothing is reported to the user; the step simply does less than its author expected.

Break outside a loop

A Break operation outside a loop fails the run as an error, with the message: "Break" is not allowed outside of a loop.

In the Web App

For how technicians run actions in the Web App, see Run an action on a record.

The error dialog

When a workflow run started by an action in the Web App fails, the Web App shows the failure in its ordinary error dialog, titled Error, with the engine's message and the buttons OK and Help. The dialog has nothing to expand: the message is all it shows, and a workflow error looks the same as any other error. Help opens the online help for that message in a new tab; when the error is an Action Form validation error, it opens the help for validation errors.

An action run on several records

An action's criteria are checked again for each record as the action runs.

  • With one record selected and the test failing, nothing runs, and the technician sees "This action cannot be executed for one of the objects because this object does not meet the action's criteria."
  • With several records selected and an action that has a condition, the Web App asks once before anything runs: "This action has additional criteria. If any selected objects do not meet the criteria, the action will not affect them. We will let you know if any objects will be skipped." The action then runs for every record that passes and skips the rest without asking again, ending with "The action skipped some objects because they did not meet the action's criteria." and the counts Selected:, Affected:, and Skipped:.

Action Form validation

When a technician submits an Action Form, the server checks its validation rules:

  • A dialog-style form has its whole rule list checked.
  • A wizard-style form has the rules of the page being left checked, plus the rules that belong to no page when the last page is left. The Attachments page checks only the rules that belong to no page.

Every rule whose condition is met shows its message, one at a time; the message is the rule's text with its placeholders expanded (see Macros Reference). A rule of the error type keeps the form open. Confirm and info messages are acknowledged, and the submit goes on.

Read the workflow log

The workflow log keeps one entry for each run it records. By default it records only failed runs, so a run that completed without an error does not appear in it (see Workflow log settings). The entry is written in one go at the end of the run and records the object, the item or global function that ran, the item that started the run, the result and its message, the initiator, the user, and the host. Below it, the run's operations are kept as a tree, so calls to other functions appear nested. Notifications the run rendered are attached to the same entry. For a global function run, the entry names the function instead of an item.

A run that ends with a result message, such as a failed run, is written to the system log as well, even when the workflow log is switched off or keeps only errors, unless the component that started the run has no system log. If writing to the system log fails, that failure is not reported.

Deleting a log entry also deletes its operations and its notifications.

Workflow log settings

Three settings govern the workflow log:

Setting Label in the Settings App Default
Whether the workflow log is enabled Enable workflow logging Enabled
Whether only failed runs are kept Log only failed executions Only failed runs
How many days entries are kept Remove records older than n day(s) 7 days

A run that completed without an error is not kept when logging is switched off or when only failed runs are kept.

Once a day, the Automation Server removes the entries that are older than the retention period, together with their operations and notifications. It does this only while it runs as the active node: while the Automation Server is stopped, no entry is removed. It uses the retention period from the settings it loaded last.

For the other logs and their retention, see Logs.

In the Settings App

In the Settings App, the workflow log is shown in the workflow manager, which the Workflow node under Logs opens. For the rights that control the Logs branch, see Logs.

Find entries in the workflow log

The workflow log shows its entries in a grid. It loads the newest 1,000 entries by run date and says "Last <n> records are loaded". While its page is on screen, it reloads what changed every 10 seconds by default.

  • The Event filter offers Creation, Modification, Deletion, and Scheduled. The Status filter offers Succeed and Failed; it does not tell apart the ways a run can fail described above.
  • Every row of a run that did not succeed is drawn in red, whatever the way it failed.
  • A row that has no object or no user name shows <deleted> in its place.
  • Delete removes the selected entries after "Are you sure you want to delete the selected record?" or "Are you sure you want to delete <n> selected records?", and reports "<n> records have been deleted.".
  • Clear All asks "Are you sure you want to delete all log records?" and then removes every entry at once, together with its operations and its notifications.

When the log is too large to load in time, it shows its number of entries instead, and Clear All stays available.

Views of the workflow log

A new 2026.1 database created with the Default Workflow (see Default Workflow Configuration) contains these views of the workflow log:

  • Errors lists only the entries whose status is Failed.
  • List lists every entry.
  • by Host, by Initiator Name, and by Initiator Type group the entries by host, by initiator name, and by initiator type.

Each of these views shows the run date, the object ID, the action name, the event, the initiator name, the host, and the status, with the newest run first. A grouped view hides the column it groups on. None of these views limits the entries to a period of time; to see, for example, the runs of the last week, filter or group the entries yourself.

An upgraded database need not contain these views, and an administrator may have changed them.

Change the workflow log settings

  1. In the workflow log, click Settings....
  2. In the Settings dialog, select or clear Enable workflow logging and, under it, Log only failed executions.
  3. Under Retention Policy, set Remove records older than to a number of day(s) from 1 to 999.
  4. Click OK.

While Enable workflow logging is cleared, Log only failed executions and the retention box are unavailable. OK saves the settings and tells the Automation Server to reload them, so the daily removal uses the new retention period without a restart.

Settings... requires the right to manage logs; without it, it answers "You do not have enough permissions to use this function." In Alloy Navigator Cloud, the retention box is unavailable and keeps the stored value.

Log Entry Details

Clicking View Details in the workflow log, pressing Enter on an entry, or double-clicking it opens the Log Entry Details window, titled with the item's name and number. The window does not block the log behind it. It shows:

  • Run Date:, Item Name: (with the item number, and Generic item for an item that belongs to no class), Object ID: (the object's ID and class, or <deleted> when the entry no longer names the object), Event:, Triggered by Action: (the action's name and number, blank when the entry names no action), Initiator Name:, Initiator Type:, Host:, and Status:, which reads Succeed or Failed, or shows the result code as a number for any other result.
  • Operations:, a tree of the run's operations with the columns Operation and Description. Selecting an operation fills Operation Details: with its Parameter and Value rows. A lookup parameter whose value no longer resolves shows <deleted> when the run's error message contains FOREIGN KEY, and is left blank otherwise. A push notification's recipient who can no longer be found shows <deleted>.
  • An Error Message: panel, only when the run failed. The status then turns red.

Object ID: shows no ID for PO Items, Vendor Products, and Approval Requests. The < and > buttons step to the previous and next entry, and Go to Item opens the workflow item the entry belongs to in its editor. The workflow log itself also has Go to Item, for the selected entry.

In the Admin Center

In the Admin Center, the workflow log is the Workflow tile of the Logs page. On its page:

  • View log is available only when exactly one entry is selected; double-clicking an entry does the same.
  • Clear all deletes all workflow log entries at once, together with their operations and their rendered notifications, after a single Yes/No question.
  • Delete removes the selected entries after a confirmation and shows no result message afterwards.
  • Clear all, Delete, and Settings are shown only to an account with the permission to manage logs.

The workflow log's settings form holds the retention period and whether only failed runs are kept. In Alloy Navigator Cloud, the form shows 7 days with only failed runs kept, both controls are unavailable, and saving stores those two values.