Build and switch on a custom rule

A workflow rule does something for you when a record changes, on a timetable, or when someone presses a button: notify the accounts team when a booking is created, raise a task for the legal team, email the buyer, call another system. This guide builds a rule, saves it switched off, tries it against a real record, and then switches it on.

Before you start

• You need the Create permission on Workflow Rules to build a rule and the Edit permission on Workflow Rules to switch it on. In the default roles only the Administrator has them. Seeing runs needs the View permission on Workflow Runs.
• You can only automate what you may do yourself. When you save or switch on a rule, each action is checked against your permissions: a Create task action needs the Create permission on Tasks, Close open tasks the Edit permission on Tasks, Generate document the Create permission on Generated Documents, Update field the Edit permission on the record's module, and so on. The rule then acts as you whenever it fires on its own.
• Prepare what the actions will use:
  • an email's wording as a message template (see Design an email template), or write the subject and body inside the action;
  • a document to attach or generate must be Published for the same record type under Document templates;
  • a role named in a notify or task action must exist under Roles & Permissions.
• If a system rule already does most of what you want, clone it instead: see Customise a system rule.

Steps

1. Open the account menu, choose Settings and click the Workflows tab (Workflows); it opens on the first tab you may see. Click Rules (Rules). The page reads "Each rule watches one kind of record, fires on a trigger, checks its conditions and runs its actions in order."
2. Click New rule. The New rule page opens, headed "Automate what happens when records change."
3. In Basics:
   • Name (required, unique, up to 150 characters), for example "Booking created: tell legal";
   • Entity (required): the kind of record the rule watches, such as Booking, Demand or Opportunity. It can't change once the rule is saved;
   • Description, Project scope ("All projects", or one project) and Priority (lower runs first when several rules react to the same thing; 0 by default);
   • untick Active, so the rule does nothing until you have tried it. The header shows the Inactive badge.
4. In Trigger, pick what starts the rule and fill in its extra fields:
   • On Create: "Runs once when a new record is created."
   • On Update: "Runs when a record changes; optionally only when chosen columns change." Tick the Watched columns that matter, or none for every change.
   • On Event: "Runs when a named event of this entity is raised (system or custom)." Choose the Event type, for example BOOKING_CREATED or DEMAND_OVERDUE.
   • Scheduled: set Start date, Time, "Repeat every" (day, week, month or year), the weekdays or the day of the month, and an optional Until. The sentence under it reads, for example, "Occurs every week on Mon at 09:00 from 28 Sep 2026, with no end date · first run 2026-09-28, then for ever". Each firing runs once for every record that meets the conditions.
   • Manual: "A button on the record; the user fills in a small form first." Click Add field for each value the person types (at least one), such as a reason.
5. In Conditions, narrow the records the rule acts on. Click Condition, choose a field (from Columns, Related rows or Context), an operator and a value; use the AND / OR switch and Group to combine tests. The counter reads "<n> conditions". Leave it empty to act on every record the trigger delivers. A Scheduled rule can only compare the record's own columns.
6. In Actions, click Add action. The "Add action" dialog lists Side effects ("Notify people, create tasks, send messages, call other systems.") and Domain operations ("Change records the way a user would; each needs the same permissions."). Pick one and fill in its card, for example for Notify users a Title and the Roles to tell, or for Create task a Title, Assign to and Due in days. Repeat for each step; the actions run in the order shown (Move up / Move down). Tick Continue on error on a step whose failure shouldn't stop the rest, and use Only when… for a condition on one step alone.
7. Click Create rule. You see '"<name>" created.' and the rule's page opens (Rule) with the badges Inactive and v1.
8. Click Test (greyed out with "Save first: the test runs the saved version" while you have unsaved changes). In the dialog, pick a Record; for an On Update rule add Simulate changes, for a Manual rule fill in the Input, for an On Event rule add Event extras if the rule reads them. Click Run dry run. The result shows Matches or Does not match, the badges In scope and Rule inactive, each condition with a green or red dot and the record's actual value, and a verdict per action (Would run, Skipped by conditions, Blocked: missing permissions…). Nothing is sent or changed. Adjust the rule, Save changes and test again until it behaves.
9. Go back to Rules (breadcrumb) and flip the rule's switch in the Active column. You see '"<name>" activated.' (You can also tick Active on the rule's page and click Save changes.)
10. Once the trigger has happened (a record created or changed, the scheduled time passed, or someone pressed the button), open the rule's row menu and choose Run history (Runs). Click the eye icon on a run: the panel shows its status and, under Actions, each step with its result or error.

What happens next

• You own the rule. When it fires on its own it acts as the person who last saved it or flipped its switch, and can only do what that person may do. A Manual rule acts as whoever presses its button instead; it appears in the Workflows menu of the record page (see Run a manual rule from a record).
• Each save of the definition raises the version (v2, v3…); flipping Active alone doesn't. Past runs keep the version they ran under.
• No run means no match. A rule only produces a run when its trigger fired and its conditions held. If nothing appears, use Test on the record.
• Rules don't set each other off. Whatever a rule changes never triggers other rules; to chain two rules, see Chain two rules with a custom event.
• A rule that has run can't be deleted, only switched off, so its runs keep their history.
• Rule changes are recorded in Settings > Audit log; there is no History button on the rule.

If something goes wrong

• Create rule or Save changes is refused with "Fix the problems below before saving.", "A rule needs at least one action or an emitted event", "A workflow rule named '<name>' already exists", "Contact rules are organization-wide", "Choose the event type this rule listens to", "Manual rules need at least one input field.", "conditions: <path> is not a field of <entity>" or an action line such as "SEND_EMAIL needs a message_template_id or both subject and body" or "Role '<name>' does not exist in this organization": fix the field or action card outlined in red. See Rule cannot be saved (trouble.workflows.rule-cannot-be-saved).
• A text with a merge-field mistake is refused as "<field>: <problem> (line <n>)". See Template syntax error (trouble.documents.template-syntax-error).
• "actions[<n>]: <ACTION> needs <permission>" on save, "You do not have permission to do that." on the Active switch, or Blocked: missing permissions in the test: you (or the rule's owner) lack a permission an action needs. Later, runs that end Errored with "permission_revoked: the acting user no longer holds …" have the same cause. See Run errored: permission revoked (trouble.workflows.run-errored-permission-revoked).
• Runs stay Pending, or a yellow bar reads "<reason>: rules are saved and events are staged, but runs stay Pending until it is fixed.": the engine isn't processing. See Runs stay Pending (trouble.workflows.runs-stay-pending) and Investigate a failed automation.
• New rule isn't shown, or the page reads "You do not have permission to view workflow rules. Ask your administrator.": see No access (trouble.admin.no-access).

Related

• Workflows
• Rules
• New rule
• Rule
• Event types
• Message templates
• Runs
• Customise a system rule
• Design an email template and use it in a rule
• Chain two rules with a custom event
• Put demand, payout and revenue runs on a schedule
• Run a manual rule from a record
• Investigate a failed automation