Login    Sites MenuBlueStep

BlueStep Platform Support

RelateScript
Outline full outline 
Overview 
How and Where are Formulas Used? 
Basic Syntax and Behavior 
Style Guidelines 
Data Types 
Operators 
Statements 
Functions 
Working with Relate Data 
How Formulas Work 
Related Topics 

Formulas are currently available in four places: 1) on most Relate form fields, 2) in Merge Reports, 3) as stand-alone formulas and 4) as end-points.  Stand-alone formulas, themselves, have six varieties:  scheduledpre-edit, pre-save, post-save, pre-delete and on-demand.  This makes a total of nine types of formulas.  Their differences are explained briefly in this article and also in the last section of this document in the article titled, "Types of Formulas."  Other detailed articles explaining how formulas are used are "The 8 Step Edit Process", "Writable or Read-Only?", "Accessing Field Data" and "Field Formulas"

Field Formulas
The first type, field formulas, are executed when the record is saved and these formulas will both read and update fields. Field formulas are limited to the form on which they occur and will not read or update fields on other forms. 

Merge Report Formulas
Merge Report formulas have access to all of the data in a single Relate record, no matter what form(s) contain the data.  They can also access data in any other Relate records.  These formulas can read data and produce values for display, but cannot update the data.  The formula is run each time the report is viewed.

Scheduled Formulas
Scheduled formulas run on a schedule and, therefore, do not require any user action to do their work.  As a matter of fact, they are frequently used to send notification emails when a user fails to take a required action such as to filing a weekly report or renewing an annual certification.  They are also useful in keeping information that naturally changes over time fresh, such as counting the days elapsed since a prior event.  They are also used to prepare data for editing which must be done on a regular basis.  Scheduled formulas can access and modify any and all data in Relate.  However, they do require a current record be designated.  For each scheduled time, they run once for each record that matches specific type, category and unit criteria.   Each matching record in turn becomes the current record for the formula.  Scheduled formulas also have control over database transactions which allows data to be stored in multiple distinct steps.

Pre-edit Formulas
Pre-edit formulas are executed before the user edits data on a particular form.  They have access to all other data in the current record, but can only modify the data that is about to be edited.  They can also access data in any other Relate records.  The results of this type of formula are not actually saved, but simply used to pre-populate data for the user to possibly modify, then save.  They are primarily used to dynamically pre-populate default values using more complex logic than is available in the basic default-value field settings.

Pre-save Formulas
Pre-save formulas are executed immediately after field formulas and serve a similar purpose.  The major difference is that Pre-save Formulas have access to read and update information contained outside the form entry currently being edited.  They can read and modify any information in the current record as well as all other Relate records.

Post-save Formulas
Post-save formulas can do almost exactly the same things as pre-save formulas.  However, they run after the data has already been saved.  Therefore, any modifications made by this type of formula will be recorded as a separate save.  These formulas benefit from being able to work with information that is not available until after the save is complete, such as the results of other types of formulas.  They can also get the URL to view or edit newly created data which did not have an identifier assigned, and therefore no URL, prior to it being saved for the first time.  For this reason, post-save formulas are most often used to send notification of new or modified data via an email, intramail or alert containing a link back to the new information.

Pre-Delete Formulas
Pre-delete formulas run prior to entries being deleted.  However, any relationship fields will have been cleared of all selected values in preparation for delete (use the changed property of the relationship field to know what had been selected).  Pre-delete formulas are used primarily for two purposes.  The first is to prevent deletion of important data.  The pre-delete formula can roll-back the current operation and prevent the delete from occurring.  The second primary use is to clean up dependant data.  For instance, when deleting a timecard entry the overtime hours need to be re-calculated for any remaining timecards later in the same week.

On-Demand Formulas
On-Demaind formulas run on a dynamic schedule specified in another formula.  They cannot be run directly by any user action.  They are used to run large computations out-of-process or run a formula on a delay after another formula runs.  On-demand formulas have a primary form entry or primary record, and an optional message from the formula initiating the on-demand formula.  If used carefully they may increase both actual performance and perceived performance.  On-demand formulas also have control over database transactions which allows data to be stored in multiple distinct steps.

End-Point Formulas
End-point formulas are very powerful, very versatile and potentially very dangerous formulas.  Only BlueStep employees are allowed to create and edit them.  However, knowing a little about their purpose is still useful.  End-point formulas are triggered by an HTTP request.  They then read and/or modify data in Relate or elsewhere.  Then they send an HTTP response.  Basically, they are a small scale webserver embedded inside the BlueStep platform and programmed via RelateScript.  End-point formulas also have control over database transactions which allows data to be stored in multiple distinct steps.