Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

05.01 Custom Fields

Define organization-specific fields on risks, mitigations, and reviews. The Customization Extra adds the custom-fields engine — text, dropdown, date, multi-select, and other field types, placed on specific tabs of the risk form, with optional encryption and required-field enforcement.

Requires: Customization Extra

The custom-fields engine — the custom_fields and custom_data tables, the per-form layout system, and the API exposure of custom values — is added by the Customization Extra at simplerisk/extras/customization/. Without the Extra activated, the risk submission form has 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." A program serving multiple business units tracks "Owning BU" or "Cost Center." 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 honest scope to know up front: custom fields work on risks (and the related risk-form tabs: details, mitigation, review). There's no custom-fields engine for assets, controls, frameworks, documents, exceptions, or other entities. Programs that want "custom fields on every entity" need to lean on existing entity attributes (descriptions, tags, the affected-asset list) or work around the limitation by encoding the data in a different shape. The risk side covers the substantial majority of customization use cases; if your customization plan calls for fields on, say, governance documents, that part doesn't fit this Extra.

The other thing worth knowing: custom fields show up in the API. Risk endpoints under /api/v2/risks return custom values keyed as custom_field_ in the JSON response. Integrations that read or write custom field values can do so 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 drop the custom_fields or custom_data tables; the data sits on disk and reappears 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 drop the tables explicitly, not just deactivate the Extra.

Before you start

Have these in hand:

  • Admin access to Configure → Extras → Customization Extra 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 that 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 names appear in custom_fields.name and propagate to every surface.
  • 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

Sidebar: Configure → Extras → Customization Extra → Activate. The activation:

  1. Creates the custom_fields, custom_data, and custom_template tables (if they don't already exist).
  2. Adds the Customization admin navigation entry that exposes the field-definition UI.
  3. Surfaces the custom-field rendering hooks on the risk submission and edit forms.

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

2. Plan the field definitions before defining them

For each custom field, decide:

  • Name — the display label (e.g., "Regulatory Citation"). Stored in custom_fields.name.
  • Type — text, dropdown, date, multi-select, number, etc. Determines how the field renders and what validation applies.
  • Tab placement — Details (tab_index 1), Mitigation (tab_index 2), or Review (tab_index 3). Custom fields appear on the tab corresponding to the workflow phase the data belongs to. A "Vendor Tier" field belongs on Details (set at submission); a "Compensating Control" field belongs on Mitigation (filled in during planning); a "Reviewer Notes" field belongs on Review.
  • Required — whether the field must be populated before the form can be saved. Use sparingly; required fields without good cause produce form-fatigue.
  • Encryption — whether the field's values should be encrypted at rest (depends on the Encryption Extra being active for actual encryption to occur). Useful for fields holding sensitive identifiers (customer account numbers, regulator case IDs).
  • Default value — the value pre-populated in the field on a new submission, if any.
  • 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 them in the UI; defining-then-redefining produces template churn that makes the form layout harder to reason about.

3. Define the fields in the Customization admin page

Sidebar: Configure → Customization opens the admin page. Each defined custom field is listed with its name, type, tab placement, and configuration. The page lets you:

  1. Add a new field via the field-definition modal.
  2. Edit an existing field to change its name, required flag, encryption, dropdown options, etc.
  3. Reorder fields within a tab to control display order.
  4. Delete a field (with the caveat below about populated data).

For each new field:

  1. Click Add Field.
  2. Enter the name, pick the type, set the tab placement and required flag, configure encryption if needed.
  3. For dropdown / multi-select fields, enter the option list (one value per line, or via the in-page list editor).
  4. Save.

The field is immediately available on the corresponding tab of the risk submission form for any user who can submit risks.

4. Verify the field appears on the form correctly

Test before announcing the field to users:

  1. Open the risk submission form.
  2. Navigate to the tab where the custom field is placed.
  3. Confirm the field renders correctly (label, type, options for dropdowns).
  4. Submit a test risk with the field populated.
  5. Open the test risk for editing and confirm the value persisted.
  6. Hit the API: GET /api/v2/risks/ and confirm the custom field appears in the JSON as custom_field_ .

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

5. Map fields to your reporting and integration patterns

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

  • Reports: Dynamic Risk Report and similar reporting views 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_ on risk endpoints. Integrations need to know the field ID (visible in the Customization admin page) 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.

6. Manage field changes carefully

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

  • Renaming a field (changing name): 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.

7. Plan for field deletion

Deleting a custom field is permanent for the data:

  1. The field definition is removed from custom_fields.
  2. All custom_data rows for that field are deleted.
  3. Existing records lose the data; reports referencing the field break; integrations referencing custom_field_ get an empty result.

Before deleting:

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

8. Plan for backup-and-restore implications

Custom field definitions live in custom_fields; data lives in custom_data; layout in custom_template. Backups should include all three. Restoring an old backup brings back the field definitions and data 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. The encryption flag triggers encrypted storage when the Encryption Extra is active. 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.

  • Putting Mitigation-phase data on the Details tab (or vice versa). Custom fields on the wrong tab appear out of context for the user filling them in. Match the tab to the workflow phase: data captured at submission goes on Details, planning data on Mitigation, review data on Review.

  • 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 entities other than risks. They don't. Assets, controls, frameworks, documents, exceptions don't have a custom-fields engine. If your plan needs custom fields on those, 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, drop the tables or delete the field definitions before deactivating.

  • Defining fields without testing across the full workflow. A field on the Details tab might render fine on submission and look broken on the edit-after-mitigation flow. Test the field through the full risk lifecycle (submit → mitigate → review → close) 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.

Related

Reference

  • Permission required: check_admin for the Customization admin page; submit_risks (or equivalent edit permission) for the user-facing form where custom fields appear.
  • API endpoint(s): /api/v2/risks and related risk endpoints expose custom field values keyed custom_field_ . The Customization admin page itself is server-rendered.
  • Implementing files: simplerisk/extras/customization/index.php (enable_customization_extra(), the field-definition CRUD, the form-rendering hooks).
  • Database tables: custom_fields (id, name, type, is_basic, tab_index, required, encryption, fgroup); custom_data (id, risk_id, field_id, value); custom_template (per-form layout configuration).
  • config_settings keys: None directly; the Extra-active flag is customization (boolean).
  • Field types: Text, dropdown, date, multi-select, number (the exact list available depends on the Extra's version; check the field-definition modal for the current set).
  • External dependencies: None; the Encryption Extra is a soft dependency for the encryption flag to actually encrypt at rest.