Advanced Settings

Reference of advanced settings for Ketryx organizations and projects

Ketryx is highly configurable using advanced settings at the organization and project level.

To access or change the organization-level settings (under Organization > Advanced), you need to be an organization owner. You can also change project-level default settings at the organization level; projects will inherit these defaults for each setting, unless the setting is explicitly defined at the project level.

To change the project-level settings (under a project's Settings > Advanced), you need to have the Manage project permission.

Keep in mind that configuring these advanced settings incorrectly can have undesired consequences for your configuration items, Jira configuration, and member authentication. Proceed with care. When in doubt, please contact Ketryx Support. By design, not all internal settings are exposed. Also note that some parameters might change in future releases.

Advanced settings are generally specified as JSON values. Watch out for proper delimiters, punctuation, and nesting when editing these values.

Some settings involve internal IDs (e.g., for item types, document types, or field keys). These IDs are documented in the Internal IDs section at the end of this reference.

Global item configuration

Item type names

Mapping of standard item type names (e.g. "Requirement") to user-defined custom names (e.g. "Feature").

This is commonly used in combination with custom settings for Item type short names and Superseded item types.

Use the item type name "Feature" instead of "Requirement"

{
  "Requirement": "Feature"
}

Item type short names

Mapping of standard item type names (e.g. "Requirement") or custom type names (e.g. "Folder") to user-defined custom short names (e.g. "FEAT").

Note that the standard type name (e.g. "Requirement") is used even if the type has been renamed (e.g. to "Feature") via the Item type names setting.

Custom type names may be defined via the project setting Issue mapping.

Use the short names "FEAT" for Requirements and "FLD" for the custom type Folder

{
  "Requirement": "FEAT",
  "Folder": "FLD"
}

Superseded item types

For each (custom) issue type name, a list of issue types it supersedes (if any). When a superseded issue type exists, it will be renamed to the new name (e.g. "Requirement" -> "Feature"), rather than creating a new issue type.

This is only effective in combination with a setting for Item type names. It only affects the Jira configuration process in case the new issue type does not exist yet. If both the previous and the new issue type exist already, the previous issue type will not be removed or renamed.

Rename the "Requirement" issue type to "Folder"

{
  "Feature": [
    "Requirement"
  ]
}

Field names

Custom name of each field, as a mapping from system field keys to custom names.

Fields with custom names are created as custom fields in Jira, rather than using the fields provided by the Ketryx Jira app. Previous field values might have to be migrated from the previous field to the new field in Jira.

This can be used in combination with Superseded field names when switching from one custom name to another custom name.

Rename "Regions" to "Regulatory regions"

{
  "regions": "Regulatory regions"
}

Superseded field names

For each field key with a custom name, a list of field names that it supersedes (if any). When a superseded (custom) field exists, it will be renamed to the new name, rather than creating a new field.

This is only effective in combination with a setting for Field names. It only affects the Jira configuration process in case the new field does not exist yet. If both the previous and the new field exist already, the previous field will not be removed or renamed.

Note that this can not be used to rename an app field to a custom field (only from one custom name to another custom name).

Select field options

Mapping from select field keys (e.g. "capaType") to their custom configuration, which allows to override the name of individual options or to remove some options.

The name of each option needs to unique among the options for a given field.

When mapped to null, an option is not exposed to the user.

Note this mechanism can not be used to add new options.

Rename the "Backend" option for the "CAPA type" field to "Server"

{
  "capaType": {
    "BACKEND": "Server"
  }
}

Remove the "Backend" option for the "CAPA type" field

{
  "capaType": {
    "BACKEND": null
  }
}

Item fields

Mapping from standard item type names (e.g. "Requirement") to a configuration of fields to show for such items.

Remove the fields "Relevant standards" and "Context" from Requirement items

{
  "Requirement": {
    "removedFields": [
      "relevantStandards",
      "requirementContext"
    ]
  }
}

Relation names

How to map relation names to Ketryx relation types when fetching data from Jira. There can potentially be several Jira relation names mapped to the same Ketryx relation. By default, the names as displayed in Ketryx are used.

Note that the direction of the relation in Jira ("inward" vs. "outward") does not matter, as long as the name matches.

Use the name "is child of" instead of the default relation name "has parent"

{
  "HAS_PARENT": [
    "is child of"
  ]
}

Xray

Xray-specific configuration.

This can be used to configure custom status names (other than the default "PASSED" and "FAILED"). For each Ketryx status ("pass", "passWithException", "fail"), a list with an arbitrary number of Xray status names (including potentially an empty list) can be configured.

Configure custom status names used in Xray

{
  "testStatusNames": {
    "pass": [
      "Passed",
      "OK"
    ],
    "passWithException": [
      "Passed with note"
    ],
    "fail": [
      "Failed",
      "Not OK"
    ]
  }
}

Custom document types

A list of custom document types to provide better flexibility in managing documents in your projects' EDMS.

Any types defined here will have their own approval groups (configured on each project's Approval rules page) and they will be selectable for all EDMS documents in every project.

NOTE: Changing the "name" of any type will effectively remove the old type and create a new one with the new name. Existing documents with the old type will not be automatically transferred over to the new type.

Add custom document types for Manual and SOP

[
  {
    "name": "Manual",
    "shortName": "MAN"
  },
  {
    "name": "SOP",
    "shortName": "SOP"
  }
]

Authentication configuration

Authentication providers

Custom authentication providers for this organization. Supported properties are email, okta, and customOAuth.

This needs to be configured in combination with a custom email domain for this organization (managed by Ketryx Support).

For authentication via Okta, create a new App Integration in your Okta instance and configure it in the following way:

Use "OIDC - OpenID Connect" authentication with the application type "Web Application"
For Grant type, choose "Client acting on behalf of a user" via an "Authorization Code"
Set the Sign-in redirect URL to https://app.ketryx.com/api/auth/callback/okta
Set the Sign-out redirect URL to https://app.ketryx.com
Make sure that all desired members of the organization are assigned to the app in Okta
Configure the authentication provider in Ketryx using Okta's client ID, client secret, and issuer URL, as in the example below

Configure Okta authentication (based on a CLIENT_ID and CLIENT_SECRET retrieved from Okta, and an appropriate Okta URL)

{
  "okta": {
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "issuer": "https://ORGNAME.okta.com",
    "allowDangerousEmailAccountLinking": true
  }
}

Allow authentication via Okta in addition to email-based authentication

{
  "okta": {
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "issuer": "https://ORGNAME.okta.com",
    "allowDangerousEmailAccountLinking": true
  },
  "email": true
}

Project item configuration

Issue mapping

Mapping from Jira issue types to Ketryx items. This array of mapping entries is traversed in order, and the first match is taken; so there can potentially be several mappings from the same Jira issue type or to the same Ketryx item type (based on different other criteria, such as labels). If there is no match, the Jira issue is not synchronized to Ketryx.

If multiple labels are specified in a single mapping entry, all of them need to match for the mapping to be effective. To specify several labels where any of them should be mapped to a certain item type, use distinct mapping entries.

In addition to inferring a certain item type, field values can also be predefined for each mapping:

fieldValues defines values that are always set, regardless of any explicit value defined on the Jira issue.
fieldDefaults defines values that are only set if there is no explicit value defined on the Jira issue.

Each of these properties is an object, mapping internal field keys (e.g. description for built-in fields or extra:My custom field for extra custom fields) to values as they would be retrieved from Jira.

An itemType of CUSTOM can be used to define a custom item type in Ketryx, along with an itemTypeName to specify its actual name. Such custom item types are considered "unchecked", i.e. they are not required to be controlled.

Map issues of type "Folder" or "Epic" to Requirements

[
  {
    "issueType": "Folder",
    "itemType": "REQUIREMENT"
  },
  {
    "issueType": "Epic",
    "itemType": "REQUIREMENT"
  }
]

Map Stories with the "Ketryx" label to Requirements

[
  {
    "issueType": "Story",
    "labels": [
      "Ketryx"
    ],
    "itemType": "REQUIREMENT"
  }
]

Map Stories with the "Ketryx" label to Requirements, and (more specifically) Stories with the label "UseCase" to Requirements with a type of "Use case"

[
  {
    "issueType": "Story",
    "labels": [
      "Ketryx",
      "UseCase"
    ],
    "itemType": "REQUIREMENT",
    "fieldValues": {
      "requirementType": {
        "value": "Use case"
      }
    }
  },
  {
    "issueType": "Story",
    "labels": [
      "Ketryx"
    ],
    "itemType": "REQUIREMENT"
  }
]

Status mapping

Mapping from Jira status names to Ketryx item states (OPEN, REOPENED, IN_PROGRESS, RESOLVED, or CLOSED).

Map the status "Backlog" to the Ketryx state Open, and "Done" to Resolved

{
  "Backlog": "OPEN",
  "Done": "RESOLVED"
}

Approval workflow

Mapping from item types (enum values such as 'REQUIREMENT', 'CUSTOM' or plain-text values such as 'Requirement', 'Folder') and Jira status names (e.g. 'Open', 'New') to approval workflow customizations.

Enforce that Requirements have a required (extra) field "Acceptance Criteria" before they can be approved

{
  "REQUIREMENT": {
    "Resolved": {
      "isApprovable": true,
      "approvalMeaning": "REVIEWED",
      "requiredFieldNames": [
        "Acceptance Criteria"
      ],
      "approvedTransitionStatus": "Closed",
      "invalidatedTransitionStatus": "Resolved",
      "shouldTransitionWhenApproved": true
    }
  }
}

Approval rules

Custom approval rule overrides, allowing an arbitrary KQL filter. These are applied after the general approval rules of the project (defined by the user) and the backend customizations defined by approvalWorkflow, i.e. these approvalRules are the most specific setting.

Electronic signature item types

Item types (with their standard names) that require an electronic signature. The default would be ["Risk", "Test Case", "Test Execution", "Test Plan"].

Only require electronic signatures on Risk items

[
  "Risk"
]

Enable Item Assistant

Whether to enable the item assistant sidebar. Enabled by default.

Enable AI

Whether to enable AI-based features, particularly the AI-based item assistant and the 'Write AI text' button in the 'Create item' dialog. This only has an actual effect if AI usage is allowed at the organization level. Enabled by default.

Enable version deletion

Whether versions can be deleted by users with the appropriate permissions. Enabled by default.

Enable item invalidation

Whether to enable invalidation of items if controlled fields change, based on invalidatedTransitionStatus in the workflow configuration (by default, Closed items are transitioned back to Resolved for invalidation). If this is not set or null, invalidation is enabled unless the project is in observe-only mode (not using the predefined Ketryx workflows).

Removal status names

Status names to interpret as removal/obsolescence of an item w.r.t. releases, similarly to deleted items. Defaults to an empty list.

Treat items with the status of "Cancel" as removed/obsolete

[
  "Cancel"
]

Deletion status name (controlled)

Status name to represent deleted items in a controlled state. This status is set by Ketryx when a deletion is detected and does not need to be approved. Defaults to "Closed".

Deletion status name (uncontrolled)

Status name to represent deleted items in an uncontrolled state. This status is set by Ketryx when a deletion is detected that still needs to be approved. Defaults to "Resolved".

Uncontrolled field names

Names of fields to ignore w.r.t. the controlled state of a record and its content hash. Changing these fields does not influence the record's content hash and does not trigger a transition back into an uncontrolled state.

Ketryx will still create a new record with the new value, but the status will remain the same (unless other, controlled fields changed as well).

Allow setting the "Document ID" field even after an item is fully approved

[
  "Document ID"
]

Extra field names

List of extra custom field names to read from Jira. These should be defined as custom fields in Jira and added to the desired screens (Ketryx will not perform this Jira configuration automatically).

Track the extra fields "Acceptance Criteria" and "Source"

[
  "Acceptance Criteria",
  "Source"
]

Unchecked items filter

KQL filter for "unchecked" items, i.e. items that do not need to be controlled before a version can be released. By default, no items are considered unchecked.

Do not require Anomalies with an Environment of "internal" to be controlled

"Environment:\"internal\""

Deferred items filter

KQL filter for deferred items (anomalies). By default (if not specified), all Anomalies with a non-empty Rationale for deferring resolution will be considered deferred. Deferred items do not need to be in a controlled state (like unchecked items).

Invalid items filters

KQL filters to determine invalid items, along with error messages to show for them. Invalid items that are active in a version block the release of that version.

Enforce Anomalies with a Resolution of "Duplicate" to have a status of either "Done" or "Cancel"

[
  {
    "filter": "type:Anomaly and Resolution:\"Duplicate\" and not status:(Done, Cancel)",
    "message": "Duplicate anomalies need to have a status of either Done or Cancel"
  }
]

Enforce that all Test Cases that are risk controls are included in the test plan

[
  {
    "filter": "TC and RC and not intestplan:selected",
    "message": "All tests that are risk controls need to be in the test plan"
  }
]

Ignored test executions filter

Filter for Test Executions to ignore for the release test status. Just like "redundant" Test Executions (that are superseded by a later Test Execution), these are still shown in the Items page, but not elsewhere.

Use Test Executions only based on Test Plan

Whether to associate Test Executions with versions only based on (Xray) Test Plan items, but not based on their version field. This is off by default, i.e. a Test Execution's version field (Introduced in version) is considered, and only if that is not set, it is associated with a version based on containing Test Plans.

Enable automatic risk item updates on risk configuration change

When enabled, Ketryx will make sure to keep all Risk items up-to-date with any risk configuration changes by creating new item records (e.g. updating all the relevant computed initial / residual risk analysis values). Please note that controlled risks may require re-approval after an configuration update. This setting is enabled by default.

Build documents to be tracked for each project build

When defined, Ketryx will detect build documents in project builds that contain build artifacts with the configured filenames.

Build documents will show up on the commits history page and release documents page.

By default, Ketryx will only allow release approval when all defined build documents have been uploaded for a given version. This behavior can be disabled via the "Require uploaded build documents" Release controls setting.

Configure different report build documents relevant for a release

[
  {
    "id": "owasp-report",
    "filename": "owasp-report.json"
  },
  {
    "id": "code-coverage-report",
    "filename": "code-coverage-report.pdf"
  }
]

Traceability configuration

Configuration for the traceability behavior. The Ketryx RTM currently offers two different engines for configuring the traceability: v2 (legacy), which comes with slightly adjustable pre-configured traceability presets, and v3, which allows much more detailed customizations such as configurable design and testing columns, tracing rules, traceability checks and much more.

(RTM v3) Enable the new RTM v3 mechanism. Defaults to the project's schema config to determine the traceability behavior (equivalent to the v2 presets)

{
  "version": "3"
}

(RTM v3) Full example for a project using the full schema config tracing use-cases, design inputs (Requirements), design outputs (SW/HW specifications), verification tests (testing design outputs) and validation tests (testing design inputs).

{
  "version": "3",
  "rtmApprovalEnabled": false,
  "enforceGreenCheck": true,
  "defaultColumnId": "design-input",
  "statusDefinitions": {
    "REQUIREMENT_MISSING": {
      "level": "ERROR"
    },
    "SPEC_MISSING": {
      "level": "ERROR"
    },
    "MANUAL_TEST_EXECUTION_MISSING": {
      "level": "ERROR"
    },
    "TEST_EXECUTION_MISSING": {
      "level": "ERROR"
    },
    "TEST_EXECUTION_MISSING_RESULT": {
      "level": "ERROR"
    },
    "VERIFICATION_TEST_MISSING": {
      "level": "ERROR"
    },
    "VALIDATION_TEST_MISSING": {
      "level": "ERROR"
    },
    "TEST_EXECUTION_FAILED": {
      "level": "ERROR"
    },
    "NOT_INCLUDED_IN_TEST_PLAN": {
      "level": "MUTED"
    },
    "TEST_EXECUTION_NOT_CONTROLLED": {
      "level": "WARNING"
    },
    "RISK_NOT_CONTROLLED": {
      "level": "WARNING"
    },
    "NOT_CONTROLLED": {
      "level": "WARNING"
    }
  },
  "rowStatusMessages": {
    "REQUIREMENT_MISSING": {
      "message": {
        "subject": "Use case",
        "description": "not covered by a design input."
      }
    },
    "SPEC_MISSING": {
      "message": {
        "subject": "Design input",
        "description": "not covered by a design output."
      }
    },
    "VERIFICATION_TEST_MISSING": {
      "message": {
        "subject": "Design output",
        "description": "not covered by a verification test."
      }
    },
    "VALIDATION_TEST_MISSING": {
      "message": {
        "subject": "Design input",
        "description": "not covered by a validation test."
      }
    },
    "MANUAL_TEST_EXECUTION_MISSING": {
      "message": {
        "subject": "Test Case",
        "description": "without manual test executions for automated tests."
      }
    },
    "TEST_EXECUTION_MISSING_RESULT": {
      "message": {
        "subject": "Test Execution",
        "description": "without a test result."
      }
    },
    "TEST_EXECUTION_MISSING": {
      "message": {
        "subject": "Test Case",
        "description": "without a test execution."
      }
    },
    "TEST_EXECUTION_FAILED": {
      "message": {
        "subject": "Test Execution",
        "description": "failed."
      }
    },
    "NOT_CONTROLLED": {
      "aliases": [
        "RISK_NOT_CONTROLLED",
        "TEST_EXECUTION_NOT_CONTROLLED"
      ],
      "message": {
        "subject": "Item",
        "description": "not fully approved yet."
      }
    }
  },
  "cellStatusMessages": [
    {
      "if": [
        "REQUIREMENT_MISSING"
      ],
      "message": "Requirement missing"
    },
    {
      "if": [
        "SPEC_MISSING",
        "VERIFICATION_TEST_MISSING",
        "VALIDATION_TEST_MISSING"
      ],
      "message": "Specification and test cases missing"
    },
    {
      "if": [
        "SPEC_MISSING",
        "VERIFICATION_TEST_MISSING"
      ],
      "message": "Specification and test case missing"
    },
    {
      "if": [
        "SPEC_MISSING",
        "VALIDATION_TEST_MISSING"
      ],
      "message": "Specification and test case missing"
    },
    {
      "if": [
        "SPEC_MISSING"
      ],
      "message": "Specification missing"
    },
    {
      "if": [
        "VERIFICATION_TEST_MISSING"
      ],
      "message": "Verification test case missing"
    },
    {
      "if": [
        "VALIDATION_TEST_MISSING"
      ],
      "message": "Validation test case missing"
    },
    {
      "if": [
        "NOT_INCLUDED_IN_TEST_PLAN"
      ],
      "message": "Not included in test plan"
    },
    {
      "if": [
        "TEST_EXECUTION_MISSING_RESULT"
      ],
      "message": "Test execution result missing"
    },
    {
      "if": [
        "TEST_EXECUTION_MISSING"
      ],
      "message": "Test execution missing"
    },
    {
      "if": [
        "MANUAL_TEST_EXECUTION_MISSING"
      ],
      "message": "Manual test execution missing for automated test"
    },
    {
      "if": [
        "TEST_EXECUTION_FAILED"
      ],
      "message": "Test execution failed"
    },
    {
      "if": [
        "TEST_EXECUTION_NOT_CONTROLLED"
      ],
      "message": "Missing approval for Manual Test Execution"
    },
    {
      "if": [
        "TEST_EXECUTION_NOT_CONTROLLED"
      ],
      "message": "Missing approval for Manual Test Execution"
    },
    {
      "if": [
        "RISK_NOT_CONTROLLED"
      ],
      "message": "Missing approval for Risk"
    },
    {
      "if": [
        "NOT_CONTROLLED"
      ],
      "message": "Missing approval"
    }
  ],
  "columns": [
    {
      "columnId": "use-case",
      "title": "Use cases",
      "kind": "design",
      "itemFilter": "type:RQ and \"Requirement type\":\"Use case\"",
      "matchCrossReferences": false
    },
    {
      "columnId": "design-input",
      "title": "Design Input",
      "kind": "design",
      "itemFilter": "type:RQ and not \"Requirement type\":\"Use case\" and not \"Requirement type\":\"Intended use\"",
      "relations": [
        {
          "kind": "indirect",
          "relationType": "HAS_PARENT",
          "referencedColumnId": "use-case"
        }
      ],
      "matchCrossReferences": false
    },
    {
      "columnId": "design-output",
      "title": "Design Output",
      "kind": "design",
      "itemFilter": "type:SW or type:HW",
      "relations": [
        {
          "kind": "direct",
          "relationType": "FULFILLS",
          "referencedColumnId": "design-input"
        }
      ],
      "matchCrossReferences": false
    },
    {
      "columnId": "verification-test",
      "title": "Verification test",
      "kind": "testing",
      "testedItemFilter": "type:SW or type:HW",
      "referencedColumnIds": [
        "design-output"
      ],
      "matchCrossReferences": false
    },
    {
      "columnId": "validation-test",
      "title": "Validation test",
      "kind": "testing",
      "testedItemFilter": "type:RQ",
      "referencedColumnIds": [
        "design-input"
      ],
      "matchCrossReferences": false
    }
  ],
  "checks": [
    {
      "checkId": "use-cases-covered",
      "kind": "coverage",
      "title": "Use cases",
      "subtitle": "Covered by design input",
      "filterDescription": "use cases not covered by a design input",
      "columnIds": [
        "use-case"
      ],
      "coveredByColumnId": "design-input",
      "checkCrossReferences": false,
      "onFail": {
        "status": "REQUIREMENT_MISSING"
      }
    },
    {
      "checkId": "design-inputs-covered",
      "kind": "coverage",
      "title": "Design input",
      "subtitle": "Covered by design outputs",
      "filterDescription": "design inputs not covered by a design output",
      "columnIds": [
        "design-input"
      ],
      "coveredByColumnId": "design-output",
      "checkCrossReferences": false,
      "onFail": {
        "status": "SPEC_MISSING"
      }
    },
    {
      "checkId": "verification-test-coverage",
      "kind": "coverage",
      "title": "Verification",
      "subtitle": "Design outputs covered by tests",
      "filterDescription": "design outputs not covered by a verification test case",
      "columnIds": [
        "design-output"
      ],
      "coveredByColumnId": "verification-test",
      "checkCrossReferences": false,
      "onFail": {
        "status": "VERIFICATION_TEST_MISSING"
      }
    },
    {
      "checkId": "validation-test-coverage",
      "kind": "coverage",
      "title": "Validation",
      "subtitle": "Design inputs covered by tests",
      "filterDescription": "design inputs not covered by a validation test case",
      "columnIds": [
        "design-input"
      ],
      "coveredByColumnId": "validation-test",
      "checkCrossReferences": false,
      "onFail": {
        "status": "VALIDATION_TEST_MISSING"
      }
    },
    {
      "checkId": "test-executions",
      "kind": "testExecutions",
      "title": "Test executions",
      "subtitle": "Created within test plan",
      "filterDescription": "test cases missing a test execution or test result",
      "onMissingManualExecution": {
        "status": "MANUAL_TEST_EXECUTION_MISSING"
      },
      "onMissingExecution": {
        "status": "TEST_EXECUTION_MISSING"
      },
      "onMissingExecutionResult": {
        "status": "TEST_EXECUTION_MISSING_RESULT"
      },
      "onNotInTestPlan": {
        "status": "NOT_INCLUDED_IN_TEST_PLAN"
      }
    },
    {
      "checkId": "failed-tests",
      "kind": "failedTests",
      "title": "Failing tests",
      "subtitle": "Within test plan",
      "filterDescription": "failing test executions",
      "onFail": {
        "status": "TEST_EXECUTION_FAILED"
      }
    },
    {
      "checkId": "all-items-controlled",
      "kind": "controlled",
      "title": "Controlled",
      "subtitle": "Items fully approved",
      "filterDescription": "uncontrolled items that need to be approved",
      "checkCrossReferences": false,
      "onTestExecutionNotControlled": {
        "status": "TEST_EXECUTION_NOT_CONTROLLED"
      },
      "onRiskNotControlled": {
        "status": "RISK_NOT_CONTROLLED"
      },
      "onItemNotControlled": {
        "status": "NOT_CONTROLLED"
      }
    }
  ],
  "columnForTestsWithoutTestedItem": "validation-test"
}

(RTM v2) Trace "Use case" requirements to other requirements to specs to tests (overriding the behavior from the project's schema config)

{
  "mode": "SYSTEM_REQUIREMENT_AND_SPECIFICATION"
}

(RTM v2) Only require validation of requirements (overriding the behavior from the project's schema config)

{
  "mode": "REQUIREMENT_VALIDATION_ONLY"
}

(RTM v2) Add "Intended use" requirements to the first column (rather than ignoring them, which would be the default)

{
  "mode": "SYSTEM_REQUIREMENT_AND_SPECIFICATION",
  "columnNames": {
    "USE_CASE_COLUMN": "User requirement"
  },
  "useCaseColumnRequirementTypes": [
    "USE_CASE",
    "INTENDED_USE"
  ],
  "ignoredRequirementTypes": []
}

Enable the RTM approval workflow for the traceability page

{
  "rtmApprovalEnabled": true
}

Allow item transition

Whether to allow items to be transitioned from the Ketryx side. By default (if not defined or null), transitions are allowed based on the project's observe-only flag: In observe-only mode, transitions are not allowed; otherwise they are allowed.

Allow item creation

Whether to allow items to be created from the Ketryx side (e.g. Risks, Test Executions, other items). By default (if not defined or null), item creation is allowed based on the project's observe-only flag: In observe-only mode, item creation is not allowed; otherwise it is allowed.

Enable item approval notifications

Whether to send notifications regarding item approvals. By default (if not defined or null), notifications are sent unless the project is in observe-only mode.

Version number pattern

Pattern for version names, used to extract normalized version number strings.

SemVer version numbers (major.minor.patch-prerelease+build)

"$0(.$0)(.$0)[-$x][+$x]"

Alphabetical version identifiers (three components, with the second and third one being optional, but being normalized to an empty part)

"$A(.$A)(.$A)"

Select text field options

Option values for each select text field in this project (e.g. region values).

When defining regions, items associated with a specific region will only be shown in region-specific documents, as defined by the document setting Region-specific documents.

Predefine two regions "EU" and "US"

{
  "regions": [
    {
      "value": "EU"
    },
    {
      "value": "US"
    }
  ]
}

Version fields

Configuration for how to determine the start and end version for an item (Introduced in version, Obsolete in version).

This is a mapping from standard item type names (e.g. "Requirement" or "Anomaly") or the wildcard * to a configuration object that lists field keys to consider. The configuration for the wildcard * is used as a fallback, if there is no specific configuration for an item type name.

By default, uses the Ketryx fields Introduced in version and Obsolete in version; in addition, Jira's built-in field Fix version(s) is taken into account (as the end version for Anomalies, or as the start version for all other item types).

Use an extra custom field "Released Version" as well as Jira's "Fix version(s)" as the introducing version, except for Anomalies where "Fix version(s)" should denote the obsoleting version

{
  "*": {
    "introducedFieldKeys": [
      "extra:Released Version",
      "jira:fixVersions"
    ]
  },
  "Anomaly": {
    "introducedFieldKeys": [
      "extra:Released Version"
    ],
    "obsoleteFieldKeys": [
      "jira:fixVersions"
    ]
  }
}

Whether to include related items in auto-created incremental releases. Disabled by default.

Incremental releases: Excluded from test plan

KQL filter for tests to exclude from the test plan in auto-created incremental releases.

Incremental releases: Omitted documents

Omitted documents in auto-created incremental releases.

Incremental releases: Target branch name

Base ref name (glob pattern) to match against before auto-creating an incremental version. By default, the main analyzed branch is taken.

Incremental releases: Source branch name

Head ref name (glob pattern) to match against before auto-creating an incremental version. By default, all head ref names are accepted.

Create transitive dependency items

Determines whether all direct and indirect dependencies should be created as dependency items. If true, all dependencies, not just root-level ones, need to be acted upon for a release to happen.

Ketryx will scan for vulnerabilities in all dependencies, regardless of this setting as long as the dependencies are found, e.g. in an uploaded SPDX file.

Note: Be very careful with this setting, as it can lead to a large number of items. Even if this setting is disabled, root-level dependencies will still show their dependencies on their Dependencies tab.

Disabled by default.

Enable vulnerability management

Whether to enable the vulnerability management feature. Enabled by default.

Vulnerability management configuration

Configuration object for the vulnerability management feature.

All fields except assessmentHeading and mitigationItemTypes will also affect the Vulnerability Report document. Any value not specifically set here will be used from the default configuration object.

Default configuration object:

{
  "assessmentHeading": "Vulnerability impact assessment",
  "resolutionLabel": "Resolution",
  "resolutionOptions": ["Not relevant", "Exploitable", "Poses threat"],
  "resolutionRichTextFields": ["Justification for resolution"],
  "riskRichTextFields": ["Rationale for connecting risks"],
  "mitigationRichTextFields": ["Rationale for connecting mitigations"],
  "mitigationItemTypes": []
};

Use a custom assessment heading

{
  "assessmentHeading": "Vulnerability risk analysis"
}

Use a custom resolution configuration

{
  "resolutionLabel": "Overall risk level",
  "resolutionOptions": [
    "None",
    "Low",
    "Medium",
    "High"
  ],
  "resolutionRichTextFields": [
    "Reasoning for risk level"
  ]
}

Rename risk and mitigation rich text fields

{
  "riskRichTextFields": [
    "Reasoning for related risks"
  ],
  "mitigationRichTextFields": [
    "Reasoning for related mitigations"
  ]
}

Hide all rich text fields

{
  "resolutionRichTextFields": [],
  "riskRichTextFields": [],
  "mitigationRichTextFields": []
}

Allow only software item specs and test cases as mitigation items

{
  "mitigationItemTypes": [
    "SOFTWARE_ITEM",
    "TEST_PROTOCOL"
  ]
}

Suggested item type task order

The item type order used by the guidance task system when suggesting a user which first items to create in a new project. Items should be referenced by their standard item type names (e.g. "Requirement") or custom type names (e.g. "Folder").

Have a Requirement, Software Item Spec and Test Case, in that order, suggested by the guidance system.

[
  "Requirement",
  "Software Item Spec",
  "Test Case"
]

Have a Requirement (which has renamed to "Functional Requirement" through the "Item type names" configuration field), custom "Folder" item type and a Software Item Spec, in that order, suggested by the guidance system.

[
  "Requirement",
  "Folder",
  "Test Case"
]

Document configuration

Omitted documents

Omitted document types in this project. These documents will not show up on a version's documents page and will not be required for approving a version.

This is separate from omitting documents "ad-hoc" on a version's Documents page, which only affects that particular version.

If not defined, a default set of omitted documents will be chosen based on the chosen schema configuration mode of the project.

Use all available documents

[]

Omit all documents except for the SRS document

[
  "AUTHORITY_MATRIX",
  "CHANGE_REQUEST_REPORT",
  "CHANGE_MANAGEMENT_FILE",
  "CLOUD_CONFIG_REPORT",
  "CODE_REVIEW_REPORT",
  "CYBER_RISK_MANAGEMENT_FILE",
  "PROBLEM_REPORT",
  "RELEASE_NOTES",
  "RISK_MANAGEMENT_FILE",
  "RISK_CONTROL_FILE",
  "RISK_MATRIX",
  "SOFTWARE_ARCHITECTURE_CHART",
  "SOFTWARE_REQUIREMENTS_SPECIFICATION",
  "SOFTWARE_DESIGN_SPECIFICATION",
  "SOFTWARE_DESIGN_STRUCTURE_MATRIX",
  "SOUP_DEPENDENCIES",
  "TRAINING_STATUS_REPORT",
  "TEST_PLAN",
  "TESTING_REPORT",
  "TRACEABILITY_MATRIX",
  "UNRESOLVED_ANOMALIES",
  "VULNERABILITY_REPORT"
]

Region-specific documents

Documents that should be generated for each region. Possible region values are defined in Select text field options.

By default, only the SRS document is considered region-specific.

Generate SRS and SDS document for each region

[
  "SOFTWARE_REQUIREMENTS_SPECIFICATION",
  "SOFTWARE_DESIGN_SPECIFICATION"
]

Milestone-independent documents

Documents that should contain all items (independently of milestones), even if they are generated as milestone documents.

Default list of documents that are considered milestone-independent

[
  "CYBER_RISK_MANAGEMENT_FILE",
  "PROBLEM_REPORT",
  "RELEASE_NOTES",
  "TEST_PLAN",
  "TESTING_REPORT",
  "UNRESOLVED_ANOMALIES"
]

Require controlled templates

Whether to only use document templates that are in a controlled state (off by default). If activated, any unapproved draft will be ignored, and the last controlled record of a template will continue to be used instead.

Omitted fields

Omitted fields for each document type and item type. Word documents showing the details of an item will not show those omitted fields.

Document types and item types are denoted by their internal identifiers. Fields are denoted by their human-readable name (e.g. "Description", "My custom field").

Omit the "Expected behavior" field from Test Cases in the Test Plan documents

{
  "TEST_PLAN": {
    "TEST_PROTOCOL": [
      "Expected behavior"
    ]
  }
}

Include title page

Whether to include a title page (on by default).

Include version page

Whether to include a page listing the document version history (on by default).

Word document

Settings for all generated Word documents.

Use the setting for Custom template variables to define custom template variables such as $DOC_ID.

Footer

{
  "footer": {
    "content": [
      {
        "left": {
          "text": "Electronically controlled document by My Corporation",
          "style": {
            "size": 8,
            "fontName": "Tahoma"
          }
        },
        "middle": {
          "text": "Confidential",
          "style": {
            "bold": true,
            "size": 10,
            "italics": true,
            "fontName": "Tahoma"
          }
        },
        "right": {
          "text": "Document ID $DOC_ID",
          "style": {
            "size": 8,
            "fontName": "Tahoma"
          }
        }
      }
    ],
    "borderTop": {
      "size": 10,
      "color": "333333",
      "style": "thick"
    }
  }
}

Excel spreadsheet

Settings for all generated Excel spreadsheets.

Custom template variables

Allows customizing the template variable input for all document types. A template variable may be configured to be user-adjustable, which would show extra inputs in the release documents UI.

This is usually used in combination with custom headers and footers.

Introduce a user-adjustable $DOC_ID variable

{
  "$DOC_ID": {
    "value": "",
    "description": "Document ID",
    "userAdjustable": true
  }
}

System Requirements Specification

Customization of SRS output documents.

Omit a dedicated "Other" section heading if it is the only section in the document

{
  "omitSingleOtherSection": true
}

Requirements Traceability Matrix

Customization of RTM output documents.

Omit use cases and specs from the RTM document

{
  "showUseCases": false,
  "showSpecs": false
}

Do not show excluded tests at all

{
  "showExcludedTests": "never"
}

Do not show excluded tests if there is no "inherited" test in the previous release

{
  "showExcludedTests": "if-inherited-execution"
}

{
  "columnNames": {
    "Use case ID": "User requirement ID",
    "Use case title": "User requirement title",
    "Requirement type": null
  }
}

Risk Matrix

Customization of Risk Matrix output documents.

Rename some columns, and omit the "System categories" column

{
  "columnNames": {
    "Item ID": "ID",
    "System categories": null,
    "Foreseeable sequence of events": "Sequence of events"
  }
}

Release history

Customization of Release History documents.

Default values:

{
  "includeScopeDescriptionSection": true,
  "omitVVReportSection": true
}

Remove the Scope description section from the release history document

{
  "includeScopeDescriptionSection": false
}

Include the V&V section in the release history document

{
  "omitVVReportSection": false
}

Release Notes

Customization of Release Notes documents.

Default values:

{
  "includeScopeDescriptionSection": true,
  "omitVVReportSection": true
}

Remove the Scope description section from the release notes

{
  "includeScopeDescriptionSection": false
}

Include the V&V section in the release notes

{
  "omitVVReportSection": false
}

Only include certain user requirements in the release notes

{
  "itemFilters": {
    "newRequirements": "\"Requirement type\":(\"User/Marketing\", \"Intended use\")",
    "changedRequirements": "\"Requirement type\":(\"User/Marketing\", \"Intended use\")",
    "removedRequirements": "\"Requirement type\":(\"User/Marketing\", \"Intended use\")"
  }
}

Only include corrective anomalies in the release notes

{
  "itemFilters": {
    "newUnresolvedAnomalies": "\"Problem report type\":Corrective",
    "resolvedAnomalies": "\"Problem report type\":Corrective"
  }
}

SBoM – SOUP – Software Configuration report

Customization of SBoM – SOUP – Software Configuration Report documents.

Rename the column "Dependency name" to "Name"

{
  "columnNames": {
    "Dependency name": "Name"
  }
}

Omit the "Ecosystem" column

{
  "columnNames": {
    "Ecosystem": null
  }
}

Test Plan

Customization of Test Plan documents.

Omit automated tests from the Test Plan Word document

{
  "showAutomatedTests": false
}

Testing Report

Customization of Testing Report documents.

Only show the last (effective) test execution for each test in the Testing Report Word document

{
  "onlyLastTestExecution": true
}

Risk Management File

Customization of Risk Management File documents.

Omit the risk evaluation matrix section from the document

{
  "showEvaluationMatrices": false
}

Omit the general information section from the document

{
  "showGeneralInformation": false
}

Date format

Default date format to render date/time values in template-based documents. Placeholders as defined by Unicode TR35 can be used.

ISO 6801-compliant time stamps

"yyyy-MM-dd'T'HH:mm:ssXXX"

Date time zone

Default time zone to use for date/time values in template-based documents. Time zones are specified using their TZ identifier.

Use the New York time zone

"America/New_York"

Test result names

Mapping of internal test result status names to custom ones.

As a special value, "EXCLUDED" can also be mapped to a custom value (with the default label being "Excluded" in the RTM).

Use custom test result names

{
  "PASS": "Passed",
  "PASS_WITH_EXCEPTION": "Passed with exception",
  "FAIL_ACCEPTED": "Failed but accepted",
  "FAIL": "Failed",
  "EXCLUDED": "Excluded"
}

Short item refs

Use short item references (usually just the Jira issue key) instead of long references (that also indicate the item type and revision number). Defaults to false if not defined.

Risk configuration

Hazardous situations

Customization of hazardous situation values.

Set new hazardous situation values

[
  "Patient harm",
  "Inaccurate readings",
  "Communication failure"
]

Event sequences

Customization of event sequence values.

Set a new event sequence value

[
  {
    "name": "Medication Dosage Error Risk",
    "steps": [
      {
        "name": "Prescription Entry"
      },
      {
        "name": "Dosage Calculation"
      },
      {
        "name": "Dispensing Medication"
      },
      {
        "name": "Administering Medication"
      }
    ]
  }
]

Event steps

Customization of event step values.

Set new event step values

[
  {
    "name": "Prescription Entry"
  },
  {
    "name": "Patient Identification"
  },
  {
    "name": "Medication Verification"
  }
]

Hazards

Customization of hazard values.

Set new hazard values

[
  "Contamination",
  "Overdose",
  "Burns"
]

Harms

Customization of harm values. A harm may include an associated initial severity. If strict mode is enabled, it is recommended to add the severity.

Set new harm values

[
  {
    "name": "Organ Damage",
    "defaultInitialSeverity": "High"
  },
  {
    "name": "Infection"
  }
]

Hazard types

Customization of hazard type values.

Set new hazard type values

[
  "Acoustic",
  "Electrical",
  "Mechanical"
]

System categories

Customization of system category values.

Set new system category values

[
  "Environment",
  "Mechanical",
  "Software"
]

Risk assessment methodologies

Customization of risk assessment methodology values.