Issue Mapping

When you will not be using Ketryx issue types, the issue types in the project should be mapped to Ketryx item types using the issue mapping advanced setting. Ketryx will read Story issues as Requirement items and Bugs as Anomaly items by default, but any other mapping, including mapping Stories or Bugs to something else (or null if you don’t want them to be tracked in Ketryx), must be established. These items will be read into Ketryx with the default item type names and short names, unless the item type names and/or item type short names advanced settings are used to rename these items in the Ketryx UI and release documentation. Please note the warnings associated with item type names in the linked documentation and tooltip in the system.

Relation Names

If Jira native links will be used to maintain traceability between design controls, the relation names advanced setting should be used to map from Jira links to Ketryx relations.

Status Mapping

If the Ketryx default workflow is not being used for certain issues that are being read as Ketryx items (or all issues being read as Ketryx items), the status mapping advanced setting should be used. This setting does not map the immutability or controlled status onto the items (i.e. mapping Done to Closed does not automatically make Done a controlled, immutable state), it is just to signal to Ketryx how the status should be displayed in the UI and documentation. For example, if you map “In Review” to “In Progress”, this signals to Ketryx that it should “In Review” in the state column of the All items screen in a yellowish color, just like it does for “In Progress”. Doing this mapping will also add the status to the filter button on the All items page and allow you to use these entities in the Approval Workflow settings. To define approval workflows that bring items into controlled, immutable states, see Approval Workflow below.

Approval Workflow

When using a workflow that is not the Ketryx default workflow, the approval workflow advanced setting should be configured to allow issues to terminate in a controlled state. This should be paired with configuration of the Jira workflow such that the transition into whichever state is the controlled state is hidden from the user, and that both the status before and after approval (i.e. Resolved and Closed) are immutable states. Note that approval workflow is set on the grain of the item type, so different review and terminal states can exist for different item types. Often, different workflows are used for different issue types, so configuring the approval workflow in Ketryx and altering the Jira workflow as necessary may be done several times for the different item and issue types. If more granular approval rules are required (ex. Requirements of Requirement type “Use Case” require additional approval), the approval rules advanced setting may be used.

It is important to note that items that gain approval after this configuration is complete will enter a controlled, immutable state. If the record of the item updates when it is in a controlled state, the item's approval will be invalidated. If you would like Ketryx to automatically unclose the item and move it back to the approvable state, turn on Enable item invalidation in the advanced settings, which is disabled by default for "observer mode" projects. As a result of these new controls, it is best to consider updating the workflow to include immutability and approvals after all bulk updates or configuration changes have been made. As an example, if a field is added to Extra field names, all issues that have that field filled will have their item record updated. Any that were controlled prior to this configuration will have their approval invalidated, unless Uncontrolled field names is used to prevent this.

Extra Field Names

Ketryx will only read built-in fields that are filled into item records, and therefore release documentation, by default. If you would like item records and release documentation to include additional fields, the extra field names advanced setting should be used to define which Jira native or custom fields should be read. If a field defined in extra field names appears on an issue screen and is filled, it will be read into the record. If not, it will not be read into the item record. Version fields should not be included in this, as they are "special" (see below).

Deferred Items Filter

In Ketryx defaults, the “Rationale for deferring resolution” field being filled signals to Ketryx that a given Anomaly is deferred in the current draft. It will continue as a deferred item that does not need to be controlled prior to release until the Obsolete in version field is filled. This “Rationale for deferring resolution field” may be added to screen for the issue type mapped to Anomaly and this will work as described. However, it is often the case that workflow states are used to defer Anomalies. In this case, or in the case where some other field is being used to mark Anomalies as deferred, the deferred items filter advanced setting should be used. It is important to note that KQL can only access data contained within the item record; if some other field is being used to mark Anomalies as deferred, this field must be given in Extra field names (described above).

Unchecked Items Filter

If there are issues that are being read into Ketryx but their uncontrolled status should not block releases, the unchecked items filter advanced setting should be used. It is important to note that KQL can only access data contained within the item record, so any field used in the Unchecked items filter should be given in Extra field names (described above). Unchecked items typically have a workflow that does not require approval. This means that the user is able to transition the item from in progress states to terminal state(s) through the Jira workflow. If the item is so irrelevant to design control documentation that it isn’t needed in Ketryx, you should use Issue mapping to map it to “itemType” : null.

Traceability Configuration

The Ketryx Traceability Matrix is highly configurable. The V-model that is desired, and the checks for coverage throughout that V-model, should be configured using the traceability configuration advanced setting. Any configuration on the Ketryx Traceability Matrix will be reflected in the Traceability Matrix release document. By default, Ketryx will enforce that all checks configured in the Traceability Matrix are fulfilled prior to release, so checks should only be configured for coverage that must be complete prior to release.

Risk Configuration

The Ketryx Risk Module is highly configurable. It is generally recommended that Risks are edited primarily in Ketryx. To configure the risk matrices in Ketryx, the following advanced settings should be used:

• Initial Occurrence Probability - Defines the set of P1 values that will appear in the dropdown.

• Initial Harm Probability - Defines the set of P2 values that will appear in the dropdown.

• Initial Total Probability - Defines the set of P0 values that will be mapped to through the Initial Total Probability Matrix based on the P1 and P2 values that are selected.

• Initial Severity - Defines the set of S values that will appear in the dropdown.

• Initial Risk Evaluation - Defines the set of risk evaluations, and their Acceptability, that will be mapped to through the Initial Risk Evaluation Matrix based on the derived P0 value and the S value selected.

• Residual Occurrence Probability - Defines the set of P1 values that will appear in the dropdown.

• Residual Harm Probability - Defines the set of P2 values that will appear in the dropdown.

• Residual Total Probability - Defines the set of P0 values that will be mapped to through the Residual Total Probability Matrix based on the P1 and P2 values that are selected.

• Residual Severity - Defines the set of S values that will appear in the dropdown.

• Residual Risk Evaluation - Defines the set of risk evaluations, and their Acceptability, that will be mapped to through the Residual Risk Evaluation Matrix based on the derived P0 value and the S value selected.

• Initial Total Probability Matrix - Defines which P0 value, defined in Initial Total Probability, will be returned for each combination of P1 and P2 values.

• Initial Risk Evaluation Matrix - Defines which Risk Evaluation value, defined in Initial Risk Evaluation, will be returned for each combination of P0 and S values.

• Residual Total Probability Matrix - Defines which P0 value, defined in Residual Total Probability, will be returned for each combination of P1 and P2 values.

• Residual Risk Evaluation Matrix - Defines which Risk Evaluation value, defined in Residual Risk Evaluation, will be returned for each combination of P0 and S values.

Version fields

Jira default Fix versions and Affects versions fields are often used to scope the set of design controls that are effective in a given release. Typically, Fix versions is used somewhat like Introduced in Version for all issues except Bugs/Defects/Anomalies. For Bugs/Defects/Anomalies, Affects versions is typically used like Introduced in Version (“in which version did we observe this Anomaly?”) and Fix versions is used more like Obsolete in Version (“in which version did we resolve this Anomaly?”). To map from the Fix versions and Affects versions fields for each issue type, the version fields advanced setting should be used. In cases where Fix versions, which is multi-select by default, the behavior of this setting should be verified. To check this, find an item that has multiple versions in Fix versions and/or Affects versions, then navigate to the Ketryx Item Record Detail page to observe what Ketryx has stored in the Versions property. Ensure that the versions listed meet expectations.