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

05.03 Mitigation Controls Customization

Customize the mitigation tab of the risk form — show or hide standard mitigation fields (planning strategy, effort, cost, current solution, security recommendations), add custom fields for mitigation-phase data, and rename the mitigation dropdown values to match your program's terminology.

Requires: Customization Extra

The form-layout customization (showing, hiding, and reordering standard mitigation fields) is added by the Customization Extra at simplerisk/extras/customization/. The dropdown-value management (renaming, adding, removing planning strategies, effort levels, etc.) is in Core and works without the Extra; see Managing Dropdown Values.

Why this matters

The mitigation tab on a risk record is where the planning happens — the user picks a planning strategy (Mitigate / Transfer / Avoid / Accept), notes the effort and cost, and writes up the planned mitigation. Most programs find that the default mitigation fields cover their needs; some programs find specific fields irrelevant ("we don't track cost separately, it's already in the project plan") or want to rename the standard dropdown values to match their lexicon ("we call it 'Compensating Control' not 'Mitigation Effort'"). Both are reasonable; both are supported.

The honest scope to know up front: most "mitigation customization" requests are actually dropdown-value management, which is in Core and doesn't need the Customization Extra. If your goal is "rename Mitigate to Implement" or "add a new planning strategy called Outsource," that's Managing Dropdown Values — you don't need the Extra. If your goal is "remove the cost field entirely from our forms" or "add a custom 'Compensating Control Justification' field on the mitigation tab," that's the Customization Extra and the rest of this article.

The other thing worth knowing: mitigation form layout is the same engine as risk form layout. The Customization Extra defines a per-form template via custom_template; the mitigation tab is one part of that template. Adding a custom field to the mitigation tab uses the same workflow as adding a custom field to the details tab (see Custom Fields) — pick the field type, set tab_index = 2 (mitigation), save.

The third thing: hiding a field doesn't delete its data. If you've populated mitigation cost on existing risks and then hide the field via the template, the values persist in the database; they just don't render on the form. Re-showing the field surfaces the values again. This is the right behavior (data preservation) but means a "hidden" field can produce "I'm not entering this anywhere" / "but it's still in the report" surprises.

Before you start

Have these in hand:

  • Admin access to Configure → Customization for the form-layout configuration, and to the relevant dropdown-management pages for value renames.
  • A clear list of which fields to show, hide, rename, or add. Don't customize speculatively. Walk through the standard mitigation form, identify what doesn't fit, and customize only the misfits.
  • Your program's terminology. If you're going to rename "Mitigation Planning Strategy" to "Treatment Strategy," confirm the language is what stakeholders actually use. A custom name that's only used in SimpleRisk and not in the program's other documents produces friction.
  • Awareness that customization affects every risk's mitigation form. There's no per-team or per-business-unit form customization; the layout is global. If different groups need different forms, the workaround is to use custom fields with conditional display based on a shared key field (and live with the form-fatigue), not to maintain multiple mitigation form templates.

Step-by-step

1. Identify what to customize

The standard mitigation fields:

  • Planning Strategy — dropdown (default values: Mitigate, Transfer, Avoid, Accept).
  • Mitigation Effort — dropdown (default values: Low, Medium, High, etc.).
  • Mitigation Cost — typically dropdown or numeric.
  • Current Solution — text area for the existing mitigation in place.
  • Security Recommendations — text area for proposed additional mitigations.
  • Mitigation Owner — user dropdown.
  • Mitigation Team — team multi-select (drives team-based segregation).
  • Mitigation Date — date.

For each: keep it as-is, hide it, rename its values, or replace it with a custom field. Most programs change 1–3 of these; a clean default is fine for the rest.

2. Manage dropdown values (Core feature)

For renames or value list changes (e.g., "rename Mitigate to Implement," "add Outsource as a planning strategy"), see Managing Dropdown Values. The relevant lookup tables:

  • planning_strategy — the planning-strategy dropdown.
  • mitigation_effort — the effort dropdown.
  • mitigation_cost — the cost dropdown.
  • mitigation_controls — the maturity/control mapping (if used).

The pattern is the same for each: open the management page, add/edit/delete values, save. Existing risks retain their assignments to renamed values (the relationships are by ID, not by name).

This works without the Customization Extra; no Extra activation needed.

3. Hide standard mitigation fields (Customization Extra)

If your program doesn't use a particular standard field (Mitigation Cost, for example), hide it via the Customization Extra's form layout:

  1. Sidebar: Configure → Customization.
  2. Open the Mitigation Tab layout (the template for tab_index = 2).
  3. For the field you want to hide, toggle its visibility off (or remove it from the template).
  4. Save.

The field disappears from new risk-mitigation forms and from edit views. Existing values persist in the database; reports that reference the field can still pull the historical data.

4. Add custom fields to the mitigation tab (Customization Extra)

For organization-specific fields on the mitigation phase (e.g., "Compensating Control Justification," "Implementation Phase," "Validation Method"), define a custom field with tab_index = 2:

  1. Sidebar: Configure → Customization.
  2. Click Add Field.
  3. Enter the name, pick the type (text, dropdown, date, multi-select, etc.).
  4. Set Tab Placement to Mitigation.
  5. Configure required, encryption, and any dropdown options.
  6. Save.

The custom field appears on the mitigation tab. See Custom Fields for the full field-definition workflow.

5. Reorder fields on the mitigation tab (Customization Extra)

The default field order may not match your program's logical workflow. To reorder:

  1. Open the Customization admin page.
  2. Open the Mitigation Tab layout.
  3. Drag fields up or down to reorder.
  4. Save.

The new order takes effect on the next form render. Reordering doesn't affect any data; it just changes the visual layout.

6. Verify the form with a test risk

Test before announcing the changes:

  1. Open the risk submission form.
  2. Submit a test risk.
  3. Open the test risk's mitigation tab.
  4. Confirm the form renders with your customizations: hidden fields gone, renamed values showing, custom fields appearing in the right tab and order.
  5. Fill in the mitigation, save, re-open, confirm values persisted.

If anything renders wrong, edit the customization; the form picks up changes on the next page load.

7. Update reports and integrations after customization

Form changes don't affect the underlying database schema (custom fields aside). Reports that pull data from the standard mitigation columns continue working when those columns are hidden from the form (the data may still be there from before; new risks won't have it).

For custom fields added to the mitigation tab, configure the relevant reports to include the custom field as a column where useful. Integrations consuming the API should be updated to read or write the custom field via custom_field_ .

8. Plan for unhide / unhide-then-rehide cycles

Hiding a field temporarily (e.g., during a workflow review) and re-showing it later works fine; the field comes back with its existing data. Hiding a field permanently and then deciding to reuse the column for a different purpose is risky — old data persists and reappears when the field is shown. Use a different field rather than reusing one whose history is mismatched.

Common pitfalls

A handful of patterns recur with mitigation customization.

  • Treating dropdown-value renames as Customization-Extra-required. The lookup table management is in Core. If your customization is just "rename these dropdown values," you don't need the Extra at all.

  • Hiding fields that downstream consumers depend on. A report or integration that reads mitigation_cost keeps working when the field is hidden from the form, but new risks won't populate the field. The integration may produce confusing "value missing" output. Coordinate hidden-field changes with the integrations that consume the data.

  • Adding custom fields without considering the tab placement. A "Compensating Control Justification" field on the Details tab gets filled in at submission time when the user doesn't yet know the compensating control; a "Submitted Vendor" field on the Mitigation tab forces the submitter to come back during planning. Match the field's tab to the workflow phase.

  • Renaming dropdown values mid-program without communication. Existing reports, dashboards, and run-of-show documents reference the old names. Changes to the dropdown values cascade to displays of existing data immediately. Communicate changes with a screenshot showing before-and-after.

  • Reordering fields on the mitigation tab without considering muscle memory. Users who've filled out 100 mitigations have a tab-key-order in their muscle memory. Reordering disrupts it for the gain of a slightly more logical layout. Reorder if the gain is real; don't reorder for cosmetic neatness.

  • Removing a planning strategy that's in use by existing risks. Dropping "Transfer" from the planning_strategy lookup orphans every risk that's currently set to Transfer. The risks keep their stored planning_strategy ID; reports may show "Unknown" or blank for those risks. Reassign before removing, or keep the value in the lookup as inactive rather than deleting.

  • Confusing the mitigation form template with the mitigation lifecycle. Customizing the form changes what fields appear; it doesn't change the mitigation workflow (planning → execution → completion → effectiveness check). The workflow is a separate concept; see your program's mitigation lifecycle documentation.

  • Adding too many custom fields. Each custom field on the mitigation tab is another thing the user fills in. The tab gets long; users skip required fields or save half-filled mitigations. 2–3 custom fields on mitigation is usually enough.

  • Forgetting that hidden fields still consume data when populated by integrations. An integration writing to mitigation_cost via the API populates the column even though the field is hidden from the form. The data exists, won't show on the form, and may surprise reviewers. Document hidden fields' API behavior.

  • Not testing the customization in the full risk lifecycle. A field that appears correctly on submission may not appear (or may appear duplicated) on edit-after-mitigation. Test through submit → mitigate → review → close.

Related

Reference

  • Permission required: check_admin for the Customization admin page and for the dropdown-value management pages.
  • API endpoint(s): /api/v2/risks/{id}/mitigation reads and writes the mitigation tab's data including custom fields keyed custom_field_ .
  • Implementing files: simplerisk/extras/customization/index.php (the form-layout engine via custom_template); simplerisk/admin/add_remove_values.php (the centralized dropdown-management page); simplerisk/admin/custom_names.php (the rename surface for some lookup values); simplerisk/includes/displayrisks.php (the mitigation tab rendering).
  • Database tables: mitigations (the per-risk mitigation row); planning_strategy, mitigation_effort, mitigation_cost, mitigation_controls (lookup tables for the standard dropdowns); custom_template (form-layout configuration); custom_data (custom field values).
  • config_settings keys: None directly; the Extra-active flag is customization.
  • External dependencies: None for Core dropdown management; the Customization Extra for form-layout customization and for adding custom fields to the mitigation tab.