Rhythm gives you two ways to describe logic, such as "members in Texas who joined before this month." A rule set lets you build conditions from drop-downs. An expression is a short formula you type, such as contact.first_name == "Maria". You save either one with the setting it belongs to, and Rhythm evaluates it later against a real record.
Why There Are Two Ways
Use rule sets for most yes-or-no logic when you do not want to write a formula. You choose a field, a comparison, and a value, and the editor shows only choices that fit that field. Use expressions when drop-down rows cannot describe the logic you need, or when the screen needs a calculated value instead of a yes-or-no answer. For example, a calculated field needs a formula that produces the field's new value.
Rule Sets
A rule set is a list of conditions joined by All or Any. In the editor, the rule reads like a sentence: All (or Any) of the following conditions are true:, with the matching conditions indented below.
- All means every condition must be true.
- Any means at least one condition must be true.
- Add Condition adds another row. Add Group adds a nested group with its own All or Any, so you can say "all of these, and any one of those."
Each condition has three parts: the fact you are testing, the operator Rhythm uses to compare it, and the value to compare against. For example: State equals TX.
After you choose a fact, the editor shows only operators that match that field's data type. It then shows the right value box for that field, such as text, a number, Yes or No, a list of allowed values, a date, a record look-up, or a multi-line box for is in list with one value per line. Conditions that use is blank or is not blank do not need a value. If you type a date directly into an equals condition instead of using the picker, enter it as YYYY-MM-DD.
When Rhythm shows a saved rule set as read-only, it displays the rule as an indented sentence, such as "All of the following are true: State equals TX".
Where You Meet the Rule Set Editor
- Query criteria, in the query designer.
- Web forms, when you choose the next page (conditional transitions), show or hide a component (conditional visibility), or raise a custom error.
- Directories, for filter rules and the rule that chooses which downstream members a directory entry includes.
- Membership applications, in the Matching conditions: of an order generation rule, which decides which package to assign.
A custom field can also store advanced rules, in the same rule format, that say when the custom field is required. See Custom Fields Explained.
Which Fields a Rule Can Test
You can choose only the facts supplied by the screen you are using. Each screen builds its own list, so a field that appears in a query can be missing from a form rule, or the other way around.
- Forms offer the record type's standard fields and custom fields, grouped under Form Data.
- Queries use the query designer's own list for each record type.
Only fields that fit one of five data types become facts: text, number, yes/no, list, and date. Other standard field types are left out.
| Custom field type | Treated in rules as |
|---|---|
| Number, Currency, Percent | Number |
| Picklist (Multi-Select), Checkboxes | List |
| Yes/No | Yes/no |
| Every other type, including Date | Text |
For standard fields, text with a date format is treated as a date. A Date custom field is treated as text, so it gets text operators and no relative-date option.
If the field you need is not offered, check whether the place you are configuring also accepts an expression. This comes up most often with a contact's address. Address components remain selectable in queries across applications, but Advanced Rules & Logic does not offer them as facts. An expression can reference an address component that the rule editor cannot; a later capability may offer another way to do this.
On a contact form, field-group conditional visibility cannot be driven by membership type through either the rule editor or a custom expression, because that data is not available there.
Relative Dates
A date condition can compare against a fixed date or a relative date. Relative dates keep the rule current each time it runs. When a screen allows relative dates, a clock icon titled Toggle relative date appears next to a date value. Click it to replace the date picker with a phrase such as "10 weeks before the beginning of the month".
The phrase includes a number, a unit, a position (before, after, or on), and what the date is relative to. Each screen names its own reference date. The query designer calls it the query execution date, and a directory's downstream rule calls it the current date. The options are listed in Expression Functions and Relative Dates.
Saved dates appear in your browser's time zone, so staff in another time zone can see the same stored date as a different day.
Expressions
You type an expression in the expression editor, which is a code box with line numbers. Some screens show a Click here for help with writing this expression. link above it. Places that use expressions include:
- Calculated fields: Calculation Expression: produces the value. If you select Use an expression to determine when this field calculation should be performed, Conditional Evaluation Expression: decides, record by record, whether the calculation runs.
- Bulk operations, when you choose records by expression.
- Directories, where the downstream-member filter can be an expression (Enter the expression below:). A member who has opted out of the directory is excluded regardless of what the filter expression says.
- Web forms: form hooks, custom errors, conditional transitions, and conditional visibility.
- Custom field default values, where the Javascript Web Hook: mode is expression or Web + Expression.
In the calculated field dialog, the merge-field chooser helps you find field names. When you choose a field, Rhythm copies its name to your clipboard and shows Copied field to the clipboard. Paste that field name into the expression.
What the Editor's Check Tells You
On screens that test expressions, the editor runs your expression against a sample record as you type. It then shows either This expression is valid. or an error that starts Invalid expression provided for, followed by the reason. Treat the green message as guidance, not a guarantee:
- The editor does not check whether the formula returns the kind of value the screen expects. A formula that returns text where yes or no is expected still passes.
- A formula that refers to a field missing from the sample record can fail the check, even though it would work on a real record.
- In the calculated field dialog, This expression is valid. appears for any text you type.
What Happens When Rhythm Evaluates Them
- Forms evaluate their conditions in the browser of the person filling in the form, as they go.
- Queries evaluate their criteria on the server when the query runs. Forms and queries use different evaluators, so test a condition in the place where you will use it.
- Calculated fields run each time a record is saved, in the order the rules are listed. When a conditional expression is false for a record, Rhythm skips that rule for that record. Rhythm does not test the condition when you save the rule, so you will see a mistake only when records are saved.
Warning
Test a new calculated field on one record before you rely on it. Rhythm saves the rule even if its expression is wrong.
Limits
- Finish the required parts of each condition before you add another. Add Condition and Add Group stay disabled until every row at that level is complete, and the screen does not say why.
- You can nest groups to any depth. You can save an empty rule set.
- When you remove a row or group, the change takes effect at once with no prompt.
- A date value and a record look-up are not required. You can save a condition without one.
- matches pattern compares text with a pattern that you write. Rhythm does not check that the pattern is valid. To test only whether a field has a value, is not blank is clearer than a pattern. If you come across a pattern such as
(.|\s)*\S(.|\s)*, read it as a "has at least one non-whitespace character" test, which is a not-empty check written as a pattern. - If a condition uses a field that is later removed from the list, saving that rule set fails until you delete the row.
- To match more than one value on a multi-select or checkbox field, add each value as its own condition inside an Any group. Selecting several values in a single condition does not do the same thing.
Example
A directory should include members in Texas who are either students or joined recently:
- All of the following conditions are true:
StateequalsTX- Any of the following conditions are true:
Membership TypeequalsStudentJoin Dateis greater than10 weeks before the current date
In expression form, a single test looks like contact.first_name == "Maria": a field path, a comparison, and a quoted text value.
For more on form logic, see Form Hooks and Expressions and How a Form Behaves for the Person Filling It In. For query operators, see Query Criteria and Filter Operators.