Workflow definitions
Workflows · Definitions
Draw the process once—its steps, branches, and roles—and prove it can always finish before anybody configures data or people.
A workflow definition is the drawing of a process. It holds the steps, their order, the branches and merges, and the participant names on the steps. It does not hold data, Apps, conditions, or people: those belong to the workflow configuration, so one drawing can be configured several times.
Manage definitionsDirect link to Manage definitions
Go to Configuration → Workflows and open the Definitions tab. The grid lists every definition by Definition name.
| Task | How |
|---|---|
| Add a definition | Select Add, enter a Definition name, and select Create. The designer opens on the new, empty drawing. |
| Edit a definition | Select the edit icon (Edit the definition). |
| Rename a definition | Select the pen icon (Rename the definition), or edit the name in the grid. Configurations follow the new name automatically. |
| Copy a definition | Select the copy icon (Copy the definition). |
| Export a definition | Select the export icon (Export the definition to a JSON file). NIM downloads <name>.json. |
| Import a definition | Select Import, choose a .json file, confirm or change the suggested Definition name, and select Import. An import never overwrites an existing definition. |
| Delete definitions | Select the delete icon (Delete the definition). You can select several rows and delete them together. |
NIM refuses to delete a definition while one of its configurations still has cases under way: Workflow 'X' cannot be deleted: configuration 'Y' still has N case(s) under way. Finish or delete those first.
The designerDirect link to The designer
The designer opens with the definition name in the top bar. It has these parts:
- Shapes tab (left): the palette. Drag an element onto the canvas.
- Props tab (left): the properties of the selected element, such as its participant or a line's meaning.
- Grid checkbox: shows a positioning grid. It only affects the view.
- Workflow menu: Validate and Simulate. See Validate the definition and Simulate the definition.
- Save: stores the drawing. The button shows Save * while there are unsaved changes.
- Exit workflow: returns to the Workflows page.
Draw the flowDirect link to Draw the flow
- Drag a start event onto the canvas.
- Right-click the start event and use Add to add the next element: a task, a gateway, an event, or an end event. NIM places it on a free side and connects it with a sequence flow.
- Keep growing the flow from the last element, or drag elements from the Shapes tab and connect them yourself.
- Finish every path with an end event.
NIM numbers each new element with a prefix that names its kind, such as userTask01, service01, or choice01. Rename an element by editing its label. Labels of flow elements must be unique within the definition, because the label identifies the step.
Sequence flowsDirect link to Sequence flows
Connect two shapes to draw a sequence flow. In a workflow definition every connector is a sequence flow. The single arrowhead sets the direction.
The text on a sequence flow that leaves a gateway is the branch label, such as Approved or Rejected. When a step ends with an outcome, NIM takes the branch whose label matches that outcome. Matching ignores case. The words true, yes, and 1 and false, no, and 0 count as booleans.
Branch conditions are not drawn in the definition. You configure them on the gateway in the configuration.
This pattern uses one branch for approval and one for refusal. See Approve before provisioning for the configuration checklist.
Meaning of a lineDirect link to Meaning of a line
Select a sequence flow and set meaning on the Props tab to positive, negative, or none. The meaning tells NIM which branch is the approval and which is the refusal:
- A task list with fixed Approve and Reject buttons enables them based on the meaning.
- An outcome of
trueorfalseselects the line marked positive or negative when no label speaks boolean. - A cancelling join needs it on its lines: see Cancelling join.
- A refusal does not need to deliver required case data. See Required values and refusals.
A label that already speaks boolean (yes, no, true, false) needs no meaning. A meaning is only valid on the outgoing lines of an exclusive gateway and on the lines into and out of a cancelling join; anywhere else it is ignored with a warning.
Elements and BPMNDirect link to Elements and BPMN
The designer uses the shapes and symbols of BPMN 2.0, the standard notation for business processes. If you know BPMN, the drawing reads the same way. NIM supports the subset of BPMN that it can run reliably.
For a symbol guide, illustrated process patterns, and links to the OMG standard, see the BPMN reference.
Supported elementsDirect link to Supported elements
Show supported BPMN elements
| Palette name | BPMN element | What it does in a case |
|---|---|---|
| start event | Start event (thin circle) | Where a case begins. A definition has exactly one. In the configuration, the start event names the App that serves as the start form. |
| end event | End event (thick circle) | Where a path ends. The case is complete when every token has reached an end event. |
| user task | User task (rectangle, person icon) | Work done by a person in a NIM App. The case waits until a performer completes it, usually with an outcome. |
| service task | Service task (rectangle, gear icon) | Work done by the NIM service, such as running a target system function or a script. No person is involved. |
| send task | Send task (rectangle, paper-plane icon) | Mails the participant of the task and continues. The mail is the template coupled to the step's notification event. |
| timer event | Intermediate timer event (double circle, clock) | Waits for a duration or for a date held in a case variable. |
| message event | Intermediate message event (double circle, envelope) | Waits until its participant sends the message, for example from a task list. |
| exclusive gateway | Exclusive gateway (diamond, ×) | Splits the flow into branches of which exactly one is taken, or merges alternative branches. |
| parallel gateway | Parallel gateway (diamond, +) | Splits the flow into branches that all run at the same time, or waits until all of them have arrived. |
| event gateway | Event-based gateway (diamond, pentagon) | Waits for whichever event comes first. Every branch must start with a timer event or a message event. The other branches are dropped. |
| cancelling join | Complex gateway (diamond, asterisk) | Merges the branches of a parallel gateway, but a branch that means negative cancels the others. See Cancelling join. |
| icon, line, text | — | Decoration only. They do not take part in the process. |
Boundary eventsDirect link to Boundary events
A boundary event sits on the border of a task and reacts while that task is waiting. Right-click a user task or service task and choose Boundary event, then one of:
- timer: when the moment comes, the task is withdrawn and the case continues on the boundary event's path. Use it for a deadline or an escalation.
- message: when the participant sends the message, the task is withdrawn. Use it to let the initiator withdraw a request that waits for approval.
- timer, not interrupting: when the moment comes, the boundary path runs as well, and the task stays available. Use it for a reminder step.
- message, not interrupting: the same, triggered by a message.
The boundary event moves and is deleted together with its task. You can change interrupting later on the Props tab. A task can have at most one non-interrupting boundary event, and the path of a non-interrupting boundary event must reach its own end event.
Use this pattern for a single reminder. See Remind without withdrawing the task for the timer and notification settings.
A boundary event on a service task can never occur, because the NIM service runs a service task to completion. NIM warns about it.
Cancelling joinDirect link to Cancelling join
A cancelling join merges the branches of one parallel gateway, like a parallel join, but it does not always wait for every branch. Use it for parallel approvals where one refusal is enough:
- Split with a parallel gateway into one branch per approver.
- After each approval step, add an exclusive gateway with an approved line and a rejected line.
- Lead the lines into a cancelling join. Set the meaning of each rejected line to negative.
- Give the cancelling join exactly two outgoing lines: one with meaning positive (every branch arrived approved) and one with meaning negative (a branch cancelled the others).
When the first approver rejects, NIM immediately withdraws the open steps of the other approvers and continues on the negative line.
Every branch between the parallel gateway and the cancelling join must end in the join. A branch cannot contain another parallel gateway, another cancelling join, or a non-interrupting boundary event.
What is not supportedDirect link to What is not supported
Show unsupported BPMN constructs
The following BPMN constructs are not available in NIM workflow definitions:
- Inclusive gateways, and complex gateways used as a split
- Script tasks, receive tasks, business rule tasks, and generic tasks
- Sub-processes and call activities
- Pools, lanes, and message flows
- More than one start event
- Implicit splits and merges: a task has exactly one incoming and one outgoing flow, so use a gateway to branch or merge
- Boundary events on anything other than a user task or service task
ParticipantsDirect link to Participants
A participant is a role name on a step, such as Manager or Approver. It is not a person: the configuration binds it to NIM users or groups, so one drawing can be configured with different people. NIM does not use pools or lanes for roles.
Set the participant on the Props tab with the participant property:
Show participant roles
| Element | The participant is |
|---|---|
| user task | Who performs the task |
| send task | Who the message is sent to |
| message event (intermediate or boundary) | Who sends the message |
On other elements a participant is ignored with a warning.
The picker offers the standard names below, then the names already used in the drawing. You can also type a name of your own. Names ignore case and are limited to 64 characters.
Show standard participant names
| Standard name | Meaning |
|---|---|
| Initiator | Whoever started the case. NIM resolves it itself, so it is never bound to users or groups. |
| Requester | On whose behalf the request is made. Usually the initiator, but not when a service desk files it for someone else. |
| Subject | Who the request is about: the new hire, or the person whose access changes. |
| Manager | The manager of the subject, unless the configuration says otherwise. |
| ResourceOwner | Who is accountable for what is being requested: the application, the group, or the data. |
| Approver | Who says yes or no. Name several approvers after what they approve, not after their order. |
| Reviewer | Who checks the content without deciding on access. |
| Fulfiller | Who performs by hand a step that no system can do. |
Name a participant on every user task, send task, and message event. A step without a participant cannot be handed to anybody. To learn how participants are bound to users and groups, see Participants and permissions.
Validate the definitionDirect link to Validate the definition
Select Workflow → Validate. A floating Workflow validation panel lists the findings. Each finding is marked as an error or a warning. The shapes involved are colored red (error) or orange (warning); select a finding to color only its shapes. Select ↻ Validate to check again after a change.
Validation checks two things:
- The drawing. Can NIM turn it into a runnable process? Examples: a flow without an arrowhead, a task with two incoming flows, a missing start or end event, duplicate labels, or a misplaced boundary event.
- Soundness. Can every case always finish? NIM explores every reachable state of the process. It reports a deadlock (nothing can continue while the case is not finished), a step that can never run, a token left behind when the case ends, and branches that meet where only one was expected (typically a parallel split merged with an exclusive gateway).
The panel header summarizes the result:
| Header | Meaning |
|---|---|
| The workflow is valid and sound. | No findings. |
| The workflow is sound; see the findings below. | Only warnings. |
| The workflow is NOT sound; it is still stored on save. | The process can deadlock or strand a case. Fix it before you publish a configuration. |
| N error(s) - the workflow will NOT be updated on save. | The drawing cannot be turned into a process. |
For every finding and its fix, see Workflow validation reference.
What happens on saveDirect link to What happens on save
Select Save to store the drawing. NIM then derives the runnable process from it:
- On success, NIM reports Workflow 'X' generated (version N). The version only goes up when the structure changes. Moving or restyling shapes does not change it.
- When the drawing has errors, the drawing is still saved, but NIM keeps the previously generated process: Diagram saved, but the workflow was not generated: N error(s). Use Validate for details.
Saving a definition never changes a running case. Cases run on a published, frozen version of their configuration. After a structural change, the configurations of the definition show the warning The workflow has structurally changed since it was configured. Open them, check them, save them, and publish again.
Simulate the definitionDirect link to Simulate the definition
Select Workflow → Simulate to walk through the process by hand. Nothing is stored, and no data, Apps, or people are involved.
The floating Workflow simulation panel shows:
- Enabled steps — click to fire: the steps that can run now, each with a badge for what triggers it (service, user, send, timer, message). Click a step to fire it. Hover over a step to preview it on the canvas.
- Tokens: the lines on which the case currently waits.
- History: the steps fired so far. Steps marked auto are gateways that settled by themselves.
On the canvas, tokens are green, enabled steps blue, and the hovered step purple. Gateways fire automatically. At an exclusive gateway you pick the branch yourself, because the simulation evaluates no data or conditions.
Use ↩ Back to undo the last step and ↻ Restart to start over on the current drawing. The panel header tells you the state: Running, Completed: every token reached an end event., or Stuck: nothing can fire while the case is not finished. A simulation cannot start while the drawing has errors.
Fire each branch of each gateway at least once, including timers and messages on boundary events. A path that gets Stuck in the simulation would also strand a real case.
Related guidesDirect link to Related guides
- BPMN reference — understand symbols, gateways, and common process patterns.
- Workflow configurations — connect the drawing to Apps, data, and routing.
- Validation reference — look up designer findings and their fixes.