Custom Fields (Advanced Model)

Custom fields capture information Amplify doesn't record by default — a business unit, a priority, a cost center, a free-text justification. In the Advanced Model, custom fields are created once under Administration > Custom Fields, and then mapped to the classifications that should use them. The same field can be mapped to many classifications, across different types of item.

This article covers the Advanced Model, and needs administrator access. Fields created here are also available to Simple Model programs as shared fields — see Custom Fields (Simple Model).

How custom fields work

A custom field is defined in one place and shared by every classification it's mapped to.

• Set on the field — its type, label, options, and whether it's Required. These apply everywhere the field is used, so making a field required makes it required on every classification it's mapped to.
• Mapping — which classifications use the field. Set it from the field's Mapped Classifications, or from each classification's Properties tab.
• Set on each classification — whether to Include on Create, which shows the field on the form when an item of that classification is created. This is set on the classification's Properties tab.

Finding custom fields

The Custom Fields page lists every custom field, with its Field Type, Label, whether it's Required, and the Classifications and Object Types it's mapped to. Use Object Type to show only fields for one type of item, or search by name or label. Click a field's name to edit it.

Creating a custom field

1. Navigate to Administration > Custom Fields.
2. Click New Custom Field. The Create Custom Field panel opens.
3. Select a Field Type. The rest of the form changes to match — see Field types.
4. Fill in the settings common to every field, described below.
5. Fill in the settings for the field's type.
6. Check the Field Demo to see how the field will look to users.
7. Click Create.

Settings for every field

• Name — a descriptive name, used to identify the field in Administration.
• Mapped Classifications — the classifications the field is used on. You can also change this later, here or from each classification's Properties tab.
• Label — what users see next to the field.
• Dataset Identifier — a unique identifier used for the field in reports and API views. It can only contain letters, numbers, and underscores, and can't be changed once the field is created, so choose one that's easy to recognize.
• Description — what the field is for. It isn't shown to users, but Ask Amplify and the Amplify MCP read it to understand the field, so a clear description gives better answers about it.
• Tooltip — a hint shown to users when they fill the field in.
• Make this custom field required — users must fill the field in before saving, on every classification it's mapped to. Not available for Calculated Fields. Where a required field is a text, number, URL, or date field, also enter a Default value, used where the field's form isn't shown when an item is created.

Field types

Fields with a list of options — each needs its options added under Options. See Adding options.

• Select Box — choose one option from a drop-down list. A Select Box can also carry reference data for each option — see Adding reference data to a Select Box.
• Multi-Select box — choose any number of options from a list.
• Radio Group — choose one option, shown as radio buttons.
• Traffic Light — choose one option, each shown as a color.

These four types, and Calculated Fields, can also use Enable filtering graphs based on the values in this field. When it's on:

• The field appears under Reporting Groups in the Filters panel of the Value Dashboard, so users can filter its graphs by the field's values.
• Select Box and Calculated Fields can be used to group initiatives in the Scenario Planner.
• The field is included in the data available to custom dashboards.

Fields users type into:

• Free Text Field — a single line of text. Set a Max Length in characters, or 0 for no limit.
• Free Text Area — several lines of text. Set a Max Length, as above. Turn on Enable Markdown support to let users format their text.
• Free Number Field — a number. Set Decimal Accuracy, the number of digits shown after the decimal point, from 0 to 9.
• URL — a web address.
• Date — a date.

Special fields:

• Amplify User Multi-Select — choose any number of Amplify users. The list of users is filled in automatically, so there are no options to add.
• Calculated Field — a read-only value worked out from other fields. See Calculated fields.
• Linked Select — a set of linked drop-down lists, where the choice in one decides the options in the next. See Linked selects.

Adding options

Options are used by Select Box, Multi-Select box, Radio Group, and Traffic Light fields.

1. Under Options, click Add Option.
2. Enter the option's Label.
3. Repeat for each option, or click Bulk Add to add several at once.
4. To give the options dataset values, turn on Provide a custom dataset value. For a Select Box, this setting is under Columns.
5. Enter a value for each option.

Users always see an option's label in the field. Its dataset value is extra information attached to the option, used elsewhere in Amplify:

• Number values — let a Select Box or Multi-Select box be used in a Calculated Field. For example, options of Low, Medium, and High with values of 1, 2, and 3.
• Text values — can be referenced in custom dashboards, such as a code your reporting uses.

For a Traffic Light field, each option's value is its color code instead, such as #FF0000.

Labels and values can't contain commas, or start or end with a space.

Adding reference data to a Select Box

Reference data is extra information held against each option of a Select Box, such as the principal or region for each school. When a user picks an option, its reference data fills in automatically as read-only fields, each labeled with the reference data's Name. Users can't edit these fields.

Reference data is available on Select Box fields only, not on Linked Selects or other field types. A field can have up to 25 pieces of reference data, each either text or a number.

To add reference data to a Select Box:

1. Open the Select Box field, or create one.
2. Under Columns, click Add Reference Data. A row is added.
3. Enter a Name. Users see it as the label of the read-only field.
4. Select a Type: Text or Number.
5. Check the Dataset Identifier. It's filled in from the field's identifier and the name, and can't be changed once saved.
6. Repeat for each piece of reference data.
7. Under Options, enter each option's values in the columns added for the reference data.
8. Click Create for a new field, or Save for an existing one.

Drag the rows under Columns to set the order the reference data appears in. With Bulk Add, the third pasted column onwards fills the reference data, in the order shown under Columns, and any further columns are ignored. Bulk Add only adds options; it doesn't change the reference data of options that already exist.

Values can be left blank. Saving with blank values asks you to confirm first, and items using those options show those fields blank. Where a Select Box has reference data, its Field Type can't be changed.

Reference data always shows the current values, so correcting a value here updates every item that uses the option. Baselines and published status reports keep the values as they were when captured. Reference data appears:

• On create forms and item pages — beneath the Select Box, wherever the Select Box is shown.
• In registers and tables — as read-only columns named after the Select Box and the reference data, such as Site - Region. These columns can be sorted, filtered, and grouped.
• In the Initiative Workbook and status reports — as separate read-only widgets, named Custom: followed by the reference data's name. Add them to the template like any other widget — see Configuring the Initiative Workbook.
• In reporting and the API — see Reporting Views Reference and Custom Fields API.

Reference data can't be used in a Calculated Field.

Calculated fields

A Calculated Field works out its value from other custom fields, using a formula. Users can't edit it; it updates when the fields it uses change.

1. Select Calculated Field as the Field Type.
2. Fill in the settings for every field.
3. In the calculation builder, add the fields the formula uses. Free Number Field, Select Box, and Multi-Select box fields can be used, where their options have number dataset values.
4. Build the Calculation Formula from those field IDs, operators, and numbers. The Formula Preview shows the result.
5. For a Multi-Select box field in the formula, choose how its selected options combine: Sum, Average, or Count. If you don't choose, they're added up.
6. Set Decimal Accuracy, from 0 to 9.

A Select Box in a formula always uses its options' dataset values, not their reference data.

Removing a field from a classification it's used on in a Calculated Field shows a warning first, listing the Calculated Fields affected.

Linked selects

A Linked Select is a group of up to five drop-down fields, linked in order. Choosing an option in one field limits the options available in the next — for example, a Region field whose choice decides which Sites are offered.

1. Select Linked Select as the Field Type.
2. Enter a Name.
3. Enter a Description.
4. In the Linked Select Fields builder, add each field in order with New Field, up to five.
5. Add each field's options with Add Option, or Bulk Add to paste them from a spreadsheet — one column sets both label and value, two columns set label then value.
6. Select an option in a field.
7. Under Link To Next Field, choose the options in the next field it allows.
8. Repeat until every option is linked.
9. Select the classifications to use the Linked Select on.
10. Click Create.

A Linked Select has one Make this custom field required setting for the whole group. When it's on, users need to choose an option in every field of the group.

Mapping a field to classifications

A field only appears on items whose classification it's mapped to. Map it from Mapped Classifications on the field, or from the classification's Properties tab, where you also set Include on Create.

Tasks don't have a classification page of their own in the Advanced Model, so task fields are set here: select the task classification under the field's Mapped Classifications. Mapped fields show when a task is edited on the schedule.

For each type of classification, see its configuring article — for example, Configuring Initiative Classifications (Advanced Model) or Configuring Benefit Classifications (Advanced Model).