05.01 Custom Fields

Requires: Customization Extra

The custom-fields engine — the field definitions, the values stored against each record, the layout system that places fields on the form, and the API exposure of custom values — comes from the Customization Extra. Without the Extra activated, submission forms have only the fixed Core fields.

Why this matters

Every organization needs to track something the Core fields don't cover. A regulated industry program tracks "Regulatory Citation" against each risk. A vendor risk program tracks "Vendor Tier" and "Contract Renewal Date" on the assets it monitors. A program running its own control catalog wants a "Testing Frequency" field on every control. Hardcoding these into Core would either bloat the data model for every customer or force every program into the lowest-common-denominator field set; the custom-fields engine in the Customization Extra is how SimpleRisk solves this without making Core unwieldy.

The scope to know up front: custom fields work on Risk, Asset, Project, Framework, and Control records. Documents and exceptions don't have a custom-fields engine — document types are configurable (see Managing Policies and Documents in the User Guide), but a document itself can't carry custom field values the way a risk or asset can. If your customization plan calls for fields on governance documents or exceptions, that part doesn't fit this Extra yet.

The other thing worth knowing: custom fields show up in the API. Endpoints for the supported entities, including /api/v2/risks and /api/v2/assets and their counterparts for projects, frameworks, and controls, return custom values keyed as custom_field_{id} in the JSON response. Integrations that read or write custom field values do it through the standard API surface; they don't need a separate custom-fields-aware client.

The third thing: custom fields persist independently of the Extra. Deactivating the Customization Extra doesn't delete your field definitions or the values captured against them; both sit dormant and reappear when the Extra is reactivated. This is by design (no data loss on deactivation), but it means a "remove all custom fields" cleanup operation has to delete the field definitions explicitly, not just deactivate the Extra.

Before you start

Have these in hand:

Admin access to the Settings Hub (Settings cog, top-right of any page) → Extras chip → Customization Extra tile for activation, and to the Customization admin page for field definition.
A plan for what custom fields you actually need. Don't define fields speculatively; every custom field adds form complexity for the user and a column to think about for integrations. Start with the 3–5 fields the program demonstrably needs; add more later as patterns emerge. Removing fields that have populated data is harder than adding new ones.
Naming conventions for the fields. Custom fields show up in the form, in reports, in the API, and in any integrations. Pick names that read clearly out of context — "Regulatory Citation," not "Reg Cit." The name you type in the field's Field Name propagates to every surface.
A decision on which field group each field belongs to. SimpleRisk defines custom fields separately per field group — Asset, Risk, Project, Framework, or Control — so a "Vendor Tier" field defined under Asset doesn't automatically appear on Risk records. Decide up front which entity the field actually describes.
A backup if the install has been live for a while. Field changes don't usually corrupt data, but defining-then-deleting fields rapidly while populating them produces orphaned data; a backup is the rollback path.

Step-by-step

1. Activate the Customization Extra

Settings cog → Settings Hub → Extras chip → Customization Extra tile → Activate. The activation:

Creates the storage it needs for field definitions, their values, and the form layouts.
Adds the Customization admin navigation entry that exposes the field-definition UI.
Surfaces the custom-field rendering hooks on the supported submission and edit forms.

If the Extra is already active, this step is a no-op.

2. Open the Customization admin page and pick a field group

Settings cog → Settings Hub → Customization tile opens the admin page. At the top, a row of pills (Asset, Risk, Project, Framework, Control, Document) selects which field group's fields and templates you're customizing. Everything below the pills, including the Custom Fields section and the Templates tab described in Template Groups and Business Units, scopes to whichever pill is active. The Document pill is the odd one out. Documents don't have custom fields, so it swaps the whole page for a document-types manager instead, covered in the Governance chapter of the User Guide rather than here.

3. Plan the field definitions before defining them

For each custom field, decide:

Field Type — text, dropdown, date, multi-select, number, and so on. Determines how the field renders and what validation applies.
Field Name — the display label (e.g., "Regulatory Citation").
Required — whether the field must be populated before the form can be saved. Use sparingly; required fields without good cause produce form fatigue.
Encryption — for text fields, whether the field's values are encrypted at rest. Only offered when the Encryption Extra is active. Useful for fields holding sensitive identifiers (customer account numbers, regulator case IDs).
Dropdown / multi-select options — the list of values, if the field type is one of these.

Sketch the full field set before starting to define fields in the UI; defining-then-redefining produces layout churn that makes the form harder to reason about, especially once you're managing more than one template group (see the companion article on that).

4. Define the fields

With a field group selected, expand the Custom Fields section (collapsed by default, above the Templates tab). It lists every custom field already defined for that field group, with its name, type, whether it's required, and edit and delete actions on each row. Expanding the section reveals a + Add button in its header.

Click + Add. The Add a Custom Field dialog opens with Field Type first, then Field Name.
Pick the type, name the field, and check Make this custom field required if it should be mandatory.
For a Dropdown or Multi Dropdown field, an alphabetical-order option appears so you can choose whether the option list sorts alphabetically or keeps the order you enter it in.
For a text field, check Encryption if the Encryption Extra is active and the field should be encrypted at rest.
Save. Managing a dropdown or multi-select field's option list happens from the same edit action on the field's row — there's no separate options icon.

A newly created field exists but isn't on any form layout yet. The next step places it.

5. Add the field to a template

Open the Templates tab (visible for every field group except Document). The Template designer shows the current layout as a drag-and-drop grid. Click + Add Field to open the field picker: two columns, Core Fields and Custom Fields, list every field not yet on the layout. Clicking a field adds it to the layout immediately — nothing to confirm. If you skipped step 4, the Custom Fields column has a New custom field row at the bottom that creates the field and adds it to the layout in one step.

Drag fields within the layout to reorder them. Removing a field from the layout doesn't delete its definition or its stored values — it just stops the field from rendering on this template.

Arranging the asset cards

The Asset pill's designer works differently from the Project, Framework, and Control ones. Assets are added, viewed, and edited in a wide window on the Manage Assets page, and that window groups its fields into cards. The designer shows those cards as a canvas you arrange directly, the same kind of canvas the Risk pill uses for a risk's details.

Out of the box there are six cards, named like the cards on a risk's details so the two designers read the same way:

General — Asset Name (full width), IP Address, and Asset Valuation.
Assignment — Team.
Classification — Site/Location.
Scoring — Asset Scoring, full width and alone in the card. It's one field that holds the asset's confidentiality, integrity, and availability ratings and the results computed from them (the FIPS categorization, the weighted score, and the weighted band), drawn in the asset window as a Summary card beside a Security Objectives card. See Data Classification and Asset Criticality in the User Guide for what the ratings mean.
Additional Information — Asset Details, Mapped Controls, Associated Risks, and Tags, in that order.
Custom Fields — a catch-all, labeled "These fields need sorting into a card". A field you add with + Add Field lands here; drag it into the card where it belongs, or leave it here if it doesn't fit anywhere else.

The banner above the canvas sums up the moves: drag a field into a different card to reassign it, drag within a card to reorder or resize it, and drag or resize a card to change its position on the page. A field that no longer fits after you shrink a card is counted on the card ("{n} field(s) do not fit in this card"), so enlarge the card rather than hunting for the field. Asset Name can be moved and resized but never removed, since every asset needs a name. Asset Scoring is optional: move it, resize it, or remove it from a template whose users shouldn't rate assets, and + Add Field lists it under Core Fields when you want it back. It's never required, whatever the layout says. Nothing is stored until you click Save at the bottom of the tab.

The layout drives every mode of the asset window. The edit and add forms follow it exactly, and the read-only view keeps the same card widths, so a half-width card sits beside its neighbour in both. Without the Customization Extra, assets use the default layout above, Scoring card included.

If you're upgrading an install that already had arranged asset templates, the upgrade adds the Asset Scoring field and the Scoring card to every asset template group once. The card goes directly under Classification, and only the cards below it move down to make room; anything beside or above it stays where you put it. If a card in your layout straddles that spot, the Scoring card goes at the bottom instead, so nothing ends up overlapping. After that first time, a template you've taken Asset Scoring off stays without it; the upgrade doesn't put it back.

Restore, beside Save, asks Restore default layout? before it does anything. Confirming puts the ten standard asset fields (Asset Scoring included) back in their default cards for the template group you're editing, puts the cards themselves back in their default order and size, and takes custom fields off the layout; their definitions and stored values stay, and you can add them back. Other template groups aren't touched.

Two refusals you might meet, and neither changes anything. A save that would take half or more of the template's fields off the layout, when you didn't remove them on this page, is refused with a message telling you to reload. That usually means the page went stale because another administrator changed the same template after you loaded it; reload, redo your change, and save again. A save that would drop Asset Name is refused with "A required field cannot be removed from the layout."

If your program only needs one layout per field group, this is the whole workflow. If different business units need different fields, say a healthcare business unit tracking HIPAA-specific data that a retail business unit doesn't, see Template Groups and Business Units for creating additional named templates and assigning them.

6. Verify the field appears on the form correctly

Test before announcing the field to users:

Open the submission form for the field group you customized (a risk, an asset, a project, a framework, or a control).
Confirm the field renders correctly (label, type, options for dropdowns).
Submit a test record with the field populated.
Open the test record for editing and confirm the value persisted.
Hit the corresponding API endpoint (e.g. GET /api/v2/risks/{id} or GET /api/v2/assets/{id}) and confirm the custom field appears in the JSON as custom_field_{id}.

If anything renders unexpectedly, edit the field definition or its position on the template; the form picks up the change on the next page load.

7. Map fields to your reporting and integration patterns

Once a field is in use, it shows up in three downstream places:

Reports: reporting views for the field group can include custom fields as columns. Configure the report column selection to add the new field where useful.
API: the field is available as custom_field_{id} on that field group's endpoints. Integrations need the field's id (visible in the Custom Fields section) to read or write it. If an integration is the primary consumer, document the mapping — "field name X = custom_field_47."
Search and filter: custom fields can typically be searched and filtered alongside Core fields, depending on the field type. Test the search behavior before assuming it works as expected.

8. Manage field changes carefully

Editing a field's name or option list affects existing data:

Renaming a field: the new name appears everywhere the field is displayed; old reports, screenshots, and integration documentation referring to the old name become stale. Communicate the rename.
Adding new dropdown options: existing records with the old options remain; the new option appears as a choice for new and edited records.
Removing a dropdown option: existing records that have the removed option as their value retain that value (orphaned). Either reassign records to a different option before removing, or accept the orphaned values.
Changing a field type (e.g., text → dropdown): risky; existing values may not fit the new type's constraints. Avoid; create a new field of the new type and migrate data instead.

9. Plan for field deletion

Deleting a custom field is permanent. Clicking the delete icon on a field's row asks "Are you sure to delete this custom field?" before it does anything, but confirming it:

Removes the field definition, including its dropdown option list if it has one.
Deletes every stored value for that field — across every record, in every field group's data, not only the one you're currently viewing.
Removes the field from any template layout it was placed on, and from any record that already has it.

Before deleting:

Export the data (via the API, a report, or a database query) so the historical values aren't lost permanently.
Confirm no active integration is reading or writing the field.
Communicate to users that the field is going away.
Then delete.

10. Plan for backup-and-restore implications

Field definitions, the values captured against them, and the form layouts are three separate things, and a backup needs all three. Restoring an old backup brings them all back as they were at backup time; if the field set has changed since, the restore reverts those changes. The standard database backup (see Database Backup and Restore) covers this; verify by listing the tables in your backup.

Common pitfalls

A handful of patterns recur with custom fields.

Defining too many fields up front. "Let's add every field anyone might ever want." The form becomes unusable; submitters skip required fields or abandon mid-submission. Start lean; add fields when the program proves it needs them.
Required fields without a clear "what to put here" guide. A required "Vendor Tier" field with no documentation produces guesses or default values. If you make a field required, document what valid values mean and provide a dropdown or default rather than free-text wherever possible.
Encrypting fields that don't need encryption. Encryption adds complexity (the field can't be searched server-side; backup-restore involves the encryption key); only encrypt fields that hold genuinely sensitive identifiers.
Renaming fields without checking integrations. Integrations referencing custom_field_47 keep working when the name changes (the id doesn't change), but human-readable references break. Keep the field id stable; rename for human clarity only when needed.
Defining a field under the wrong field group. A "Vendor Tier" field created while the Asset pill is active only shows up on assets — creating a near-identical field under Risk later, rather than realizing it's already there, is a common way programs end up with duplicate-looking fields that aren't actually linked.
Treating custom fields as a substitute for proper data modeling. A "Customer Name" custom field on a risk that's actually about a specific customer should probably be a structured asset link instead. If the custom field is becoming a foreign key to another entity, model it properly (asset, business unit, etc.) rather than encoding it as free-text.
Assuming custom fields work on every entity. They don't — Documents and exceptions still have no custom-fields engine. Assets, projects, frameworks, and controls do, as of the current release; if your plan needs custom fields on documents or exceptions, the plan needs adjustment.
Deactivating the Customization Extra and being surprised the data persists. Deactivation hides the form fields and the admin UI; the underlying tables stay. Reactivation restores everything. To actually remove custom-field data, delete the field definitions before deactivating.
Defining fields without testing across the full workflow. A field might render fine on submission and look broken on the edit-after-mitigation flow. Test the field through the full record lifecycle before going live.
Forgetting custom fields exist when planning a Core upgrade. Core upgrades don't touch custom-fields data, but they may change the layout of the standard form. After upgrading, verify custom fields still render correctly; bug-report any layout issues.