1

Rules editor

From Resco's Wiki
Jump to navigation Jump to search
Resco Academy
Resco Academy has a course on a similar subject:
Business logic
Client-side

Server-side

Rules are the most important tool for adding business logic to your Resco Mobile CRM app. Rules are scripts that are performed when a user of the mobile app opens a new view or form, taps a button or record, modifies any value, etc. You can modify many things using the scripts, most notably you change data or change the UI.

Various rules can be defined for each of the user interface components, such as form or view. They are usually edited in Woodford, but other standalone tools, like the Questionnaire Designer also allow working with rules.

Actions that trigger rule execution

When you edit a UI component in Woodford, you can define actions that trigger rule execution.

Action Description Form View Other
On Load These rules are checked when you open a form. You can use these rules for example to apply custom format to certain records. Yes Questionnaire Designer
On Change These rules are checked when any field is modified. Example: simple form validation.
They are also executed when you open a form (a new form starts empty, then the values are changed as they are loaded from the database and displayed).
Yes Yes (*) Questionnaire Designer, Schedule Board
On Save These rules are checked when you save a record. For example, saving a record can automatically also update a field in a parent record.
For questionnaires, on save rules can be performed either when you save them or when you complete them.
Yes Yes (*) Questionnaire Designer
Select Form This rule is executed when a form is about to be displayed. Yes
Row Script This rule is executed when a row of a list is about to be displayed. Yes
On Can Execute This rule is executed when a command is about to be displayed. Use it to control in which situations users can see and use the command, so that you can hide this command in situation, when its action is not suitable. See Form commands for more information and examples. Yes Questionnaire Designer
On Execute This rule is executed when a command is pressed / tapped. It defines the actions that the command performs. Yes Questionnaire Designer
Button Click Executed when a row button is clicked. Yes Yes Questionnaire Designer
Cell Click Executed when an editable or clickable cell is clicked. Yes
On Item Added Executed when a user adds a new appointment on the map. Route plan
On Item Completed Executed when a user marks an appointment as completed. Route plan
Edit Rule Calendar rules can for example change the color of calendar entries, modify records, or make the calendar read-only. Calendar
On Create

In the Schedule Board, this rule is executed when a new entity is created.
In reports, the rule is executed when a new instance of a report or a repeating block is created.
In questionnaires, the rule is executed when a new questionnaire is created (even before On Load).

Schedule Board, Report Designer, Questionnaire Designer
On Repeat This rule is executed when a new instance of a repeatable group is displayed. Questionnaire Designer
On Delete This rule is executed when an existing instance of a repeatable group is deleted. Questionnaire Designer

(*) Applies to editable views.

Starting the rules editor

Forms and views:

  1. Edit an app project in Woodford.
  2. Select an entity from the Project menu and click Show UI.
  3. Edit a form or view.
  4. Click one of the rule buttons available in the toolbar.
Note

Select Form button is available directly from the list of Mobile Views, Forms and Charts of an entity.
Maps are based on views. View rules apply also to map views.

Route plan:

  1. Edit an app project in Woodford.
  2. Select Route Plan from the Project menu.
  3. Edit a route plan.
  4. Click On Item Added or On Item Completed.
    • If you don't see the buttons, uncheck the option View-only Mode.

Calendar:

  1. Edit an app project in Woodford.
  2. Select Calendar from the Project menu.
  3. Edit a calendar and go to the Rules tab.
  4. Select an entity and click Edit Rule.

Questionnaire Designer:

  1. Edit a questionnaire template in the designer.
  2. Click one of the rule buttons available in the toolbar.

Schedule Board:

  1. Edit an app project in Woodford.
  2. Select Scheduler from the Project menu.
  3. Edit a scheduler, then click On Create or On Change.

Report Designer:

  1. Edit a report template in the designer.
  2. Select either the report body or a repeater.
  3. Click Edit Sources to display a list of variables defined for that component.
  4. Select any variable and click On Create.

Using the editor

The following functions are available when editing rules.

Save, Save & Close
Save your changes.
Syntax Check
Check if the script workflow is valid. Invalid scripts cannot be saved.
Disable Rule, Enable Rule
Temporarily disable a rule, until you turn it back on. To permanently disable a rule, delete it.
Edit functions
Common functions, such as Copy or Delete, help you work with longer scripts effectively.
Step
Add a step. Steps do things, for example modify data or user interface.
Say Text
Display a message.
Set GPS
Select longitude and latitude fields. The arguments are precision and age. Precision represents a condition for how precise the GPS search needs to be used in the rule. It is set in meters. Age represents a condition for how old the GPS search result can be. It is set in seconds.
Variable, Shared
Define or modify a variable. You can use the variable later in the same script. Shared variables can be used even in other scripts within the same user interface component.
Scan Image
Allows you to initiate barcode scanning or image recognition from rules.
If, Else
Use to define conditions when a particular step should be performed.
Condition, Group And, Group Or, Ungroup
Use Condition to add another condition to the same If. Define if the all conditions must be met (AND) or only some (OR). Use Ungroup in nested conditions.
Export XML, Import XML
Rules can be exported and reused in a different location in the project or in a different project.
Edit XML
Display rule code in XML format.

Building a function step

Each rule consists of steps. Every type of step can be described as an expression with usually three parts (from left to right):

  • Variable - usually this is the thing that we're about to modify in this step
  • Operation - this is the operation, comparison or function that we perform
  • Argument(s) (optional) - parameters of the function

Click Step on the toolbar to add an empty step to your rule.

Variables and arguments are using the dot notation.

Form variables

Click Pick Value and select the variable that you want to modify in this step from a drop-down list. Some of the available variables are listed below, the exact list depends on the rule.

Entity
Use if you want change the value of an entity field in the database.
Entity.websiteurl Concat www.example.com/ Entity.name
Form
Use if you want to change how your form is displayed.
Form.fax.IsVisible Assign False
Tabs
Use to change a particular tab on your form.
Tabs.General.IsMaximized Assign True
Shared
Modify your shared variable. You have to declare a variable before you can modify it.
Shared.CityCountry Concat 3 Entity.address1_city , Entity.address1_country
Caption
Modify the caption of your form.
Caption AddPrefix Draft
IsFormEditable
Can the form be edited?
IsFormEditable Assign False
ChangedItem
This is often used in conditions to determine which item was changed. In Cell Click and Button Click rules, this is the name of the clicked item. In On Change events, it is a variable that can be assigned the changed entity field.
ChangedItem Assign address1_city
CommandsVisibleForNew
FormName
Used mostly in Select Form rules to control which form should be used to display a particular record.
FormName Assign MyForm1
Commands
ErrorMessage
A string variable where you can set an error message for form. In case of On Save event, this stops the saving.
ErrorMessage Assign Web site URL cannot be empty!
WarningMessage
A string variable where you can set an error message for form. In case of On Save event, this does not prevent saving, user can decide to continue.
WarningMessage Assign Web site URL is empty! Continue anyway?

Form tab variables

Properties of form tabs that can be managed using rules

These are the variables that you can work with on a form tab:

  • IsVisible: Display or hide the tab
  • IsSelected: Tab gains focus
  • IsMaximized: Maximize the tab over whole form (no other field or list are visible, but the elements on left are visible, e.g., list view)
  • IsExpanded: Is the tab is collapsed or expanded (in the app, tabs can be collapsed or expanded using arrow(“V”) button)
  • IsLoaded: Ensure that the tab is loaded
  • IsDirty: Has the tab been modified?
  • IsEnabled: Can app users modify the tab content? (available for form tabs created using the Add Detail button)
  • AllowCreateNew: For associated or unassociated lists, allow creating new items

Additional variables for media tabs

  • IsEmpty: Does not contain data
  • Caption: Caption of the tab (displayed in the app)
  • CommandsMask: Enable or disable document actions; see JavaScript Bridge reference for information about inputs
  • IsEditable: Is the attachment tab editable for document edit actions?
  • MaxImageWidth: The image is reduced to the specified maximum width
  • MaxImageHeight: The image is reduced to the specified maximum height
  • DesiredRatio: Specify the desired width to height ratio, for example, "1.3"
  • EnforcementMode: Select whether and how to enforce the image limits (no enforcement, autocrop, autoresize, autocrop and resize, open image editor)

Form field variables

Some of the variables for form fields are universal:

  • IsEnabled
  • IsVisible
  • Validate
  • Focus
  • ErrorMessage
  • Label
  • Style

Other depend on the field type:

Text Number Date Option set
  • PlaceholderText
  • IsPassword
  • Kind
  • Decimal Places
  • Minimum, Maximum
  • DisplayFormat
  • IsTimeVisible

Row Script variables

TemplateIndex
Used to assign different row designs to various rows
TemplateIndex Assign [1]CustomRow
Row
Used to modify the text style of a particular field
Row.name.Style Assign black_bold

Cell Click, Button Click variables

Handled
If false (default) the standard behavior is executed after the rule. If True, it is skipped.
Handled Assign False
DirectEdit
Controls how the changes to the entity are handled (if there are any).
  • True and the entity is dirty after the rule executes, the entity is saved to storage (OnSave rule is run).
  • False, if a property is changed the ChangeRule is run and the entity is added to the list of dirty entities to be saved on user command.
  • Null (not-set, default), changes are ignored.

Scheduler variables

Source Entity
This is the entity from which tasks are created.
Source Entity.name AddSufix (scheduled)
Activity Entity
This is the entity for tasks.
Activity Entity.requiredattendees AddParty Configuration.systemuserid

Questionnaire variables

Questionnaire
Handles every action referencing questionnaire record, handles the properties of the Questionnaire, e.g. clearing and changing ownerid (ID of the user creating the questionnaire in app)
Group
Handles every action referencing question group record, handles the properties of the question group element.
Questions
Handles actions related to questions of a particular group.
RootQuestions
If you use question groups in your questionnaire and have some questions that are outside of any group, this is used to reference them in the rules.
QuestionGroups
If you use question groups in your questionnaire and have some questions that are in a different group, this is used to reference them in the rules.
Shared
Modify your shared variable. You have to declare a variable before you can modify it.
Caption
Modify the caption of your questionnaire.
Command
Used in On Can Execute and On Execute rules to specify a command, its parameters (if available), and whether the command is enabled (visible) or handled.
ChangedItem
Used most often as a condition to specify which item of the questionnaire has been changed.
IsLoaded
Used in very specific cases, when you need to handle the loading of groups/question reload based on some conditions
SourceGroup
Used specifically in On Repeat rule editor, to set conditions or parameters based on the question group used as a source for the creation of a new one
SourceQuestions
Used specifically in On Repeat rule editor, to set conditions or parameters based on the question located in the group used as a source for the creation of a new one

Operations

Each variable data type will have a different set of functions. See the table for details.

Function name Description Variable data types Argument data types
AddDays Returns DateTime argument plus X days DateTime Arg1: DateTime; Arg2: Number
AddHours Returns DateTime argument plus X hours DateTime Arg1: DateTime; Arg2: Number
AddItem Adds argument to end of list. StringList Arg1: Number, Boolean, String, DateTime
Addition Returns addition of arguments Number Arg1: Number; Arg2: Number
AddMinutes Returns DateTime argument plus X minutes DateTime Arg1: DateTime; Arg2: Number
AddMonths Returns DateTime argument plus X months DateTime Arg1: DateTime; Arg2: Number
AddParty Adds a party to an activity Activity Entity User
AddPrefix Adds argument value as prefix to variable Text Text, Number, Boolean, Date
AddSufix Adds argument value as suffix to variable Text Text, Number, Boolean, Date
AddWeeks Returns DateTime argument plus X weeks DateTime Arg1: DateTime; Arg2: Number
AddYear Returns DateTime argument plus X years DateTime Arg1: DateTime; Arg2: Number
ArcCos Trigonometric function Number Number
ArcSin Trigonometric function Number Number
ArcTan Trigonometric function Number Number
Assign Assigns value to variable Text, Number, Boolean, Date Variable data type, all types for text variable
AssignNew Creates a new instance of an object in the variable
CalculateDistance Calculate the distance (in meters) between two points defined by latitude and longitude Number Arg1 - Arg4: Number
Clear Assigns null or empty value to variable Text, Number, Boolean, Date
ClearItems Removes all items from list variable StringList
Concat Returns concatenated string from two arguments Text 2 args: Text, Number, Boolean, Date
Concat3 Returns concatenated string from three arguments Text 3 args: Text, Number, Boolean, Date
Convert Converts value from string Number, Boolean, Date String value
Cos Trigonometric function Number Number in radians
Delete Deletes the record Entity
Difference Returns difference between first and second arguments Number Arg1: Number; Arg2: Number
Division Returns division of arguments Number Arg1: Number; Arg2: Number
Element At Returns a string from a StringList variable Lookup, String Arg1: Index of the string from the list
ExecuteCommand Execute a form command from rules Command Arg1: command parameter (optional)
ExecuteJS Execute JavaScript from rules Boolean, String, Number, Money, DateTime, StringList, Entity, Lookup Arg1: name of the IFrame form tab that links to the script; Arg2: name of the JavaScript function
Exponentiation Returns the nth exponent of a given number Number Arg1: Number; Arg2: Number
Format Returns a formatted string from StringList (How to use?) Text Arg1: Text; Arg2: StringList
Format Single Returns a formatted string with lookup target information. More info Webinar Text Arg1: Text with placeholders: {1} for entity ID, {2} for entity name. Arg2: Lookup field
Format Text Returns a formatted string that can contain references to entity fields using the dot notation - {entity.field:format} (Example) Text Text with entity fields, e.g. Call us at {Entity.phone} or mail us at {Entity.emailaddress}.
Get Date Part Return a portion of a date time field DateTime
GetItem Returns item at specified index. StringList Number
GetUnixTime Converts datetime into unix time Number Arg1: Date Time
IndexOf Returns the first occurrence of a specified substring within a string Number Arg 1: String; Arg 2: substring
InsertItem Adds argument to specified index. Index starts at 0. StringList Arg1: Number, Boolean, String, DateTime; Arg2: Number
LengthOf Return the length of a string Number Arg1: String
LoadAggregate Allows you to use Fetch XML aggregation functions Arg1: entity; Arg2: field; Arg3: aggregation function
Logarithm Returns the logarithm to the base n of a given number Number Arg1: Number; Arg2: Number
MessageBox Shows users a menu with options to choose from. More info Blog Number Arg1: String (the title or question); Arg2: String list
Multiplication Returns product of arguments Number Arg1: Number; Arg2: Number
Negate Returns negated value of argument Boolean Boolean
N-th Root Returns the nth root of a given number Number Arg1: Number; Arg2: Number
OpenForm Open a form for a related record Lookup Arg1: JSON with data that updates (some) values on the form
RemoveItem Removes item at specified index StringList Number
RemoveParty Removes a party from an activity Activity Entity User
Save Saves an entity record that you created or changed in rules
Available only for On Save and On Execute rules.
In questionnaires, available for root questions (and not for question groups).
Entity
SaveAfter Saves an entity record that you created or changed in rules
Available only for On Save and On Execute rules.
In questionnaires, available for root questions (and not for question groups).
Entity Arg1: Other entity that must be saved first
SetNow Assigns current time to variable DateTime
SetToday Assigns current day to variable DateTime
SetTomorrow Assigns tomorrow to variable DateTime
Sin Trigonometric function Number Number in radians
Substring Returns a sub-string Text Arg1: Text; Arg2 and Arg3: Number
Tan Trigonometric function Number Number in radians
TimeDifference Returns difference between first and second argument Number Arg1: Date Time; Arg2: Date Time; Arg3: unit of time

Text = String, Memo
Number = Integer, Float, Decimal, Number

Arguments

After selecting the variable and the operation, you usually have to select one or more arguments. Some operations don't have arguments, for example "Clear". Some operations have multiple arguments, for example "Concat".

An argument can be either a constant value or a variable.

  • Click the xy button to switch to variable.
  • Click the π (pi) button to switch to a constant.

constants and variable in Resco's Rule editor

Building a condition

Conditions allow you to specify when (under which conditions) a set of steps will be executed. A condition is a part of a rule, where you test a variable against a value and act in one way if the condition is met by the variable or another way if not. Conditions always evaluate to true or false. You can chain conditions using AND and OR logical operators.

Similar to function steps, conditions also often have three parts: variable, operator, and argument(s).

Variables

The variables in conditions mostly overlap with variables in function steps. Some additional variables exist:

Configuration

Use to evaluate conditions related to a user, app, and device.

Configuration.platform Equals Android

Configuration.roles allow you to modify the behavior of the app depending on the user role. For example, you can make a form read-only for certain security roles or enable a specific command only for a certain role. Use the Contains operator with roles, and specify either the name or the ID of the security role.

Configuration.roles Contains Sales Manager
Configuration.roles Contains c2b83d0f-89b4-e111-9c9a-00155d0b710a

IsLoaded

IsLoaded property checks whether the form or questionnaire is fully loaded and visible on the screen, with all the values assigned. For example, you can use it to differentiate between the initial loading of a form and manual user change.

IsLoaded Equals True

Relationship

Relationship allows you to determine from where a particular form/view/questionnaire opens. However, a relationship has to exist between the two records. Depending on whether the lookup relationship is on the original record or the destination record, either source or target is populated.

For example:

  • If you display an account and go to its primary contact through a lookup on the account form, on the contact form, the relationship.source will be populated with the account reference (account.primarycontactid).
  • If you display an account and go to one of its related contacts, on the contact form, the relationship.target will be contact.accountid.
  • If you open a record directly from the home screen or from an unrelated list, no relationship will be defined.

In the case of questionnaires:

  • The relationship target gets the object from where you entered the questionnaire in the user interface. For example, if you open a questionnaire from an Account form, the relation target is then the Account record.
  • The relationship source is the record from the form that you opened from the questionnaire. However, opening forms of other records from a questionnaire is very rare.

The relationship sourceUIElement is the tab name of the associated view from which you open a related record.

Operations

The operators in conditions are quite different from operators in functions.

Function name Description
ContainsData
Does Not ContainData
Equals
Does Not Equal
Equals Current User
Does Not Equal Current User
Equals Current User's Teams
Does Not Equal Current User or User's Teams
Equals Current Business Unit
Does Not Equal Current Business Unit
Contains
Does Not Contain
Contains Option
Does Not Contain Option
StartsWith
Does Not StartWith
EndsWith
Does Not EndWith
MatchesRegex
Does Not MatchRegex
Is Less Than or Equal To
Is Less Than
Is Greater Than or Equal To
Is Greater Than
Type Of Use to check the entity that a lookup is pointing to.
On
OnOrAfter
OnOrBefore
NextXHours
LastXHours
Next X Days
Last X Days
Next X Weeks
Last X Weeks
Next X Months
Last X Months
Next X Years
Last X Years
In
Not In

Using variables

Rules support two types of user-defined variables:

  • Variable: You can use the variable later in the same script.
  • Shared: You can use a shared variable even in other scripts within the same user interface component.

Use the buttons Variable and Shared to declare a variable and assign an initial value to it.

  1. Select a type: String, Boolean, Integer, Float, Decimal, Date Time, Lookup, Entity, Picklist, StringList.
  2. Name the variable, for example MyString1.
  3. Assign an initial value to the value.
Variable Integer MyNumber1 TimeDifference Entity.createdon Entity.modifiedon minutes
Variable String MyString1 Concat Email me at Entity.emailaddress1

Once the variable has been initialized, you can use it in other steps and conditions.

Step Entity.websiteurl Assign MyString2
Warning We recommend always initializing shared variables before using them. If you use multiple shared values, initialize them in order. This is particularly critical in the case of views, where uninitialized shared variables may cause the app to crash.

Deleting variables

When you delete the variable, all steps that are using the variable on the left side will be also deleted.

Steps using the variable on the right side will reset and you have to define them again.

StringList type

StringList is a special type of variable that you can define. It represents an array or list of string variables. It has only a limited set of operations available.

To populate a StringList variable, you can either assign it a different string list or add strings using the AddItem step.

Variable StringList MyStringList
Step MyStringList AddItem Alpha
Step MyStringList AddItem Beta
Step MyStringList AddItem Gama

To work with the content of the array, use the Element At operation and specify the index of the string in the array.

Variable String SingleItem Element At MyStringList 1
If SingleItem ContainsData
Then Do stuff...

Entity type

Variables of the type Entity are used to store a single entity record (with all its fields). There are multiple ways how to fill in the initial values of this variable:

  • NewInstance: Create a new blank record of the selected entity.
  • LoadReference: Load a related record from related entity.
  • LoadFetch: Load a particular record from the database. Opens a new Filter editor window that allows you define a FetchXML command that finds the record.

Option set filtering

You can use rules to filter the values available in an option set on a form. It also applies to Salesforce picklists.

Warning Can overwrite existing values! When you open a form with the option set filtering enabled and the record's option set value is not among the allowed values, the option set value is overwritten by the first allowed item (sorted alphabetically).
Step Form.opportunityratingcode.ComboItems SetItems Warm, Cold

Use rules to determine the available options in option sets

Asynchronous operations in rules

The rules include multiple asynchronous operations:

  • LoadFetch
  • LoadReference
  • LoadAggregate
  • SetGps

Additionally, when we use the Assign operation to add a lookup to an entity, this behaves like LoadReference.

Asynchronous operations cannot be used in the following rules:

Code editor

Rules offer a no-code/low-code way of defining business logic. Some users don't mind code; in fact, they prefer it. For this reason, the rules editor also provides an alternate representation of the rules.

code editor in rules

See also




Was this information helpful? How can we improve?