Custom Fields
Custom fields extend host information with additional data fields. You can define separate fields for each module.
Concept
Custom fields supplement the standard host data with additional information relevant to your organization, such as:
- Location information
- Contract or SLA data
- Internal reference numbers
- Technical notes
Managing Fields
Access field management via Settings > Custom Fields.
Creating a Field
- Click Add Field
- Configure the field:
| Field | Description |
|---|---|
| Name | Internal field name (no spaces, unique) |
| Display Name | Label shown in the interface |
| Description | Help text for the field |
| Type | Data type of the field (see below) |
| Modules | Which modules the field is available for |
| Scope | Host, group, or module (see below) |
| Required | Must the field be filled in? |
| Default Value | Pre-filled value for new entries |
| Hide in UI | Hide the field in the overview |
| Hide in Summary | Hide the field in the compact view |
| Sort Order | Order of the fields in the display |
Field Types
| Type | Description | Example |
|---|---|---|
| text | Single-line text field | Location, room number |
| number | Numeric value | Contract number, port |
| dropdown_single | Single-select dropdown | SLA level (Gold/Silver/Bronze) |
| dropdown_multiple | Multi-select dropdown | Tags, categories |
| datetime | Date and time | Maintenance date, contract end |
| checkbox | Yes/No toggle | Production system, VPN active |
Dropdown Options
For the dropdown_single and dropdown_multiple types, you can define the selection options:
- Enter the options as a list
- Example:
Gold, Silver, Bronze
Scope
| Scope | Description |
|---|---|
| host | Field is stored per host (default) |
| group | Field is stored per host group |
| module | Field is stored module-wide |
Populating Fields
In the Detail Panel
- Open a host
- Custom fields are displayed in the overview
- Click on the value to edit it (inline editing)
- Press Enter to save
When Creating a Host
If a field is marked as Required, it must be filled in when creating a new host.
Display
In the Host Table
Fields with the Show in Table option enabled appear as additional columns in the host table of the respective module.
In the Detail Panel
All custom fields for a host are displayed in the overview tab of the detail panel.
In Reports
Custom fields are available as variables in report templates and can be included in reports.
Module Assignment
Fields can be configured for specific modules or all modules at once:
- All - Field appears in all modules
- OPNsense - Only in the OPNsense module
- Proxmox VE - Only in the PVE module
- Proxmox PBS - Only in the PBS module
- Linux - Only in the Linux module
- Windows - Only in the Windows module
Visibility
| Option | Description |
|---|---|
Hide in UI (hide_in_ui) | Field is not displayed in the normal overview but is available via the API. Useful for technical fields that are only populated by scripts/checks. |
Hide in Summary (hide_in_summary) | Field is not displayed in the compact overview (e.g., tooltip) but appears in the detail panel. |
Automatic Population
Custom fields can be populated not only manually but also automatically through Health Checks. See Health Checks > Custom Field Mappings.
Values from scripts (since v3.68.0)
Every script (also a check or a job script) can set fields of the machine it runs on by printing a line:
$key = (Get-BitLockerVolume -MountPoint C:).KeyProtector | Where-Object KeyProtectorType -eq 'RecoveryPassword' | Select-Object -First 1
Write-Output "DZ-FIELD: bitlocker_key=$($key.RecoveryPassword)"echo "DZ-FIELD: ram_slots=$(dmidecode -t memory | grep -c 'Size: [0-9]')"Rules:
- The field needs the option Scripts may write under Settings > Custom Fields and the scope Host. Fields without that option are never changed by a script (an agent cannot overwrite e.g. a contract field).
- The name is the internal field name. The field must apply to the module of the machine (or to all modules).
- The value is checked against the field type: number, yes/no (
yes,no,true,false,1,0), choice only from the options (comma separated for multi select), date as ISO 8601. Text at most 4000 characters, control characters are removed. At most 50 fields per run; with several lines for one field the last one wins. - The run result lists under
dz_fieldswhich fields were set and which were not (unknown, not allowed, invalid value). - In the detail panel the tooltip of a field shows when a script last set it.
Field type Secret (since v3.68.0)
For values like BitLocker recovery keys there is the type Secret (encrypted):
- The value is stored encrypted (key
SCRIPT_VAULT_KEYfrom.env, like secret script variables). - The detail panel shows only
••••••••with a Reveal button. Administrators and roles with the permission Show secret fields (customfields.secrets, Operator has it) may reveal it. Every reveal is written to the audit log (reveal_custom_field_secretwith field and machine). MCP tokens can never read the value. - Script output, the log and the live output show the value as
********. - Secret fields are not available as script placeholders.
- A field with stored values cannot change its type from or to Secret. Create a new field instead.
Practical Examples
IT Service Provider
Field: sla_level (Select: Gold, Silver, Bronze)
Field: contract_end (Date)
Field: contact_person (Text)
Field: location (Text)Internal IT Team
Field: department (Select: Development, Marketing, Sales, IT)
Field: cost_center (Text)
Field: is_production (Boolean)
Field: notes (Textarea)