Custom Fields

Purpose: This article explains how Custom Fields extend Administrate's data model: which records support them, the data types available, permissions, and how custom field values can be used in reporting, communications, imports, and the API.

Administrate offers a robust standard data model to support your training operations. However, it's common to want to store data that isn't included in the default configuration. Custom Fields let you add your own fields to many Administrate records, and the values behave like standard fields: they can be edited on the record, reported on, merged into communications, imported in bulk, and read and written through the API.

This article explains:

• Which records support custom fields
• Creating and configuring a custom field
• The available data types
• Per-role permissions
• Using custom field values in reporting, communications, imports, and the API
• Deleting a custom field safely
• Legacy Contact fields (Custom System Fields)

On this page

• Where custom fields are available
• Configuration
• Data types
• Custom Field permissions
• Using custom field values
• Deleting a custom field
• Legacy Contact fields (Custom System Fields)

Where custom fields are available

Custom fields can be added to most core records, including Accounts, Contacts, Course Templates, Events, Sessions, Learners, Learning Paths, Learning Path learners, Achievements, Stock Items, Training Token issues, Companies, and LMS Content. The left-hand panel of the Custom Fields screen is the authoritative list for your instance, along with the number of fields configured per record type.

Bookings are the exception: they carry Attributes, a separate mechanism managed outside the Custom Fields screen. Attribute values still appear in communication merge fields for booking audiences.

Configuration

Super Users can configure Custom Fields in Control Panel → Custom Fields. Select a record type in the left-hand panel to view its fields, then click Create Field to add a new custom field.

When creating or editing a custom field, you can:

• Set a Name.
• Mark the field as Required. Required is enforced when users edit the record on screen; API and import writes that leave the field out entirely are not blocked, so do not rely on it for completeness in integrations.
• Choose the Data Type and Field Type (see Data types).
• Add permissions per user role (see Custom Field permissions).
• Add a Tooltip to show help text when users hover over the field.
• Set a Unique API Name: a human-readable identifier that integrations can use to look the field up. Both it and the field's underlying key are unaffected by renaming the field's label.

A single Custom Field can be associated with multiple record types. For example, associating a Custom Field with both Course Template and Event allows Events created from a Course Template to default their custom field values from the template. Values copy once, at Event creation, for fields associated with both record types.

Data types

Choice lists keep data consistent and filterable, so prefer a Choice field over free text when the possible values are known, for example a department list or an onboarding wave.

Custom Field permissions

You can restrict access to each custom field per user role:

• None: No visibility or access.
• View: Users can view the field but cannot edit it.
• Edit: Users can view and edit the field.

Once configured, custom fields can be edited later from the same screen.

Using custom field values

Custom field values are usable everywhere standard fields are:

• On the record: the field appears on the record's form for users whose role has access.
• Reporting: custom fields are available as report columns and filters, listed with a "Custom:" prefix. Choice fields filter by their option values.
• Communications: templates can merge custom field values into messages using a bracketed merge field whose key is the field's Unique API Name (or an internal key); the merge field picker lists custom fields alongside standard fields and inserts the right key for you. See Communication Templates.
• Data imports: each custom field gets its own column in import templates, so values can be created and updated in bulk. Date custom fields import in YYYY-MM-DD format. See Importing data into Administrate.
• API: custom field values are readable and writable through the GraphQL API. Fields are addressed by a stable key that renaming does not change, with the Unique API Name as a human-readable way to look fields up.

Deleting a custom field

Caution

Deleting a custom field deletes all data stored in that field. If you may need the data later, consider removing field permissions or deprecating the field instead of deleting it.

Legacy Contact fields (Custom System Fields)

Some instances, particularly long-standing ones, show extra fields on Contact records that do not appear in Control Panel → Custom Fields. These are Custom System Fields: an older, fixed set of built-in Contact fields that predates the Custom Fields system described above. They are often renamed to something instance-specific, so a field labeled "Contract Date" or "Topic of Specialism" on your Contacts may be one of them.

How they differ from Custom Fields:

• The set is fixed. There is a built-in collection of about twenty fields with set types: text fields, checkboxes, two date fields, a membership number, and several instructor-specific fields. New ones cannot be created.
• They are managed by Administrate, not in the Control Panel. Renaming a field, showing it, or hiding it is done by Administrate on request; there is no customer-facing screen for this. Contact Support if you want one of these fields relabeled, enabled, or hidden.
• Values are edited normally. Users with access can edit the field's value on the Contact record like any other field, and the values are available in reporting and via the API.
• They are not supported by the Data Import tool. Contact import templates deliberately exclude Custom System Fields, so their values cannot be updated in bulk through an import. Bulk changes require the API.

Custom System Fields are deprecated in favor of Custom Fields. If you are setting up new data to track, create a Custom Field instead: Custom Fields are self-service, support more data types, carry per-role permissions, and can be updated in bulk through the Data Import tool. If you are using a Custom System Field today and need bulk updates, consider creating an equivalent Custom Field and asking Support to help migrate the existing values.