Login    Sites MenuBlueStep

BlueStep Platform Support

Relate Components
Outline full outline 
General Concepts/Getting Started 
The Relate Inspector 
Relate Structure 
Folders 
Forms 
Fields 
Option Lists and Groups 
Multi-Entry Reports 
Merge Reports* 
Formulas* 
End Points 
Wizards* 
Permission Report 
Other Elements and Functions* 
Using Relate Outside Relate* 
Design Patterns 

A formula is a piece of RelateScript which is triggered by an event in the system.  RelateScript is the proprietary scripting language of Relate.  Full documentation for the language and its functions is available.  This page describes the process of configuring a formula and the meaning of all the settings.

Formulas are created and edited in a three step wizard.  The settings on each step of the wizard effect the options available on the next step.  Many of the settings described here only apply to specific types of formulas and will not be available for other types.

Step 1 - Formula Name & Type Description
Formula Name The name of the formula.  Formulas are never visble to any users other than Relate Administrators, so chose a name that makes sense to you.
Description The description of the formula as seen by Relate administrators on the relate structure and while editing the formula.
Folder Location The folder in Relate structure where the formula resides.  The location of the formula is purely for organizational purposes and does not ever effect its function.
Bundle Settings Formulas may belong to bundles, assuming bundles have been created.  These settings are complex and virtually identical for all Relate components.  They are described in the article on bundles.
Enabled If this setting is "Yes", then the formula will run whenever its triggering event occurs.  If not enabled, the formula will ignore triggering events and never run.
Fixed Id/Frozen These settings are available only to BlueStep staff and are used to identify and lock formulas that are used by the underlying platform logic.  By convention, positive numbers are reserved for use by the Java development team.  Negative numbers can be used for other purposes.
Custom Lookup Properties This setting is used by the system to add additional identifying attributes as a part of the underlying platform logic.  Since there is currently no available feature to find and use formulas using these properties, the setting is available only to BlueStep staff.
Formula Type The formula type setting determines what type of even triggers the formula to run.  The various options are described directly on the formula edit screen and in the RelateScript documentation in the topic called "How and Where Formulas are Used" and connected topics.
Step 2 - Formula Options Description
Record Type A record is needed to identify what types of records the formula will work with.  This setting specifies what types of records may be the current or primary record for the formula.  Formulas do not work without a current record.
Record Categories

Based on the record types are selected, all applicable record categories for those types will be shown.  This allows further refinement of which type of records this formula applies to.  In other words, it defines what types of records may be the primary/current record of the formula.

For each category you may select "N/A", "Must Have", "Has Any Of These" or "Cannot Have".  If the category is unimportant in determining whether a particular record may be used as the primary record, leave the setting as "N/A".  If the category is required choose "Must Have".  The "Must Have" option may not be available if multiple record types were chosen and the category does not apply to all selected record types.  If the record must belong to at least one of a group of categories, select "Has Any Of These" for all of the categories in the group.  If the report should not be applied to records of a particular category, select "Cannot Have".

The record types and categories determine which forms will be available within the current record when the formula is running.  The record type and category setting determine what data will be available to work with in step 3.

Unit The unit setting determines which unit the formula will run in.  In most cases, the root level unit should be selected.  However, if a particular bit of formula logic only applies to a certain unit, the formula may be configured to run in a particular sub-unit.
Include Sub-Units If sub units are included, then the formula will run not just within the unit selected, but in all of its sub units.  Under most circumstances, this option should be selected.
Schedule

These settings are only available for scheduled formulas.  They determine exactly when the formula will be scheduled to run.  

Time Zone -- The time zone setting which determines in which time zone the schedule will be computed.  The timezone setting applies to all other schedule settings.

  • One Time -- Schedules the formula to run just once at a specific date and time.
  • Every n minutes -- Schedules the formula to run repeatedly with a fixed interval computed in minutes.  Intervals between 5 and 1440 minutes (24 hours) are possible.
  • Every week -- Schedules the formula to run once a week on a specific day of the week and at a particular time of day.
  • Every month -- Schedules a formula to run one or more time each month on specific days of the month.  To work correctly in February, days of the month after the 28th are not allowed.  Instead, a negative number may be used to schedule the formula relative to the last day of the month.  In this case -1 is the last day of the month, -2 is the next to last day of the month, etc.  The formula will be scheduled to run shortly after midnight in the specified timezone.

Create variation -- When BlueStep staff create a new system for a new client, all of the scheduled formulas have the same default schedule.  This can cause server overload when the same formula in many organizations attempts to run at the exact same moment, particularly if it is a complex formula which works with a large amount of data.  This setting allows schedules to automatically have variations so they don't all run at once.

Run immediately when saved -- Occationally a scheduled formula needs an ad-hoc run in addition to its normal schedule.  Rather than switch the formula to run once at the ad-hoc time, then reconfigure the original schedule after the ad-hoc run, this setting, if checked adds an additional run to the schedule immediately after saving.  This setting is not available when creating a new formula, only when editing an existing formula.

Important: For repeating schedules (every setting except "One Time") the formula will run once when created.  This because of the nature of repeat scheduling and issues with reliability under heavy server load.  Occationally heavy server load or temporary server unavailability prevents a formula from running when scheduled.  Rather than just give up, the system runs the formula as soon as it is able to.  The unfortunate side effect of this logic is that when a formula is newly created the system will look at the repeating schedule, detect that the formula failed to run at its last scheduled time, and then try to "catch-up" by running the formula immediately.  To prevent this from happening, it is sometimes helpful to create a scheduled formula with no logic and save it.  This causes the formula to run immediately but not do anything.  However, it establishes a baseline schedule after which scheduling will behave more predictably.  Note that under the same logic this issue may occur when a formula which is not a scheduled formula is edited and converted to be a scheduled formula.  Without a baseline schedule, the scheduler will attempt to catch up and will, therefore, run immediately.

On-Demand Identifier
Step 3 - Formula Description
Primary Form
Add Query/Report
Add Form

 

Formula
Check Formula