Rules editor

Resco Academy has a course on a similar subject:

Business Logic

Business logic
Client-side Rules editor (no-code) Resco JavaScript Bridge Server-side Server processes (no-code) Plug-in assemblies (C# scripts) Configuration (Admin Console) Calculated fields Entity notification workflow SMS gateway

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:

Edit an app project in Woodford.
Select an entity from the Project menu and click Show UI.
Edit a form or view.
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:

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

Calendar:

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

Questionnaire Designer:

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

Schedule Board:

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

Report Designer:

Edit a report template in the designer.
Select either the report body or a repeater.
Click Edit Sources to display a list of variables defined for that component.
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

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 - Gets or sets whether the item is editable.
IsVisible - Gets or sets whether the item is visible.
Validate - Gets or sets whether the item needs validation. When set to true, the item cannot be empty; users have to enter or select a value.
Focus - Set focus to the item.
ErrorMessage - Gets or sets the item error message displayed during validation.
Label - Gets or sets the item label.
Style - Gets or sets the item's style.

Other depend on the field type:

Text	Number	Date	Option set
PlaceholderText IsPassword Kind	Decimal Places Minimum, Maximum DisplayFormat	IsTimeVisible	ComboItems (more info)

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 (example)
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.

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	Use e.g. for multi-select choice questions
Does Not Contain	Use e.g. for multi-select choice questions
Contains Option	Use e.g. for option set choice questions
Does Not Contain Option	Use e.g. for option set choice questions
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.

Select a type: String, Boolean, Integer, Float, Decimal, Date Time, Lookup, Entity, Picklist, StringList.
Name the variable, for example MyString1.
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.

If you stumble into an "Entity Not Loaded" error when executing rules, use the ContainsData operator to check if a variable has been populated before proceeding with your rule's logic.

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.

Shared variable limits

There's a limit to how many shared variables you can use.

On forms and questionnaires, you can use up to 1000 shared variables.
On views, you can use up to 750 shared variables.

The app displays an error if you go past this limit.

Note	This usually happens when you use shared variables of the type "entity". In fact, this adds a shared variable for each field of the entity. If you add a huge entity with many fields, you can run into the limit.

In the example above, a single shared variable in the On Change rule on the Contact entity form results in multiple entries in the Fields & Components pane (one for each field).

Global constants

In addition to the variables defined in rules, Woodford admins can define global constants. These are read-only and available in selected rules and JavaScript.

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

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.

Rules editor

Contents

Actions that trigger rule execution

Starting the rules editor

Using the editor