Scripts

Introduction to Scripts

Scripts are used in many places in PYXI. These include:

• Action Scripts – these result in actions taking place e.g. updating a record, adding records, sending emails etc. They are the backbone of Automations and, optionally, Steps and User Actions
• Form Scripts – these are used to set out a Form for user input, and can used in Steps and User Actions. A Form Script is typically paired with an Action Script that describes what to do with the information entered on the Form. Steps and User Actions usually have both a Form Script and an Action Script working in tandem
• Template Scripts – these are used to set out information for display. They are the backbone of Pages, and are also used for purposes such as defining the exact information displayed by each record in a Column View, or for adding customised information to other views such as the Funnel View
• View Scripts – these are used to define a View. Views (such as Column and Funnel views) require various parameters to be set, depending on the particular view. These are set as variables within a script. This gives you the flexibility to build logic into any of the settings of such Views

Scripts are usually evaluated in the context of a specific record. This means that all Calculations performed within the Script are evaluated in the context of that record, so Fields of that record are available as variables in the Calculation.

Script Syntax

The following section describes the standard syntax which applies to all scripts. Any script lines that are not described below will be processed in accordance with the specific script type e.g. for Template Scripts, all other lines become the template output; Action Scripts have additional commands for saving data to records, adding records, sending emails etc., and Form Scripts have a specific format to describe fields and sections within the form to be displayed.

Scripts are evaluated line-by-line. Blank lines are ignored, and white space (spaces or tabs) at the beginning of lines is also ignored. Some script commands described below may affect whether a line is processed (e.g. if it is within an IF…ELSE structure), or whether a line is processed repeatedly (e.g. within a FOR EACH structure where the same script line may be processed for multiple records).

The PYXI script syntax is designed to be as easy to use and flexible as possible, but we do recommend a few points of best practice which, whilst not compulsory, will make your development, understanding and maintenance of your scripts easier:

• Documentation – you can add as many commentary lines to your scripts as you like. As with any programming, it is a very good idea to write commentary about what your script is for, what it does, and how it does it. In particular, describe each variable used and especially note any unusual or non-obvious logic. Remember that commentary is not just for someone else, but also for you in six-months time – you will thank your earlier self for good documentation!
• Indentation – it is a good idea to indent script lines for structures such as IF…ELSE…ENDIF. We recommend using four spaces per indentation. You will see this approach in all our examples and published Blueprints
• Capitalisation and Naming Conventions Almost everything within PYXI scripts is case-insensitive – technically it doesn’t matter if you write ENDIF, endif or eNDif – but consistency is good. We recommend that all commands such as IF, ENDIF etc. are capitalised; names of record Fields are in proper case (e.g. Name, Address), and variable names start with a lower-case ‘v’ for variable or ‘r’ for record followed by proper case e.g. vCount or rPerson. If you follow this convention, variables will be colour-coded automatically within the script editors, further assisting in making your scripts readable.

Comments

All lines whose first character is # are ignored, so can be used to provide useful commentary on the script as a whole or individual items within it (variables, sections of logic etc.).

Comment lines can (and should) be indented with the lines to which they relate.

Examples:

Variables

Variables are an important concept in scripts. A variable is a temporary ‘bucket’ into which you can place any value. The variable has a name which, by convention, is a lower-case ‘v’ followed by a Proper case description of the variable. As a special case, and again, by convention only, any variable which contains a record as its value is named with an initial lower-case ‘r’.

Variables are temporary. They only exist while the script is being evaluated. They are not saved or stored in any way ready for the next time the script is run. If you want the value of a variable saved, you have to do it explicitly e.g. by saving it to a Field of the current record, using it as a value in adding a record, or saving it as an account-level configuration setting.

The values of all variables are made available at the end of a script evaluation. Depending on what the script is for, this can be important. For example, if an Action Script is called by an API call, then the value of all variables is passed back as part of the API response. More commonly, scripts used to define specific items within PYXI, such as Forms, Views or Charts, rely on setting values in pre-defined variable names (which, by the way, don’t need to conform to the previous naming convention). See the specific pages on each of these script types for further details and examples.

Variables are available within calculations in the same script. Simply refer to the variable name in the calculation in the same way that you would a Field name of a record. Note that if you name a variable the same as a Field of the record for which the script is being evaluated, the variable name takes precedence over the record value in the calculation. This is generally not considered good practice as it may make your script hard to understand. You are usually better off explicitly naming the variable distinct from the Field name, and showing the logic that decides which to use later in the script.

The standard syntax for setting a variable is

Note that 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:

There is a special syntax for dealing with multi-line variables, such as Instructions. Every line between the — START and — END lines of the named variable will be added to the variable value, preserving each as a separate line in the final value.

You can get creative with the content of a multi-line variable using coding logic. If you start the same variable name again, the next lines are simply appended to the previous content.

IF / ELSE

You can conditionally include lines of the script by including them within an IF structure. This takes one of the following forms:

You can, of course, nest such structures to any depth needed. If you do this, you’ll find being very disciplined with your indentation is essential to ensure that you correctly END all your structures and avoid getting into a logical mess (not to mention a script that might fail to evaluate at all)

FOR EACH – Process Multiple Items

This syntax can be used to process multiple alternatives:

• Multiple records of a given RecordType, optionally limited with a Filter statement
• Multiple records of a given List of records, which may be in an existing variable, or be a defined List field of the Data Record for which the script is being evaluated
• Multiple items of an array or other iterator e.g. a DOM list from one of the WebScraper functions

The following syntax repeats the enclosed script lines for multiple records defined by a Record Type and an optional Filter.

This pattern is commonly used in Template Scripts to display a table of records. For example, the following code generates a list of all people named Smith, with their address and mobile numbers. For a full discussion of how to reference Fields of a record using the colon, see the Calculations page.

You can make use of an existing list Field Name on a record, or a list in an existing variable, by using FOR EACH followed by the listFieldName. This is instead of specifying the record type and a filter. Now, this alternative loops through each record in the list of records defined as that list Field.

Typically, any link between two record types results in a ‘list’ Field of the ‘parent’ record. These are either predefined (such as People as a Field of Organisation), or are generated as a result of a Field that holds a reference to another (‘linked’) record. See the LinkedRecord… fields of Field for full details.

The chosen variable is set to each record in turn, enabling it to be referenced in calculations inside the loop structure.

A Template Script example, assuming this is part of a script evaluated on an Organisation record:

Note that, in this case, People is a built-in listField on Organisation.

Lastly, you can iterate through any array variable using similar syntax. On each iteration, the chosen ‘AS’ variable is set to the current element of the array.

In the following (not spectacularly useful) example, the FOR EACH statement loops through each element of the array aSplit, which is generated as the array of each line in the linesText multi-line variable; then counts the total number of lines and the number of non-empty lines.

The following is an example using the same syntax on an iterator using the WebScraper functions. This interrogates a given web page, in this case a PYXI help page, and iterates through a list of nodes defined by a CSS selector.

FINISH

The command FINISH on a line by itself results in the script evaluation ending immediately. No further lines of the script are processed, even if the FINISH statement is inside a loop or IF…ELSE structure.

Example: