diff --git a/site/guide/risk-tiering/configure-risk-tier-calculation.qmd b/site/guide/risk-tiering/configure-risk-tier-calculation.qmd index 5ab831ab8..917317803 100644 --- a/site/guide/risk-tiering/configure-risk-tier-calculation.qmd +++ b/site/guide/risk-tiering/configure-risk-tier-calculation.qmd @@ -4,10 +4,10 @@ # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial title: "Configure risk tier calculation" date: last-modified -description: "Set up scoring levels, risk factors, components, scoring rules, thresholds, and override rules inside a draft template." +description: "Set up scoring levels, risk factors, components, scoring rules, thresholds, tier assignment rules, and override rules inside a draft template." --- -This page covers all calculation configuration inside a risk tier template: scoring levels, risk factors, components, scoring rules, thresholds, and override rules. All configuration requires the template to be in **Draft** status — configuration is locked once a template is published. +This page covers all calculation configuration inside a risk tier template: scoring levels, risk factors, components, scoring rules, thresholds, tier assignment rules, and override rules. All configuration requires the template to be in **Draft** status — configuration is locked once a template is published. For creating a template, defining risk tier levels, and managing its lifecycle, see [Manage risk tier templates](manage-risk-tier-templates.qmd). @@ -199,9 +199,55 @@ Tier assignment maps every combination of factor levels to a risk tier. See [Override rules](#override-rules) below. +## Set up a Rules template {#set-up-a-rules-template} + +A Rules template assigns the tier from an ordered list of rules instead of a score. Each rule has one or more conditions and a target tier. Rules are evaluated in order, the first rule that matches sets the tier, and a default tier applies when no rule matches. + +Use Rules when your methodology escalates on specific answers rather than on a total — for example: "Critical if more than four answers are critical, or if there is a critical answer in Consumer Impact and another in Fairness." + +### 1. Configure scoring levels and risk factors (if needed) + +Scoring levels and risk factors are only required if a rule uses a **Count of** condition, which counts how many components scored at chosen levels. Rules that only compare inventory field values need neither. + +To use **Count of**, set up scoring levels, risk factors, and components with scoring rules as described in [Set up a Scorecard template](#set-up-a-scorecard-template), steps 1–3. The factor aggregation method and weights are not used under Rules. + +### 2. Add tier assignment rules + +1. Go to the **Tier Assignment** section and click **Add Rule**. +2. In **Assign tier to**, select the tier this rule assigns. +3. Under **When these conditions are met**, click **Add Rule** to add a condition, and choose how conditions combine with **AND** or **OR**. +4. Click **Add Group** to combine some conditions with a different operator — for example: "A **OR** (B **AND** C)." Groups can be one level deep. +5. Click **Add Assignment Rule**. +6. Repeat for each rule. Order rules from the most severe tier to the least severe — the first rule that matches wins. + +### 3. Choose condition types + +Each condition is one of two types: + +- **Field value** — compares one inventory field, picked from the record fields in the field list, using the same field types and operators as [override rules](#supported-field-types-and-operators). +- **Count of** — counts the components that scored at one or more chosen scoring levels and compares the count to a number, for example: "count of **Critical** is more than 4." Select **Count of** under **Scoring** in the field list, choose the scoring levels to count, the operator and the number, then optionally limit the count with **in** to specific risk factors or individual components. Without a limit, the count covers every component in the template. + +:::{.callout-note} +**Count of** is unavailable until the template has scoring levels and at least one risk factor with a component. +::: + +### 4. Select the default tier + +In the **Default** row of the **Tier Assignment** section, select the tier assigned to records that no rule matches. A default tier is required before the template can be published. + +### 5. Configure override rules + +See [Override rules](#override-rules) below. Override rules are evaluated before the tier assignment rules. + +:::{.callout-tip} +### Express a decision tree as rules + +Any decision tree can be written as Rules: each path from the top of the tree to a tier becomes one rule whose conditions are the branch tests along that path, combined with **AND**. Order the rules so the most specific paths come first, and use the default tier for the final branch. Rules do not offer a visual tree editor, and conditions cannot branch on a computed factor score or total. +::: + ## Override rules -Override rules allow you to hard-code a specific tier outcome for records that match certain field conditions, bypassing the computed score or matrix lookup entirely. If a rule matches, the tier it specifies is used and no further rules or scores are evaluated. +Override rules allow you to hard-code a specific tier outcome for records that match certain field conditions, bypassing the computed score, matrix lookup, or tier assignment rules entirely. If a rule matches, the tier it specifies is used and no further rules or scores are evaluated. Use override rules when certain field values are disqualifying regardless of the overall score — for example: "if a model processes health data AND is customer-facing, always assign Critical." @@ -243,10 +289,10 @@ Override rules are copied forward when a new template version is created. Removi Before publishing, verify: -**Both methods:** +**All methods:** - [ ] At least one risk tier is defined -- [ ] At least one risk factor is configured +- [ ] At least one risk factor is configured (Rules: only if a rule uses **Count of**) - [ ] Every factor has at least one component - [ ] Every component has at least one scoring rule - [ ] All scoring rules map to valid scoring levels @@ -262,6 +308,12 @@ Before publishing, verify: - [ ] All factor level thresholds are set for every factor - [ ] Every factor level combination in the matrix has an assigned tier +**Rules only:** + +- [ ] At least one tier assignment rule is defined +- [ ] A default tier is selected +- [ ] Scoring levels are defined if any rule uses **Count of** + ## What's next - [Manage risk tier templates](manage-risk-tier-templates.qmd) — publish, version, and manage the template lifecycle. diff --git a/site/guide/risk-tiering/manage-risk-tier-assessments.qmd b/site/guide/risk-tiering/manage-risk-tier-assessments.qmd index 5a08df76e..b4819aa3c 100644 --- a/site/guide/risk-tiering/manage-risk-tier-assessments.qmd +++ b/site/guide/risk-tiering/manage-risk-tier-assessments.qmd @@ -7,7 +7,7 @@ date: last-modified description: "Create, review, publish, and version risk tier assessments for individual inventory records." --- -A risk tier assessment is a formal evaluation of a specific inventory record against a published risk tier template. It reads the current inventory field values, applies the template's scoring rules, and produces a tier determination — either computed from scores or set by an override rule. +A risk tier assessment is a formal evaluation of a specific inventory record against a published risk tier template. It reads the current inventory field values, applies the template's scoring rules, and produces a tier determination — computed from scores, assigned by the template's tier assignment rules, or set by an override rule. This page covers creating an assessment, reviewing factor scores, publishing, managing versions, and handling stale assessments. @@ -39,7 +39,7 @@ If no active template exists for the record's type, a new assessment cannot be c ## Review factor scores -The assessment detail page is organized into five sections. Together they show how the record's current inventory field values translate into a risk tier. +The assessment detail page is organized into sections that together show how the record's current inventory field values translate into a risk tier. Which sections appear depends on the template's calculation method: a Rules template shows **Tier Assignment Rules** instead of the **Factor Score Breakdown** and **Risk Tier Thresholds**. ### Risk Factors @@ -72,6 +72,10 @@ The **Current Total Score** row at the bottom shows the sum across all factors. The **Risk Tier Thresholds** table shows the score band for each risk tier. The row corresponding to the current total score is highlighted, indicating where the record lands on the scorecard. +### Tier Assignment Rules + +For a template that uses the Rules method, the **Tier Assignment Rules** section displays the template's rules as read-only, in the order they are evaluated, followed by the default tier. The rule that set this record's tier is highlighted. + ### Override Rules The **Override Rules** section displays the template's override rules as read-only, evaluated in order against this record. Each rule shows its number, target tier, and condition — for example: "Rule 1 → Tier 1: If Estimated Dollar Exposure ≥ 10000000." @@ -83,7 +87,12 @@ Override rules are part of the template and cannot be modified from within an as The **Calculated Tier** section shows the final tier determination for this assessment: - If an override rule matched, the section indicates which rule applied and the tier it assigned. -- If no override rule matched, the tier is determined by where the current total score falls in the threshold bands. +- For a Scorecard template, the tier is determined by where the current total score falls in the threshold bands. +- For a Rules template, the section names the first rule that matches, or states that no rule matched and the default tier applies. + +For a Rules template, a **Why** list under the tier shows each condition of the matching rule and whether it held — including conditions that did not, which explain why a less severe rule did not apply. For a **Count of** condition, it shows the count, what the rule needed, and the answers that were counted — for example: "2 scored Critical in Consumer Impact Risk (needs at least 1)." + +If required inputs are missing, no tier is calculated and the section lists what to complete. For a Rules template this includes any empty inventory field that a tier assignment rule reads. ## Assessment sidebar @@ -93,7 +102,7 @@ The sidebar on the assessment detail page shows: - **Assessment Stage** — the assessment's current governance stage, shown when risk tiering workflows are in use. The stage tracks review progress separately from the status and updates live as a workflow advances. See [Set up risk tiering workflows](set-up-risk-tiering-workflows.qmd). - **Active Workflows** — the workflow runs governing this assessment, shown when risk tiering workflows are in use. Click **See All Workflows** to start a manually triggered workflow or inspect a run. - **Assessment Version** — a dropdown showing the current version (for example: "13 (Latest)"). Use this to navigate to any previous version of the assessment. -- **Risk Tier Template** — the template name and version this assessment is linked to, with a badge showing the calculation method (Scorecard or Risk Matrix). +- **Risk Tier Template** — the template name and version this assessment is linked to, with a badge showing the calculation method (Scorecard, Risk Matrix, or Rules). - **Published / Published By** — the publication date and the user who published it (shown once the assessment has been published). Actions available from the sidebar depend on the assessment's status: @@ -110,6 +119,8 @@ When you are satisfied with the factor scores and the calculated tier: Only one assessment can be Active per record at a time. +Publishing is unavailable until every required input is complete and a tier can be calculated. + If a [risk tiering workflow](set-up-risk-tiering-workflows.qmd) is configured to start on publish for this record type, publishing also starts a governance review of the published version. Publishing a new version ends any still-running review of the previous version and starts a fresh one. :::{.callout-note} diff --git a/site/guide/risk-tiering/manage-risk-tier-templates.qmd b/site/guide/risk-tiering/manage-risk-tier-templates.qmd index a3b6f950a..3db5bcc94 100644 --- a/site/guide/risk-tiering/manage-risk-tier-templates.qmd +++ b/site/guide/risk-tiering/manage-risk-tier-templates.qmd @@ -36,6 +36,7 @@ On the template detail page, select the **Tier Calculation Method**: - **Scorecard** — factor scores are summed into a total that falls into a threshold band mapped to a tier. Factor weights can optionally be configured in the Risk Factors section. - **Risk Matrix** — each factor is independently classified into a discrete risk level, and the combination of all factor levels is looked up in a matrix to determine the final tier. +- **Rules** — an ordered list of rules assigns the tier; the first rule that matches wins, and a default tier applies when none match. Once selected, configure the scoring logic for your chosen method. See [Configure risk tier calculation](configure-risk-tier-calculation.qmd). diff --git a/site/guide/risk-tiering/working-with-risk-tiering.qmd b/site/guide/risk-tiering/working-with-risk-tiering.qmd index 26886a3ed..71e9cb648 100644 --- a/site/guide/risk-tiering/working-with-risk-tiering.qmd +++ b/site/guide/risk-tiering/working-with-risk-tiering.qmd @@ -37,11 +37,12 @@ The complete methodology for evaluating a record's risk. A template defines tier A formal evaluation of a specific record against a risk tier template. An assessment records the field values entered, the computed scores, the system's suggested tier, any override rules that applied, and the final published determination. **Tier calculation method** -Controls how risk factor scores roll up into a final tier: +Controls how a record's inputs become a final tier: - **Scorecard (Sum)** — factor scores are summed into a total that falls into a threshold band mapped to a tier. - **Scorecard (Weighted)** — same as Sum, but each factor carries a weight (0–1); factor scores are multiplied by their weights before summing. Factor weights are required. - **Risk Matrix** — each factor is independently classified into a discrete risk level, and the combination of all factor levels is looked up in a matrix to determine the final tier. +- **Rules** — an ordered list of rules, each with conditions and a target tier. The first rule that matches sets the tier; if none match, a default tier applies. Suited to decision-tree and knock-out methodologies, and to counting how many answers reach a severity. **Risk tier** A discrete risk classification outcome — for example: Low, Medium, High, Critical. Risk tiers are defined as part of a template and represent the possible outputs of an assessment.