Customize fields (Classic UI)

Level: intermediate

Add a field

Creatio lets you add the following field types:

• simple field
• image field
• calculated field
• multicurrency 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 object column
• use a new object column

Add a simple field in the Section Wizard

Instructions: Set up page fields (user documentation).

Add a simple field in Creatio IDE

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

1. Create a replacing view model schema of the record page that contains the field. Instructions: Implement a replacing module.

2. Set up the field layout.

   1. Add the diff schema section.
   2. Add a configuration object that contains the layout settings of the page fields.

3. Publish the schema.

As a result, a simple field based on an existing object column will be added using Creatio IDE.

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

1. Create a replacing object schema. Instructions: Implement a replacing object.

2. Add a column that corresponds to the page field to the schema. Instructions: Specify the object ID for custom parent object.

3. Create a replacing view model schema of the record page that contains the field. Instructions: Implement a replacing module.

4. Add a localizable string that contains the field name to the replacing view model schema (optional). Instructions: Operations with localizable resources.

5. Set up the field layout.

   1. Add the diff schema section.
   2. Add a configuration object that contains the layout settings of the page fields.

As a result, a simple field based on a new object column will be added using Creatio IDE.

Add an image field

1. Create a replacing object schema. Instructions: Implement a replacing object.

2. Add an image column to the schema.

   1. Go to the properties area → Columns node’s context menu → → Other → Image Link.

   2. Fill out the column properties.

      Property	Property value
      Code	The image code. Starts with the prefix.
      Title	The image title

3. Select the image column to use as the object image.

   1. Go to the replacing object schema → Object settings property block.

   2. Fill out the image properties.

      Property	Property value
      Image	Select the image column as the object image.

4. Create a replacing view model schema of the record page that contains the field. Instructions: Implement a replacing module.

5. Add a localizable string that contains the field name to the replacing view model schema (optional). Instructions: Operations with localizable resources.

6. Add an image to the schema.

   1. Go to the properties area → Images node’s context menu → .

   2. Fill out the image properties.

      Property	Property value
      Code	The image code
      Image	Upload the image file

   3. Click Add.

7. Implement the business logic that adds the default image to a new knowledge base article.

   1. Add the methods schema section.

   2. Implement the following methods.

      Method	Method description
      getPhotoSrcMethod()	Receives the image by link.
      beforePhotoFileSelected()	Called before the image selection box opens.
      onPhotoChange()	Called upon the image change.
      onPhotoUploaded()	Saves the link to the changed image in the object column.

8. Set up the image field layout.

   1. Add the diff schema section.

   2. Add a configuration object that contains the layout settings of the page fields. To add an image field to the page, use the auxiliary PhotoContainer wrapper container that has the "image-edit-container" class.

   3. Implement the following properties in the values property.

      Property	Property description
      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.

As a result, an image field will be added.

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:

1. Create a replacing object schema. Instructions: Implement a replacing object.

2. Add a column that corresponds to the page field to the schema. Instructions: Specify the object ID for custom parent object.

3. Create a replacing view model schema of the record page that contains the field. Instructions: Implement a replacing module.

4. Add a calculated field.

   1. Add the attributes schema section.

   2. Add an attribute to set dependencies.

   3. Declare the dependencies property. The property contains the array of configuration objects. The dependencies property includes the following properties.

      Property	Property description
      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.

5. Implement the business logic.

   1. Add the methods schema section.

   2. Implement the following methods.

      Method	Method description
      	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.

6. Set up the field layout.

   1. Add the diff schema section.
   2. Add a configuration object that contains the layout settings of the page fields.

As a result, a calculated field will be added.

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.

Use multicurrency field to:

• 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:

1. Create a replacing object schema. Instructions: Implement a replacing object.

2. Add a column that corresponds to the page field to the schema. 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. Instructions: Specify the object ID for custom parent object.

   Add one of the following columns:

   • 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

3. Create a replacing view model schema of the record page that contains the field. Instructions: Implement a replacing module.

4. Add the dependencies.

   For a multicurrency field, add the MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities modules as dependencies.

5. Add a multicurrency field.

   1. Add the attributes schema section.

   2. Add the following attributes:

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

   3. Declare the dependencies property. The property contains the array of configuration objects. The dependencies property includes the following properties.

      Property	Property description
      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.

   4. Add the mixins property.

   5. Set MultiCurrencyEditUtilities mixin as property value.

6. Implement the business logic.

   1. Add the methods schema section.

   2. Implement the following methods.

      Method	Method description
      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.

7. Set up the field layout.

   1. Add the diff schema section.

   2. Add a configuration object that contains the layout settings of the page fields.

   3. Implement the following properties in the values property.

      Property	Property description
      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.

As a result, a multicurrency field will be added.

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: Implement a replacing module.

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: Implement a replacing module.

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: Implement a replacing module.

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: Implement a replacing module.

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: Implement a replacing module.

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: Implement a replacing module.

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.
      Lock the record page fields (option 1)

      this.set("IsModelItemsEnabled", false);

      Lock the record page fields (option 2)

      "IsModelItemsEnabled": {
          dataValueType: Terrasoft.DataValueType.BOOLEAN,
          value: true,
          dependencies: [{
              columns: ["PaymentStatus"],
              methodName: "setCardLockoutStatus"
          }]
      }

   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: Implement a replacing module.

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.
      Example that keeps a field and detail unlocked (option 1)

      getDisableExclusionsColumnTags: function() {
          return ["SomeField"];
      }
      getDisableExclusionsDetailSchemaNames: function() {
          return ["SomeDetailV2"]
      }

      Example that keeps a field and detail unlocked (option 2)

      isModelItemEnabled: function(fieldName) {
          var condition = this.get("SomeConditionAttribute");
          if (fieldName === "ExampleField" || condition)) {
              return true;
          }
          return this.callParent(arguments);
      }
      
      isDetailEnabled: function(detailName) {   
          if (detailName === "ExampleDetail") {
              var exampleDate = this.get("Date");
              var dateNow = new Date(this.Ext.Date.now());
              var condition = this.Ext.Date.isDate(exampleDate) && exampleDate >= dateNow;
              return condition;
          }
          return this.callParent(arguments);
      }

   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: Manage an existing additional feature.

Set up the field display conditions

1. Create a replacing object schema. Instructions: Implement a replacing object.

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: Specify the object ID for custom parent object.

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: Implement a replacing module.

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: Implement a replacing module.

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. Instructions: Implement a replacing object.

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: Implement a replacing module.

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: Implement a replacing module.

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: Implement a replacing module.

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)

Configuration elements

Operations with localizable resources

Data-operations (front-end)

Manage an existing additional feature