Maestro Business Rules

MaestroThe UI design product. | Form Builder | 23.04This feature was updated in 23.04

Maestro allows you to create and add various business rules to components used in a form. A business rule is a JavaScriptJavascript (JS) is a scripting languages, primarily used on the Web. It is used to enhance HTML pages and is commonly found embedded in HTML code. JavaScript is an interpreted language. Thus, it doesn't need to be compiled. that is invoked by different events pertinent to a component. These events can be triggered by the Angular JS digest cycle, for example, visibility and editability, or a user taking an action, for example, click, blur, and so on. Some examples are listed below:

Maestro's core engine firing life-cycle events, load and pre-submit
Visual components firing the standard rule types
Responses from calls to dynamic data services
Custom rules defined by Native Components
Your own rule code calling Form.fireRule()

Maestro comes with the following pre-configured business rules types, which you can select in the Create Rule dialog:

Visibility
Editability
Validation
Validate on Change
Calculation
Mandatory If
Click
Blur
Focus
Change
Dynamic Class

For more information, see List of Maestro Rules.

You can also create your own business rule types and add them to the Create Rule dialog, so they are available from the Properties pane. However, these rule types must be for native components only so they can be linked up. For more information, see Component Options.

Some components can't have rules added to them, so you won't see the Rules category or any rules displayed in the Properties pane. These components are:

Business rules have access to some form data allowing you to obtain additional information from Journey Manager. When a rule is invoked, a JavaScript receives the following parameters:

data - an object:
- for non-repeated items - the form data object holding values for all form fields plus additional system-related data.
- for repeated items - the repeating object instance holding all sibling repeating values, including any nested repeats, plus other properties such as the current index, the repeated data object array and the parent item.
item - an object holding the structure and definition of the form field including style and 'properties' properties, as well as repeat-aware getData and setData methods to get and set the form field's data.
info - an object describing the event which triggered the rule, or the object returned from a success or failure call in a remote data handler.

In addition to these parameters, there is a local value variable that is set to the specific field instance value in the form data object. The value variable is repeat-aware, so it represents either the sole data value, or the indexed data value in a repeat. Changing value does not change the form data object, so it can be considered as read-only.

The rule execution context also exposes the following objects, which you can call via API methods:

Form
Util
Calc
DynamicData

The Rule editor provides a quick access to the API documentation, so click API Methods to open Maestro API Reference documentation in a new tab. We recommend checking Introduction to Maestro Business Rules to get started.

While you are writing your business rules, you should keep in mind the following suggestions:

The Rule editor

Sometimes, the Rule editor can become confused about exactly what you are trying to achieve, and can interpret what you are typing in the wrong way. If you are getting unexpected results, you may want to switch to Source mode, and review the underlying HTML. You may have accidentally injected HTML tags you didn't expect.

Test often

When you are developing rule's formulae, test your work often. Several types of errors can result in your form not displaying correctly in Preview mode. The more often you test, the more likely you are to find the bit of code that is causing the problem.

Use a field within a calculation

A calculation is assumed to be code, and therefore everything is interpreted as JavaScript. When you insert a field into a calculation, simply reference the field id as data.firstname.

If you need to include text, include it in single or double quotes.

For example:

"Welcome " + data.firstname

Insert a field into text

A caption or display field is interpreted as text, and so you need special syntax in order to have everything interpreted as code. Maestro uses double curly braces to inject code into the string.

For example, to insert a field value into a piece of text, such as a caption or a display field, use the following notation:

{{ data.firstname }}

You can perform calculations within the braces, like this:

{{ data.firstname + " " + data.lastname }}

The braces mean: "Treat whatever is inside the braces as a calculation rather than as text.

Hide text display until all dependent values are valid

Sometimes a text display can look strange if only some of the values that are used within it have been completed. To avoid this, simply create a Visibility rule that looks something like this:

data.firstname != "" && data.lastname != ""

+data.term != 0 && +data.frequency != 0

Treating field values as numbers

All data is inherently treated as text. If you want to force a field's value to be treated as a number, prefix it with a "+". (If you don't do this, when you try to add two numbers, they will be concatenated as strings rather than added together. You can also use JavaScript functions to format the result. For example:

(+data.term * +data.frequency).toFixed(2)

(+data.term) + (+data.frequency).toFixed(2)

Treating field values as boolean (true/false)

All data is inherently treated as text. If you want to force a field's value to be treated as a boolean or logical value, prefix it with !!. For example:

if (!!data.is_married) ...

Conditional values

If you have, for example, some values in a dropdown list, and want to turn these into more human readable values, you could use an if statement or a switch statement. However, if you want to embed the logic inside some text, you can use the following object key lookup syntax:

{{ {'52': 'per week', '24': 'bi-monthly', '12': 'per month'} [data.frequency] }}

This is a shortcut for:

Depending on the values of [data.frequency], use the following lookup values:

'52' = 'per week'
'24' = 'bi-monthly'
'12' = 'per month'

This defines an in-line JavaScript object, and then uses the field's data value to index into that object. More information is available at this website.

Note that if there is no match, then the first pair will be used, and so this can be used as a default.

If you are experiencing some issues with business rules, learn how to debug business rules.

Next, learn how to create a rule.

Topics