API – Automation – Rules and Events

Rules

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

Rules can be set-up either by adding as individual records, or more typically as part of a Blueprint. See Rules for details of the fields available on a Rule record.

Events

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.

Worked Example

Assume you have set-up a Rule against the Person record type with the following Script:

IF contains(Email, vOldDomain) SAVE Email = left(Email,find("@",Email)) + vNewDomain ENDIF

The Rule’s Events field contains mycustomevent.

Sample Blueprint

[Rule] Name, RecordTypeName, Description, Events, Script EmailDomainUpdate, Person, "Update Domain on Email Address", mycustomevent,<<< IF contains(Email, vOldDomain) SAVE Email = left(Email,find("@",Email)) + vNewDomain ENDIF >>>

Assume that the record ‘Bob Smith’ with ID 12345 has email address bob.smith@defunct.com

Trigger an event with API call as follows:

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "event", "recordurl": "person/12345", "event": "mycustomevent", "data": { "vOldDomain": "defunct.com", "vNewDomain": "newdom.com" } }

Sample Response

{ "success": true }

Bob Smith’s email address will now be bob.smith@newdom.com