Chain two rules with a custom event

Rules never set each other off on their own: whatever one rule changes is ignored by the others, so rules can't loop. When you do want one rule to follow another, for example "when a demand goes 30 days overdue, escalate it; when it is escalated, give the Sales Manager a task", you connect them with a custom event. The first rule raises the event when it finishes; the second listens to it.

Before you start

• You need the Create permission on Workflow Rules to add an event type and the Edit permission on Workflow Rules to change the rules. In the default roles only the Administrator has them.
• Both rules must watch the same entity (both on Demand, say), and the event type must be of that entity too. The app refuses a mix.
• Both rules must be your own (custom) rules. System rules can't be changed; clone one first (see Customise a system rule). To build a rule from scratch, see Build and switch on a custom rule.

Steps

1. Open the account menu > Settings > Workflows > Event types (Event types). The page lists the system events, marked with a lock icon, and any custom ones.

2. Click New event type. The panel "New event type" opens, pre-filled with the entity you have filtered on and sort order 100.

3. Fill in the panel and click Add event type:

   • Code (required): capital letters, digits and underscores, starting with a letter and unique in your organization, for example DEMAND_ESCALATED (hint "A–Z, digits, _ ; unique in your organization");
   • Name (required), for example "Demand escalated";
   • Entity (required): the kind of record both rules watch;
   • Description: "Optional; shown to people picking the event for a rule.";
   • Sort order and Active (keep it ticked).

   You see '"<name>" added.' The new event appears without a lock icon, with Rules 0.

4. Open the rule that should run second (Rule). In Trigger, choose On Event and pick your event under Event type (entries read "name (code)"; placeholder "Choose an event type…"). Make sure the rule is Active, then click Save changes. You see '"<name>" saved as version <n>.' and the trigger badge reads On Event.

5. Open the rule that should run first. In the Advanced section ("Chain rules by raising a custom event when this one finishes."), click Show and pick your event under Emits event type. Click Save changes. You see '"<name>" saved as version <n>.'; with the section collapsed it reads "Raises a custom event after the actions run."

6. Let the first rule run on a record (or wait for its trigger). Then open the second rule and click Run history (Runs). Open its latest run with the eye icon: Trigger event shows your code, Trace depth reads 1, and Outbox event links to the event the first rule raised (Outbox; the grid marks it "depth 1" and its panel shows Trace depth 1 and, when the first rule was itself started by an event, a Parent event).

What happens next

• The event is raised only when the first rule succeeds. If the first rule's run ends Errored, the second rule doesn't run. A step that failed with Continue on error ticked still counts as success.
• The event is raised only while someone listens. If no active rule listens to the event when the first rule finishes (the second rule is switched off, or scoped to another project), nothing is raised and nothing is queued for later.
• Chains stop two levels deep. The second rule may raise another custom event for a third rule, but a rule raised beyond that never runs: each listener gets a Blocked run with "Blocked: <CODE> from rule "<name>" would run at trace depth <n> (maximum <m>)". This stops runaway loops.
• The event type now counts its listeners in the Rules column, and it can't be deleted while rules use it.
• To check the second rule without waiting, use Test on it and add the values the event would carry under Event extras.

If something goes wrong

• "The event type belongs to a different entity than the rule." when saving the first rule: the Emits event type list offers custom events of every entity, but the rule may only raise one of its own entity. "A rule can only emit a custom event type" and "A rule cannot emit the event it listens to" have the same fix: pick another custom event of the rule's entity. "Choose the event type this rule listens to" on the second rule: pick the event. The event isn't offered under Event type: it belongs to another entity, or it is inactive. See Rule cannot be saved (trouble.workflows.rule-cannot-be-saved).
• "An event type with this code already exists." or "This code is reserved for the engine's own event types." when you click Add event type: choose another code. See Already exists (trouble.admin.already-exists).
• The second rule never runs: check that the first rule's run ended Success, that the second rule is Active and in scope for the record's project, and that the event type is still Active (making a custom event inactive also stops the first rule raising it). See Investigate a failed automation.
• A run reads Blocked with "Blocked: … would run at trace depth …": the chain is deeper than two levels. Shorten it. See Action failed (trouble.workflows.action-failed).
• "Rules listen to this event type. Deactivate it or change those rules first." when deleting the event type or changing its entity: rules still listen to it or raise it, or recent outbox events refer to it. See Rule cannot be deleted (trouble.workflows.rule-cannot-be-deleted).

Related

• Event types
• Rule
• New rule
• Rules
• Runs
• Outbox
• Build and switch on a custom rule
• Investigate a failed automation