Event based workflow rule – wait for a time or a change, then act¶
An event based workflow rule starts a process for a record when a matching change was saved. The process waits for a point in time that the record stores – a due date, a deadline – or for a further change of the record, runs actions and can repeat. It runs on the server, keeps its state in the database and survives restarts, so a wait of days or weeks is normal. This page describes its settings and behaviour. It is intended for administrators who configure business rules.
1. At a glance¶
| Purpose | Reminders before a due date, escalations after a deadline, follow-ups that repeat until a status changes |
| Starts | When a record was saved with a change that matches one of the triggers and the "Execution Condition" is true |
| Runs | On the server, as the "Identity" of the rule, one process per record |
| Waits for | A point in time computed from the record, a further change of the record, or whichever comes first |
| Related | Event based background action rule (runs right after the save), Scheduled actions (runs on a schedule, not per record), Background processing, Monitoring |
Summary¶
- A process is a chain of processing items: wait for a time, wait for an event, wait for a time or an event, execute an action, jump back to an earlier item.
- Every wait item evaluates its target time when the process reaches it. A wait item that also watches the record follows a date that is moved while the process waits.
- The "Abort Condition" is checked before every item; while it is true, the process ends.
- Everything a process decides is recorded and shown under Monitoring → Background Processes → "Workflow Rules".
When to use which rule¶
| You want | Use |
|---|---|
| Something right after the save | Event based background action rule |
| Something at a time the record stores, or after nothing happened for a while | Event based workflow rule |
| Something at fixed times, for all records at once | Scheduled action |
A scheduled action that looks for due records every night runs for every record every night, and misses a date that was moved between two runs. A background action rule with "Execution Delay (Seconds)" waits a fixed time from the save and loses the job when the server restarts. The time based rule waits per record, follows the date, and survives restarts.
2. Settings¶
The editor has three tabs.
Tab "General"¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Disabled" | The rule does not start new processes; see section 4 for processes that already wait | off |
| "Priority" | Order in which the rules of one save are handled, ascending | 0 |
| "Identity" | The user the process runs as. It decides which records the conditions and the actions may read and write. | required |
| "Max Concurrent Processes" | How many processes of this rule may run for one record at the same time. A start event that matches while the limit is reached is ignored and recorded with the outcome "Ignored". 0: unlimited. |
1 |
| "Max Executions" | How often the process may be started for one record in total, finished processes included; ignored starts do not count. A start beyond the limit is recorded with the outcome "Ignored". 0: unlimited. |
0 |
| "Store Execution Log" | Whether the application log of each action of the process is kept with its entry in the execution history | "Inherit (use the next level)" |
Plus "Display Name", "Description" and "Tags" in the header (see Business rules).
Tab "Start Event"¶
The triggers that start a process, exactly as for the other event based rules: the + adds one, the minus button removes one, any one of them matching starts the process. The event types are described in Business rules, section 6. Below the triggers, the "Execution Condition": an optional condition that has to be true, evaluated against the saved record, for a process to start.
Tab "Process"¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Abort Condition" | Optional condition, evaluated against the record before every item. While it is true, the process ends with the outcome "Aborted". Typical: the record was closed. | empty – never |
| "Processing items" | The chain of items, starting with the first one. See below. | at least one item |
Processing items¶
An item is added with + – at the top for the first item, below every outcome of an item for the one that follows. Each item has a "Name" (shown in the monitoring; give items a jump returns to a name) and, depending on its kind:
| Kind | Settings | Outcomes |
|---|---|---|
| "Wait for Time" | "Target Time": an expression that yields the date and time to wait for, evaluated against the record when the item is reached. "Time Zone": whether that value is local server time (the usual case for date fields) or UTC. | "When the time elapsed" |
| "Wait for Event" | "Triggers": the changes of the record that end the wait, with the same settings as the start event | "When the event occurs" |
| "Wait for Time or Event" | Both of the above, plus "On Event": "Re-evaluate target time" evaluates the target time again when a trigger matches and keeps waiting in the same item; "Continue with 'On event'" leaves the item through its second outcome | "When the time elapsed"; "When the event occurs" only with "Continue with 'On event'" |
| "Execute Action" | "Action": the action to run against the record | "Then" |
| "Jump to Item" | "Jump To": the item to continue with – usually an earlier one, which builds a loop | none |
An outcome without an item ends the process ("Ends the process" is shown there). Removing an item removes everything below it. Adding a new first item puts the existing chain below its first outcome.
Example: a reminder that follows the due date¶
A task has a field Due Date and a field Status. Three days before the due date the assignee should get a reminder; when the due date is moved, the reminder moves with it; when the task is done before, nothing is sent.
| Item | Settings |
|---|---|
| "Wait for Time or Event" – "Wait for reminder date" | "Target Time": Due Date minus 3 days, "Time Zone": Local time. "Triggers": Due Date changes. "On Event": "Re-evaluate target time" |
| below "When the time elapsed": "Execute Action" – "Send reminder" | "Action": the action that sends the mail |
| "Abort Condition" of the rule | Status = "Done" |
With the start event "Due Date changes to any value" the process starts when a due date is entered. Moving the due date does not start a second process: with "Max Concurrent Processes" = 1 the running process gets the change and computes its target time again.
Example: remind every week until done¶
| Item | Settings |
|---|---|
| "Wait for Time or Event" – "Wait" | "Target Time": Reminder Date. "Triggers": Status changes to "Done". "On Event": "Continue with 'On event'" |
| below "When the time elapsed": "Execute Action" – "Remind" | sends the reminder |
| below its "Then": "Execute Action" – "Move reminder date" | sets Reminder Date to Reminder Date plus 7 days |
| below its "Then": "Jump to Item" | "Jump To": "Wait" |
| below "When the event occurs": "Execute Action" – "Thank" | sends a closing mail |
A loop needs a wait on its way round. A jump that reaches itself again through actions only is stopped after 100 items, and the process ends with the outcome "Failed".
3. Behaviour¶
From the save to the first item¶
- While the record is edited, every field change is compared with the start triggers of the rule – no matter whether a user, an action, another rule or the REST API changed the field.
- After the record was saved successfully, nexxcite goes through the matching rules in the order of their "Priority". For each one: a rule that is disabled, has no identity or no item is skipped; the "Execution Condition" is evaluated against the saved record; the limits "Max Concurrent Processes" and "Max Executions" are checked for this record.
- A process is written to the database and advanced right away on the server that saved the record: the "Abort Condition" is checked, and the first item is entered.
A rule starts at most one process per save, however many of its triggers matched.
How a process moves¶
| Item | What happens when it is reached | Continues when |
|---|---|---|
| Wait for time | The target time is evaluated once and stored | The time has passed – within about 10 seconds, on a server that processes scheduled actions |
| Wait for event | The process waits; nothing runs | A matching change of the record is saved – on the server that saved it |
| Wait for time or event | The target time is evaluated and stored, the triggers are watched | Whichever comes first; a matching change either continues with "When the event occurs" or computes the target time again and keeps waiting |
| Execute action | The action runs against the current state of the record, as the "Identity", with the details of the change that started or last continued the process | Right away, when the action succeeded. A failed action ends the process with the outcome "Failed". |
| Jump to item | The target item is entered like any item | Right away |
Before every item the "Abort Condition" is evaluated against the current state of the record; while it is true, the process ends with the outcome "Aborted". An outcome without an item ends the process with "Completed".
Outcomes¶
| Outcome | Meaning |
|---|---|
| Completed | The last item had no follow-up |
| Aborted | The abort condition was true, or the rule was deleted |
| Failed | An action failed, a target time could not be computed, the item the process waited in was removed from the rule, or a loop never waited |
| Cancelled | The record was deleted, or an administrator cancelled the process |
| Ignored | The start event matched, but "Max Concurrent Processes" or "Max Executions" was reached. No process ran; the entry names the limit. A start that the "Execution Condition" prevents is not recorded. |
Errors while a process is advanced¶
If a step throws – the database was unavailable, an expression could not be evaluated – the process is tried again after 1, 5, 15 and 60 minutes. After 5 failed attempts it ends with the outcome "Failed". Each attempt is recorded in the trace of the process.
4. Changing the rule while processes wait¶
| Situation | Effect |
|---|---|
| The rule is disabled | Waiting processes stay exactly where they are. Nothing happens for them until the rule is enabled again; then elapsed times are caught up, and the next matching change continues a process that waits for one. No new processes start. |
| The rule is deleted | Its processes end with the outcome "Aborted" when they would next continue. |
| The rule is edited | Waiting processes continue with the items as they are now. A process whose current item was removed ends with the outcome "Failed". |
| The record is deleted | Its processes end with the outcome "Cancelled". |
5. Timing¶
| Situation | Effect | Remark |
|---|---|---|
| A target time has passed | The process continues within about 10 seconds | Checked by the servers that process scheduled actions (ApplicationServer:ProcessScheduledActions) |
| A target time lies in the past when the item is reached | The process continues right away | For example a reminder date that is already over |
| A matching change is saved | The process continues within seconds, on the server that saved the record | |
| A server stops while it advances a process | Another server takes the process over after about 10 minutes | The state of the process is in the database, nothing is lost |
| Several servers process scheduled actions | Each process is advanced by exactly one of them |
6. Monitoring¶
Admin Studio → Monitoring → Background Processes → "Workflow Rules" lists every waiting process with its rule, record, current item, the time it waits for and its state, and below it the processes that finished with their outcome. A click opens the details: the facts of the process and its trace – every decision it took, with time and server.
| Button | Effect | Permission |
|---|---|---|
| "Open rule" | Opens the rule in its editor | editing business rules |
| "Actions of this process" | Shows the executions of the actions the process ran, in the tab "Executions" | – |
| "Advance now" | Treats the wait time as elapsed and advances the process now. Not offered for a process that waits for an event only. | "Background Job Administration" |
| "Cancel process" | Ends the process with the outcome "Cancelled", after a confirmation | "Background Job Administration" |
The actions a process runs appear in the execution history like every other background action, with the origin "Event based workflow rule".
7. Settings for operation¶
The processes do not need any setting to work. The following values are set in the configuration
of the application (appsettings.json or environment variables).
| Setting | Default | Meaning |
|---|---|---|
RuleProcesses:PollIntervalSeconds |
10 | How often the servers that process scheduled actions look for processes whose wait time has passed |
RuleProcesses:PollBatchSize |
100 | How many due processes one look advances before the next one takes over |
RuleProcesses:StaleClaimMinutes |
10 | After this time, a process a stopped server was advancing is taken over by another server |
RuleProcesses:MaxAttempts |
5 | Attempts to advance a process whose step throws, before it ends with "Failed" |
RuleProcesses:RetryDelayMinutes |
1, 5, 15, 60 | Minutes to wait before each attempt; the last value repeats |
RuleProcesses:LoopLimit |
100 | Items a process may pass without a wait before it is stopped as a loop |
How long finished processes are kept is set in the
global settings
("Keep finished workflow processes for (days)", 0 keeps everything). "Max Executions" is
counted separately and is not affected by it.
8. Frequently asked questions¶
Does a process keep waiting when the server restarts? Yes. The state of every process is in the database. After the restart the servers continue where the processes stand; a target time that passed in the meantime is caught up.
The due date was moved, but the reminder did not move. Why? Only a "Wait for Time or Event" item with a trigger on the date field and "On Event" = "Re-evaluate target time" follows a changed date. A plain "Wait for Time" evaluates the date once, when it is reached.
Can a process react to a change from the REST API or from another rule? Yes. The start event and the triggers of the wait items see every saved change of the record, no matter where it came from.
Can two processes of one rule run for the same record? Only if "Max Concurrent Processes" allows it. With the default of 1, a matching start event while a process runs is ignored – it does not restart the running process.
Where do I see why a process ended? In the trace of the process under Monitoring → Background Processes → "Workflow Rules", in the list of finished processes.