We are preparing a new source of documentation for you. Work in progress!

Rules editor

From Resco's Wiki
Jump to: navigation, search

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 modify any field. 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
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. 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 an row button is clicked. Yes Yes
Cell Click Executed when an editable or clickable cell is clicked. Yes
On Item Added Route plan
On Item 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 This rule is executed when a new entity is created. Schedule Board, Report 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.

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.

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.

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, 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?

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

Operations

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

Function name Description Variable data types Argument data types
Assign Assigns value to variable Text, Number, Boolean, Date Variable data type, all types for text variable
Clear Assigns null or empty value to variable Text, Number, Boolean, Date
Convert Converts value from string Number, Boolean, Date String value
Negate Returns negated value of argument Boolean Boolean
AddSufix Adds argument value as suffix to variable Text Text, Number, Boolean, Date
AddPrefix Adds argument value as prefix to variable Text Text, Number, Boolean, Date
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
Substring Returns a sub-string Text Arg1: Text; Arg2 and Arg3: Number
Format Returns formatted string from StringList (How to use?) Text Arg1: Text; Arg2: StringList
Addition Returns addition of arguments Number Arg1: Number; Arg2: Number
Difference Returns difference between first and second arguments Number Arg1: Number; Arg2: Number
Multiplication Returns product of arguments Number Arg1: Number; Arg2: Number
Division Returns division of arguments Number Arg1: Number; Arg2: Number
N-th Root Returns the nth root of a given number Number Arg1: Number; Arg2: Number
Exponentiation Returns the nth exponent of a given number Number Arg1: Number; Arg2: Number
Logarithm Returns the logarithm to the base n of a given number Number Arg1: Number; Arg2: Number
TimeDifference Returns difference between first and second argument Number Arg1: Date Time; Arg2: Date Time; Arg3: unit of time
GetUnixTime
Get Date Part Return a portion of a date time field DateTime
LengthOf
IndexOf
SetNow Assigns current time to variable DateTime
SetToday Assigns current day to variable DateTime
SetTomorrow Assigns tomorrow to variable DateTime
AddMinutes Returns DateTime argument plus X minutes DateTime Arg1: DateTime; Arg2: Number
AddHours Returns DateTime argument plus X hours DateTime Arg1: DateTime; Arg2: Number
AddDays Returns DateTime argument plus X days DateTime Arg1: DateTime; Arg2: Number
AddWeeks Returns DateTime argument plus X weeks DateTime Arg1: DateTime; Arg2: Number
AddMonths Returns DateTime argument plus X months DateTime Arg1: DateTime; Arg2: Number
AddYear Returns DateTime argument plus X years DateTime Arg1: DateTime; Arg2: Number
AddItem Adds argument to end of list. StringList Arg1: Number, Boolean, String, DateTime
InsertItem Adds argument to specified index. Index starts at 0. StringList Arg1: Number, Boolean, String, DateTime; Arg2: Number
GetItem Returns item at specified index. StringList Number
RemoveItem Removes item at specified index StringList Number
ClearItems Removes all items from list variable StringList
LoadAggregate
Element At
AddParty Adds a party to an activity Activity Entity User
RemoveParty Removes a party from an activity Activity Entity User
Save
SaveAfter
AssignNew
Delete

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

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 user, app, and device.
Configuration.platform Equals Android
IsLoaded
IsLoaded property checks whether the form is fully loaded and visible on screen with all the values assigned. Use for example to differentiate between initial loading of a form and manual user change.
IsLoaded Equals True
Relationship

Operations

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

Function name Description
ContainsData
Does Not ContainData
Equals
Does Not Equal
Contains
Does Not Contain
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 variables:

  • Variable: You can use the variable later in the same script.
  • Shared: You can use 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 other steps and conditions.

Step Entity.websiteurl Assign MyString2

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 special type of variable that you can define. It represents a list of variables. In editing state you can’t initialize it right away, you have to add items in to the StringList using the AddItem step.

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

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.

Step Form.opportunityratingcode.ComboItems SetItems Warm, Cold

See also