Workflow Submission Fields

When a submission moves through a Workflow Builder workflow, Unqork writes workflow metadata directly the submission object. These fields are accessible through template expressions and the Submissions API. Use them to build dashboards, filter submission lists, or write conditional logic based on where a submission is in a process.

Available Fields

Field Details

_workflow.state.currentState

The name of the workflow node the submission currently occupies. Matches the node name as configured in the Workflow Builder.

Use this field to filter a submission list to a specific workflow step. For example, all submissions currently at a "Pending Review" node.

_workflow.state.stateHistory

An array of workflow node names the submission has passed through, from the start node to the current node. Each entry records a transition in the workflow.

Use this field to audit the a submission took through a workflow, identify submissions that passed through a specific node, or calculate how long a submission spent between steps.

status.current

The current status value on the submission. Status values are set by workflow nodes or by direct submission updates.

status.all

An array of all status values the submission has held, in the order they were applied. Use this field to review the full status history of a submission.

_workflow.timerExecutionCounts

An object keyed by timer node name. Each value is the number of times that timer has fired for this submission. A timer node that has fired three times has a count of 3.

Use this field to build logic that responds to how many times a timer has fired. For example, an escalation after a timer fires a set number of times without resolution.

Accessing These Fields

These fields are available anywhere template expressions are supported, including module component settings and the List Submissions for Dashboard API.

In a template expression:

{{__submission__._workflow.state.currentState}}

In a List Submissions for Dashboard query:

Use the fields parameter to include workflow fields in the response. Pass workflowId instead of moduleId when querying workflow submissions.

GET https://{environment}.unqork.io/fbu/uapi/system/getSubmissions?workflowId={workflowId}&fields=__submission__._workflow.state.currentState,__submission__._workflow.state.stateHistory,__submission__.status.current,__submission__.status.all

To filter results by workflow state, add the filter parameter:

GET https://{environment}.unqork.io/fbu/uapi/system/getSubmissions?workflowId={workflowId}&fields=__submission__._workflow.state.currentState&filter={"_workflow.state.currentState":"Pending Review"}

To find the workflowId, open the workflow in the Workflow Builder. The ID is in the URL:

https://{environment}.unqork.io/workflow/{workflowId}

Considerations

• These fields are populated for submissions that are associated with an active workflow. Submissions not connected to a workflow do not have _workflow fields.
• stateHistory and status.all grow as the submission progresses through the workflow. For long-running processes, these arrays can become large.
• timerExecutionCounts includes timer nodes that have fired at least. Nodes that have not yet fired do not appear in the object.
• Node names in currentState and stateHistory reflect the names configured in the Workflow Builder. Renaming a node does not update historical entries in stateHistory.