Introduction to Maestro Business Rules

   MaestroPreviously known as Transact Maestro.  |  Form Builder |  Platform Developer

Maestro business rule functions can be created and edited in the Code View or in the rule editor dialog accessed from the Rules section of the properties panel.

Values in Scope within a Maestro Rule Function

All rule functions can access the current data value of the field to which they are attached using the variable value (see Shortcuts). In addition to that, they receive several other parameters, injected references and shortcut variables as described below.

Statements vs Expression

All Maestro business rules get packaged within a function body, providing various parameters and variables described further below. The returned value from this function is the result of the rule. So, for example the following validation rule would result in a Boolean true (meaning validation passed) or an error message string depending on the value of the field.

if (value > 17) {
    return true;
} else {
    return "Not old enough";
}

However, for a rule that only returns one calculation, you can enter a simple expression and omit the return keyword. It will be added into the generated function automatically. So the same rule could be expressed simply as follows:

value > 17 ? true : "Not old enough";

Due to the semantics of the JavaScript OR (||) operator, this can be simplified further:

value > 17 || "Not old enough";

The general rule of thumb is that if the result can be expressed as a simple calculation then it doesn't need the return keyword. If it requires control flow, nested functions or any other kind of statements then you should use return where appropriate.

Parameters

Maestro business rule functions receive three parameters:

  • data – The data context that the rule operates in. For items that are not in a repeat, this will be the main form data context. Each instance of a repeat creates a new data context. Instances of nested repeats have a separate data context within the data context of their parent repeat, and so on. This can be used to look up other items of data, in the same context, or in parent, sibling or child contexts.
  • item – The view item that this rule is attached to. This can be used for looking up properties of the item.
  • info – An extra parameter that some component-specific rules use to supply additional information. For example, the Page Controller component Change rule has an info parameter with from and to properties that identify the pages being navigated from and to. To inspect the value of the info parameter for a specific rule in the JavaScript console add the following line:
    console.log(info);

As explained above, a new data context is created for each instance of a repeat. To navigate to the parent context use data.$p. To navigate to the repeat item's own data entry in the parent context (which will be an array of all the data contexts in that repeat) use data.$r. To find out a data context's index within a repeat, use data.$i.

So, to get to a sibling context - say the previous instance in a repeat - you would first navigate to the repeat's data entry and then use square-brackets to address the relevant child context in the array

data.$r[data.$i - 1];

If the item for which the rule is defined is in a container, you can access that container item using item.$parent.

Within any given container item, the child items are held in an array of rows, each of which is an array of child items within that row. So the first child of a containers first row would be item.rows[0][0].

In this way you can navigate up, down and across the view hierarchy. However, to get to a specific item it's easier to look it up in the flattened map held in Form.items, such as

Form.items.myRadioButton;

The properties of each item are available on the key properties. So to get the placeholder text of a Text Field with ID firstName you would use

Form.items.firstName.properties.placeholder;

Global API Objects

In the previous section we saw the a reference to an object called Form - in that case to access its items property, containing an ID-keyed map of all the view items. There are several of these global objects. (They are not global in the sense of being available on the window object, but they are injected into the scope of each business rule function using Angular.) These objects (or "Services" in the Angular terminology) are described below. A full reference of API methods available on each of them can be found using the API Methods Reference link in the Code View.

$rootScope

The Angular $rootScope object - can be useful if you are an Angular expert. See the Angular documentation.

$q

The Angular $q object. This can be used for creating and aggregating Promises. See the Angular documentation, as well as general documentation about JavaScript Promises.

$timeout

The Angular timeout function. This is similar to JavaScript's standard setTimeout function, but ensures that any data updates are rendered again in the form. Also, it can be used with a callback, as follows:

$timeout(function() {
    data.status = "Success";
}, 5000);

or it can be used to return a prommise, as follows:

$timeout(5000).then(function() {
    data.status = "Success";
});

Form

The Form service contains a number of properties and methods for general form interactions such as validation and submission.

Calc

The Calc service provides some useful methods for running calculations on data.

Resource

The Resource service provides methods for working with external resources, such as formatting image URLs.

Util

The Util service provides general utilities to assist with tasks such as searching and sorting arrays, walking the row/child view hierarchy and so on.

DynamicData

The DynamicData service provides methods for interacting with Dynamic Data Services published in Transact Manager.

Scroll

The Scroll service provides a way to scroll to and focus on particular form fields.

Insights

The Insights services enables rules to register events with Transact Insights analytics.

Translation

The Translation service has some helper methods for working with multi-lingual forms, although for basic access to localized terminology use the T shortcut described further below.

Other Shortcut Variables

value

This is a shortcut to the current data value for the field to which the rule is attached. So for a rule on a Text Input with ID lastName it is the equivalent of using data.lastName.

Rules

In the final published form, all the business rules are contained within a single Rules service. This shortcut lets you navigate to and even run business rules from within other business rules.

Business rule functions have names formatted as follows:

<rule-type>_<item-id></item-id></rule-type>

Basic standard rule types are ok (validation), us (editability), sh (visibility) and eq (calculation). Other action rule types have their full action name, such as click, blur and change. Components can also provide their own custom rule types.

So, the click rule on a button with ID verify could be accessed with

Rules.click_verify;

and the validation rule for a Decimal Field with ID age would be

Rules.ok_age;

Whilst you could call the age validation rule from another rule in the same data context with the code

Rules.ok_age(data, Form.items.age);

It would only return the validation state of that field. To properly validate the field, including display of approriate errors and setting form validation state, you should use the validation methods available in the Form service object.

T

This is the hierarchical map of all terminology items for the currently selected language in a multi-lingual form. So, to get the translated placeholder text for an item with ID firstName you could use

T.firstName.properties.placeholder;

SystemProfile

This is a shortcut to the SystemProfile node of the form's data, which contains metadata about the submission provided by Transact Manager.

Job

This is a shortcut to the Job section of the forms SystemProfile data. Useful for some collaboration job scenarios.