Workflows in Apps

Last updated: October 14, 2026Applies to current supported NIM releases

Workflows · Apps

Everything end users do with a workflow happens in a NIM App: starting a request, performing a step, following a case, and handing work to a colleague.

End users never see Studio. They work with workflows through NIM Apps that use the workflow tables and the workflow actions described on this page.

The Apps of a workflow

App	Purpose	Built with
Start form	Collects the request and starts a case.	The App named on the start event, with a Start workflow case action.
Step App	Lets a performer do one user task, such as an approval with comments.	The App named on the user task, with a Complete workflow step action.
Task list (inbox)	Shows each user what waits for them, and opens or completes it.	A grid on workflow.my_tasks, with Open workflow step and Complete workflow step actions.
My requests	Shows users the cases they started or took part in, and lets them withdraw a request.	A grid on workflow.my_cases, with workflow.case_data and workflow.case_history for details.
Supervisor App	Lets supervisors follow every case of a configuration and correct, retry, or cancel cases.	A grid on workflow.cases, with Amend workflow case, Retry workflow step, and Cancel workflow case actions.
Delegations App	Lets users hand their steps to a colleague while they are away.	Grids on workflow.my_delegations and workflow.delegatable_steps, with the delegation actions.

Hide step Apps from the dashboard

A step App only makes sense when it is opened for a step. Clear the App property show in dashboard, or the Dashboard checkbox in the App list, to keep it off the App dashboard. This is not a permission: everyone who may run the App can still open it.

App variables for workflows

• Start form: any App variable can go into the case. Tick it in the configuration's start event under Variables from app to case.
• Step App: to receive a value from the case when the step opens, the App variable must have the type input. Add it on the App's Variables tab. Values the step hands back are ticked under Variables from app to case.

See Workflow configurations.

Example: a task list with approve and reject buttons

1. Add a grid on workflow.my_tasks to an App.
2. Add a column with the Workflow: open step template. It runs Open workflow step with the row's work_item_id.
3. Add a column with the Workflow: approve template. It shows its button when completion is decide and outcome_positive is set, and runs Complete workflow step with that outcome and the row's work item.
4. Add a column with the Workflow: reject template. It shows its button when outcome_negative is set. Optionally, let it open a form for a reason first.
5. Add a column with the Workflow: send message template for messages, such as a withdrawal by the initiator.

To let initiators withdraw their requests, draw an interrupting boundary message event with participant Initiator on the approval step, and add the Workflow: send message template to a grid on workflow.my_cases.

Workflow tables

The workflow tables are internal tables. Select them in a grid, dropdown, or other table control under Table name, such as workflow.my_tasks. Unlike other tables, their rows depend on who is signed in: each user sees only their own work, cases, and delegations.

Set the table's parameters under Parameters. An empty or unknown value means all. After a workflow action runs, NIM refreshes every grid on a workflow table that the action changed.

The table builder offers ready-made templates for workflow buttons: Workflow: open step, Workflow: approve, Workflow: reject, and Workflow: send message.

workflow.my_tasks

Show parameters, columns, and usage

The open steps waiting for the signed-in user, oldest first.

Parameter	Values
match	all (default); personal: named on the user, including delegated steps; group: through a group the user is in, or Anyone signed in; delegated: only steps someone handed to the user.
kind	all (default); user: steps performed in an App; message: messages the user may send, such as a withdrawal.
completion	all (default); decide: can be completed from the list with an outcome; open: must be opened in its App; send: a message.

Column	Contents
case_id	The ID of the case.
work_item_id	The ID of the step. Pass it to Open workflow step and Complete workflow step.
since	When the step appeared.
subject	The case subject.
initiator, initiator_email, initiator_user_id	Who started the case. Empty and 0 when the service started it.
outcomes	The outcomes the step can be completed with from the list, separated by , . Empty when the step must be opened in its App.
outcome_positive, outcome_negative	The outcome that means approval and the outcome that means refusal, from the line meanings in the drawing. Empty when there is none, or when the step must be performed in its App.
task, description	The step's ID and its label in the drawing.
step_display_name	The step's display name, or its label.
participant	The participant of the step.
kind	user or message.
completion	decide, open, or send.
match	personal, group, or delegated.
delegated_from, delegated_from_user_id	For a delegated step: whose step it is.
app	The App the step is performed in. Empty for a message.
configuration, configuration_display_name	The configuration and its display name.
workflow	The name of the definition.

When a step must be performed in its App only because it writes a required value, outcome_positive is empty but outcome_negative is kept. Approve then opens the App, and Reject stays a direct button. See Required values and refusals.

workflow.my_cases

Show parameters, columns, and usage

The cases the signed-in user started or performed a step of, most recently changed first.

Parameter	Values
role	all (default); initiator: cases the user started; participant: cases the user completed a step of.
status	all (default); open: running or stuck; completed: completed or cancelled.

Column	Contents
case_id	The ID of the case.
work_item_id	The message the user may send on this case in person, such as a withdrawal. Empty otherwise.
completion	send when there is such a message, otherwise empty.
subject, result	The case subject and case result. The result can be empty while the case runs.
status	running, stuck, completed, or cancelled.
started, changed	When the case started and last changed.
step	The open step or steps, by display name.
waiting_for	The participants of the open steps.
waiting_for_actors	The users or groups the case waits for now. A group is shown as the group, not its members.
waiting_since	When the oldest open step appeared.
blocked_reason, blocked_step	Why a blocked case does not move, and on which step.
initiator, initiator_email, initiator_user_id	Who started the case.
role	initiator or participant. initiator wins when both apply.
configuration, configuration_display_name, workflow	What the case runs on.

workflow.cases

Show parameters, columns, and usage

Every case of the configurations the signed-in user supervises with the See right. Administrators see every case. See Supervisors.

Parameter	Values
configuration	The name of one configuration. Empty for every configuration the user supervises.
status	all (default), open, or completed.

The columns are those of workflow.my_cases, without work_item_id, completion, and role.

workflow.case_data

Show parameters, columns, and usage

The case variables of one case.

Parameter	Values
case_id	Required. Bind it to the selected row of a my_cases or cases grid. Empty returns no rows.

Column	Contents
variable	The case variable.
type	Its type.
value	Its value as text. Dates are in ISO format.
filled	Whether it has a value.
builtin	Whether it is a built-in variable.
description	Its description.

A user sees a case when they started it, performed a step of it, have an open step on it, or supervise it with See. Otherwise, the table returns no rows, as for a case that does not exist. Supervisors see every variable. Other users see only the variables their participant may read under the case data permissions.

workflow.case_history

Show parameters, columns, and usage

The history of one case, oldest first. It takes the same case_id parameter, and the same rule decides who sees a case.

Column	Contents
sequence, time	The order and time of the event.
kind	The kind of event. See History.
step, step_display_name	The step involved.
work_item_id	The step's work item. Pass it to Retry workflow step.
detail	What happened.
user_id, user	Who did it. 0 and empty for the system.
on_behalf_of_user_id, on_behalf_of	For delegated work: on whose behalf.

workflow.my_delegations

Show parameters, columns, and usage

The delegations the signed-in user has given or received.

Parameter	Values
direction	all (default), given, or received.

Column	Contents
delegation_id	The ID. Pass it to Remove workflow delegation and Enable workflow delegation.
direction	given or received.
from, from_user_id, to, to_user_id	The delegator and the delegate.
scope	The steps, in words: all steps or Configuration: Step; ….
scope_steps	The steps as Add workflow delegation takes them: configuration/task; …. Empty for all steps.
valid_from, valid_until	The period.
enabled	Whether it is switched on.
active	Whether it applies right now.
note, created	The note and when it was made.

workflow.delegatable_steps

Show parameters, columns, and usage

Every user task and message event of every published configuration: the steps a user can delegate. It has no parameters, and every user sees the same rows.

Column	Contents
step	The step as configuration/task, ready for Add workflow delegation.
configuration, configuration_display_name, workflow	Where the step belongs.
task, description, step_display_name	The step's ID, label, and display name.
participant, kind	Who performs or sends it, and whether it is a user task or a message.

Workflow actions

Add workflow actions like any other App action: select the trigger, open Actions, select + Add, and choose the Action type. Every workflow action has a Description, the message shown when the action has run. It can contain {variable} placeholders.

Except Open workflow step, workflow actions run on the NIM service. They do not run in the App designer's test mode.

Start workflow case

Show action settings and behavior

Starts a case from a start form.

Field	Use
Workflow	Leave empty to start the workflow this App is the start form of. Choose a published configuration only when more than one published configuration starts from this App.
Case id variable	Optional. An App variable that receives the ID of the new case.

The ticked App variables go into the case, the session mappings are read from the starter's session, and the signed-in user becomes the initiator. Service tasks at the beginning of the process run immediately.

The action fails when the App is not the start form of a published configuration, or when it is the start form of several published configurations and the action does not name one.

Open workflow step

Show action settings and behavior

Opens the App of a step for its performer, typically from a task list row.

Field	Use
Work item variable	The App variable that holds the step's work_item_id, such as vWorkItemID from the selected my_tasks row.

NIM checks that the step waits for the signed-in user (personally, through a group, or by delegation), opens the step's App, and prefills its input variables from the case. When the step does not wait for the user, the action fails with This task cannot be opened.

Complete workflow step

Show action settings and behavior

Completes a step, from the step's own App or from a task list.

Field	Use
Outcome	The outcome, such as Approved, true, or {vDecision}. Use Pick to choose a branch label of a configuration that uses this App. Leave empty to complete without an outcome.
Case status variable	Optional. An App variable that receives what the case did next: completed or waiting.
Completes	the step this app was opened for (default), or a work item this app holds in a variable, for a task list that completes a step per row.

How it works:

• From the step's own App, the ticked App variables go back into the case.
• From another App, such as a task list, only the outcome is passed. This is refused for a step that must be performed in its App, except for a refusal.
• The outcome is matched against the branch labels after the step, ignoring case. true, yes, and 1 and false, no, and 0 also select the line marked positive or negative.
• The step must wait for the signed-in user.

The action fails, for example, when a required value is missing, a value does not fit its case variable, the participant may not write a variable, or the step is no longer waiting.

Supervisor actions

Show action settings and behavior

These actions require the matching right in the configuration's Supervisors grid. Administrators always have it.

Action	Fields	Right	Effect
Amend workflow case	Case id variable, Case variable, Value	Manage	Sets a case variable. An empty value clears it. The value is converted to the variable's type, and the case continues if it was blocked.
Retry workflow step	Case id variable, Work item variable	Manage	Runs a failed step again. Take the work item from a case_history row.
Cancel workflow case	Case id variable, Reason	Cancel	Withdraws every open step and cancels the case. The reason is recorded in the history.

Without the right, the action fails with Case … runs under configuration '…', which this user does not supervise.

Delegation actions

Show action settings and behavior

In an App, the delegator is always the signed-in user. Users can only change their own delegations.

Action	Fields
Add workflow delegation	Delegate user id variable: an App variable with the NIM user ID of the delegate. Steps: configuration/task entries separated by ;, such as the step column of delegatable_steps; empty for all steps. From and Until: a date, or a date and time; empty for no limit. Note. Enabled: true (default), false, or {variable}.
Remove workflow delegation	Delegation id variable: the delegation_id of a my_delegations row.
Enable workflow delegation	Delegation id variable, and Enabled: true or false.

See Workflow delegations for the rules.

NimScript: find an open case

In a script column of a filter, the function wfCaseOpen(configuration, variable, value[, initiatorUserId]) finds the oldest open case of a configuration whose case variable holds a value. Use it, for example, to show that a request for a group is already under way, or to prevent a duplicate request.

When you pass the NIM user ID of an initiator, only the cases that user started count.

The function returns an object with these fields:

Field	Contents
found	Whether there is an open case. When there is none, every other field is empty.
case_id, started, subject	The case, when it started, and what it is about.
status, blocked_reason	running or stuck, and why a stuck case does not move.
initiator_user_id, initiator_name	Who started the case.
step	The step or steps that are open now.
work_item_id	The message the given initiator may send on the case, such as a withdrawal. Pass it to Complete workflow step on a grid row.
open_count	How many open cases hold the value. The other fields describe the oldest.

wfCaseOpen(configuration, variable, value, params.user_id).started

The function is meant for scripts, not for {} substitution in a text.

Related guides

• Form Builder — arrange request forms, configure buttons, and create modals.
• Table Builder — build task list grids and workflow button columns.

Report a problem with this page

Found an error or a missing step? Open the feedback form and describe what needs changing. The article details and Documentation topic are filled in for you.

Need help with your NIM environment? Contact Support.