Introduction

Action Scripts are one of the most important tools in a PYXI application design. They are used wherever a developer-defined Action is to be performed – this includes:

• In an Automation – fundamentally, an Automation is the mechanism for triggering the execution of an ActionScript, either against a specific record or, in the case of Overnight Automations, non-record specific where the ActionScript contains the logic to find the records it needs to process.
• In a Step – a Step allows the user to enter information in a Form, then that information is passed to an ActionScript that uses the information, typically to update fields on the record for which the Step was executed, or perhaps to add related records such as transactions, or even to trigger WebHooks, send Emails or whatever else the business need requires.
• In an HomePage Item – an HomePageItem can be used similar to a Step to allow a user to enter information on a Form then process it in an ActionScript. The main difference is that HomePageItems are not specific to a record, whereas Steps are always presented on a specific record. HomePageItems are usually used to provide application-wide functionality, so you would normally expect an ActionScript on an HomePageItem to focus heavily on setting config variables or creating controlling records of some sort.
• In a DataLoad – the DataLoad API call allows for the inclusing of an optional ActionScript to be performed on each Record that is created or updated by the load, and a separate optional ActionScript that is executed on completion of the Data Load. These scripts are included as parameters to the API call and are not otherwise stored anywhere in the PYXI application configuration.

Note that Action Scripts can only be evaluated by Administrators or Developers. Why? Because Action Scripts are not constrained by record add/edit restrictions e.g. allowEditCalcs field of RecordType. For example, you may want a particular record type not to be editable in general through the user interface (or general record update API calls), but only by controlled script update. Use an allowEditCalc to forbid edit in certain, or all, circumstances (a calc of false will do the trick for the latter case). Then, updates can be controlled through Scripts included in Automations or elsewhere, but the application business logic must be carefully designed before such Scripts are implemented.

ActionScript Syntax

All the standard Script Syntax automations apply to ActionScripts. In addition, the following sections discuss additional features relevant only to ActionScripts.

Update the Current Record

You can update any editable field of the record against which the ActionScript is being executed.

The general syntax of a line to update a field is as follows:

Note that, as with the setting of variables in a script, everything to the right of the equals sign is treated as a calculation. If you just put some text there, it will be treated as a variable name or Field name. If you mean the text itself, you must enclose it in quotation marks.

Examples:

Important – the record will be updated once the whole script has been parsed, so any references to existing field names in calculations will always return the existing value on the record regardless of whether they occur before or after a ‘SAVE’ line in the script.

Add a Record

You can add a record of any RecordType that permits it – generally, any built-in record type such as Person, Organisation, and any custom Record Types added to the account.

The general syntax to add a record is as follows:

Note, in particular, that you should NOT put ‘SAVE’ at the beginning of each line that sets a field value of the new record. This is because SAVE deals specifically with updating values on the record against which the script is being evaluated, not on the record which is being added in an ADD RECORD section.

Important – the record will be added once the whole script has been parsed, so you should not attempt to refer to the added record later within the same script, as it will not yet exist.

There is no practical limit to the number of ADD RECORD sections you can include within a single script, and you can, of course, include ADD RECORD sections within control structures such as IF/ELSE and EACH. You can also include IF/ELSE structures inside the ADD RECORD section.

Example

Add a Note to a Record

You can add a note to the record against which the ActionScript is being executed. The general syntax is as follows:

The note will be created with the given title (evaluated as a calculation) then the note text contains all of the following non-control structure lines within the ADD NOTE section up to the END line, evaluated as a template. IF/ELSE and other control structures are respected and processed as normal.

Send an Email

You can send an email using the following general syntax:

The email will be created with the given subject (evaluated as a calculation), sent to the recipient email address generated by the ‘To’ calculation, then the body of the message contains all the following non-control structure lines within the SEND EMAIL section up to the END line, evaluated as a template. IF/ELSE and other control structures are respected and processed as normal.

Example

Call a Webhook

A Webhook is a mechanism to allow your PYXI application to call an external application by sending data to a specific URL. The Webhook itself is defined in a Webhook record, and is identified by its Name.

Use the following general syntax to trigger the calling of a Webhook sending details of the record against which the script is being executed, plus optionally any additional payload data defined in this script section.

Note that each line building up the payload data is evaluated as a calculation, so if you want to specify a straight-forward text value, you must enclose it in quotation marks.

Example

Note that Webhook calls are asynchronous – they happen in the background, not necessarily immediately, and do not return any values for processing. You would normally expect the code of the receiving application to make subsequent API calls back to your PYXI application if there is further action to be taken. See the Webhooks section for a fuller discussion.

Perform a Calculation

By default, if a line of an ActionScript is not understood as one of the specific statements or constructs discussed elsewhere, then it will simply be evaluated as a calculation. It only makes sense to use this facility to execute calculation functions that do something rather than just returning a value. Typical examples include triggerEvent() and setSetting(). See examples below.

Send a User Notification

To send a Notification to the current User, use the following syntax on a single line:

This will create a message to be displayed to the user, being the templateText evaluated as a template.

Example

Trigger an Event

You can trigger an event which will result in any matching Automations being executed i.e. any Automation that includes the event name in its Events field and whose Filter the record passes. Triggering an event from an ActionScript like this is limited in that it does not allow you to pass any data to an event, unlike if you trigger an event externally using the event API call.

To trigger an event on the record against which the script is being evaluated, use the following syntax on a single line:

Alternatively, you can trigger an event on any record that is already saved in a variable, as follows:

Note that a common use-case is to trigger an event for multiple records, as part of a batch-update. Typically, code for this will look similar to the following example:

Set a Persistent Setting

Persistent Settings are applicable to a PYXI account, rather than to a specific record. You can store any text, numeric or logical value in a setting, and can also store a reference to a specific record in the account.

Persistent Settings are normally used to store set-up or status information. They can be set or read using API Calls, and from within the application, can be set using the a line within an ActionScript with the syntax below, then be read anywhere within a calculation or template using the getSetting function.

Note that a Persistent Setting name can be any unique text upto 80 characters long. As variables are normally associated with a particular ‘module’ of functionality, typically provided as an add-on Blueprint, it is good practice to name your settings starting with a unique name that is not likely to conflict with any other modules.

For comprehensive examples on the usage of persistent settings, check out the GDPR Blueprint.

Examples