API – Automation – Rules and Events
Rules are one of the key building blocks of automation of applications and business logic using PYXI.
The concept of a Rule is straightforward – it is an ActionScript that is (usually) applied against a specific record when something (an ‘event’) happens. Events are discussed further below, but these basically comprise the built-in events ‘add’ and ‘edit’, plus any custom events.
There is also the special case of setting a Rule to run overnight. In this case, a Rule is either evaluated against every record of a particular record type (subject to an optional Filter), or if no record type is specified, the Rule is evaluated once against the whole account. In this latter case, the assumption is that the Rule’s script is designed to select the records it acts against, or updates account-wide configuration settings or similar.
Rules can be 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.
Setting up a Rule
Events occur against an individual record. Events trigger Rules.
The following events are triggered by standard PYXI application logic:
- add – triggered immediately after a record has been added
- edit – triggered immediately after an existing record has been edited
- email – triggered after an incoming email has been attached to a record. In this case, the event receives the EmailIn record in variable Email and the Note record in variable Note
Events can also be triggered with the event API call. An event can be given any alpha-numeric name (subject to a 30-character length restriction) – all Rules that have this event within their Events field will be triggered. Note that the Rule’s Events field itself is restricted to 30 characters – you should usually keep event names much shorter in case you ever need to flag a Rule as triggered by multiple event names.
Events can pass data to any of the Rules which they trigger. Specifically, the data becomes input data to the Action Script stored on the Rule record.
Note that there is no explicit Event record type that needs setting up. If an event name is triggered for which no Rule has been set-up, nothing happens, but equally no error is generated.
Assume you have set-up a Rule against the Person record type with the following Script:
The Rule’s Events field contains mycustomevent.
Assume that the record ‘Bob Smith’ with ID 12345 has email address email@example.com
Trigger an event with API call as follows:
Bob Smith’s email address will now be firstname.lastname@example.org
Other API Help Pages
ActionsRead a Record | Update a Record | Add a Record | List Records | Evaluate a Template | Execute an Action Script | Apply a Blueprint | Get a Blueprint | Add a File | Get a File | Get/Set a Config Value | Get Category Values | Get Group Memberships of a User | Get Members of a Group | Load Data | Get Metadata for a Record Type | Get Metadata on Calculation Functions | Trigger an Event | Get Usage Statistics | Validate a Calculation | Validate a Filter Expression
Discussion TopicsLinking Records | Automation – Rules and Events
Return to Developer Help