Workflow runs and the outbox

An outbox event is the note the system writes to itself when something happens that a workflow rule listens to: "booking BK-2026-27-00007 was created at 11:02 by Kavita". A workflow run is what one rule did about one such event (or about one schedule match, or one press of a manual button): the record it worked on, each action in order with its outcome, and the result. The outbox and the runs together are the audit trail of your automation, and the place you go when something did not happen.

How it works in NirmaanOne

The outbox: from a change to an event

1. When a record is created or changed, or a business step happens (a demand is issued, a payment clears, an offer is signed), the app checks whether any active rule of your organization listens to it: the right kind of record, the right trigger or event type, the rule's project (if scoped), and, for On Update rules with watched columns, one of those columns actually changed. Only then is an outbox event written. If no rule listens, nothing is recorded.
2. The event is written in the same transaction as the change itself. If the change fails, there is no event; if the change is saved, the event cannot be lost. It carries a snapshot of the record as it stands after the change, the changed columns with old and new values, any extra details of the event (days overdue, the offer's side, the stage it came from), who did it and the Origin: api for a user's change, scheduler for the daily checks and scheduled rules, workflow for an event emitted by another rule.
3. Every 10 seconds the automation picks up Pending events, and a change also nudges it at once, so most events move within a second or two. The event is then claimed and processed.

An event's Status moves Pending → Dispatched (handed over) → Processing (taken up) → Processed. An event stuck in Dispatched or Processing for 30 minutes is handed over again; after 5 attempts without success it becomes Failed with "not processed after 5 dispatches". An error during processing also marks it Failed with the error. Requeue (the Edit permission on Workflow Rules) puts a Failed event back to Pending with the attempt count reset; only Failed events can be requeued. Processed events are deleted 30 days after processing, at 03:30 each night; runs are kept.

Changes made by rules themselves never produce outbox events, so a rule cannot set off other rules by accident. The one deliberate exception is a rule's Emits event type, which stages a custom event at Trace depth one higher than the run that emitted it.

Runs: one per rule that matches

When the engine processes an event it finds the active rules that listen to it, in priority order, evaluates each rule's conditions against the record, and creates one run per rule whose conditions hold. A rule whose conditions fail gets no run at all: nothing is recorded, and the event's panel lists only the runs that were created ("No rule listened to this event." when there were none).

A run records the rule and its version at the time, the record, the trigger event, the trace depth, when it was queued, started and finished, the manual form input if any, and one action run per action:

• Actions run strictly in order. Each action run is written before it starts, then marked Success with its result (the users notified, the task created, the addresses mailed, the run number of a demand run…), Errored with the error text, or Skipped when its Only when… block was false. Inactive actions are not recorded.
• A domain operation (cancelling a booking, creating a demand run…) is saved together with the change it made, so it is never half done. If the engine is interrupted in the middle of one, the action is marked "Interrupted while the operation was running; verify the result before retrying" and the run ends Errored, so nothing is silently repeated.
• Results of earlier actions are available to later ones, and to their Only when… conditions.

The run's own Status:

• Pending: created by an event, a schedule match, a manual start or a retry, waiting to be picked up ("Waiting to be picked up.").
• Running: the actions are being executed.
• Success: every active action finished or was skipped. If an action with Continue on error failed, the run is still Success and notes "1 action(s) failed and were skipped: …".
• Errored: an action without Continue on error failed ("SEND_EMAIL failed: no_recipients: No valid email address after rendering the recipients"), the record no longer exists ("The entity no longer exists"), a domain operation was interrupted, or the acting user no longer holds a permission the action needs ("permission_revoked: the acting user no longer holds …").
• Blocked: the run was never started because an emitted event would have gone deeper than two levels of chaining: "Blocked: <event> from rule "<name>" would run at trace depth 3 (maximum 2)".

Every run acts as a user: the rule's owner for event and scheduled runs, the person who pressed the button for manual runs. See the rule owner.

Retrying

Retry on an Errored run (the Edit permission on Workflow Runs) puts the run and its errored actions back to Pending and queues it again ("Retry queued; the run resumes at the first action that did not finish."). Actions already marked Success or Skipped are not repeated, so a notification is not sent twice. The rule must still be active ("This rule is inactive.") and only Errored runs can be retried ("Only errored runs can be retried."). Fix the cause first: add the missing email address, publish the document template, restore the permission.

Manual runs

A run started from a record's Workflows menu is queued at once, and the progress dialog follows it ("The engine is working on it…", "Finished in …", "Finished with an error."). If the engine was not reachable at that moment, the run is picked up on the next sweep, one minute after it was created.

When nothing moves

If automation is switched off or its queue or processing is down, rules still save and events are still staged, but events wait as Pending in the outbox (and manual runs as Pending runs) until it is fixed; nothing is lost. Administrators (the Edit permission on Workflow Rules) see the banner on every Workflows tab and the Health tab's engine, broker and processing cards; other users only notice runs that never finish.

Writing the event with the change, and one run per rule with one row per action, is what makes the automation trustworthy: nothing fires for a change that was not saved, nothing that fired is lost, and a failure tells you exactly which step of which rule stopped, on which record, and why.

Example

On 3 Oct 2026 at 11:02:17 Kavita, a Sales Executive at Sunrise Developers LLP, completes the booking wizard for Unit B-1203, Sunrise Heights: booking BK-2026-27-00007 for Mr Rohan Mehta at an agreed consideration of ₹2,35,00,000, token ₹5,00,000. Two active rules listen to Booking created in that project: the seeded "Booking created: accounts and legal (system)" and the custom "High-value booking: finance sign-off" (agreed amount ≥ ₹2,00,00,000). The seeded "Booking created: welcome mail with allotment letter (system)" is switched off, so it is not a listener.

1. The booking is saved. In the same transaction one outbox event is written: Booking created, record BK-2026-27-00007, origin api, actor Kavita, trace depth 0, status Pending.
2. At 11:02:18 it is handed over: Dispatched. The automation claims it: Processing.
3. The engine evaluates the two rules. Both match (₹2,35,00,000 ≥ ₹2,00,00,000 for the second), so two runs are created, Pending, in priority order, then executed:
   • Run A ("Booking created: accounts and legal", version 1, acting as the organization's administrator): action 1 Notify users notifies the two Accountants and one Legal & Documentation user, result count: 3; action 2 Create task creates "Prepare agreement for booking BK-2026-27-00007" for the Legal & Documentation member with the fewest open tasks, due 10 Oct 2026. Both Success; the run ends Success at 11:02:19, duration 0.4 s.
   • Run B ("High-value booking: finance sign-off", version 1, acting as Priya): action 1 notifies both Finance Leads, count: 2; action 2's Only when… actions.0.count > 0 holds, so the task "Sign off booking BK-2026-27-00007" goes to Meera, due 6 Oct 2026. Success.
4. The event becomes Processed at 11:02:19. Its panel lists both runs; each run's panel links back to the event. The booking page's Tasks card shows the two tasks, and the rule list's Last run column shows Success, "just now", for both rules.

Now suppose Run B had a third action, Send email to {{ contact.email }} using the Booking confirmation template, and Mr Mehta's contact had no email address. Actions 1 and 2 finish as above; action 3 fails with "no_recipients: No valid email address after rendering the recipients"; the run ends Errored with "SEND_EMAIL failed: no_recipients: …". The event is still Processed: the failure belongs to the run, not the event. An accountant adds the email address to the contact; an administrator opens the run and presses Retry. The run goes back to Pending, is picked up within seconds, skips actions 1 and 2 (already Success), sends the email, and ends Success. Nobody was notified twice and no second task was created.

If instead processing had been stopped from 11:00 to 11:45, the booking would still have been saved with its event, which would simply wait as Pending in the outbox; after two minutes the Health tab's Processing card would read "Backlog is stuck". When it restarts, the automation hands the event over and the two runs are created and executed as above, 43 minutes late but complete. Nothing needs to be requeued, because the event never failed.

Where you see it

• Runs: every run, its actions, results and errors, and Retry.
• Outbox: every staged event, its payload, the runs it produced, and Requeue.
• Health: outbox and run counts per status, the oldest pending event, and whether automation, its queue and processing are up.
• Workflows: the engine banner shown when runs would stay Pending.
• Rules and Rule: the Last run column and Run history.
• Event types: the events that can be staged.
• Booking and the other record pages with a Workflows menu: manual runs and their progress dialog.
• Tasks and Notifications: what successful runs leave behind.

Related

• Workflow rules, conditions, actions and the rule owner
• Triggers and event types
• System rules and starter templates
• Message templates