Rules editor
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 edited in Woodford.
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 |
| 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 button 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. | Yes | – | – |
| On Execute | This rule is executed when a button is pressed / tapped. It defines the actions that the command performs. | Yes | – | – |
| 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 |
(*) 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.
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.
Maps:
- Maps are based on views. View rules apply also to map views.
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.
- 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
- 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.
ErrorMessage 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.
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 |
| Format | Returns formatted string from StringList | 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 |
| 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 | |
| Function | Description | Variable data types | Argument data types |
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
- Is the form fully loaded? Use to differentiate between initial loading of a form and manual user change.
IsLoaded Equals False
- 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 |