Workflow configurations

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

Workflows · Configurations

Bring a drawing to life: decide which App each step runs in, which data travels with the case, and how every branch is chosen.

A workflow configuration is a layer on top of one workflow definition. It holds everything the drawing leaves open: the case variables, the App in which each user task is performed, the actions of each service task, timer moments, gateway routing, the people behind each participant, and the permissions. A definition can have several configurations, each with its own name. A case is always started on a published configuration.

Configuration checklist

Connect the start and step Apps, map case variables, bind participants, and set permissions. Then resolve validation findings and publish. Participants and permissions covers people and access; Publishing covers releasing the configuration.

Manage configurations

Go to Configuration → Workflows and open the Configurations tab. The Workflow configurations grid shows:

Show configuration grid columns

Column	Shows
Configuration name	The name a case is started by. Edit it in the grid to rename the configuration. Running cases are not affected.
Display name	What end users read for this workflow.
Definition	The definition the configuration belongs to.
Description	A free description.
Published	Yes, No, or Yes * when the configuration has changed since it was published.
Case data	Open or Enforced: the permission mode.
Findings	none, or the number of errors and warnings. definition is gone when the definition was deleted.
Cases	none, or the number of cases and how many are under way.

Use the row icons to edit, copy, rename, or delete a configuration.

• Add opens + Add configuration. Enter a Configuration name, pick the Definition, and select Create. The configuration screen opens.
• Copy creates an unpublished copy.
• A configuration name cannot start or end with a space, cannot contain \ / : * ? " < > |, and must be unique.
• NIM refuses to delete a configuration that still has cases under way.

The configuration screen

The top bar shows the configuration and its definition, with these buttons:

• Save: stores the configuration. It shows Save * while there are unsaved changes. Errors block saving and open the Validation tab. Warnings do not block saving.
• Publish / Unpublish: see Publish and unpublish.
• Exit configuration: returns to the Configurations tab. NIM asks whether to save unsaved changes.

The screen has a side bar on the left and five tabs:

Tab	Use it to
Steps	See the drawing. Click the start event, a step, or a gateway to configure it in the side bar. Shapes with findings are colored orange (warning) or red (error).
Variables	Correct and clean up the case variables, and set the case subject and case result.
Participants	Bind each participant to NIM users or groups. See Participants and permissions.
Permissions	Decide which participant may read and write which case variable, and who supervises the cases.
Validation	Solve the findings that block saving or publishing. See Validation.

Configure the workflow as a whole

With nothing selected on the Steps tab, the side bar shows Display name of the configuration. End users read this name in their task lists, their cases, and their mail. While it is empty, they read the configuration name. A display name takes effect immediately, without publishing again.

Configure each step

Select an element on the Steps tab. The side bar shows what can be configured for it. Only the start event, user tasks, service tasks, send tasks, timer events, message events, and exclusive gateways have settings. End events and parallel gateways have none. A cancelling join is configured through the meaning of its lines in the definition.

Start event: the start form

The start event names the App from which a case is started: the start form.

1. In Start … - a case is started from app, choose the App. Choose (none: started by the api or the service) when cases are only started from Studio or the API.
2. Under Variables from app to case, tick each App variable whose value goes into the case. Ticking declares a case variable with the same name and type. Type another name under Case variable to give the case variable a different name, or to map onto an existing one.
3. Optionally, under Variables from the session of whoever starts the case, tick session variables, such as the starter's manager ID. Type the name the value gets in the case, such as initiatorManagerId.

The App starts the case with a Start workflow case action. See Workflows in Apps.

Keep in mind:

• Nothing is filled from the case into the start form, because there is no case yet while the form is filled in.
• Nobody is assigned to the start: anyone who may open the App may start a case.
• Session values are read by the service at the moment the case starts, not from the form, so the person filling it in cannot change them. Session variables are defined under Configuration → Variables → Session.

User task

A user task is performed by a person in a NIM App.

Setting	What it does
… performed in app	The App the performer opens for this step. Changing the App clears the step's variable mappings.
Performed by	Read-only. Shows who performs the step, based on the participant in the drawing and its binding on the Participants tab.
Must be performed in its app	When ticked, a task list can only offer Perform: the step must be completed in its App. When cleared, a task list may complete the step with one of its outcomes, such as Approve or Reject, without opening the App.
Variables from case to app	Prefill: tick each input variable of the App to fill it from a case variable when the step opens. Required input variables are shown in bold, and in red while they are not ticked.
Variables from app to case	Result: tick each App variable whose value goes back into the case when the step is completed.
Display name	What end users read for this step in task lists, mail, and the case history. While empty, they read the label from the drawing. Takes effect without publishing again.

Only App variables of the type input can be prefilled from the case. If the App has none, add an input variable on the App's Variables tab.

With enforced permissions, the prefill list offers only the case variables the step's participant may read.

Required values and refusals

Mark a case variable Required on the Variables tab when a step must deliver it. A step that writes a required variable cannot be completed while the value is empty. It also cannot be completed from a task list, which delivers no data, so Must be performed in its app is ticked and locked.

There is one exception: a refusal owes no value. When the line after the step has the meaning negative, the step can still be rejected from a task list without the required value. A task list then opens the App for Approve and keeps Reject as a direct button.

Service task

A service task runs one or more actions on the NIM service.

1. Under Actions, select Add.
2. Choose the Action type:
   • Target system function execution: run a function of a target system, such as creating an account or adding a group membership.
   • Script function execution: run a function of a NIM script.
   • Service resource command: run a command on a NIM resource.
3. Configure the action. Bind arguments to case variables, including the built-in variables. Results that the action hands back declare case variables automatically.
4. Select Save.

Drag the rows to change the order; the actions run from top to bottom. An unfinished action is marked with ⚠.

If an action fails, the step fails and the case waits. A supervisor can run the step again after fixing the cause.

Send task

A send task mails its participant and continues. Its message is the mail template coupled to the event <configuration>.<step> of type workflow-step. Without a template, the send task sends nothing. See Workflow notifications.

Timer event

A timer event, intermediate or on the border of a task, goes off at a moment you set in Timer event … goes off:

• after a duration: enter a Duration of at least 1 and choose minutes, hours, or days. The duration counts from the moment the step became active.
• on the date in a case variable: choose a Case variable of type date or date-time. The variable is read once, when the step becomes active.

A timer that is not configured fails its step in a running case. On the border of a task, the timer competes with the task: whichever happens first continues the case. NIM checks timers every minute. Repeating timers are not supported.

Message event

A message event is sent by its participant, for example the initiator who withdraws a request. Nothing needs to be configured except a Display name. On the border of a task, sending the message withdraws the task.

Exclusive gateway

Choose how the gateway picks its branch in Exclusive gateway … decides by:

Option	How it routes
the outcome the step before it ended with (default)	Matches the outcome of the previous step, such as Approved, against the branch labels. One branch may be unlabeled: it is the default for any other outcome.
a case variable, matched against the branch labels	Matches the value of the chosen Case variable against the branch labels.
a condition on each branch	Takes the branch whose condition holds. Exactly one must hold, so give the last branch otherwise.

For conditions, configure a test per branch in the side bar, or select Table to edit all branches in one grid with the columns Branch, Variable, Type, Operation, and Value. The operations are:

• =, !=, <, <=, >, >=
• contains, not contains, in, not in
• is empty, is not empty
• otherwise

Text is compared without regard to case unless you choose the (case sensitive) variant of an operation. A condition that combines tests with and, or, or not is edited as text under the grid.

Switching to another option clears what the previous option configured. Parallel gateways, event gateways, and cancelling joins have no routing settings.

Case variables

Case variables are the data a case carries from step to step. Most variables are declared by ticking a value in the side bar. Use the Variables tab to correct them and to clean up what is no longer used.

The Case data grid shows:

Show case variable columns

Column	Meaning
Case variable	The name. Names ignore case. Edit the name to rename the variable everywhere it is used.
Type	string, number, boolean, date, or date-time.
Required	A step that writes this variable cannot be completed while it is empty. See Required values and refusals.
Filled by	The steps, session values, and actions that write the variable. When the source name differs, it is shown, such as request (session managerId).
Used by	The steps, gateways, timers, and participants that read it.
Description	A free description.

• Select Add to declare a variable by hand.
• Renaming a variable renames it in every mapping, condition, action, timer, participant rule, permission, and in the case subject and result.
• Deleting a variable removes its mappings and permissions. Branch conditions that use it become findings.
• Remove N unused variable(s) removes variables that nothing fills or reads. Select it again to confirm.

When an App variable and a case variable have different types, NIM converts the value where it can and shows a warning.

Built-in variables

NIM fills these read-only variables itself. They are shown greyed on the Variables tab and can be used in prefills, actions, conditions, and the case subject and result. They are always readable, whatever the permissions.

Show built-in variables

Variable	Type	Value
wfInitiatorUserID	number	The NIM user ID of whoever started the case. 0 when the service started it.
wfInitiatorName	string	The login name of whoever started the case.
wfInitiatorEMail	string	The e-mail address of whoever started the case. Empty when there is none.
wfOutcome	string	The label of the line taken by the most recently completed step, such as Approved. Empty until a step ends with an outcome.

Names that start with wf are reserved for the workflow. You cannot declare a case variable with such a name.

Case subject and case result

The Variables tab also holds two text templates. Use Append to insert a {variable} placeholder.

• Case subject: what a case is about, such as Access request for {fullName} to {groupName}. It is shown wherever a case appears in a list, filled in from the case data at that moment. When empty, a case is named by its configuration name and the first eight characters of its case ID.
• Case result: how a case turned out, such as {decision}, or {wfOutcome} for the last outcome. It is shown to the initiator next to the subject. It is empty until the step that writes the variable is done. When the template is empty, no result is shown.

Every participant sees the subject and result. With enforced permissions, NIM warns when they name a variable that a participant may not read.

Validation

The Validation tab lists every finding in a Findings grid with the columns Status, Where, Tab, and Description. The tab title shows the number of findings, such as Validation (3).

Select a description to jump to the tab where you fix it. On the Steps tab, the element is selected, and a panel shows the full message.

• Errors block saving and publishing.
• Warnings block publishing, except two advisories: a send task without a mail template, and a display name that another configuration also uses.

When nothing is left, the tab shows ✓ This configuration is complete; it can be published. For every finding and its fix, see Workflow validation reference.

When the definition changes structurally after you configured it, the configuration shows The workflow has structurally changed since it was configured; check the configuration and save it again. Check each step, then save to clear it.

Related guides

• Participants and permissions — bind performers and control case data access.
• Publish and unpublish — release the validated configuration.

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.