Custom fields

Custom fields let your organization record information Modulix does not track out of the box: a cost center on departments, an employee number on users, a contract type on companies. You define them once, and they appear in the forms, details and lists of that kind of record, in imports and exports, and in the API. No code is needed.

Before you begin

• The Custom Fields module must be enabled. See Modules.
• To define fields, you need Define custom fields (custom-fields.field.manage). Owners and administrators have it by default.
• Custom field values have no permissions of their own. Anyone who can view a record can see its custom field values, and anyone who can edit the record can change them.

Key concepts

• Record type: the kind of record a field belongs to, for example User, Contact, Company, Organization unit or Note. The core and each enabled module declare which of their record types accept custom fields.
• Key: the technical name of a field, used by the API, imports and exports, for example cost_center.
• Archived field: a field hidden from forms and lists. Its values are kept, and you can restore it.

The Custom fields page

In the sidebar, under Administration, select Custom fields.

On the left, Record types lists every record type of the core and of your enabled modules, with the module it belongs to and its number of fields. Select one to see its fields on the right.

The custom fields of a record type.

The table lists the fields in the order they appear in forms, with their label, key, help text, Type and whether they are Required. Archived fields are hidden; when a record type has some, turn on Show archived (count) to see them.

Field types

Type	What people enter
Text	A single line of text.
Long text	Several lines of text.
Number	A whole or decimal number, with optional bounds.
Money	An amount in a currency.
Checkbox	Yes or no.
Date	A calendar date.
Dropdown	One value from a list.
Multi-select	Several values from a list.
Link	A web address (http or https).
Email	An email address.
Person	A member of the organization.
Record	A record of another type, e.g. a company.

Add a field

1. On the Custom fields page, select the record type.
2. Select Add field. The New field on record type dialog opens.
3. Enter the Label people will see, for example Cost center.
4. Check the Key. Modulix proposes one from the label. It must be lower snake case: lowercase letters, digits and underscores, starting with a letter, for example cost_center.
5. Choose the Type.
6. Optionally enter Help text. It is shown under the input in forms.
7. Fill in the options of the type (see below).
8. Under Behavior, choose:
   • Show in lists: adds a column and a filter to the lists of this record type.
   • Required: records cannot be saved without a value.
   • Default value: prefilled when a record is created.
9. Select Add field. Modulix shows "Label added".

Adding a Dropdown field with choices.

warning

The record type, the Key and the Type cannot be changed once the field exists. For Money fields the Currency, and for Record fields the record type it Points to, are fixed too. Choose them carefully.

Options by type

Type	Options
Text	Maximum length: 255 characters by default, up to 1,000.
Long text	Maximum length: 5,000 characters by default, up to 20,000.
Number	Minimum, Maximum, and Decimal places (0 for whole numbers).
Money	Currency (your organization's currency by default), Minimum and Maximum. Amounts accept the currency's decimals, for example 2 for CAD, 0 for JPY.
Dropdown and Multi-select	Choices: select Add choice for each value, and use the arrows to order them. Up to 200 choices.
Record	Points to: the type of records people pick, for example Company.

Choices keep their stored value when you rename their label, so renaming a choice does not change existing records. If you remove a choice, records using it keep it until they are edited.

Where custom fields appear

• Forms: an Additional fields section in the create and edit forms of the record. For users, it is in the Add user and Edit dialogs of the Users page. Required fields block saving until they have a value, including on records that existed before the field was added: they are checked the next time someone edits the record.
• Record pages: an Additional information card on records that have a details page, such as organization units.
• Lists: with Show in lists, a column and a filter in the lists that support it, such as contacts, companies and users.
• Imports and exports: each field is a column of its own. See Import and export.
• API: records carry their custom field values. See the REST API page for developers.

Custom fields in a record's form.

Change, reorder, archive or delete a field

Select the label of a field, or the actions button (…) at the end of its row, then:

Action	What it does
Edit	Changes the label, help text, options, choices, Required, Default value and Show in lists. Select Save changes.
Move up / Move down	Changes the order of fields in forms and lists.
Archive	Hides the field everywhere. Values are kept.
Restore	Brings back an archived field with its values. Turn on Show archived to find it.
Delete	Deletes the field and all its values, permanently.

Before deleting, the Delete label? dialog counts the records that have a value, for example "12 records have values for this field. They will be deleted permanently." If you might need the values later, archive the field instead. To confirm, select Delete field.

Settings

In Settings, section Custom Fields:

Setting	Default
Maximum fields per record type (archived fields included)	50 (between 1 and 200)

Permissions

Permission	What it allows	Granted by default to
custom-fields.field.manage (Define custom fields)	Open the Custom fields page; add, change, reorder, archive and delete fields.	Owner, Administrator

Tips and limits

• If the list of record types says No record types available, enable a module that supports custom fields, such as Organization Structure or Notes.
• Use Person rather than Text for people: values stay linked to the member, and only members of the organization can be chosen.
• On very large record types (hundreds of thousands of records), filtering and searching on custom fields can be slow.