System data types

Forms, widgets, business process tasks, and other areas use fields of different types. Choose the field type based on the data you need to store, pass, and display. For example, use the String type for a comment and the Money type for a contract amount.

This article describes the purpose, settings, and limitations of data types. It also gives recommendations on which type to choose for your task.

Only system administrators can add fields to forms, pages, and process context.

To learn more about adding fields to forms, see Context tab. To learn about working with data types in scripts, see BRIX TS SDK.

Overview of available field types

The table briefly describes the use and features of all field types available in BRIX.

How to choose between field types

Some field types are similar in use but differ in capabilities and limitations. Here are some tasks you can solve with different field types.

Choose a field for selecting options from a list

To give users a list of options to choose from, you can use fields of the Category and App types.

Choose a field for organizing data

You can organize related data on a form. For example, in an order card, you can enter the product, unit of measure, quantity, and so on separately for each line item. To do this, you can use fields of the App and Table types.

Descriptions of field types

Here is how to use and configure all available data types.

String

This type is used to add text information.

The content can be displayed as a string or text. Moreover, the following options are available:

• Hidden. Used to hide data, such as a password, with special characters. Users can view the value while entering or editing it by clicking the strikethrough-eye icon . In the app item view form, the text is hidden and the view icon is unavailable.
• Markdown. Allows you to format the text you enter. Read more in the Markdown article.

Apart from general settings, this type has an additional setting:

• Validators. Here you can set a template to validate the text that the user enters.
• Input mask. An input mask is a set of regular expressions. Only expressions without flags are available in masks. Read more about writing regular expressions in the MDN Web Docs documentation.
• Message shown when the input does not comply with the mask. Write a message shown when the user enters text that doesn’t comply with the input mask. Read more in the Create input masks for Strings using regular expressions article.
• By default. In the Advanced mode of form settings for the Text and Markdown options, you can specify information that will appear in the input field, such as filling instructions. While working with the field, the user can edit the added text.
   
  For the Markdown option, a preview of the text with applied formatting is available both when setting up the field and while filling it in.

Number

This field is used for entering numbers. It is not possible to enter characters other than digits.

Important: For money amounts and financial calculations, use the Money field type. Calculations with decimal numbers can be inaccurate. To learn more, see Inaccurate calculations in JavaScript.

When adding a Number field, choose:

• Integer or Non-integer. Here you can select the number format.
• Maximum number of digits after separator. This option is available only for non-integers and allows you to specify how many decimal places will be displayed on the form. The limit is selected from the list ranging from two to ten. Let’s say a field is calculated using a formula, and you set the maximum number to digits after separator to 2. If the result of the calculation is 3.14159, only 3.14 will be displayed on the form.
  If a user types the number manually on the create or edit form, they will not be able to enter more decimal places than specified by the limit.

Calculations involving decimal numbers may be inaccurate due to how JavaScript runs in the user’s browser and Node.js on the server.

Yes/No switch

This type adds a checkbox or a radio button that allows the user to mark one of two options.

The default options are Yes and No, but you can rename them.
To display one of the values on the form by default, select the check box next to it. If necessary, you can change the field value on the form.

Choose a selection type:

• Checkbox

• Radio button

You can configure the selection type you chose when creating the field. To do that, open the Form Settings, select the field, and change the type.

When developing interfaces, you can use the Checkbox widget, which displays a Yes/No Switch variable as a checkbox with descriptive text to the right. For example, add the widget to a form or page if the description is long and needs to fit on a single line.

Date/time

This type is used to add a date and/or time to a form.

To configure the field:

1. Select the display format for the value:

• Date/time. The user will need to specify a date and time.
• Date. The user will need to specify only a date. The time is automatically set to 00:00.
• Time. The user will need to specify only the time.

2. Enable the following additional options:

• Set current date and time. The current date and time will be specified in the field by default. If you select this option for a business process variable, the date of the process start will be specified in the field.
• Do not require to specify time. For the Date/time option, you can make the time optional.
  

You can also define the default time:

• • Day Start. The default time will be 12:00 AM.
  • Day End. The default time will be 11:59 PM.

• Use a fixed timezone. Enable this option so that the date and time in the field are displayed in the same time zone for all users. Select it from the drop-down list. When entering and viewing a value, it is displayed to the right of the field.
  

Category

This type lets you set up a field for choosing one or more options from a list. You can:

• Set a fixed list of options in the field settings. For example, payment methods.
• Generate options dynamically with a script. For example, get the app statuses and let the user choose one of them. When the statuses change, the list of options updates automatically. To learn more about working with the Category data type in scripts, see BRIX TS SDK.

Note that you can also give users a list of options with an App field. In that case, each option is a separate item. To compare these field types, see Choose a field for selecting options from a list.

Here is how a Category field is set up:

1. Specify a name and determine the number of options by selecting Single or Multiple.
2. The way the values are displayed on the form varies depending on the selected option.

For the Single option, you can specify a display option:

• List. Show selectable options as a drop-down menu.
  
• Radio buttons. Show all selectable options at once.
  

For the Multiple option, one display option is available — a list of options with the ability to select multiple ones.

3. Add the values the user will see, and select the checkbox next to the option that is selected by default in the field.
    
   If the options are generated by a script, you can skip this setting.
4. Check the box next to the option that will be selected by default in the field.

In a Category field, you can fill out the selection options using scripts, for example, by creating a dynamic list from app statuses. The statuses are stored in a variable and passed to the field as an array of values. Any changes to the app automatically update the list, eliminating the need to edit it manually.

For more information on setting up a dynamic list of options in a Category field, see BRIX TS SDK.

Money

Use this field to enter amounts with a currency code.

Use Money for monetary amounts and financial calculations because it supports accurate calculations in scripts with the addm() method. See the BRIX TS SDK  for details.

To learn why you should not store money values in Number fields, see Inaccurate calculations in JavaScript.

Here are the settings for the Money field type:

• Currency. Select the currency type from the drop-down list to the right of the field name. You can change the currency when you edit the field after saving. However, the values entered by users before that will not change until somebody edits the field and saves the data. The currency names and codes are in accordance with the ISO 4217 standard.
• Digits after decimal point to be displayed. Specify the number of digits to be displayed after the decimal point on an app item form. This feature is available for integers as well. For example, if you enter 2 in this field, the data on a form will be displayed in the following way: $100.00.
  The maximum number of digits depends on the currency type. If it is exceeded, you see the icon. Hover over it to see the number of digits allowed.

Account

This field type is used to store messenger accounts. An app that has this type of field in its context can be linked with sessions in live chats from the Live Chats workspace.

You can specify the Account type: Telegram, WhatsApp, etc. You can also select Other. This format can be used to store an account not included in the list, for example, an additional email address.

If you select Several, the user will be able to select the account type on their own and add several accounts when entering information in this field on the form.

Phone number

Use this field to enter a phone number.

You can specify the Phone number type: main, home, work, etc.

If you select Several, the user will be able to select the phone number type on their own when entering information in this field on the form.

The Validation level option allows you to determine how the number entered on the form is checked against the format of numbers in the selected country:

• Warn About Invalid Value. If the user enters a number in an incorrect format, the icon will appear to the right of the field. At the same time, the app item with such a value in the field can be saved.
• Forbid Invalid Values. If the number format is incorrect, a warning message will appear below the field. To save the app item, the user needs to correct the phone number.

You can add a phone extension using a separator. For example:

• +14841234567 x1234
• +14841234567 ext 1234
• +14841234567;1234
• +14841234567 # 1234

The view form will display the extension number as follows: +14841234567 x1234.

Email

Use this field to enter an email address.

You can select the Email type: main, home, or work.

If you select Several, the user will be able to select the type on their own.

The Validation level option allows you to how the email address entered on the form is checked:

• Warn About Invalid Value. If the user enters an email address in an incorrect format, the icon will appear to the right of the field. At the same time, the app item with such a value in the field can be saved.
• Forbid Invalid Values. If the address format is incorrect, a warning message will appear below the field. To save the app item, the user needs to correct the address.

When this field is filled in, additional options are available on the view form: the user can quickly proceed to add and send an email to the specified address, as well as copy the email to the clipboard. To do that, click the icon next to the entered email and select the option you need.

• Default Email Client. Select this option to open the page of the main email client installed on your PC. The recipient’s address will be filled out automatically.
• BRIX365. If you linked an email address to the BRIX built-in email client in the Email workspace, you can create and send an email directly in the BRIX interface. The compose window will open if you click it. The To field will be filled in automatically.
• Copy to Clipboard. Copy the email address to the clipboard.

Image

In an Image type field, you can attach a .jpg, .tif, .tiff, .avif, .webp, .gif, .bmp, or .png file. When setting up this field, you can select how many images can be attached to it: One or Many.

If you check the Clip image when uploading box, the user will be able to select an area of the image to display when uploading it.

This is how it is displayed on the form.

Files

A Files type field allows you to attach files of any type, such as invoices, documents, videos, etc.

You can specify if the user can attach One or Many files.

Please note that if you change the type from Many to One, you will be able to keep only one file in the field when editing a previously created item storing various files. Once you save the app item, the excessive files will be removed.

Access to a file is determined by the app data access settings of the app that contains the Files field. To let other users work with the file, you can grant them additional permissions for the item.

To learn about adding and viewing files, available actions, and file version management, see Files data type.

Full Name

This field allows the user to enter the last name, first name, and middle name.

Arbitrary app

This type allows the user to select an item from any app. As a result, the selected item is added to the form as a link.

Specify how many app items the user can select on the form:

• One. Only one item of any app.
• Many. Several items from one or more different apps. For example, three from the Orders app, two from the Clients app, etc.

To add a link to the app item on the form, click the field or the magnifying glass icon and in the search window select the app from the list.

A window with app items for selection will open. If the Many option is enabled, check the boxes next to the items you want to select.

To select another app item, click the recycle bin icon to the right of the link. The field will be cleared.

If the recycle bin icon is not displayed, the field is read-only. It is impossible to change its value.

You can add an Arbitrary App type field to a widget. Then you can use it as a universal component on different forms.

Please note that when you configure input and output variables or bind settings to an Arbitrary App type field, you can specify variables of the following types: Arbitrary App, App, File, or Users.

To learn more about mapping context variables, see Start Process. To learn about linking fields, see Bind a widget option to a context variable.

Link

This field allows displaying a link to a website, a document, or workspace in BRIX, or to other internet sources.

After adding the field to the form, set up:

• Open in a new window. This option is enabled by default. Clicking the link will open a new browser tab.
   
  If you want the link to a resource to open on the current BRIX tab, disable this option. However, a link to an external internet source will always open in a new window.
• Displayed value. Specify a name for the link that users will see on the view form. If you leave this field blank, the URL will be displayed.
• Default. In advanced form configuration mode you can specify a value that appears in the field by default when the user fills it in, such as an address template. The user can edit it.

Table

With the Table field, you can structure data by rows and columns, change its design, and insert special formulas that will perform calculations.

Note that you can also use an App field to store related data. See Choose a field for organizing data for differences and examples.

Learn more about working with fields of this type in Table data type.

Folder

Use this data type to add a folder from the Files workspace. The filled field contains a link to the folder. The user can click it to switch the contents.

In the settings, select how many folders the user can specify in the field: One or Many.

To select the folder in the configured field, use one of the ways:

• Enter the folder name and select the one you need in the drop-down list.
• Click the magnifying glass icon next to the field, in the opened window select a folder and click Accept.

Inside the added folder, the user can:

• View the files of the folder.
• Sort the folder objects by name, date of change, or file size.
• Create a new object: file, subfolder, web-document, or a link to the app item.

Role

In a Role type field, you can specify a user, a group of users, or an org chart item.

Using a Role type field is convenient when you need to specify a whole group of users of an org chart item. You don’t need to select each specific user. You only need to select the necessary group or position.

You can allow employees to specify locked users and those who have received an invitation to the company but have not yet logged in to the field.

Users

In this field, you can select one or more specific system users.

After adding the field to the form, specify the settings:

• Enter the field name and code.
• Select the number of users you can specify in the field: One or Many.

For the Users (One) property in the interface designer, you can place nested fields, such as Full Name, Position, etc., on a widget template or app form.

For the Users (Many) type property, you can configure search by parameters and select users from the list by clicking the magnifying glass icon.

• Check the following options:

• • Show locked users and Show invited users. The employees will be able to specify locked users and  those who have received an invitation to the company but have not yet logged in in the field.
  • Add filter. Configure conditions for filtering entries when selecting users in the field. For example, to show only employees of a certain position. Read more about it in the Add a filter for users and app items on the item form article.

App

This type is used to specify one or multiple items from a particular app. In a filled field, a link to the related item is displayed. The user can click it to open the item page.

Note: When configuring a list of options, an App field works similarly to a Category field. To organize related data, it can be used similarly to a Table field. See How to choose between field types for differences and examples.

Read more in the App data type article.

App type

This field is used to specify system apps. During its configuration, you can define the number of apps available for selection: One or Multiple.

The field stores links to apps, which can be used in scripts. These links consist of two parts:

• namespace. The code of the workspace where the app is located.
• code. The app code.

For example, this kind of field can be used in custom modules designed for tracking changes in app items or for integration with third-party services.

Let's say you added a property of the App type (Multiple) to a module for integration with Jira. Then, when configuring the module, you can specify which apps have their items synchronized with data in Jira.

Event

You can use this data type in the context of a custom widget to send an event from a child widget to a parent one. Events are a button click, data entry in a field, etc. When placing a widget on a form or a page, you can find a custom event in the widget settings on the Events tab. You can work with it in the same way as with system events available by default.

In this way, you can set up a script to run in the parent widget when an action occurs in the child widget. For example, if in the child widget a field value changes or the user clicks a button, then calculations with a formula or data filtering are performed in the parent widget.

To do this, you need to add an Event type variable in the child widget and link a script to it in the parent widget. Then the following happens:

• In a child widget, it records an event, for example, the user clicks a button.
• In a parent widget, it starts an action, for example, data filtering is performed after clicking a button.

You can read more information about the property of the Event type and how to use it in BRIX TS SDK. See the use cases with this data type in the Send an event from a child widget to a parent one and Send an event between two child widgets articles.

Arbitrary type

You can use this type to pass or store arbitrary data in the context. You can read more about it in BRIX TS SDK. You can use this type as an auxiliary variable in scripts. For example, use it to record the results of a client script to create a dynamic form. For more information about this example, read the Use business process activities article.

Report

A report is a system component that displays data from several source apps in the form of a table. For example, in the Order Register report you can link different apps of the system and display information about an order, customer, contract, and invoice. Read more in Reports in BRIX.

The Report type field allows to add a link to the report created in the system to the app form or page. When you click on the link, the page with the configured report table will be opened.

Creating a Report type field is available only in the interface designer on the Context tab.

To add a Report type field:

1. In the app, enable advanced form setting mode.
2. Go to the interface designer of the selected app form or page and click +Add on the Context tab.
3. Specify a name and property type, select the report created in the system, and click Create.

Now you will be able to refer to the fields of the selected report in scripts using TS SDK methods or add a link to the report on a form or page.

4. Click the Template tab, select Properties in the right panel, and drag the Report type property to the field to be modeled.
5. In the opened window, name the field on the form and click Save.
6. To edit the report link name, change the field name on the Context tab.
7. Save and publish the configured form or page.

For the Report type field, the Read-only option is enabled. Users will be able to navigate to the report page using the specified link, but will not be able to change the field value.