Administration Guide

User-Defined Fields

On this page

A user-defined field is a field you add to an object class yourself. It is a real database column whose name starts with UDF_. The product's database schema has no user-defined fields, and a new 2026.1 database created with the Default Workflow adds none (see Default Workflow Configuration): every user-defined field is added by an administrator. For the fields that come with the product, see Fields.

You add and change user-defined fields in the Admin Center and in the Settings App; for the two applications, see Admin Center and Settings App. In both applications, General > Fields needs the Fields permission. It is listed under Administrative Access > General, and an account with Administrative Access has it.

NOTE: Adding a user-defined field, like deleting, renaming, or resizing one, changes the structure of the class's database table. Before the Settings App saves such a change, it recommends closing all Alloy Navigator applications and asks you to confirm; see Save your changes. The Admin Center creates the field without this question. The Web App, the Self Service Portal, and the Alloy Navigator API are not restarted for the change: their running sessions pick it up; see When users see a change.

In the Admin Center

The Admin Center manages user-defined fields on the same General > Fields page and per-class Fields nodes as system fields; see Fields.

Add a user-defined field

  1. Under General > Fields, select the class's table, or open the class's Fields node in the Workflow tree, and click New.
  2. Enter the field name. The name always starts with the UDF_ prefix, and the form refuses the bare prefix UDF_.
  3. Choose the Type. For a Reference field, choose in Reference to, in the Reference group, whether it refers to a person or a technician.
  4. Set the size where the type has one. A String, Encrypted, or Lookup field starts at 50 characters, and a Float field at 1 decimal place.
  5. Under Display, enter the Field Label, up to 100 characters. For a Lookup, Multi-select, or Reference field, you can also enter a Filter that narrows the values the field offers.
  6. For a Lookup or Multi-select field, enter its values. You can reorder the list by dragging the rows, give each value tags, and delete several values at once with one confirmation. Each value is limited to the field's size.
  7. Under Options, select Read Only, Mandatory, or Hidden as needed. On Object Activity, a user-defined field offers Hidden only. Mandatory is disabled for a Logical field.
  8. Click Ok.

When you click Ok, the form refuses a name already used on the table: "There is another field with this name. Please enter another name." If the save still finds the name on the table, it is refused with "The '<name>' field already exists in the '<table>' table."

The column is created at once, and the field is placed last on the Custom Data tab.

Change a user-defined field

Select the field and click Edit. Once a field is saved, its Type and, for a Reference field, what it refers to cannot be changed. The size shown for an Encrypted field is the number of characters, not the stored width.

A save writes the label to the field and copies it to the same field on every database view that depends on the table; Read Only and Mandatory are copied too when you edit a table. The list of values you save becomes the field's list: a value you removed from it is deleted. A save with an empty label, an empty filter, or no values keeps the previous label, filter, or values.

Renaming a field renames its column and updates the field's placeholders in the workflow of its own class. Placeholders elsewhere keep the old name. A new name already used on the table is refused with "The '<name>' field already exists in the '<table>' table." After the save, the Check your workflow dialog names the old and the new name and points you to the Settings App's Search in Workflow feature to find and update the remaining uses. For a Reference field, its _ID column is renamed too, and only the placeholders of its _ID field are updated; placeholders that name the displayed value keep the old name.

Making a field smaller depends on the type:

  • An Encrypted field cannot be made smaller: "Cannot decrease the length of Encrypted fields. Existing encrypted data would be corrupted."
  • A String or Lookup field asks you to confirm. If you continue, stored values longer than the new size are cut to it, and so are the Lookup field's values.

Arrange fields with UDF Layout

UDF Layout on the class's Fields page is available when the class has at least one user-defined field. It opens the Custom Data Display drawer, which covers the user-defined fields on the Custom Data tab and in the Custom Data section of the General tab. The drawer sets where the fields appear. A field's label and, for a Reference field, what it refers to are set in the field's own window; see Add a user-defined field.

  1. Click UDF Layout. The drawer has two sections: "Custom Data" tab, with a Tab caption box, and "Custom Data" section on the General tab, with a Section caption box. Both captions start as "Custom Data" when no caption has been set, and neither can be saved blank.
  2. Select a field and arrange it with the buttons of its section: Move Up and Move Down, Move to "General Tab" in the first section or Move to "Custom Data Tab" in the second, and Hidden, which hides the selected field or shows it again. You can also drag rows to reorder them. A hidden field's row reads "Hidden".
  3. To group fields on the Custom Data tab, use Manage Groups in the "Custom Data" tab section. The section on the General tab has no groups.
    • New Group asks for a Group name, which starts as "New group", and inserts the group above the topmost selected row. It is unavailable when the selected row is a group or directly follows one.
    • Rename Group and Delete Group are available when exactly one group row is selected. Delete Group asks "Are you sure you want to delete the selected item?".
  4. Click Ok, or Cancel to discard the changes.

A group is a heading row before the fields that belong to it. A group heading that is the last row, or that is directly followed by another heading, is refused: 'The group "<group name>" should contain at least one field.'

Saving the drawer writes both captions and each field's place, order, group, and hidden state in one step.

Add a field to All Tickets

  1. Select the All Tickets node and click Add. The Add field panel opens.
  2. Pick the field. The list offers only fields not yet available in All Tickets and My Tickets, and five check-mark columns, Change Requests, Incidents, Problems, Service Requests, and Work Orders, show which ticket classes include each field. For the other classes, the two lists display empty values for it.
  3. Optionally, under Label, enter a Custom Label of up to 100 characters. When you leave it blank, the field keeps its default label.
  4. Click Ok.

Fields whose names end in HTML or ID are not offered. The currency code field is offered only while multicurrency is turned on; otherwise the addition is refused with "Currency_Code field requires Multicurrency to be enabled." When the field has been added to All Tickets since the list was opened, for example by another administrator, the addition is refused.

To take a shared field off All Tickets, select it and click Remove, then confirm Remove Ticket Field. This deletes the shared definition and rebuilds the All Tickets list.

Delete a user-defined field

Select the field, click Delete, and confirm Permanently delete?. In All Fields, Delete is available only for a user-defined field that is not on a database view.

IMPORTANT: The Admin Center drops the column, its data, and its list of values at once; for a Reference field, it also drops the _ID column. It does not check whether workflow items, forms, or views use the field.

In the Settings App

The Settings App manages user-defined fields on its Fields page. The page opens from General > Fields, which lists every licensed class your account may administer, followed by a Miscellaneous folder with Object Activity, Classification and Reference Tables, and All Fields. It also opens from each class's own Fields node in the Workflow and Business Logic group, and the All Tickets/My Tickets node has a Fields node too. For the system fields on the same page, see Fields.

Commands of the Fields page

On a class that allows user-defined fields, the page offers New, Delete, Edit, and UDF Layout.... On All Tickets/My Tickets, the first two read Add and Remove, and UDF Layout... is not shown. Other tables and the All Fields lists offer neither New nor UDF Layout....

Delete is available for a table's user-defined field or a shared All Tickets field. Edit, which a double-click on a row also runs, is available for any system field and for a table's user-defined field. On All Tickets/My Tickets, Edit opens a shared field in its own window; see Add or remove All Tickets fields.

A hidden field stays on the page's list, with its hidden state. Hidden does not remove the field from the action-form field editor or the field-mapping editor. The field-mapping editor never offers a Lookup or Multi-select user-defined field, hidden or not.

Save your changes

Changes on the Fields page are kept until you save them. Click Save on the Standard toolbar, choose it as the first item of the File menu, or press Ctrl+S. Save is enabled while any open page has unsaved changes, and one save commits every manager page you have opened in the session, each with its own questions.

Before saving, the Settings App asks:

  • When you added, deleted, renamed, or resized a user-defined field, changed a Float field's decimal places, or added, removed, or edited a shared field: "You are about to change Alloy Navigator database's structure! To avoid possible errors, it's recommended that you close all Alloy Navigator applications first. Continue?"
  • When you deleted a user-defined field, also: "You are about to delete one or more user-defined fields. All data stored in these fields will be lost. This will affect all workflow items, reports, and Alloy Navigator objects that rely on these fields. Continue?"

Answering No to either keeps the changes unsaved. A save that only changes a user-defined field's label, filter, Mandatory, Read Only, or Hidden, a system field's settings, or the UDF layout asks neither question. After a structure change, the All Tickets view is rebuilt.

Add a user-defined field

  1. On the class's Fields page, click New. The New User Defined Field window opens.
  2. Under Binding, type the name after the fixed UDF_ prefix in Field Name:. Origin: shows the table. Choose the Field Type:.
    • For a Reference field, choose Person or Technician in Reference to:, in the Reference group that appears for this type.
    • For a String, Encrypted, or Lookup field, set Size:.
    • For a Float field, the box reads Decimal Places: and is set to 2 whenever you choose Float.
  3. Under Display, enter the Field Label:. For a Lookup, Multi-select, or Reference field, you can also set a Filter:; see Filter the field's values.
  4. For a Lookup or Multi-select field, build the list under Lookup values with New, Edit, Delete, Move Up, Move Down, and Tags. New and Edit open Add Value or Edit Value, with a Value: box. Delete asks "Delete record?" or, for several values, "Delete <n> records?".
  5. Under Options, select Mandatory, Read Only, or Hidden as needed. The group is not shown for the Activity table, and Mandatory is disabled for a Logical field.
  6. Click OK. OK needs a label, a name, a type, and, for a Reference field, a Reference to: entry.
  7. Save the page.

OK refuses:

  • A name ending in _ID: "UDF names ending with "_ID" are prohibited in Alloy Navigator. Specify another field name."
  • A name already used: "There is another field with this name. Please enter another name."
  • A blank Lookup value: "The lookup value can't be blank."
  • An Encrypted field of a ticket class under a name already shared on All Tickets: "Cannot create the "<name>" field of Encrypted type because another user-defined field with that name is already added to the All Tickets grid."
  • A new hidden field of a ticket class whose name is shared on All Tickets: "Cannot add this hidden field because a field with that name is added to the All Tickets grid."

On OK, the window estimates the table's row size with the new field, and when the estimate is over 8000 bytes it warns: "The size of this field will put the record over the maximum allowed size of 8KB.This will result in data loss if you attempt to add or edit a record." and asks "Continue?". Yes goes on, No returns to the window, and Help opens the help topic. The estimate counts the new field at its type's fixed size, or, for a String, Memo, Encrypted, Lookup, Multi-select, or Reference field, at twice its size but no more than 24 bytes. It counts the table's existing columns only while the Fields page lists 300 fields or more.

Each value of a Lookup or Multi-select field is limited to the field's size, and a Multi-select value cannot contain a semicolon. A new field is placed on the Custom Data tab. When you save the page, the column is added to the table, and the field is added to every database view that depends on the table.

Filter the field's values

A filter narrows the values the field offers. When the field is placed on an action form, the filter stored with that form's field applies there instead: the field's own filter does not carry over to the action form, and an action form's filter does not change the field elsewhere. The Filter: box is editable for a Lookup, Multi-select, or Reference field, and read-only for the other types; for a Reference field, it becomes editable once you choose a Reference to: entry.

  • F(x) opens the Build Expression window. Its prompt reads select * from <table> where, and you write the condition that follows. OK checks the condition; an empty filter is allowed.
  • In the Build Expression window, Select Template... inserts a stored filter template. When the template has parameters, Assign Filter Parameters asks for them first, each as a value or an expression.
  • Choosing another Field Type: empties the filter.
  • A new field keeps its filter only for Lookup and Reference. For a new Multi-select field, set the filter afterwards with Edit.
  • Emptying the box and saving removes the filter.

Change a user-defined field

Edit opens the User Defined Field window. Field Type: and Reference to: are disabled.

  • Renaming renames the column and updates the field's placeholders in the workflow of its own class, as in the Admin Center, and then points you to Search in Workflow for the remaining uses. The window's Usage tab lists the workflow items of the field's class that hold its placeholder; see Fields.
  • A user-defined field of a ticket class whose name is shared on All Tickets cannot be renamed ("Cannot rename this field because it is added to the All Tickets grid.") or hidden ("Cannot hide this field because it is added to the All Tickets grid").
  • Making a String or Lookup field smaller asks "You are trying to decrease the field length from <old> to <new> characters. This may cause existing data to be truncated. Do you want to continue?". No leaves the window open with nothing changed.
  • Making an Encrypted field smaller is refused: "Cannot decrease the length of Encrypted fields. Existing encrypted data would be corrupted." The Size: box goes back to the stored size.

To change a field's type, delete the field and create a new one. The Settings App accepts the same name again at once, before you save. The save drops the old column with its data, after the data-loss question, and creates a new, empty column of the new type. The new field is a new definition: its label, options, and values are what you set in the New User Defined Field window, and it is placed on the Custom Data tab.

Arrange fields with UDF Layout

  1. Click UDF Layout.... The Custom Data Display window opens with two lists: the "Custom Data" tab list with a Tab caption: box, and the "Custom Data" section on the General tab list with a Section caption: box.
  2. Arrange the fields with Move Up and Move Down (Ctrl+Up and Ctrl+Down), Move to "General Tab" and Move to "Custom Data Tab", or by dragging them within and between the lists. A group's caption row can be dragged only within the "Custom Data" tab list. Use Hidden to hide a field.
  3. To group fields on the Custom Data tab list, use Groups...:
    • New group... asks for a Group name:, "New group" by default, and inserts the group's caption row before the selected field.
    • Rename group... renames the group.
    • Delete group... asks "Delete the group?". The fields of a deleted group move to the group above it.
  4. Click OK. OK is disabled while either caption is blank, and it refuses a group with no field under it: "The group '<name>' should contain at least one field."
  5. Save the Fields page.

Add or remove All Tickets fields

  1. On the All Tickets/My Tickets Fields page, click Add. The Field Properties window opens, with Field: and a grid of the fields not yet added, one column per ticket class.
  2. Pick the field. The list leaves out fields whose names end in _ID. Binding shows Field Name: and Available for:, and Display shows Default Label: and Custom Label:.
  3. Optionally, enter a Custom Label:, and click OK.
  4. Save the page.

A field that is hidden on any ticket class is refused as soon as you pick it: "This user-defined field cannot appear in the All Tickets and My Tickets views because it is hidden from users for <views>". OK stays disabled until you pick a field that is not hidden. When the field selected as the window opens is hidden, it is cleared without the message.

The shared column gets one type: any difference in type or size between the ticket classes makes it String, any Memo makes it Memo, a String or Lookup field takes the largest size, and a String left without a size gets 50.

Edit on a shared field changes only its Custom Label:. While the field is hidden on any ticket class, the label cannot be changed and the window shows the same message. A shared field that no ticket class carries any more shows "This field is not available for any Ticket class and will be hidden." in Available for:.

Remove asks "Remove this Ticket field from the All Tickets grid?".

Delete a user-defined field

  1. Select the field and click Delete, then confirm "Delete the user defined field?".
  2. Save the page, and answer the data-loss question.

When the field's placeholder is used in its class's workflow, Delete is refused: "Unable to delete field "<label>" because one or more workflow items refer to it. Remove dependencies first." The field's window then opens on its Usage tab.

When the deleted field started a group, the group name passes to the next field if that one has no group. On a ticket class, when no other ticket class keeps a field of that name and All Tickets shares it, the shared field is removed too, without a further question. The column is removed when you save.

In the Web App

  • A mandatory user-defined field carries the required asterisk on the full form, and the form is not saved while the field is empty: "This field is required." On an action form, the action form's own setting for the field decides whether it is mandatory. On the full form, a layout item's own mandatory setting for the field overrides the field's setting, except on the form that creates a new record.
  • The Hidden setting applies only where a form does not place the field itself. A hidden field that an action form places is still shown there. When several records are updated at once, a hidden field is not shown in the list of fields to update.
  • A Lookup, Multi-select, or Reference field's own filter applies where the Web App builds a field list with no form, including an action without a form, a step action whose form is empty, the field list for updating several records at once, and the field list for customizing a list view. When a form exists, a field placed on it uses the form field's own filter, even an empty one, and a field not on the form gets no filter; this holds for action forms and View Forms alike. A filter of a field on the Activity table is never used.
  • An Encrypted field shows ******** when read-only and is not offered as a list column.
  • A field added to All Tickets becomes a column that views of the All Tickets and My Tickets lists can use. It appears in no list until a view that includes it is saved, as a shared view or as a technician's own view. A hidden field is not offered.

When users see a change

The Web App picks up these field changes without a restart: a user-defined field created, changed, or deleted in the Admin Center, a field added to or removed from All Tickets in the Admin Center, a field added or deleted, a label changed, and a Settings App save that changes a user-defined field's settings or the database structure. Each Web App session checks for such changes at sign-in and then, when the session is used, at most every 30 seconds; when a label or the database structure has changed since its last check, the session reloads its field information.

The Self Service Portal and the Alloy Navigator API pick up the same changes the same way, without a restart. Each checks when a session is used, at most once a minute, and reloads its field information when a label or the database structure has changed since the last check. A mobile app that works through the API is served by a session that is refreshed the same way.

Field types

Type Size What it holds
Integer Fixed A whole number. In the Web App, from -2147483648 to 2147483647.
Logical Fixed A logical value. A Logical field cannot be made mandatory.
Currency Fixed An amount, stored with four decimal places. In the Web App, digits typed beyond the field's precision, 2 decimal places by default, are dropped.
Float 1 to 9 decimal places A decimal number. In the Web App, up to 15 digits with at most 9 decimals.
String 1 to 1000 characters Text up to the field's size.
Memo No limit Text with no size limit.
Encrypted 1 to 990 characters Text stored encrypted.
Date Fixed A date. In the Web App, the picker goes up to 100 years from today.
Date/Time Fixed A date and time. In the Web App, the picker goes up to 100 years from today.
Duration Fixed A number of minutes. In the Web App, up to 99999 hours and 59 minutes.
Lookup 1 to 1000 characters One value from the field's own list of values.
Multi-select - Several values from the field's own list of values.
Reference - A person or a technician. Service accounts and disabled accounts are excluded, and a technician reference is limited to technicians.

You cannot create an HTML field.

A Reference field has two columns: the field itself holds the displayed value of the referenced record, and a second column, named after the field with _ID added, holds the reference. When the reference changes, or the referenced value is renamed, the displayed value is updated.

A Currency or Duration field has no format of its own. It uses the installation's currency and duration formats, which are set for the whole installation under Currency format and Duration format on the Admin Center's Language & Region page.

An Encrypted field is masked: the Web App's read-only view shows ********. Workflow placeholders for an Encrypted field resolve to the decrypted value, so notification text, generated documents, and other workflow output carry the value in clear text. Among the ways workflow reads a placeholder, only the template designer's HTML preview shows ********** in place of a stored value.

Limits and classes

There is no limit on the number of user-defined fields per class. What is limited is the size of the table's database row. When you add a field in the Settings App, the window estimates the row size and warns when the estimate goes over the limit; see In the Settings App.

User-defined fields are allowed on the classes that have a table of their own, except Brand, Company Address, Report, Software Product, and Stock Room. These are Activity, Announcement, Approval Request, Approval Stage, Asset, Change Request, Computer, Configuration, Consumable, Contract, Document, Group, Hardware, Incident, Invoice, Invoice Item, Knowledge Base Article, Library Item, Location, Network, Organization, Person, Problem, Product, Project, Project Task, Purchase Order, Purchase Order Item, Reservation, Service, Service Catalog Item, Service Request, SLA, Software License, Stock Rule, Tracked Software, Vendor, Vendor Product, and Work Order. A class without a table of its own, such as an aggregated list, never takes them. Activity is among the allowed classes, so activity records take user-defined fields like any other object.

In the Admin Center, you can add user-defined fields to every one of these classes except Invoice Item, which has no Fields node there. Add user-defined fields to Invoice Item in the Settings App.

Where the fields are placed

Every table has two places for user-defined fields: the Custom Data tab and the Custom Data section on the General tab. Both captions can be changed. On the Custom Data tab, fields can be arranged in groups; the section on the General tab has no groups. Every field also has an order.

A hidden field is removed from the user-facing forms that do not place the field themselves, while its column stays in place; see In the Web App.

Shared ticket fields

A shared ticket field shows a field that already exists on the ticket classes (Incidents, Problems, Change Requests, Service Requests, and Work Orders) as one column of the All Tickets and My Tickets lists. It is a definition only and creates no column: the column is filled from each ticket class that has the field, and the ticket classes that do not have it show an empty value. When the classes' fields differ in type or size, the shared column takes one common type. A field that is hidden on any of the ticket classes does not appear in the shared column. For the ticket classes, see Tickets.

NOTE: The Web App does not offer an Encrypted field as a list column; see In the Web App. When you add a field to All Tickets in the Admin Center, the list of fields to pick from does not leave Encrypted fields out. In the Settings App's Field Properties window, the list leaves an Encrypted field out only when the ticket classes carry exactly one Encrypted field name; when they carry two or more, every Encrypted field stays on offer.

  • Fields - system fields, labels, the field tables, and the Usage tab.
  • Form Layouts - arrange fields on the Web App's record forms.