Workflow Admin — fixing stuck workflows

What you'll learn#

• When and why to use Workflow Admin
• How to find a stuck workflow and diagnose what went wrong
• The admin actions available and when to use each
• A standard diagnostic workflow you can follow when something is reported stuck

What Workflow Admin is#

Most of the time, a document flows through its approval without any hitches: tasks get assigned, approvers act on them, and the document reaches Approved or Rejected. But sometimes things go wrong in ways that stop the workflow silently from a regular user's perspective:

• A task was assigned to a position that's now vacant (the person left; nobody replaced them).
• A callback URL pointing to an external system stopped responding.
• An execution script (an internal step VAT Portal runs between tasks) failed on bad data.

When something like that happens, the workflow engine parks the instance in Maintenance status. Regular users see their document sitting in "Approving" forever. This is where Workflow Admin comes in: it's a diagnostic and repair tool that lets admins see why an instance is stuck and take action to unblock it.

Opening Workflow Admin#

Document Flow → Workflow Admin in the sidebar. The entry only appears if your account has permission for it — specifically the wfl_instance resource. If you don't see it, you don't have access.

The list page — finding the stuck instance#

The Workflow Admin list shows every workflow instance in your company.

At the top of the page:

• Six status filter tabs: All, Active, Approved, Rejected, FailedToInitiate, and Maintenance. The Maintenance tab is amber-highlighted on purpose — it draws attention because it's usually what you care about.
• A Document ID search input — useful if a user gave you the document number and you want to jump straight to its workflow instance.

The table shows:

• Instance ID
• Document ID
• Status (color-coded badge)
• Created by (resolved to the person's name)
• Created / Updated timestamps
• Comment (a short note, if any)

Click any row to open its detail page.

The detail page — diagnosing the problem#

When you click into a stuck instance, you get a detailed view with everything needed to figure out what went wrong.

General Info and Callback URLs#

At the top, two cards show the basics:

• General Info — Instance ID, Workflow ID, Document ID (clickable — opens the document's detail page in the same tab), current status, any comment that was attached.
• Callback URLs — the initUrl and completeUrl configured on the workflow. These are the external HTTP endpoints VAT Portal calls when the workflow starts and completes. Misconfigured URLs are a common source of stuck workflows.

Task Instances#

A collapsible table listing every task in the workflow instance, with:

• Task name, step number (cons), status, who completed it (if anyone), any comment, and an Error column that shows a number > 0 if that task errored.

Per-task actions (if you have update permission):

• Edit Push Result — configure the webhook that fires after the task completes.
• Edit Ask Approval — configure the webhook that fires to ask for approval.
• Trigger Push Result — manually fire the push-result callback for an already-approved task. Only visible for Approved tasks. Useful when the original call failed and you want to retry.

Scripts — the main diagnostic tool#

Scripts are the small internal commands VAT Portal runs while processing a workflow — things like "activate this task", "fire this webhook", "advance to the next step". The Scripts card lists every script that's been executed (or tried) for this instance, in order.

• Successful scripts appear normally.
• Failed scripts are highlighted in red — red left border, red tint on the background, error message in red text below the script details.

This is the single most useful card for diagnosis. If the workflow is stuck, one of these scripts failed; the error message usually tells you exactly what went wrong in plain-ish English:

• "No active user found for position ID 42" → the position is vacant, assign a user to it
• "URL not reachable: http://erp.internal/api/callback" → the callback endpoint is down or misconfigured
• "Field value not convertible to number" → data in the document doesn't match what a condition expected

Once you see the error, you know what to fix.

Admin Actions#

The Admin Actions card is where you make changes. The buttons available depend on the instance status and your permissions.

The standard diagnostic workflow#

Here's the routine that covers most real incidents:

1. Open Workflow Admin → filter to Maintenance. If nothing's there, the system isn't stuck — check with the user for the actual document ID, search for it, and look at its status.
2. Click the stuck instance to open the detail page.
3. Scroll to the Scripts card. Look for the first red-highlighted script. Read its error message.
4. Fix the root cause — outside Workflow Admin. Examples:
   • Vacant position → go to HR → Positions → Employees, and assign someone.
   • Bad callback URL → go back to the Admin Actions card on this same page and click Update URLs to fix it.
   • User removed → either reassign in HR or Update URLs as appropriate.
   • Condition evaluation error → the workflow design itself may need fixing in the Flow Editor; for the current stuck instance, Rejecting and asking the user to correct/resubmit is often the quickest path.
5. Click Reactivate. The workflow resumes from the point it stopped. If it runs through cleanly, the status moves out of Maintenance and the stuck document proceeds.
6. If Reactivate fails (script fails again), read the new error message and go back to step 4.

If the root cause can't be fixed and the instance must end, Reject with a clear comment explaining why. The user can then correct and resubmit as a fresh workflow run.

Per-task admin actions (Push Result / Ask Approval)#

The webhook settings on individual tasks exist for integrations with external systems. Most admins won't touch these — they're set up once when the workflow is designed and then left alone. You might need them when:

• An external system changed its endpoint and the webhook URL needs updating for this specific instance.
• A push-result callback originally failed (the external system was down) and now that it's back, you want to retry — use Trigger Push Result on an Approved task to manually fire the callback.

If you're not sure whether to edit these, don't. Talk to whoever set up the original integration.

Common questions#