Documentation

Creatio development guide
PDF
This documentation is valid for Creatio version 7.16.0. We recommend using the newest version of Creatio documentation.

Custom business rules of the mobile application

Glossary Item Box

Introduction

Business rules are a standard Creatio mechanism that enables you to set up the page field behavior on the record edit page. You can set if the field is visible, required/optional, available for editing and filtering the values. More information about business rules can be found in the “Business rules in mobile application” article.

In the mobile application you can add business rule that implements custom logic (custom business rule). The Terrasoft.RuleTypes.Custom method is provided for this type of business rules.

Properties of the config configuration object

When adding a custom business rule via the Terrasoft.sdk.Model.addBusinessRule(name, config) method you can use properties of the config configuration object of the base business rule (“Business rules in mobile application”). In addition, the executeFn property is also provided.

Properties used in the config configuration object:

  • ruleType – rule type. For the custom rules it should contain the Terrasoft.RuleTypes.Custom value.
  • triggeredByColumns – array of columns which initiates trigging of the business rule.
  • events – array of events determining the start time of the business rule. It should contain values from the Terrasoft.BusinessRuleEvents enumeration. Default value: Terrasoft.BusinessRuleEvents.ValueChanged.
  • executeFn – a handler function that contains the user logic for executing the business rule.

The Terrasoft.BusinessRuleEvents enumeration contains following values:

  • Тerrasoft.BusinessRuleEvents.Save – the rule trigs before saving the data.
  • Terrasoft.BusinessRuleEvents.ValueChanged – the rule trigs after changing the data (at modification).
  • Terrasoft.BusinessRuleEvents.Load – the rule trigs when the edit page is opened.

Properties of the executeFn handler function

The handler function declared in the executeFn property should have the following structure:

executeFn: function(record, rule, checkColumnName, customData, callbackConfig, event) {
}

Function parameters:

  • record – a record for which the business rule is executed.
  • rule – an instance of the current business rule.
  • checkColumnName – the name of the column that triggered the business rule.
  • customData – an object that is shared between all rules. Not used. Left for compatibility with previous versions.
  • callbackConfig – a configuration object of the Ext.callback asynchronous callback.
  • event – an event that triggered the business rule.

After the completion of function operation it is necessary to call either the callbackConfig.success or callbackConfig.failure. The following call options are recommended:

Ext.callback(callbackConfig.success, callbackConfig.scope, [result]);
Ext.callback(callbackConfig.failure, callbackConfig.scope, [exception]);

Where:

  • result – the returned boolean value obtained when the function is executed (true/false).
  • Exception – the exception of the Terrasoft.Exception type, which occurred in the handler function.

In the source code of the handler function, you can use the following methods of the model passed in the record parameter:

  • get(columnName) – to get the value of a record column. The columnName argument should contain the column name.
  • set(columnName, value, fireEventConfig) – to set the value of the record column. Parameters:
    • columnName – the name of the column.
    • value – the value assigned to the column.
    • fireEventConfig – a configuration object to set the properties that are passed to the column modification event.
  • changeProperty(columnName, propertyConfig) – for changing column properties except its value. The columnName argument should contain the column name and the propertyConfig object that sets the column properties. Possible properties of the propertyConfig object:
    • disabled – activity of the column. If true, the control associated with the column will be inactive and disabled for operation.
    • readOnly – “read only” flag. If true, the control associated with the column will be available only for reading. If false – the access for reading and writing.
    • hidden – column visibility. If true, the control associated with the column will be hidden. If false – the control will be displayed.
    • addFilter – add filter. If the property is specified, it should have a filter of the Terrasoft.Filter type that will be added to the column filtration. Property is used only for lookup fields.
    • removeFilter – remove the filter. If the property is specified, it should have a name of the filter that will be removed from the column filtration. Property is used only for lookup fields.
    • isValid – flag of column validity. If the property is specified, it will change the validity flag of the control associated with the column. If the column is invalid, then this can mean canceling of saving the record, and can also lead to the determining the record as invalid.

For example, for changing the properties (but not the values) of the “Owner” column:

record.changeProperty("Owner", {
    disabled: false,
    readOnly: false,
    hidden: false,
    addFilter: {
        property: "IsChief",
        value: true
    },
    isValid: {
        value: false,
        message: LocalizableStrings["Owner_should_be_a_chief_only"]
    }
 });

Examples of the custom business rule

Example 1

Highlight the field with the result of the activity, if its status is “Completed”, the [result] field is not filled and the ProcessElementId column has a value.

// Rule for the activity edit page.
Terrasoft.sdk.Model.addBusinessRule("Activity", {
    // The name of the business rule.
    name: "ActivityResultRequiredByStatusFinishedAndProcessElementId",
    // Business rule type: custom.
    ruleType: Terrasoft.RuleTypes.Custom,
    //The rule is initiated by the Status and Result columns.
    triggeredByColumns: ["Status", "Result"],
    // The rule will work before saving the data and after changing the data.
    events: [Terrasoft.BusinessRuleEvents.ValueChanged, Terrasoft.BusinessRuleEvents.Save],
    // Handler function.
    executeFn: function(record, rule, column, customData, callbackConfig) {
        // A flag of the validity of the property and the rule.
        var isValid = true;
        // The value of the ProcessElementId column.
        var processElementId = record.get("ProcessElementId");
        // If the value is not empty.
        if (processElementId && processElementId !== Terrasoft.GUID_EMPTY) {
            // Set the validity flag.
            isValid = !(record.get("Status.Id") === Terrasoft.Configuration.ActivityStatus.Finished &&
                Ext.isEmpty(record.get("Result")));
        }
        // Change the properties of the Result column.
        record.changeProperty("Result", {
            // Set the column correctness indicator.
            isValid: {
                value: isValid,
                message: Terrasoft.LS["Sys.RequirementRule.message"]
            }
        });
        // Asynchronous return of values.
        Ext.callback(callbackConfig.success, callbackConfig.scope, [isValid]);
    }
});

Example 2

Adding and deleting filtration by a custom logic.

Terrasoft.sdk.Model.addBusinessRule("Activity", {
    name: "ActivityResultByAllowedResultFilterRule",
    position: 1,
    ruleType: Terrasoft.RuleTypes.Custom,
    triggeredByColumns: ["Result"],
    events: [Terrasoft.BusinessRuleEvents.ValueChanged, Terrasoft.BusinessRuleEvents.Load],
    executeFn: function(record, rule, column, customData, callbackConfig) {
        var allowedResult = record.get("AllowedResult");
        var filterName = "ActivityResultByAllowedResultFilter";
        if (!Ext.isEmpty(allowedResult)) {
            var allowedResultIds =  Ext.JSON.decode(allowedResult, true);
            var resultIdsAreCorrect = true;
            for (var i = 0, ln = allowedResultIds.length; i < ln; i++) {
                var item = allowedResultIds[i];
                if (!Terrasoft.util.isGuid(item)) {
                    resultIdsAreCorrect = false;
                    break;
                }
            }
            if (resultIdsAreCorrect) {
                var filter = Ext.create("Terrasoft.Filter", {
                    name: filterName,
                    property: "Id",
                    funcType: Terrasoft.FilterFunctions.In,
                    funcArgs: allowedResultIds
                });
                record.changeProperty("Result", {
                    addFilter: filter
                });
            } else {
                record.changeProperty("Result", {
                    removeFilter: filterName
                });
            }
        } else {
            record.changeProperty("Result", {
                removeFilter: filterName
            });
        }
        Ext.callback(callbackConfig.success, callbackConfig.scope, [true]);
    }
});

Example 3

An example of the logic for dropping negative values to 0.

Terrasoft.sdk.Model.addBusinessRule("Opportunity", {
    name: "OpportunityAmountValidatorRule",
    ruleType: Terrasoft.RuleTypes.Custom,
    triggeredByColumns: ["Amount"],
    events: [Terrasoft.BusinessRuleEvents.ValueChanged, Terrasoft.BusinessRuleEvents.Save],
    executeFn: function(model, rule, column, customData, callbackConfig) {
        var revenue = model.get("Amount");
        if ((revenue < 0) || Ext.isEmpty(revenue)) {
            model.set("Amount", 0, true);
        }
        Ext.callback(callbackConfig.success, callbackConfig.scope);
    }
});

Example 4

Example of generating the activity header for the FieldForce solution.

Terrasoft.sdk.Model.addBusinessRule("Activity", {
    name: "FieldForceActivityTitleRule",
    ruleType: Terrasoft.RuleTypes.Custom,
    triggeredByColumns: ["Account", "Type"],
    events: [Terrasoft.BusinessRuleEvents.ValueChanged, Terrasoft.BusinessRuleEvents.Load],
    executeFn: function(record, rule, column, customData, callbackConfig, event) {
        if (event === Terrasoft.BusinessRuleEvents.ValueChanged || record.phantom) {
            var type = record.get("Type");
            var typeId = type ? type.get("Id") : null;
            if (typeId !== Terrasoft.Configuration.ActivityTypes.Visit) {
                Ext.callback(callbackConfig.success, callbackConfig.scope, [true]);
                return;
            }
            var account = record.get("Account");
            var accountName = (account) ? account.getPrimaryDisplayColumnValue() : "";
            var title = Ext.String.format("{0}: {1}", Terrasoft.LocalizableStrings.FieldForceTitlePrefix, accountName);
            record.set("Title", title, true);
        }
        Ext.callback(callbackConfig.success, callbackConfig.scope, [true]);
    }
});
© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?