6 Platform Settings

This chapter describes every page where an administrator configures GRC Platform itself: the Settings area, the settings that live inside a module (risk scoring, control testing, incident classifications), and the shared vocabulary records use (labels and custom fields). Accounts, groups and roles are described in Users, Groups and Roles; sign-in, LDAP, SAML, SCIM and session length in Authentication and Single Sign-On; the Audit Log in Audit Log and Evidence Integrity; snapshots in Backup and Restore. Email and notifications have their own chapter (Notifications and Email), and API tokens and AI assistants are in API Access and Integrations.

6.1 How settings are stored and applied

Settings changed on these pages are stored in the database, in the setting table, and travel with every backup snapshot. The three integration secrets (SMTP password, LDAP bind password, SAML private key) are stored encrypted with the instance's settings key (see Configuration Reference). Nothing on these pages is read from environment variables, with one exception: the product name falls back to APP_NAME until a name is saved under Branding.

Each application process (web and worker) caches a setting for 30 seconds. A change you save takes effect at once for the page you are on and within 30 seconds everywhere else, including in the background worker that sends email. The daily sweep schedule is applied to the job queue when you save it (see Scheduler in Notifications and Email).

Every save on these pages writes an Audit Log entry with the values before and after. Saves that change security posture (integrations, session and token limits, separation of duties, SSO only, AI assistant access, SCIM) also email every administrator a security alert.

6.2 Map of the settings pages

The Settings page has a card for each of the sixteen pages below, grouped under Identity & Access (Users, Groups, Roles, Provisioning, Sessions), Governance & Customization (Branding, Policies, Privacy, Labels, Custom Fields, Notifications), Integrations (Integrations, AI assistants, API Tokens) and System (Audit Log, Backups); a group with no card for you is hidden. Each card is shown only to people the page itself admits (the Opens with column), so no card leads to a Forbidden page. The Settings entry at the foot of the sidebar is shown to anyone who sees at least one card. An administrator sees all sixteen. Of the built-in roles, a GRC Manager sees Custom Fields, Notifications and Audit Log; an Auditor sees Custom Fields and Audit Log; a Risk Owner sees Custom Fields. A Data Liaison sees no Settings entry.

Three groups of settings live inside a module instead:

"Administrator" in these tables means an account with the Administrator flag. Some changes check the flag whatever a role grants, so a custom role with settings:update can view those pages and still cannot save them; the page shows the controls disabled or hides the Save button.

6.3 Branding

Settings → Branding white-labels the platform. Out of the box the product is called "TraxrGRC", uses the standard blue theme and a shield icon, and names no vendor anywhere. Viewing needs settings:read; saving needs settings:update.

The Name and color card has its own Save button:

The Logo card has Upload logo and Remove:

• The file may be PNG, JPEG, WebP or SVG, at most 256 KB. The type is checked from the file's content, so a renamed file is refused.
• The logo replaces the shield in the sidebar, on the sign-in page and on public assessment pages, and becomes the browser tab icon. A wide logo works best at about 4:1.
• The logo is stored in the database (and so in backups) and served from /api/branding/logo to anyone, since the sign-in page shows it before sign-in. An SVG is served with a policy that stops any script inside it from running.
• Remove returns to the shield.

Every save and every logo change is recorded in the Audit Log (module settings, entity branding or branding.logo).

To brand a new instance:

1. Open /settings/branding.
2. Enter the Product name your users know the service by.
3. Enter the Brand color as #rrggbb, or pick it.
4. Leave Show "Powered by" credit off unless your agreement asks for it.
5. Click Save.
6. Click Upload logo and choose the file.
7. Open the sign-in page in a private window to check the result. Other open sessions pick up the change within 30 seconds.

Set APP_NAME in the deployment as well (see Configuration Reference) when you want the right name to appear before anyone has signed in to set it, for example on the first sign-in page after installation.

6.4 Labels

Labels are short colored tags, such as board-visibility or quick-win, used to group records across modules and classifications. Settings → Labels (address /settings/labels) manages the list. Labels can be attached to eight record types: risks, controls, assets, third parties, incidents, policies, audit findings and projects.

• The record pages of risks, controls, third parties, incidents, policies and projects have a Labels picker below the description.
• Assets and audit findings have no record page of their own, so the asset list and an audit plan's Findings tab edit labels inline, in the Labels column of each row.
• Every one of these lists has a Labels column. Its filter finds records carrying a label whose name contains the text you type, and Export CSV writes the label names separated by "; ".

The page lists each label's Name (with its color), Color (hex value), Assignments (how many records carry it), Created and actions.

Rules for a label:

• Name: lowercase letters, digits and single dashes, up to 60 characters, for example critical-vendor. Names are unique.
• Color: one of the preset swatches or any hex color (#0ea5e9).
• Deleting a label removes it from every record. It cannot be undone, and the Audit Log keeps the deletion.

Because creating a label from a record's picker needs settings:create, record owners without Settings rights can only choose labels that already exist. Create the vocabulary up front.

6.5 Custom fields

Custom fields add your own attributes to records, such as a cost center on projects or a vendor tier on third parties. Settings → Custom Fields (address /settings/custom-fields) defines them.

6.5.1 Where custom fields apply

The page has one tab per record type. A field belongs to one record type for good; it cannot be moved to another.

Assets, business units, audit findings and exceptions have no custom fields.

6.5.2 Field types

Select and Multi-select fields need at least one option; options are unique, up to 200 characters each and up to 100 per field.

6.5.3 Creating and changing fields

Opening the page needs customFields:read. Creating, changing and deleting fields need the matching right at the all level. The built-in GRC Manager role holds all four; Risk Owner and Auditor can read.

1. Open the tab for the record type and click Create field.
2. In the Create custom field dialog, enter the Name (unique within the record type, up to 200 characters), choose the Type and set the Sort order (lower numbers first).
3. For Select and Multi-select, add the Options with Add option.
4. Tick Required if every record of this type must have a value.
5. Click Create field.

In the list, the Active switch hides a field from records without deleting it or its values; turn it back on to show them again. The pencil opens Edit custom field (save with Save changes); the trash deletes the field after the Delete custom field? confirmation, together with every value stored for it. Deleting cannot be undone.

Points to know before changing a field in use:

• Required is checked when someone saves the field values on a record. It does not stop a record from being created without a value, by a form, a CSV import or the API. A required checkbox must be ticked to save.
• Changing a field's Type does not convert values already stored. Create a new field and retire the old one instead.
• Removing an option does not change records that already hold it.
• Renaming a field changes its CSV import column (Custom: <field name>), so update any saved import files.

6.5.4 How custom fields appear

• On the record's page, in a Custom Fields tab or card listing the active fields in sort order, with required ones marked. Edit opens the values dialog. Viewing needs read on the record; editing needs update on it.
• In CSV imports for risks, controls, policies, third parties, incidents and projects, as extra columns headed Custom: <field name> (see Loading and Importing Data).
• In the REST API, at /api/v1/custom-fields (definitions) and /api/v1/custom-fields/values (values per record).

Custom fields are not shown as list columns and are not part of the Report Center reports.

6.6 Risk Settings

Risk Management → Risk Settings (address /risks/settings) holds the scoring engine every risk uses. It opens with settings:read; changing it needs settings:update, and adding or removing entries also needs settings:create or settings:delete, all at the all level. The User Manual chapter Risk Management explains how scores are calculated; this section covers what an administrator decides and what each change does to existing risks.

6.6.1 What a new installation contains

These are created only when the tables are empty. An upgrade never puts back a classification or band you deleted.

6.6.2 Classifications

Classifications are the tabs of the risk register. Each has a Name, a Slug (lowercase, unique; built from the name when left blank), a Sort order and an optional Description. Add one with New classification. A classification cannot be deleted while any risk uses it; move those risks first. The Third-party classification's slug (third-party) cannot be changed, because attaching risks to vendors depends on it; its name can. A risk moved out of it is detached from its vendor, and both the risk's and the vendor's history record that.

6.6.3 Magnitudes

The Likelihood and Impact scales, each with its own Add button. Each level has a Kind, a Name, a numeric Value, a Sort order and an optional Description. Values are unique within a scale, and risks store the value. A level's value cannot be changed, and the level cannot be deleted, while a risk or a matrix cell uses it; the refusal says how many records refer to it. Renaming a level is always allowed.

6.6.4 Calculation matrix

One score per likelihood and impact pair, labeled L1 to L5 and I1 to I5 by value. Cells are tinted with the band their score falls in. Click Save matrix to store all cells at once; every risk is recalculated immediately.

A pair with no cell scores 0, which no band covers, so its risks show as unscored. After adding a level, fill in its new row or column and click Save matrix before anyone rates a risk with it.

6.6.5 Appetite bands

Each band has a Name, a Min score, a Color, an Over appetite switch and a Sort order. A band covers scores from its minimum up to the next band's minimum. Bands marked over appetite drive the red banner on risks, the Risks over appetite dashboard widget and the risk.appetite.breach email. Creating, editing or deleting a band recalculates every risk.

6.6.6 Recalculate all risks

Recalculate all risks recomputes every risk's residual score from the current matrix, bands and treatments, and sends the over-appetite email for any risk that crosses into an over-appetite band. Use it after changing data outside the normal screens, for example after a database restore.

6.6.7 Changing the scale on a live register

Every save on this page rescores all risks at once, and a risk that moves into an over-appetite band emails its owner. Before changing a scale in use:

1. Agree the new scale with the risk owners and write down how old ratings map to new ones.
2. Add the new levels first, then fill the matrix and click Save matrix.
3. Re-rate the affected risks (by CSV import with inherent_likelihood and inherent_impact, or in the app).
4. Delete the old levels once nothing uses them.

To replace levels, matrix and bands in one step, use the bundle loader's riskScale or PUT /api/v1/risk-scale (see Loading and Importing Data). That route refuses the change while any risk uses a level the new scale drops.

6.7 Control testing settings

On Risk Management → Controls, the Settings button (shown with settings:read) opens Control testing settings, a single choice:

Create the audit plan first (for example "Control testing findings"); until a plan exists the dialog says so. Saving needs settings:update. The schedules, metrics and success criteria of individual controls are set on each control (see the User Manual, Risk Management).

6.8 Incident classifications

Incident classifications are the categories incidents are filed under (for example Phishing or Data breach). The Classifications button on the Incidents page opens the Incident classifications dialog; it appears for people with incidents:update at the all level. Add a classification with a Name and a Sort number, rename or reorder it with the pencil, and delete it with the trash. A classification cannot be deleted while incidents use it. A new installation has none.

6.9 Policy settings

Settings → Policies has one card, Approvals made outside the app, with one switch:

Only an administrator can change it; the change is recorded in the Audit Log. Turn it on before loading policies through the bundle loader with effectiveDate and signatories (see Loading and Importing Data).

6.10 Privacy settings

Settings → Privacy has two cards.

Records of processing header is printed at the top of the Article 30 register export. Viewing needs settings:read; saving needs settings:update.

Empty fields print empty.

DPIA approval has its own Save and is changed only by an administrator:

Saving audits each changed setting and, when any value changes, emails every administrator ("DPIA approval settings changed").

6.11 Sessions page: token lifetime, storage and separation of duties

Settings → Sessions (address /settings/security) holds three cards. Anyone with settings:read can view them; only an administrator can save. The Two-step verification card is described under Two-step verification in Authentication and Single Sign-On.

The Sign-in sessions, API tokens and storage card:

Saving the card is audited and emails every administrator.

The Separation of duties card has one switch, Relax separation of duties, off by default. By default:

• the person who requested a risk, compliance or policy exception cannot decide it;
• the person who requested an in-app policy approval cannot approve it;
• a Data Liaison cannot review their own questionnaire answers;
• when Require a second person to approve DPIAs is on, a DPIA's author cannot approve or reject it.

Turning the switch on lifts only the "same person" condition, for teams too small to have a second person decide. The person still needs the right the decision always needs. Every decision that succeeds only because of the switch is stored and audited as self-approved, and the record shows a Self-approved badge (Self-decided for a rejection). Turning the switch off stops new self-approvals; past ones keep their badge. Naming yourself as the approver of your own exception stays refused either way.

The card warns that auditors usually expect a second person on these decisions. Saving is audited and, when the value changes, emails every administrator. Leave it off unless the team genuinely has one person in the role, and record the decision in your control documentation.

6.12 Settings checklist for a new instance

Work through these in order after the first administrator signs in (see Installation for the steps before this):

1. Branding: product name, color and logo.
2. Integrations → SMTP, then Send test email (see Notifications and Email).
3. Authentication: LDAP or SAML, SCIM if used, and break-glass administrators (see Authentication and Single Sign-On).
4. Sessions: session and idle limits, API token lifetime, storage per user, separation of duties.
5. Users, groups and roles (see Users, Groups and Roles).
6. Risk Settings: classifications, scales, matrix and appetite.
7. Incident classifications, Labels and Custom fields.
8. Policies and Privacy settings.
9. Notifications: templates, scheduler, rules.
10. Load or import your data (see Loading and Importing Data).
11. AI assistants and API tokens, only when an integration needs them.