Event based background action rule – run an action on the server after the save¶

An event based background action rule runs an action as a background job when a record was saved with a matching change. The user does not wait for it, and it works the same way no matter where the change came from. This page describes its settings and behaviour. It is intended for administrators who configure business rules.

1. At a glance¶


Purpose	Starts an action as a background job after a save in which a trigger matched
Typical use	Send a notification, create or update records in other entities, call an external system, follow-up processing with a delay
Related	Event based UI action rule (runs synchronously in the session), Actions, Background processing

2. Settings¶

The editor has three tabs.

Tab "General"¶

Setting	Meaning	Default / required
"Disabled"	The rule does not run	off
"Priority"	Order in which the jobs of one save are handed to the background processing, ascending	0
"Execute in user context"	"Execute action on behalf of the identity that triggered the event": the job runs as the user who saved the record	off
"Execution Limit"	`None`: new and existing records. `OnlyOnCreation`: only for changes while the record is new. `OnlyOnUpdate`: only for records that already exist. `LimitedNumberOfTimes`: behaves like `None`, see section 5.	`None`
"Max Executions"	How often the rule may run for the same record in total. A matching save after that starts no job and is recorded in the execution history as "Skipped" with the reason. `0` means unlimited. See section 5.	0 (unlimited)
"User"	The user the job runs as. It decides which records the action may read and write. Not available while "Execute in user context" is on.	required unless "Execute in user context" is on

Plus "Display Name", "Description" and "Tags" in the header (see Business rules).

Tab "Triggers"¶

The list of triggers. The + adds one, the minus button removes one. The rule runs when any one of them matches; a rule without triggers never runs. Each trigger has an "Event Type" and, depending on it, a "Field", "From" and "To". The event types are described in Business rules, section 6.

Tab "Action"¶

Setting	Meaning	Default / required
"Execution Condition"	Optional condition. The job is only started while it is true.	empty – always
"Action"	The action that runs as a background job against the saved record	required
"Execution Delay (Seconds)"	Optional expression with a whole number of seconds to wait after the save. Empty, zero or a negative result: the job runs immediately.	empty
"Store Execution Log"	Whether the application log of the run is kept with its entry in the execution history: "Inherit (use the next level)", "Never", "On failure or warnings", "Always"	"Inherit (use the next level)"

3. Behaviour¶

From the change to the job¶

While the record is edited, every field change is compared with the triggers – no matter whether a user, an action, another rule or the REST API changed the field. The "Execution Limit" is checked at this moment. A matching rule is noted.
After the record was saved successfully – after the After Save UI actions – nexxcite goes through the noted rules in the order of their "Priority":
- A rule that has been disabled in the meantime is skipped.
- The "Execution Condition" is evaluated against the saved record. If it is not true, no job is started.
- The user is determined: with "Execute in user context" the user who saved, otherwise "User". Without a user, no job is started.
- The "Execution Delay (Seconds)" is evaluated.
- The job is handed to the background processing.
The job runs the action against the saved record, as the determined user, immediately or after the delay.

If the save fails, no job is started. The noted rules stay noted and run after the next successful save of the same record in the same editing session.

One job per save¶

A rule starts at most one job per save, however many of its triggers matched and however often the field changed. The same rule starts a new job with the next save that matches again.

Data for the action¶

The action receives the details of the change in the special variable "Event Based Action Data", as JSON text: the rule, the field whose change matched first, its old and new value, the user who made the change and the list of all fields changed in this save.

Monitoring¶

Every job is recorded under Admin Studio → Monitoring → Background Processes as a background action that was started by a business rule, with its result and – depending on "Store Execution Log" – its log. All jobs of one save carry the same correlation, so they can be shown together. With "Inherit (use the next level)", the setting of the action applies and then the configuration key ExecutionHistory:LogCaptureMode (default: on failure or warnings). See Monitoring.

4. Examples¶

Welcome mail for a new customer. Entity Customer, trigger "Any Change", "Execution Limit" = OnlyOnCreation, "User" = a technical user "Mail service" with the rights the action needs. The action sends the welcome mail to the address of the customer. It runs once when a new customer is saved for the first time, not on later changes.

Escalation after one hour. Entity Ticket, trigger "Change To Value" on Priority with "To" = Critical, "Execution Delay (Seconds)" = 3600, "Execution Condition" none. The action checks whether the ticket is still unassigned and, if so, notifies the team lead. Because the action reads the ticket when it runs, it sees the state one hour after the save.

5. Limitations¶

LimitedNumberOfTimes behaves like None. The number of runs is limited by "Max Executions" alone, whichever "Execution Limit" is chosen.
"Max Executions" counts every start of the rule for a record, from the moment this version runs – runs before the update are not counted. The count is kept in a table of its own, so neither the retention of the execution history nor a switched-off history resets it; it is removed with the record. Rules saved earlier with a negative value are treated as unlimited.
The "Execution Condition" and the delay are evaluated at the time of the save, not when the job runs. If the condition must hold at that later time, check it again in the action.
Waiting jobs live in the memory of the server. If the server stops before a delayed job ran, the job is lost and shown as "Abandoned" in the execution history.
With "Execute in user context", a save made by a background job or the REST API runs the job as the user of that job or API access.