Skip to main content
Version: 8.1

Customize fields (Classic UI)

Level: intermediate

Types of fields and field operations

Creatio provides the following field types:

  • simple field
  • image field
  • calculated field
  • multicurrency field

Creatio lets you execute the following field operations:

  • implement the field validation
  • set the default field value
  • set up the field requirement
  • set up value filtering for a lookup field
  • set up the field locking conditions
  • set up the field locking exceptions
  • set up the field display conditions
  • add automatic field numbering
  • add an info button to the field
  • add a tooltip to the field
  • calculate the date difference between the fields

Add a field

You can add a field using the following tools:

  • Section Wizard
  • Creatio IDE

Add a simple field

You can add a simple field in the following ways:

  • use an existing column
  • use a new column

Add a simple field in the Section Wizard

To add a simple field in the Section Wizard, follow the instructions in the user documentation article: Set up page fields.

Add a simple field in Creatio IDE

To add a simple field in Creatio IDE using an existing column:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Set up the field layout in the replacing view model schema. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

You can add a simple field in Creatio IDE using a new column in the following ways:

  • Create a replacing object schema and add a column to it.
  • Create a replacing view model schema of the record page that contains the field. Then create an attribute in the view model schema and add a field to the created virtual column.

This article covers one of the ways below.

To add a simple field in Creatio IDE using a new column:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  4. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.
  5. Set up the field position in the replacing view model schema. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

Add an image field

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add an Image Link type column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  5. Add an image to the schema image collection.

  6. Set up the image field in the replacing view model schema.

    1. Implement the following methods in the methods property:

      • the method that receives the image by link
      • the method that is called before the image selection box opens
      • the method that is called upon the image change
      • the method that saves the link to the changed image in the object column
    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications. Use the auxiliary PhotoContainer wrapper container that has the "image-edit-container" class to add an image field to the page. Implement the following properties in the values property of the diff array of modifications:

      • getPhotoSrcMethod(). Receives the image by link.
      • onPhotoChange. Called upon the image change.
      • beforePhotoFileSelected(). Called before the image selection box opens.
      • readonly. Defines whether the image is modifiable.
      • generator. The control generator. Specify ImageCustomGeneratorV2.generateCustomImageControl for the image field.

Add a calculated field

A calculated field is a record page control whose value is calculated based on the status and values of other controls of the page.

In Creatio, calculated fields operate based on subscriptions to attribute change events of the page view model schema. When the column values of the object schema change, the current column value changes.

To add a calculated field to the record page:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Set up the calculated field in the replacing view model schema.

    1. Add a calculated column (attribute) for which to set dependencies to the attributes property. Declare the dependencies property for the attribute. The property contains the array of configuration objects. The dependencies property includes the following properties:

      • columns. An array of column names. The current column value depends on the values of listed columns.
      • methodName. The name of the handler method that is called when the value of at least one of the listed columns changes.
    2. Implement the following in the methods property:

      • The handler method of the column change event. The calculated column depends on the changed column.
      • onEntityInitialized(). An overrided base virtual method. Called after Creatio initializes the object schema of the record page. Call the handler method in the onEntityInitialized() method. The handler method ensures the field is calculated not only when the dependency columns change but also when the record page opens.
    3. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Add a multicurrency field

A multicurrency field is a record page control whose value is calculated based on the status or values of other controls of the page.

Multicurrency field lets you:

  • Enter a monetary amount.
  • Specify the currency of the monetary amount.
  • Record the equivalent of the amount in the base currency specified in Creatio settings.

When the currency changes, Creatio automatically converts the amount based on the currency exchange rates.

To add a multicurrency field to the record page:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the following columns to the replacing object schema:

    • a Lookup type column that stores the currency
    • an exchange rate column
    • a column that stores the total amount in the selected currency
    • a column that stores the amount in base currency

    You can only define a single column in the object schema. The defined column must store the total amount in the selected currency. The rest of the columns can be virtual unless the business task requires their values to be stored in the database. You can define the columns as attributes in the view model schema.

    To do this, follow the guide in a separate article: Develop configuration elements.

  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Add the MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities modules as dependencies to the declaration of the view model class.

  5. Set up the multicurrency field in the replacing view model schema.

    1. Add the following attributes to the attributes property:

      • currency
      • exchange rate
      • total amount
      • amount in base currency
      • exchange rate collection
      • collection for the currency selection button

      Declare the dependencies property for the attributes. The property contains an array of configuration objects. The dependencies property includes the following properties:

      • columns. An array of columns whose values determine the value of the current column.
      • methodName. The name of the handler method that is called when the value of at least one of the listed columns changes.
    2. Add the MultiCurrencyEditUtilities mixin to the mixins property.

    3. Implement the following methods in the methods property:

      • onEntityInitialized(). Overrides the base virtual method. Called after Creatio initializes the object schema of the record page.
      • setCurrencyRate(). Sets the currency exchange rate.
      • recalculateAmount(). Recalculates the total amount.
      • recalculatePrimaryAmount(). Recalculates the amount in base currency.
      • onVirtualCurrencyChange(). Handles the changes to the virtual currency column.
    4. Add a configuration object with the settings that determine the field layout to the diff array of modifications. Implement the following properties in the values property of the diff array of modifications:

      • primaryAmount. The name of the column that contains the amount in base currency.
      • currency. The name of the column that references the currency lookup.
      • rate. The name of the column that contains the exchange rate.
      • generator. The control generator. Specify MultiCurrencyEditViewGenerator.generate for the multicurrency field.

Implement the field validation

Creatio performs validation by checking whether the filled out fields conform to the specified requirements. Page fields are validated at the column level of the page view models. The custom validator method executes the field validation logic.

To implement the field validation:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add a localizable string that contains the validation message to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Set up the field validation in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • The validator method that checks whether the condition is true. Validator is a view model method that matches the value of the view model column to the business requirements. The method must return the object that contains the validation results.

      • If the field validation is successful, the validator method returns an object that contains an empty string.
      • If the field validation is unsuccessful, the validator method returns an object that contains the invalidMessage property. The invalidMessage property contains a message string displayed below the field when a user attempts to enter an invalid value and in the message box when a user attempts to save a page with the field that did not pass the validation.
    • setValidationConfig() is an overrided base method that binds the validator method to the corresponding column of the record page’s replacing view model schema. The setValidationConfig() method calls the addColumnValidator() method. The addColumnValidator() method has the following parameters:

      • the name of the view model column to bind the validator
      • the name of the method that validates the column value

      If you implement the field validation in the replacing view model schema of the base page, call the parent implementation of the setValidationConfig() method before calling the addColumnValidator() method to ensure the validators of the base page fields are initialized correctly.

Set the default field value

Creatio lets you set the default field value in the following ways:

  • at the level of business object columns in the replacing object schema

    When you create a new object, some page fields must be populated with the corresponding values. In this case, specify the values of the corresponding object columns as default values in the Object Designer.

  • in the source code of the replacing view model schema of the record page

    In some cases, you cannot set a default value via the object column properties. For example, the values might be calculated based on the values of other object columns. In this case, you can only set a default field value via coding.

View the record page’s default field value types set at the level of business object columns in the replacing object schema in the table below.

Default value types

Default value type

Description

Constant

You can set a constant default value for the following column types:

  • String.
  • Number.
  • Lookup.
  • Boolean.

System setting

The System settings section contains system settings. You can add a custom system setting to the section. The system setting value is set at the user level, not the application level.

System variable

System variables are global variables that store data about Creatio settings. The system variable value is set at the application core level, not the user level.

To set the default field value:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Set up the default field value in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • onEntityInitialized(). An overrided base virtual method. Called after Creatio initializes the object schema. Call the handler method in the onEntityInitialized() method. The handler method ensures the field value is set when a record page opens.
    • The handler method that calculates the field value.

Make the field required

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the BusinessRuleModule and ConfigurationConstants modules as dependencies to the declaration of the view model class.

  3. Make the field required in the replacing view model schema.

    To do this, take the following steps in the rules property:

    • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
    • Set the property property to REQUIRED. The value marks the column as required. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
    • Specify the execution conditions of the business rule in the conditions array.

Set up the filtering of lookup field values

Creatio lets you set up the filtering of lookup field values in the following ways:

  • use the FILTRATION business rule
  • specify the filters explicitly in the attributes property of the column description

To set up the filtering of lookup field values using the FILTRATION business rule:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the filtering of lookup field values in the replacing view model schema.

    1. Take the following steps in the rules property:

      • Set the ruleType property to FILTRATION. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the autocomplete property to true. The value performs inverse filtering.
    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Set up the filtering of lookup field values by specifying the filters explicitly in the column description to apply arbitrary filtering, sorting, and to add extra columns to the query when displaying the drop-down list.

To set up the filtering of lookup field values by specifying the filters explicitly in the column description:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the filtering of lookup field values in the replacing view model schema.

    To do this, take the following steps in the attributes property:

    • Set the dataValueType property to LOOKUP. The value sets the column data type. The Terrasoft.core.enums.DataValueType enumeration represents the column data types.

    • Specify the configuration object of the lookup field in the lookupListConfig property.

      The lookupListConfig property has the following optional properties:

      • columns. An array of column names added to the query besides the Id column and the primary column for display.

      • orders. An array of configuration objects that determine the order of displayed data.

      • The property that sets the filtering:

        • filter. The method that returns the object of the Terrasoft.BaseFilter class or its inheritor. Creatio applies the returned object to the query.
        • filters. The array of methods that return the collection of the Terrasoft.FilterGroup class.

Add the filters to the collection using the add() method. View the parameters of the add() method in the table below.

Parameters of the add() method

Parameter

Data type

Description

key

String

Key.

item

Mixed

Element. The object of the Terrasoft.BaseFilter class or its inheritor serves as the item parameter. Learn more about setting up filters in a separate article: Data-operations (front-end). By default, the AND operator combines the filters in the collection. If you need to use the OR operator, specify it explicitly in the logicalOperation property of the Terrasoft.FilterGroup object.

index

Number

The index to insert. If the index is not specified, it is not rated.

Lock the field based on specific conditions

Creatio can lock every field and detail of the record page simultaneously if the corresponding conditions are met. This lets you avoid creating a large number of business rules.

You can lock the fields of the following detail types:

  • list detail
  • editable list detail
  • field detail

To lock the field based on specific conditions:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the conditions that lock the field in the replacing view model schema.

    1. Enable locking in the attributes property using the IsModelItemsEnabled attribute.

      You can enable field locking in the following ways.

      • Set the IsModelItemsEnabled attribute to false.
      • Set the IsModelItemsEnabled attribute to the default value.
      • Use the IsEnabled attribute for a field detail.
      this.set("IsModelItemsEnabled", false);
    2. Take the following steps in the rules property:

      • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the property property to ENABLED. The value sets the column availability. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      • Specify the execution conditions of the business rule in the conditions array.
    3. Add a configuration object to the diff array of modifications:

      • Specify the CardContentWrapper global container in the name property to lock all record page fields.
      • Specify the DisableControlsGenerator generator in the generator property of the values property for containers whose fields to lock.
      Example setup of the diff array of modifications
      diff: /**SCHEMA_DIFF*/[
      {
      "operation": "merge",
      "name": "CardContentWrapper",
      "values": {
      "generator": "DisableControlsGenerator.generatePartial"
      }
      }
      ]/**SCHEMA_DIFF*/

Creatio locks detail buttons and menu items that launch detail operations. However, you can still open the object page of an editable list detail. The fields of the object page are locked based on the business rules.

Creatio does not lock the field if it is bound to the enabled property in the diff array of modifications or business rule.

Keep the field unlocked

Creatio lets you keep certain fields and details unlocked.

To specify the field to keep unlocked:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Specify the field to keep unlocked in the replacing view model schema.

    1. Enable locking in the attributes property using the IsModelItemsEnabled attribute.

    2. Implement the methods that return the list of fields and details to keep unlocked in the methods property:

      • getDisableExclusionsColumnTags(). Keeps a column unlocked.
      • getDisableExclusionsDetailSchemaNames(). Keeps a detail unlocked.
      • isModelItemEnabled(). Keeps a column unlocked. Complex exception logic. The method is called for each field. Accepts the name and returns the field availability flag.
      • isDetailEnabled(). Keeps a detail unlocked. Complex exception logic. The method is called for each detail. Accepts the name and returns the detail availability flag.
      getDisableExclusionsColumnTags: function() {
      return ["SomeField"];
      }
      getDisableExclusionsDetailSchemaNames: function() {
      return ["SomeDetailV2"]
      }
    3. Add a configuration object to the diff array of modifications. The object must contain the settings of the CardContentWrapper container that locks the fields.

To disable field locking, use the corresponding toggle of the CompleteCardLockout item on the Feature toggle page. Learn more about the Feature toggle page in a separate article: Feature toggle mechanism.

Set up the field display conditions

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Set up the field display conditions in the replacing view model schema.

    1. Take the following steps in the rules property:

      • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the property property to VISIBLE. The value sets the column visibility. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      • Specify the execution conditions of the business rule in the conditions array.
    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Enable automatic field numbering

Automatic field numbering generates a record number automatically based on the specified template. Automatic numbering is implemented in the Documents, Invoices, and Contracts sections.

You can enable automatic field numbering in several ways:

  • in the front-end
  • in the back-end

Enable automatic field numbering in the front-end

  1. Create the following system settings:

    • [Entity]CodeMask. The object number mask.
    • [Entity]LastNumber. The current object number.

    Entity. The name of the object to whose column to apply automatic numbering. For example, InvoiceCodeMask is the invoice number mask and InvoiceLastNumber is the current invoice number.

  2. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Set up automatic field numbering in the front-end in the replacing view model schema.

    To do this, implement the onEntityInitialized() overrided base virtual method in the methods property. Called after Creatio initializes the object schema. Call the getIncrementCode() handler method of the BasePageV2 base record page schema in the onEntityInitialized() method. The handler method assigns a generated number to the Code field.

    The getIncrementCode() method includes the following parameters:

    • callback. The function that is called after receiving the service response. Pass the response to the corresponding column (attribute).
    • scope. The scope to call the callback function (optional).

Enable automatic field numbering in the back-end

  1. Create the following system settings:

    • [Entity]CodeMask. The object number mask.
    • [Entity]LastNumber. The current object number.

    Entity. The name of the object to whose column to apply automatic numbering. For example, InvoiceCodeMask is the invoice number mask and InvoiceLastNumber is the current invoice number.

  2. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Add a Before record added event to the replacing object schema.

  4. Implement the event subprocess in the business process.

Add an info button to the field

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Attach an info button to the field in the replacing view model schema.

    To do this, attach a configuration object with the settings that determine the info button layout to the page field in the diff array of modifications. Implement the itemType property in the values property of the diff array of modifications. Set the implemented property to Terrasoft.ViewItemType.INFORMATION_BUTTON.

Add a tooltip to a field

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Attach an info button to the field in the replacing view model schema.

    To do this, attach a configuration object with the settings that determine the tooltip layout to the page field in the diff array of modifications. Set up the tooltip in the tip property of the diff array of modifications.

Calculate the date difference between the fields

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Calculate the date difference between the fields in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • onEntityInitialized(). Overrides the base virtual method. Called after Creatio initializes the object schema of the record page.
    • setEndDate(). The auxiliary method that sets the date. Call the getDate() method in the setEndDate() method. The called method retrieves the date.

See also

Set up page fields (user documentation)

Develop configuration elements

Operations with localizable resources

Data-operations (front-end)

Manage an existing additional feature