Computed Fields

Ketryx allows you to define computed fields that automatically calculate their values based on other field values. This feature is useful for deriving risk scores based on non-standard frameworks, auto-classifying items, performing matrix lookups, and maintaining consistent calculated values across your configuration items.

How to enable

To enable computed fields:

1. Contact Ketryx Support to enable the enableComputedFields feature flag for your organization

2. Once enabled, you can configure computed fields in your organization's Advanced Settings

Use cases

Computed fields support several workflows:

• Risk scoring - Automatically derive risk levels from probability and severity inputs using non-standard matrix lookups

• Classification - Auto-classify items based on field values (e.g., marking items as "Controlled" or "Uncontrolled" based on severity)

• CVSS scoring - Extract severity levels and scores from CVSS vectors

• Conditional values - Set field values based on conditions (if/then logic)

• Derived text - Concatenate or transform text field values

Computed fields are read-only. Users cannot manually edit the values of computed fields—they are always calculated based on their input fields.

Configuring computed fields

Computed fields are configured at the organization level in Advanced Settings under Custom item fields configuration.

Step 1: Define the custom field

First, add your computed field to the Custom item fields configuration. The field must be of type SELECT or SHORT_TEXT:

{
  "Risk Level": {
    "type": "SELECT",
    "options": ["Low", "Medium", "High", "Critical"],
    "isEditableInKetryx": true
  }
}

Step 2: Add the computed field configuration

In the Item fields configuration, reference your custom field and add a computedFieldConfig object:

{
  "Requirement": {
    "addedFields": [
      {
        "kind": "CUSTOM",
        "name": "Risk Level",
        "computedFieldConfig": {
          "expression": "vars.matrix[fieldValue.Probability][fieldValue.Severity]",
          "vars": {
            "matrix": {
              "Low": {
                "Minor": "Low",
                "Major": "Medium",
                "Critical": "High"
              },
              "Medium": {
                "Minor": "Medium",
                "Major": "High",
                "Critical": "Critical"
              },
              "High": {
                "Minor": "High",
                "Major": "Critical",
                "Critical": "Critical"
              }
            }
          },
          "description": "Calculates risk level from probability and severity"
        }
      }
    ]
  }
}

Configuration schema

Property	Type	Required	Description
expression	string	Yes	The computation expression (see Expression syntax)
vars	object	No	Variables available in the expression for lookups and constants
description	string	No	Documentation describing what the field computes

Expression syntax

Computed field expressions use the same syntax as the Ketryx document templating language. Expressions are evaluated in real-time as users edit input fields.

Accessing field values

Use fieldValue.FieldName or fieldValue["Field Name"] to access other fields:

fieldValue.Description
fieldValue["Requirement Type"]
fieldValue.Severity

Accessing variables

Use vars.variableName to access variables defined in the vars configuration:

vars.matrix[fieldValue.Input1][fieldValue.Input2]
vars.severityLevels[fieldValue.Category]

Supported operations

Operation	Example	Description
Field access	fieldValue.Title	Access a field value
Variable access	vars.lookup	Access a configured variable
Ternary (if/else)	condition ? "Yes" : "No"	Conditional logic
Comparison	fieldValue.Score > 5	Compare values (==, !=, >, <, >=, <=, ===, !==)
Logical AND	a && b	Both conditions must be true
Logical OR	a || b	Either condition can be true
String concatenation	"Prefix: " + fieldValue.Name	Combine strings
Array/object indexing	vars.matrix[key1][key2]	Lookup values in nested objects

Input field types

The following field types can be used as inputs to computed fields:

• SHORT_TEXT - Plain text fields

• RICH_TEXT - Rich text fields (e.g., Description)

• SELECT - Dropdown/select fields

Note: CVSS scoring fields receive special handling—they are converted to an object with level, score, and vector properties:

fieldValue.CvssScore.level   // "Critical", "High", "Medium", "Low", "None"
fieldValue.CvssScore.score   // Numeric score (e.g., 9.8)
fieldValue.CvssScore.vector  // The CVSS vector string

Output field types

Computed fields can output to:

• SELECT - The expression result must match one of the field's configured options

• SHORT_TEXT - The expression result is converted to a string

Expression examples

If statements (conditional logic)

Set a field value based on a condition:

fieldValue.Severity != null && fieldValue.Severity !== "High" ? "Controlled" : "Uncontrolled"

More complex conditions:

fieldValue.Score >= 9 ? "Critical" : 
fieldValue.Score >= 7 ? "High" : 
fieldValue.Score >= 4 ? "Medium" : "Low"

Matrix lookup

Look up a value from a two-dimensional matrix:

Expression:

vars.riskMatrix[fieldValue["Probability"]][fieldValue["Severity"]]

Variables:

{
  "riskMatrix": {
    "Remote": {
      "Negligible": "Low",
      "Minor": "Low", 
      "Serious": "Medium",
      "Critical": "High"
    },
    "Occasional": {
      "Negligible": "Low",
      "Minor": "Medium",
      "Serious": "High",
      "Critical": "High"
    },
    "Probable": {
      "Negligible": "Medium",
      "Minor": "High",
      "Serious": "High",
      "Critical": "Critical"
    }
  }
}

Simple value mapping

Map one field's value to another:

Expression:

vars.categoryMapping[fieldValue.Category]

Variables:

{
  "categoryMapping": {
    "Bug": "Corrective",
    "Enhancement": "Perfective",
    "Security": "Preventive"
  }
}

CVSS severity extraction

Extract severity level from a CVSS field:

fieldValue.CvssVector.level

Or use the built-in filter:

fieldValue.CvssVectorString | toCvssSeverityLevel

Field dependencies

Computed fields can depend on other computed fields. When a computed field uses another computed field as an input, the fields are evaluated in the order they are defined.

Important: If Field B depends on Field A, Field A must be defined before Field B in your configuration.

{
  "addedFields": [
    {
      "kind": "CUSTOM",
      "name": "Risk Score",
      "computedFieldConfig": {
        "expression": "vars.matrix[fieldValue.P1][fieldValue.P2]"
      }
    },
    {
      "kind": "CUSTOM", 
      "name": "Risk Category",
      "computedFieldConfig": {
        "expression": "fieldValue[\"Risk Score\"] >= 7 ? \"High\" : \"Low\""
      }
    }
  ]
}

Real-time calculation

When users edit items with computed fields:

1. Changes to input fields trigger automatic recalculation

2. Recalculation is debounced (500ms delay) to avoid excessive requests

3. Computed field values update in real-time in the form

4. Computed fields remain read-only—users cannot override calculated values

Error handling

If an expression fails to evaluate:

• An error toast notification appears: "Could not recalculate fields"

• The computed field retains its previous value (or remains empty if never calculated)

• The error is logged for troubleshooting

Common causes of errors:

• Null values - Input field is empty; use null checks in expressions

• Missing lookup keys - The input value doesn't exist in your lookup table

• Syntax errors - Malformed expression syntax

Tip: Use null checks to handle empty fields gracefully:

fieldValue.Input != null ? vars.lookup[fieldValue.Input] : "Unknown"

Limitations and considerations

• Custom fields only - Computed fields must be custom fields, not built-in system fields

• Read-only - Users cannot manually edit computed field values

• Feature flag required - The enableComputedFields flag must be enabled

• Definition order matters - Dependent computed fields must be defined after their dependencies

• Supported output types - Only SELECT and SHORT_TEXT field types can be computed

• No relation field access - Expressions cannot access related items' field values

Troubleshooting

Computed field not updating:

• Verify the enableComputedFields feature flag is enabled

• Check that input fields are populated (null values may cause issues)

• Ensure input field names in the expression exactly match field names (case-sensitive)

Expression returning wrong value:

• Verify lookup table keys match actual field values exactly

• Check for trailing spaces in select field options

• Use browser developer tools to inspect the calculation request/response

Field showing as editable:

• Confirm the computedFieldConfig is properly configured

• Verify the field is added to the correct item type in Item fields configuration