Overview
Rules can be used to apply additional logic to the field. There 2 types of rules present in the system:
Validation Rules.
Formatting Rules.
Validation Rule allows checking the value against some custom logic and show validation message if the value is incorrect. For example, the start date cannot be later than the end date of the campaign.
Formatting Rule allows applying custom CSS formatting to the field that depends on its value. For example, change the color of the item's status.
Configuration
The Rules can be configured in the Module > Rules settings.
The Rule Configuration window
Parameter | Description |
Active | Allows to enable/disable the rule |
Name | Name of the rule |
Description | Explanation of the rule logic (optional) |
Type |
|
The JSON that defines the fields the rule to be applied to and the custom logic. The structure is the same for both rules types | |
The JSON that defines the behavior of the field when the rule is applied. It depends on the rule type | |
Sort Order | Defines the order of displaying rules in the list on Rule Configuration page |
Rule JSON Contents
This configuration is the same for all rule types. It defines the field and conditions to match.
{
"type": "group",
"id": "9a99988a-0123-4456-b89a-b1607f326fd8",
"children1": {
"a98ab9b9-cdef-4012-b456-71607f326fd9": {
"type": "rule",
"id": "a98ab9b9-cdef-4012-b456-71607f326fd9",
"properties": {
"field": "FD_5",
"operator": "less",
"value": [
"FD_10"
],
"valueSrc": [
"field"
],
"operatorOptions": null,
"valueType": [
""
]
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8",
"a98ab9b9-cdef-4012-b456-71607f326fd9"
]
}
},
"properties": {
"conjunction": "AND",
"not": false
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8"
]
}The only part that should be configured is properties node:
"properties": {
"field": "FD_5",
"operator": "less",
"value": [
"FD_10"
],
"valueSrc": [
"field"
],
"operatorOptions": null,
"valueType": [
""
]
}
Parameter | Description |
|---|---|
"field" | Main field which will be checked for matching the rule logic |
"operator" | A logical operator that will compare the field value with some criteria. The list of supported operators |
"value" | Criteria against which the main field will be compared. It could be:
If the value is an option in the selectbox field, you have to specify its ID, not the actual value. For simple options it is option ID, for module links, it is ID of the linked item |
"valueSrc" | Value source must correspond to the value type:
|
"valueType" | Currently, this parameter is not used by the system, so it doesn't matter what is specified here. Could be just left empty |
Rule JSON Action: Validation
{
"noMatch":{
"message":"End Date cannot be earlier then Start Date"
}
}
Parameter | Description |
|---|---|
"message" | Text to be shown as a validation message if the checked value does not pass the rule logic |
Rule JSON Action: Formatting
{
"fieldsToApply":[
"FD_1", "FD_2", "FD_3"
],
"match":{
"formatting":{
"css":{
"color":"white",
"backgroundColor":"blue",
"borderRadius":"12px"
},
"customProperties":{
"prefixImage":"done_all",
"cell":"inner"
}
}
},
"noMatch":{
"formatting":{
"css":{
"color":"white",
"backgroundColor":"red",
"borderRadius":"12px"
},
"customProperties":{
"prefixImage":"highlight_off",
"cell":"outer"
}
}
}
}
Parameter | Description |
|---|---|
"fieldsToApply" | the list of fields formatting will be applied to, e.g. "FD_1", "FD_2", "FD_3" |
"match" | Defines formatting to be applied if the field value passed the rule logic |
"noMatch" | Defines formatting to be applied if the field value failed the rule logic. This section is optional for the formatting rule |
"css" | Includes CSS properties for formatting, e.g. color, backgroundColor, border etc. |
"prefixImage" | Additional property for displaying the icon as a value prefix. The set of supported icons |
"cell" | Defines to which element the formatting will be applied. It is noticeable in the table-view search result.
|
Known limitations
Formatting rules with a following CSS property will not be applied:
white-space:pre-wrap.Formatting is not applied to checkboxes/radio buttons on item infosheet.
Supported Operators for Rules
Operator | Applicable to | Description | JSON (properties only) |
|---|---|---|---|
greater | Date, Integer, Decimal, Calculation | Compare a field with a static value or another field | Compare with value: Compare with field: |
less | |||
greater_or_equal | |||
less_or_equal | |||
equal | Date, Integer, Decimal, Calculation, Text, Module Link, Simple Option. Please note, for option fields only compare with option ID is supported, not with another field. e.g. FD_15 = 57 (57 - id of status "Completed"), but not FD_15 = FD_17 | ||
not_equal | |||
unique | Date, Integer, Decimal, Text, Module Link (single + multiple option), Simple Option | Checks that specified sequence of fields is unique in the module items | |
in | Date, Integer, Decimal, Calculation, Text, Module Link, Simple Option | Checks if the field value matches one or more values. Please, note that for the field with options, option ID must be specified as a value. Only valueSrc='value' is supported. valueSrc from 'field' and 'expression' will not work | |
not_in | |||
is_null | Date, Integer, Decimal, Percent, Calculation, Text, Module Link, Simple Option | Checks if the field has an empty value | value, valueSrc, valueType must be empty for this type of operator |
is_not_null | |||
empty | |||
not_empty |
Please, note!
Field-to-field comparison operators 'greater', 'less', 'greater_or_equal', 'less_or_equal', 'equal', 'not_equal' do not support DateCalculationData fields. It (DateCalculationData) is supported only for Field to value or to expression comparison.
When applying operators 'greater', 'less', 'greater_or_equal', 'less_or_equal', 'equal', 'not_equal' the field with empty value the rule will always evaluate to FALSE as empty value cannot be normally compared. If you need to handle this, use 'is_null'/'empty' operator check in conjunction.
Static date in value can be specified in ISO 8601 format. It is strongly recommended to specify static dates with an explicit timezone in the rules:
2019-02-20T08:00:00ZUTC timezone with 0 offset.
2019-02-20T08:00:00+02:00UTC+2:00 timezone.
2019-02-20T08:00:00-05:30UTC-5:30 timezone.If timezone is not explicitly specified the time will be evaluated respecting end user time zone which might be different from the timezone of the site or user who created the rule. This can lead to unpredictable results and cannot be handled reliably.
Comparison between decimal and integer numeric field types is not supported. Nevertheless, decimal and percent fields are perfectly comparable.
Functions in Rules
It is possible to use a formula as a value for comparison. The formula may include the math operators, numerics, and functions. The valueSrc must be specified as expression in this case.
Function | Description | Example |
CURRENT_TIMESTAMP() | Returns the current time in milliseconds. Math operators not supported. Suggested to use addDate() function or separate calculation field. | |
startOfPeriod(FD_, ) | Return date rounded up to specified unit: 01-01-yyyy if years; 01-MM-yyyy if months; Monday of the week if weeks; hours, mins are truncated if days | |
ROUND_UP_BY_FIELD_DATA(FD_) | Round the date argument to the precision of the date in the field in question (that is on the left side of comparison clause). Not recommended to use as the logic is not obvious. Use startOfPeriod() instead. | |
addDate(FD_, , ) | Add a number of specified date units to a date and return a new date. | |
Unique Validation
It is possible to validate than the combination of values in chosen fields is unique across the module. For that, use unique operator and specify the fields to be checked as a unique combination. Note, in this case, you have to specify one field as the main field and additional fields as values to compare.
{
"type": "group",
"id": "9a99988a-0123-4456-b89a-b1607f326fd8",
"children1": {
"a98ab9b9-cdef-4012-b456-71607f326fd9": {
"type": "rule",
"id": "a98ab9b9-cdef-4012-b456-71607f326fd9",
"properties": {
"field": "FD_6317",
"operator": "unique",
"value": [
"FD_6318",
"FD_6319",
"FD_6320"
],
"valueSrc": [
"field",
"field",
"field"
],
"operatorOptions": null,
"valueType": [
"date",
"date",
"date"
]
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8",
"a98ab9b9-cdef-4012-b456-71607f326fd9"
]
}
},
"properties": {
"conjunction": "AND",
"not": false
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8"
]
}
Rule Conjunction
It is possible to combine several rules into one using AND/OR conjunction logic. For example, to validate that the date matches some date interval, .e.g. from 2019-07-01 to 2019-08-01 such combined rule with AND conjunction can be used:
{
"type": "group",
"id": "9a99988a-0123-4456-b89a-b1607f326fd8",
"children1": {
"a98ab9b9-cdef-4012-b456-71607f326fd9": {
"type": "rule",
"id": "a98ab9b9-cdef-4012-b456-71607f326fd9",
"properties": {
"field": "FD_4249",
"operator": "less",
"value": [
"2019-08-01T08:00:00Z"
],
"valueSrc": [
"value"
],
"operatorOptions": null,
"valueType": [
"date"
]
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8",
"a98ab9b9-cdef-4012-b456-71607f326fd9"
]
},
"a9bbbaa8-0123-4456-b89a-b16bb8078746": {
"type": "rule",
"id": "a9bbbaa8-0123-4456-b89a-b16bb8078746",
"properties": {
"field": "FD_4249",
"operator": "greater",
"value": [
"2019-07-01T08:06:15.015Z"
],
"valueSrc": [
"value"
],
"operatorOptions": null,
"valueType": [
"date"
]
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8",
"a9bbbaa8-0123-4456-b89a-b16bb8078746"
]
}
},
"properties": {
"conjunction": "AND",
"not": false
},
"path": [
"9a99988a-0123-4456-b89a-b1607f326fd8"
]
}Validation Rules for different date accuracy formats
Date field can be configured with different skeletons which can show date with different accuracy (time, day, week, month, year):
dd-MM-YYYY;
mm-YYYY;
dd-MM-YYYY hh:mm;
etc.
Validation rules can be applied to fields with different accuracies.
Default behavior
For example, comparison 10-2021 (MM-YYYY) < 22-10-2021 (dd-MM-YYYY) will return true, as less precise dates are evaluated as beginning of the period by default. In this case, 10-2021 will be evaluated as 01-10-2021 (first day of the month), so 01-10-2021 < 22-10-2021 is true.
Custom behavior
You can use startOfPeriod(FD_, ) formula if you need to get specific behavior. The formula will round the date argument to the specified accuracy i.e. beginning of the period.
For example, comparison 10-2021 < startOfPeriod(22-10-2021, 'months') will return false. As date units are specified as 'months', the formula will round the date argument to beginning of the month i.e. startOfPeriod(22-10-2021, 'months') → 01-10-2021. So 01-10-2021 < 01-10-2021 is false.