Rules are attached to a Record Type and contain an ActionScript that is evaluated against a record. A Rule is triggered against a record in the following circumstances, depending on the settings on the Rule:
- When a new record is added (the Rule is run after the record has been added). Note that it does not matter how the record was added – through the user interface, via data load, API call or by an ActionScript. The Rule will only be triggered if the record matches the Filter Condition set on the Rule.
- When a record is edited (the Rule is run after the changes from the edit). Note that it does not matter how the record was added – through the user interface, via data load, API call or by an ActionScript. The Rule will only be triggered if the record matches the Filter Condition set on the Rule.
- When a custom event is triggered through an API call or using an ActionScript. If the event name is included in the event names defined on the Rule, then the Rule will be triggered if the record matches the Filter Condition set on the Rule. For further discussion and worked examples, see Automation using Rules and Events.
- Overnight, if the Rule’s isRunOvernight flag is set and the record matches the Filter Condition set on the Rule.
There is also a special case for overnight rules. If no record type is specified, the Rule is evaluated once against the whole account. In this case, the assumption is that the Rule’s ActionScript is designed to select the records it acts against, or updates account-wide configuration settings or similar.
Rules are often used to set values such as Status flags that may require more complex logic than can be sensibly included as a DefaultValueCalc in a Field.
Rules effectively provide the mechanism for a ‘calculate and store’ approach to a Field, compared with a straightforward calculated field. Calculated fields are not stored, so their values cannot be used in Filter conditions, and they can affect performance if large numbers of records are being read e.g. to generate a report. Instead, consider writing a Rule and using it to save the value to a Field. In this case, you would normally expect to set the Field flag isUserEditable to false, which will ensure that the field value cannot be edited manually in the user interface.
A Rule is created by adding a Rule record, which contains the following fields:
|Name *||Name||text||Maximum length – 60 characters|
|RecordTypeName||Record Type||recordtype||The Record Type of records on which this Rule will act. If left blank, the rule will be applied against the overall account. Note that this only makes sense for a rule flagged as isRunOvernight and for which the script is written not to rely on being owned by a single record. Typically such a script will either work on multiple records using EACH loop syntax, update account-level configuration settings or do other non-record-specific logic such as creating Cohorts.|
|Script *||Action Script||actionscript||This script is applied to the record when it is triggered, or to each record in turn for overnight scripts, always provided that the record matches the Filter condition.|
|Filter||Filter||text||Optional Filter expression – leave blank to have the rule evaluated against any record (which also means against every record in the case of an Overnight Rule). This rule will be applied only to records that match the Filter condition. This includes newly added records – the Filter will be applied against the record after it is initially created but before the Rule is applied.|
|Events||Triggering Events||text||An optional comma-separated list of event names that trigger this rule. As standard, these include add and edit, triggered when
a record is added or edited; but events can be given custom-names and triggered by API call to provide any level of script behaviour as part
of integration with other applications.|
Maximum length – 30 characters
|isRunOvernight||Run Overnight?||logical||Apply this rule to all records that match the Filter, overnight. Typically you would use this for Rules that consider states that change over time e.g. changing a status field to Overdue, or generating a new record after the passage of time for recurring events such as a review process.|