> For the complete documentation index, see [llms.txt](https://documentation.ketryx.com/wZDI3WrsOK0i3HMp81Me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ketryx.com/wZDI3WrsOK0i3HMp81Me/manuals/man-01-ketryx-lifecycle-management.md).
# MAN-01 Ketryx Lifecycle Management
## 1. Introduction
### 1.1. Purpose
The purpose of this manual is to explain the ongoing usage and operations of the Ketryx Platform, a lifecycle management system built to streamline high-quality software development and support FDA software compliance and compliance with standards such as ISO 13485, IEC 62304, ISO 14971, IEC 61508-3, and EU AI Act, among others.
### 1.2. Scope
The scope of this manual is the complete usage of the Ketryx Platform. This includes a description of the Ketryx Framework, a logical framework of rules and entities that are implemented within the Ketryx Platform software system.
### 1.3. Referenced Documents
1. ISO 13485
2. IEC 62304
3. ISO 14971
4. IEC 61508-3
5. EU AI Act
### 1.4. Definitions and Acronyms
For the purposes of this document, the terms and definitions given in U.S. QSR (21 CFR Part 820), ISO 13485, IEC 62304:2006-AMD1, IEC 61508-3, and EU AI Act apply. Where contradictory, IEC 62304 and ISO 13485 prevail.
1. ALM: Application Lifecycle Management
2. QMS: Quality Management System
3. QS: Quality System
4. EDMS: Electronic Data Management System
5. Activity: a set of one or more interrelated or interacting Tasks
6. Configuration Item (CI): an entity that can be uniquely identified at a given reference point
7. Deliverable: required result or output (includes documentation) of an Activity or Task
8. Task: a single piece of work that needs to be done
9. Effective/Controlled Configuration Item: a Configuration Item that is in active use by the system for a given version
10. Traceability: the degree to which a relationship can be established between two or more products of the development Process
11. Process: a set of interrelated or interacting Activities that transform inputs into outputs
12. Verification: confirmation through the provision of objective evidence that specified requirements have been fulfilled
13. Project: a self-contained (sub) system or service with its own verification, validation and release lifecycle, and its own access control and approval rules. Each project defines its own versions. Projects might contain references to other (“sub” or “service”) projects. This is the primary “scoping construct” in Ketryx.
14. System: integrated composite consisting of one or more of the processes, hardware, software, facilities, and people, that provide a capability to satisfy a stated need or objective.
15. Product: a version of a system validated to a test case that meets certain requirements and is provided to users
16. Sub-system: integrated collection of software items or hardware items organized to accomplish a specific function or set of functions
17. Service: a self-contained and validated system with specific predefined interface requirements
18. Organization: an organization or organizational unit (e.g., Center of Excellence, Business Unit), managing its own members and projects. Each project is owned by one organization
19. Member: a user within an Organization. Each Member can be either an owner or a regular organization member.
20. Guest: a user with read-only or view-only access in the Organization. Guests cannot modify or create any data in the system. To learn more about Guest role, please refer to [this section](/wZDI3WrsOK0i3HMp81Me/reference/user-management-guide/guest-role-users-with-read-only-access.md).
21. Owner: an owner is a member with an elevated access level. Organizations can have multiple owners due to the significance of this role's permissions. Owner abilities include, but are not limited to:
1. Enforce Multi-Factor Authentication (MFA) for all electronic signatures within the organization.
2. Promote other users to organization owners or revoke owner status from others (MFA required). However, owners cannot remove their own owner status.
3. Reset a user's MFA status, but only if the user has the organization set as their *current* organization — this prevents malicious actors from adding users to their organizations just to reset their MFA.
22. Group: a group of Members defined in an Organization.
23. COTS: Commercial Off-The-Shelf
24. MFA: multi-factor authentication is a security method that requires multiple types of credentials to verify identity, adding an extra layer of protection. Ketryx supports two MFA methods: WebAuthn (Web Authentication) and OTP (One Time Password).
25. Electronic signature: method of authentication that is used to sign electronic records or documents. It serves as a means to indicate the individual's intent to approve, authenticate, or authorize the content of an electronic record. 21 CFR Part 11 defines it as a "means a computer data compilation of any symbol or series of symbols executed, adopted, or authorized by an individual to be the legally binding equivalent of the individual's handwritten signature." Organizations can require multi-factor authentication (MFA) for electronic signatures in Ketryx, to ensure compliance with 21 CFR Part 11.
26. T2 Tool: Software tool that supports but does not itself perform verification or validation tasks, and whose failure could result in undetected software defects
#### 1.4.1. Multi-Factor Authentication (MFA) Reset
When enforced in the organization, there are a couple of common scenarios where you might encounter a prompt to reset your Multi-Factor Authentication (MFA) in Ketryx:
1. Authenticator Removal: If you have removed or uninstalled the authenticator app linked to your Ketryx account, the system can no longer verify your identity using that method, requiring an MFA reset.
2. Switching Devices or Browsers: When you change machines, browsers, or use a security key-based authentication method (e.g., TouchID), the associated key might no longer be accessible. In this case, Ketryx may still display the security key as an option, but you won't be able to complete the authentication process.
You can request your organization owner to reset your MFA status. To avoid interruptions, we recommend designating **at least one backup organization owner** in addition to your primary owner, in case the primary owner needs to have their MFA reset.
### 1.5. Responsibility and Authority
The *Organization* shall define responsibilities by assigning *Members* to *Groups*. **Authority** over configuration items is provided to *Members* and *Groups* through the project’s **Approval Rules**, which consist of **Approval Steps**. These steps can be configured to require approval from either *Groups* or *Members*. By default, Ketryx is configured with approval steps based solely on *Groups*. The approval rules can be found under the project Settings if the *Member* has permission to view that information. To modify the approval rules and, as a result, the authority of your project’s QMS, you would need to have edit permissions for **Approval Rules**.
Ketryx comes with sensible default configurations that can cover many modern software development workflows. For responsibility and authority, Ketryx has five default groups and a set of default approval rules. Ketryx can be configured to add groups and support additional work instructions. The default groups are:
1. Product Managers
2. R\&D Leads
3. Developers
4. Quality Managers
5. Quality Control
It is considered best practice to have members assigned to only one group to ensure division of responsibility. Any abstract approval structure, whether based on groups or users, can be created in Ketryx. Organization owners can create additional groups and define permissions for those who can manage groups and approval steps.
Further information on how to configure a project’s **Approval Rules** can be found in [MAN-11 Approval Rules](/wZDI3WrsOK0i3HMp81Me/manuals/man-11-approval-rules.md).
## 2. Ketryx
### 2.1. Ketryx Framework
The Ketryx Framework is an object-based, gated, risk-based product development framework for validated application lifecycle management. Users, called *Members* within an *Organization*, work collaboratively to create products, set requirements, and collect evidence that those requirements are met through the IT systems used throughout the product lifecycle. *Members* and *Organizations* are examples of two types of entities in Ketryx that can interact in a pre-specified, structured manner.
In Ketryx, *Members* use *Configuration Items* (CI) to build *Systems*, *Sub-Systems*, and *Services*. CIs are the atoms from which systems are built and are managed in various tools native to the given task (requirement management, source control, etc.). Each *System*, *Sub-System*, and *Service* is a CI, and it is managed in Ketryx as a *Project*. Projects can interface with other projects to create the structure needed for complex system engineering.
*Members* have authority and permission over CIs and their lifecycle, depending on each project’s *Approval Rules*. Some *Members* can author, review, and approve a configuration item for it to become controlled and effective. Others might only have permission to view a Project. If a *Group* that a *Member* is a part of has assigned training, *Members* must perform that training, or they will not be able to perform actions (i.e., approvals) as part of the *Group*. Specific *Groups* and/or *Members* are required to approve the release of the validated product (i.e., project version). Further details on the framework and the different entities (i.e., objects) that exist in it are provided in the following sections.
#### 2.1.1. Entities
Ketryx has six different types of entities that interact in pre-defined ways to create the type of structure and traceability safety-critical applications require. The following are the types of entities in Ketryx, and the diagram below shows how they interact:
1. Organization
An *Organization* consists of *Members* who work together to create products. Each *Member* must have a role as either an *owner* or a regular *member* of the organization. An owner can add other members to the organization and potentially promote them to owners.
2. Project
A self-contained *Subsystem*, *System*, or *Service* and related activities that together create a product. Each Project has its own verification, validation, and release lifecycle, its own access control and approval rules, and its own versions. A project is typically done by a Product Team within an organization.
3. Member
Individuals that are part of the *Organization*.
4. Group
A set of users within an *Organization* that has authority/permissions.
5. Permission
Permissions control what a user (or user group) can do within an organization or project.
6. Configuration Item
An entity that can be uniquely identified at a given reference point.
#### 2.1.2. Configuration Items
*Configuration Items* can be combined within *Projects* to make any arbitrary System, Sub-system, or Service. CIs can govern all aspects of the Total Product Life Cycle (TPLC) and, through the Ketryx Platform, can be used to create evidence for audit or submission. Each controlled configuration item represents an approved record, and a validated system can only be created with controlled configuration items. Evidence of this controlled state can be seen in each release’s electronically signed documentation.
The following Configuration Items are available in Ketryx, each with its own *Work Instruction*.
1. Requirement
[WI-01 Requirement](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-01-requirement.md)
2. Software Item Spec
[WI-02 Software Item Spec](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-02-software-item-spec.md)
3. Task
[WI-03 Task](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-03-task.md)
4. Test Case
[WI-04 Test Case](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-04-test-case.md)
5. Test Execution
[WI-05 Test Execution](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-05-test-execution.md)
6. Anomaly
[WI-06 Anomaly](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-06-anomaly.md)
7. Complaint
[WI-07 Complaint](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-07-complaint.md)
8. Change Request
[WI-08 Change Request](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-08-change-request.md)
9. CAPA
[WI-09 CAPA](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-09-capa.md)
10. Risk
[WI-10 Risk](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-10-risk.md)
11. Hardware Item Spec
Specification of a hardware item, similar to a Software Item Spec.
12. Software Dependency
Software dependencies are managed through [Ketryx Software Supply Chain Management: Software Dependencies](/wZDI3WrsOK0i3HMp81Me/manuals/man-03-supply-chain-management-software-dependencies.md).
13. Cloud Dependency
Cloud dependencies are managed through [Ketryx Software Supply Chain Management: Cloud Dependencies](/wZDI3WrsOK0i3HMp81Me/manuals/man-04-supply-chain-management-cloud-dependencies.md).
14. Test Plan
A set of Test Cases required to release a Version. By default, all Test Cases within the same Project are included in a Version’s Test Plan.
15. Version
A release of a validated product. Approval rules for versions also apply to release documents associated with a version.
16. Document
[WI-11 Document](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-11-document.md)
A document in the Ketryx EDMS, potentially relevant for training Members.
*Configuration Items* are how members build validated systems. They utilize configuration items to construct, validate and perform change control or systems, resulting in validated products. Each configuration item represents a task or task phase, with multiple representing a series of tasks, also known as an activity.
Members perform tasks as part of the lifecycle activities of *Projects*. *Projects* can be nested within each other to form any arbitrary complex system of systems. Generally, a project can represent a System, Sub-system, or Service, which can be connected. Systems can then be validated and verified (V\&V) through a *Test Plan*. An example of a product lifecycle that can be implemented in Ketryx is given below. The *Test Plan* would indicate which Test Cases need to be performed (through a Test Execution CI) and passed before product approval by the PLT.
If instead of a V-model, we look at the pre-market lifecycle sequentially, we get the following diagram, which describes the lifecycle process requested in ISO/IEC 62304. In section 5 of this manual, we will review this diagram (and section 5 of ISO/IEC 62304) in detail.
Looking at it beside the earlier lifecycle process diagram shows how the Ketryx Platform allows the development of products developed under the Ketryx Framework.
**Configuration Item States**
Configuration items managed through work item/task management tools (e.g., Jira) have four native states, described below. Additional states can be added.
**Open** - The item is proposed.
**In Progress** - The item proposal is being drafted into a final proposal. The ticket can be reviewed and edited.
**Resolved** - The ticket is in an immutable state and is pending review and signatures from relevant approval steps.
**Closed** - The ticket is closed, and no further actions are needed. For a design ticket, this state would mean the design is verified.
#### 2.1.3. Components
The framework focuses on three components:
**Risk Management:** systematic application of management policies, procedures, and practices to the tasks of analyzing, evaluating, controlling, and monitoring risk[^1].
**Configuration Management:** Configuration Management (CM) is a systems engineering process for establishing and maintaining consistency of a product's performance, functional, and physical attributes with its requirements, design, and operational information throughout its life.
**Agile Software Development:** Iterative and flexible approach to software development, focusing on building smaller pieces of functionality.
These three components are integrated into the Ketryx Framework, Ketryx Platform, and the way *Members* build validated products. Each is discussed in detail later in this manual.
### 2.2. Ketryx Platform
The Ketryx Platform (“Ketryx”) is a connected application lifecycle management platform that automates the Ketryx Framework. It allows teams to use portions of the Ketryx Framework relevant to their quality system and day-to-day activities.
Ketryx allows *Members* to easily integrate a risk-based approach into their software development tooling and centralize their work from a single source of truth. It allows teams to develop software across those tools with full traceability and visibility in a 21 CFR Part 11 validated system.
Ketryx is built on three principles:
1. **End-to-end traceability:** allowing users to understand how everything is connected
2. **Compliant-by-design:** guiding users on regulated software development
3. **Minimalist but connected:** easy to learn and build in
The Ketryx Platform consists of several interconnected modules and 3rd-party integrations, such as Jira and Git. These allow users to define requirements and enforce them across IT tools, creating complete and auditable configuration items. These can demonstrate compliance with the Total Product Life Cycle approach that is continuously recorded, viewed, used, and audited in Ketryx.
Ketryx supports the following common control use cases, with additional ones possible to add:
1. **Design Controls:** Record and manage requirements, specifications, and other design control items in Jira.
2. **Configuration Management Controls:** Record your source code, build, distribution and deployment directly from your source code management and cloud provider.
3. **Process Controls:** Following Compliant-by-Design (CbD) can be provenly enforced across IT systems. Evidence can be generated and collected to show that Design Controls have been met. Design Controls can be recorded and managed in Jira.
4. **Cybersecurity Controls:** Integrate cybersecurity requirements directly into your product, and scan your code daily for application vulnerabilities and software supply chain vulnerabilities.
5. **Release Control:** For applications created and managed in Ketryx, releases are carefully managed through a gated approval compliant with relevant quality assurance standards.
6. As described by the Ketryx Framework, Ketryx has 16 entities called Configuration Item(s) (CIs). Together they can represent the Total Product Life Cycle of any arbitrary system.
Ketryx easily connects to other systems providing users with a seamless, traceable experience, including guided workflows and evidence generation. The following systems are supported in Ketryx.
**Source Code Repository:** Any Git repository works with Ketryx. Specific advanced source code management tools and evidence collection modules currently only work with GitHub.
**Task/Work Item Management:** Ketryx connects to Jira Cloud through an [Atlassian Marketplace app](https://marketplace.atlassian.com/apps/1228398/ketryx-for-jira). Once installed and connected to a Ketryx Organization, Projects created in Ketryx can be connected to Jira spaces (formerly projects)*.* This will create Ketryx-specific workflows, work types, and screens in Jira and automatically configure the connected Jira spaces with them (unless it contains work items already, in which case the initial configuration is more manual). The Ketryx-specific Jira work types correspond to Configuration Items 1 through 11, while Software Dependencies, Cloud Dependencies, Test Plans, Versions, and Documents are primarily managed natively in Ketryx.
**Cloud Deployment:** Ketryx currently supports AWS as a native integration. You can still use any other feature of Ketryx and record evidence as discussed.
#### 2.2.1 Global Data Loading Indicator
To optimize performance, Ketryx displays pre-computed data on many pages while simultaneously processing up-to-date information. A loading indicator in the top right corner indicates how current the displayed data is
When up-to-date data is still computed, the loading indicator will show nine pulsating dots:
When all data on the current page is up-to-date, the loading indicator will show a check mark:
Clicking the loading indicator will give additional information about the currentness of the shown data.
### 2.3. Related Manuals
| Manual ID | Manual title |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [MAN-02](/wZDI3WrsOK0i3HMp81Me/manuals/man-02-software-release-process.md) | Software Release Process |
| [MAN-03](/wZDI3WrsOK0i3HMp81Me/manuals/man-03-supply-chain-management-software-dependencies.md) | Supply Chain Management: Software Dependencies |
| [MAN-04](/wZDI3WrsOK0i3HMp81Me/manuals/man-04-supply-chain-management-cloud-dependencies.md) | Supply Chain Management: Cloud Dependencies |
| [MAN-05](/wZDI3WrsOK0i3HMp81Me/manuals/man-05-milestones.md) | Lifecycle Management: Milestones |
| [MAN-06](/wZDI3WrsOK0i3HMp81Me/manuals/man-06-test-management.md) | Lifecycle Management: Test management |
| [MAN-07](/wZDI3WrsOK0i3HMp81Me/manuals/man-07-traceability.md) | Lifecycle Management: Traceability |
| [MAN-08](/wZDI3WrsOK0i3HMp81Me/manuals/man-08-risk-management.md) | Lifecycle Management: Risk management |
| [MAN-09](/wZDI3WrsOK0i3HMp81Me/manuals/man-09-git-based-configuration-items.md) | Lifecycle Management: Git-based configuration items |
| [MAN-10](/wZDI3WrsOK0i3HMp81Me/manuals/man-10-managing-items-in-ketryx.md) | Managing items in Ketryx |
| [MAN-11](/wZDI3WrsOK0i3HMp81Me/manuals/man-11-approval-rules.md) | Approval rules |
| [MAN-12](/wZDI3WrsOK0i3HMp81Me/manuals/man-12-computational-controls.md) | Computational control |
| [MAN-13](/wZDI3WrsOK0i3HMp81Me/manuals/man-13-data-export.md) | Data export |
### 2.4. Related Work Instructions
| Work Instruction ID | Work Instruction title |
| ------------------------------------------------------------------------------- | ---------------------- |
| [WI-01](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-01-requirement.md) | Requirement |
| [WI-02](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-02-software-item-spec.md) | Software Item Spec |
| [WI-03](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-03-task.md) | Task |
| [WI-04](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-04-test-case.md) | Test Case |
| [WI-05](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-05-test-execution.md) | Test Execution |
| [WI-06](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-06-anomaly.md) | Anomaly |
| [WI-07](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-07-complaint.md) | Complaint |
| [WI-08](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-08-change-request.md) | Change Request |
| [WI-09](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-09-capa.md) | CAPA |
| [WI-10](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-10-risk.md) | Risk |
| [WI-11](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-11-document.md) | Document |
| [WI-12](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-12-variants-and-versions.md) | Variants and Versions |
## 3. Risk Management
**Associated Deliverable:** Risk Management File, Risk Control Matrix, Risk Matrix, V\&V Report
**Tooling:** Risk Management Screen, Risk Controls Screen, Risk Configuration Item
*Members* can conduct project-level and configuration item-level risk analysis. Risks in Ketryx can be used to follow an ISO 14971-like process and are based on Hazardous Situations. The focus should be on what can happen and how to prevent harm to the patient. Risk management can be done continuously in Ketryx for each successive version and each system individually and in a centralized fashion.
Each risk is managed individually as a *Risk* configuration item. As a whole, risks can be managed through the manufacturer’s risk management process. While the Ketryx framework provides tools and automation for risk management, management of product and none product risk is the sole responsibility of the finished product manufacturers, which should have an approved risk management plan.
For a more in-depth guide to risk management in Ketryx, please refer to manual [MAN-08 Risk Management](/wZDI3WrsOK0i3HMp81Me/manuals/man-08-risk-management.md).
## 4. Configuration Management
**Deliverable:** Design Control documents (SRS, SDS, etc.), Software Bill of Materials, Part 11 Verification Report
**Tooling:** Software Dependency Screen, Cloud Configuration Report, Release Configuration Item Screen, Electronic Document Management System (EDMS)
### 4.1. QMS Configuration Management
All QMS documents can be stored in the Ketryx Electronic Data Management System (EDMS).
### 4.2. Design Control Configuration Management
#### 4.2.1. Design Control Artifacts
Design controls artifacts can be found and tracked in Ketryx through several screens and files. Relevant screens include
1. the Requirements traceability matrix screen,
2. the Graph screen (showing the architecture diagram),
3. the Risk management screen,
4. the Test management screen, and
5. the Item records screen.
Design control artifacts that can be exported or downloaded directly can be found in the section on [Records and Artifacts](#7-records-and-artifacts).
To become controlled, each design control configuration item must undergo a design verification step that can be electronically signed. This is the design verification activity for each configuration item, which is done according to the configuration item’s pre-defined **Approval Rule**.
#### 4.2.2. Software Supply Chain
Configuration management for the application software supply chain, including open source, cloud, COTS software, and other dependencies, is further explained in the [Ketryx Software Supply Chain Configuration Management Manual](https://docs.google.com/document/d/1C6SHz6PKhPYHAemDFr83lqOSGMGE_DLG/edit#heading=h.lnxbz9).
### 4.3. Change Management
Ketryx takes a risk-based approach to change management. The default system configuration supports three tiers for change management: the item level change control, the structured change control using the Change Request CI, and the structured action using the CAPA CI.
The three risk-based change control levels provide users the flexibility and structure needed to perform change management in large-scale software applications. The exact usage of these depends on your organization and the context of the product you are building.
1. **Item level change control.** Completed via the configuration item's native record. This is further discussed in each item’s Work Instruction.
1. For Jira: change the status from open to *In Progress*, *Resolved*, and *Closed*
2. For Git:
1. software item (i.e., source code): completed via a merge request
2. software dependency information record (SOUP record): completed via Ketryx; see [MAN-03 Supply Chain Management: Software Dependencies](/wZDI3WrsOK0i3HMp81Me/manuals/man-03-supply-chain-management-software-dependencies.md)
2. **Structured change control using the Change Request CI**. Create a Change Request work item in Jira and follow the tasks described in [WI-08 Change Request](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-08-change-request.md).
3. **Structured action using the CAPA CI**. Create a CAPA item in Jira and follow [WI-09 CAPA](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-09-capa.md) to perform an action that can result in change control.
Together these three levels of change management, the configuration item level, the Change Request level, and the Action/CAPA level, can allow users to conduct various complex change management activities, which can be used to capture all the information required by the strictest safety-critical industry requirements.
## 5. Application Lifecycle Management
### 5.1. Software Development Process
In Ketryx, software development is part of a gated product development process, with each gate having milestones and deliverables.
When building safety-critical systems across some industries and jurisdictions, it is important to ensure that the design inputs are fully defined by the design output (i.e., realized in/by the design output). As a result, before system validation, it is necessary to review and approve design-related items and the complete system sequentially, starting at the initial requirements and moving toward the final product technical requirements. This waterfall-like approach is supported by Ketryx’s gated approach while still allowing users to develop software using a variety of development methodologies, including agile-based ones. This is done by enforcing structure for deliverables and the design control management process as part of the release process.
To release software in Ketryx, validation activities must be performed as described in each release’s *Test Plan*. All Configuration Items that are part of the release must be placed under change control (unless they are unresolved anomalies), the software must be validated per the *Test Plan*, and the artifacts listed in section 7 of this manual must be generated, reviewed, and approved. Only then can the Groups relevant for Version approval review, approve, and release the software. The below figure notes the software development activities and their deliverables, as well as the audit activities Ketryx can support to ensure needed activities are performed. Further detail on the software release process is provided later in this manual and can also be found in [MAN-02 Software Release Process](/wZDI3WrsOK0i3HMp81Me/manuals/man-02-software-release-process.md).
Once the software is released and maintenance is required, a complementary process is used.
### 5.2. Default Configuration
While many aspects of Ketryx can be modified based on a company’s quality system and business activities, there are sensible default configurations built into Ketryx. These include the groups and approval rules for an organization and project, respectively.
#### 5.2.1. Default Groups
At the core of Ketryx are the groups that different system users can be a member of. These groups represent the responsibilities users have on their journey to create validated applications.
The following Groups are defined by default:
1. **R\&D Leads**
Group Description: Leads the development of software products and makes the technical decisions about the product. **Confirms that specifications and the application meet the requirements**.
2. **Product Managers**
Group Description: Leads product development, defines requirements and deals with complaints. **Confirms that the application meets users' requirements**.
3. **Quality Managers**
Group Description: Leads all quality assurance and quality activities and writes and approves tests. **Confirms that the product and the company processes comply with relevant regulations**.
4. **Developers**
Group Description: **Implements specifications into working applications and writes unit tests**.
5. **Quality Control**
Group Description: Writes and executes tests. **Tests implementations and confirms that they meet test case acceptance criteria and processes complaints**.
#### 5.2.2. Default Approval Rules
By default, the following **Approval Steps** are defined for configuration items of the respective type. Each *Approval Step* is based on one of the default *Groups*, and at least one approval is required for each step. Unless otherwise noted, items of the respective type have an Item Assignee who also needs to approve. These default **Approval Rules/Steps** can be changed by a user with the proper permissions in the *Approval rules* page under a project's *Settings* tab.
1. Requirement: R\&D Leads, Quality Managers, Product Managers
2. Software Item Spec: R\&D Leads, Quality Managers
3. Task: none (only the Item Assignee needs to approve)
4. Test Case: R\&D Leads, Quality Managers, Quality Control
5. Test Execution: Quality Managers
6. Anomaly: R\&D Leads, Quality Managers
7. Complaint: R\&D Leads, Quality Managers, Product Managers
8. Change Request: R\&D Leads, Quality Managers
9. CAPA: R\&D Leads, Quality Managers, Product Managers
10. Risk: R\&D Leads, Quality Managers
11. Hardware Item Spec: : R\&D Leads, Quality Managers
12. Dependency: R\&D Leads, Quality Managers (no Item Assignee)
13. Test Plan: R\&D Leads, Quality Managers (no Item Assignee)\
\
Note: Ketryx applies the same default approval rules to all Test Plans, regardless of whether they're [Release test plans](https://docs.ketryx.com/manuals/man-06-test-management#id-2.2.-defining-a-release-test-plan) (managed in the Tests page) or external Test Plan items such as [Xray Test Plans](https://docs.ketryx.com/manuals/man-06-test-management#id-2.3.-xray-tests) (which are synchronized into Ketryx from Jira/Xray)
14. Version: R\&D Leads, Quality Managers, Product Managers (no Item Assignee)
15. Document: R\&D Leads, Quality Managers, Product Managers (no Item Assignee)
Further information on how to configure a project’s **Approval Rules** can be found in [MAN-11 Approval Rules](/wZDI3WrsOK0i3HMp81Me/manuals/man-11-approval-rules.md).
### 5.3. Processes, Tasks, Items, and Members
The Ketryx Platform facilitates product creation, management, and retirement. The Ketryx Framework is a set of rules that govern how processes, activities, and tasks can be performed on Items by Members.
Each configuration item represents the abstract notion of the system component, with each version of it a record of that configuration item. Each approval process of an item involves performing all the tasks required by that configuration item’s work instruction, which checks Ketryx’s Rule Engine and creates a controlled record. Only Ketryx can change the state of an Item to *Closed* by checking with Ketryx’s Rule Engine, which determines if that Item’s current attributes satisfy its description in the Quality System Format. Each *Closed* record is then stored in Ketryx.
The creation of a Requirement, its drafting, and approval constitutes an activity. Specifically, it is a Design Control activity that ensures requirements are developed, verified, and approved in a controlled and documented manner.
The relationship between processes, activities, and tasks is shown in the diagram below. A process is a set of integrated activities that transform inputs into outputs. An activity is a set of integrated tasks. Generally, Ketryx configuration items are tasks or activities.
Throughout different lifecycle processes, manufacturers use configuration items to manage the tasks required to create a validated system. As mentioned earlier, each configuration item has four states: Open, In Progress, Resolved, and Closed. Members must conduct tasks to move Items between the four states. For a requirement, for example, to move from Resolved to Closed, all the selected approval steps must verify the design (design verification).
For an Item to be an ***effective*** configuration item in a given Version, it must be Closed, and the Version must match its version range, as specified by the fields *Introduced in version* and (for long-lived item types) *Obsolete in version*. There are generally two categories of configuration items in Ketryx:
1. **Long-lived** item types have both an *Introduced in version* (the first version they are effective in, *inclusive*) and an *Obsolete in version* field (the first version they are *not* effective in, *exclusive*). These include Anomalies, Configuration Items, Requirements, Risks, Software Item Specs, Hardware Item Specs, and Test Cases. If the *Introduced in version* is not explicitly defined, these items are assumed to be in the first version. If *Obsolete in version* is not explicitly defined, these items are assumed to be in every subsequent version.
2. **Point-wise** item types only have an *Introduced in version* field, which ties them to the specific Version they are effective in. These include CAPAs, Change Requests, Complaints, Test Executions, and Tasks, as well as Release Documents and Milestone Documents in projects where release documents are [tracked as configuration items](https://documentation.ketryx.com/wZDI3WrsOK0i3HMp81Me/manuals/pages/DOipwJYDUqdMqBE9DbgD#id-3.9.1.-release-documents-as-configuration-items).
Note that, for Anomalies, *Introduced in version* denotes the first version they are known to affect, while *Obsolete in version* denotes the version they are expected to be resolved in.
Records of items that are *deleted* in Jira are still kept in Ketryx. A record that marks the deletion is created in Ketryx, which is essentially treated like an obsolete item w\.r.t. release management. If the item has been in a controlled state before, the deletion marker needs to be approved (in Ketryx) for the deletion to be considered controlled, i.e. it starts out in the *Resolved* state; otherwise (if the item has only been in a draft state), the deletion is considered controlled right away, i.e. it is immediately *Closed*.
### 5.4. Versions and Releases
The baseline version of each release is determined based on its version number: The latest released version preceding the given version is considered the baseline. By default, Ketryx looks for a [SemVer](https://semver.org/)-compatible version number within a version's name to derive its version number. This can be customized using advanced setting [Version number pattern](/wZDI3WrsOK0i3HMp81Me/reference/advanced-settings.md#version-number-pattern), and in each version's settings.
Depending on the configured release controls, a version can only be released if all included items are in a controlled state.
Wherever a version can be selected (e.g., to filter items), the *Current* state can usually also be selected, which represents the current "draft" of design controls. This includes all items that are not marked as obsolete in any version (regardless of when they were introduced). Jira-based items on *Current* show the current content as you would see in Jira. Git-based items, such as SOUP dependencies, on *Current* are derived from the primary analyzed branch or tag (typically `main` or `master`), as opposed to the version-specific *release ref pattern* (such as a `v1.0` tag), configured for each repository in the project settings.
#### 5.4.1. Release types
There are three different types of releases in Ketryx:
1. A *full* release incorporates all items in their *current* state. For Jira-based items, this is based on the information you currently see on the Jira work item. This is the default release type and is appropriate when the entire project is being released together.
2. A *patch* release inherits the state of each long-lived item from its baseline version. Only items explicitly marked as introduced or obsolete in the patch release (based on its version number) use their current (controlled) state. Everything else carries over exactly as it appeared in the baseline.
3. An *incremental release* also incorporates only specific changes, similar to a patch release. But instead of opting into changes based on a version number, items matching a certain [KQL](/wZDI3WrsOK0i3HMp81Me/reference/ketryx-query-language.md) filter are considered in scope for change. In addition, certain items related to any matching items can be incorporated as well, including affected or new items of Change Requests and CAPAs, affected and resolving items of Anomalies, affected items of Complaints, and risk control measures of Risks.
The rest of this section focuses on how incremental release scoping works in practice.
**5.4.1.1. Incremental Release Scope Filter**
The scope filter determines which record of each item Ketryx treats as active in an incremental release. You configure it on a version's Settings page to limit the release to only the changes relevant to that version
**How It Works**
An incremental release has two key components:
1. A scope filter ([KQL](/wZDI3WrsOK0i3HMp81Me/reference/ketryx-query-language.md)) that defines which items are in scope for this release.
2. A baseline version that serves as the reference point for all other items. The baseline version is automatically determined as the latest released version preceding the current version (according to [SemVer](https://semver.org/)), but it can be overridden in the version's settings.
**Items matching the scope filter** use their current record as the active record in this version. These are the items being actively worked on for this release.
**Items not matching the scope filter** fall back to the baseline version. Their state is inherited exactly as it was in the baseline, whether that record was controlled, uncontrolled, or deferred.
{% hint style="info" %}
**Important: The scope filter queries against the Current draft.**
The *Current draft* reflects the current state of all items in the project as they exist in the connected system (e.g., Jira). It does not apply any versioning logic. Every item in the project is present in the *Current draft* regardless of which version it belongs to or which version view you are configuring. Excluded items are the one exception and will not appear.
**A scope filter that is too broad will match unintended items. For example:**
* `RQ` matches **all** Requirements in the *Current draft*, including those introduced in a future version that are not relevant to this release.
* `RQ and Components:"Patient Portal"` matches only Requirements belonging to a specific component, significantly reducing the risk of pulling in unintended items.
If your filter is too broad, those unintended matches will use their current record in the incremental release rather than falling back to the baseline. Always define the scope filter as specifically as possible.
**Note:** The KQL Filter intestplan/in-test-plan is **not supported** by the scope filter. If you would like to scope to specific TCs whose *Current* record you want to take based on their inclusion in an external test plan (e.g. Xray or TestRail), use "is contained in":(TP identifier).
{% endhint %}
**Example**
Suppose you are working on version 1.0.1, and your scope filter is set to `Components:"Patient Portal"`. The baseline version is 1.0.0.
| Item | Matches Scope Filter? | Active Record Used |
| ------------------------------------------------------ | --------------------- | ------------------------------ |
| `RQ` in Patient Portal component | Yes | Current record |
| `Anomaly` in Patient Portal component | Yes | Current record |
| `RQ` controlled in 1.0.0, not in Patient Portal | No | Controlled record from 1.0.0 |
| `Anomaly` uncontrolled in 1.0.0, not in Patient Portal | No | Uncontrolled record from 1.0.0 |
In the last row, even though the anomaly is not in scope for 1.0.1, it still appears as uncontrolled because its baseline record was uncontrolled. The scope filter doesn't hide out-of-scope items; it determines which version of the record Ketryx treats as active.
> **Note:** Items with their "Introduced in version" set to an incremental release will not appear in that release unless they also match the scope filter. Because these items do not exist in the baseline, they cannot be inherited and will be absent from the release entirely.
**Where to Configure**
1. Select the relevant project.
2. Click ***Releases*** in the left sidebar.
3. Select the version you want to configure.
4. Click ***Settings*** in the left sidebar.
5. Under ***Baseline Version***, set the baseline.
6. Scroll down to ***Release Type*** and select ***Incremental***. This reveals the scope filter field, which accepts standard KQL syntax.
Always verify that your baseline version is correct, as it determines the fallback state for every item outside your scope. When teams work on multiple versions in parallel and the baseline version is unreleased, edits to out-of-scope items can cause them to appear as uncontrolled in the current incremental release. Record locking, described in the next section, resolves this..
#### 5.4.2. Locking item records for release baselines
For finer-grained control over which records are used in a version, particular records of each item can be *locked* to the release baseline. Locked records override the automatic logic described for the different release types above.
This can be useful when starting to work on a following version while the current release is not finished yet. If you want to edit existing items without affecting the current release, you can lock their current records for this release, so that new records created based on your edits are not incorporated into the release.
To lock the current record, select items on the *All items* page and choose *Lock selected records for this release baseline* from the extended menu (`...`).
You can also lock a particular record from the history of each item, by navigating to its record detail page, and managing locks in the *Baseline locking* section. This can be useful to use a particular historic record of an item in the release baseline, when the item has already been changed in the meanwhile.
Item locks can be removed by choosing *Unlock selected items for this release baseline* from the extended menu on the *All items* page, or on the item record detail page.
Locking and unlocking records requires the *Manage project* permission on the project. Locking-related actions show up in the changes associated with the record as well as the project's audit change log.
You are also able to lock the ‘Last Controlled Record’ to the current release for multiple items in bulk. By navigating to the *All Items* page & selecting multiple Configuration Items, you will be able to lock the *last controlled record* of selected items. This bulk action is particularly useful when preparing a release after numerous Configuration Items have been modified, as it ensures the Last Controlled Record of the selected items is locked to the selected release version. This also helps if you forgot to bulk lock your controlled records for a version before starting to work on them again.
Bulk Locking of the Last Controlled Record for multiple items.
This action will only lock the items that **have controlled records** - if an item has never been controlled, it will not be locked. A warning message will display before you confirm this action.
If an item does not have any controlled records, it will not be locked with this action.
**5.4.2.1. Using Record Locking with Incremental Releases**
Record locking is especially useful when combined with incremental releases (see Incremental Release Scope Filter section), particularly when teams are working on multiple versions in parallel and the baseline version has not yet been released.
**Example**
Version 1.0.1 is an incremental release. The baseline version, 1.0.0, has not yet been released. Because 1.0.0 is unreleased, it reflects the current state of its items, meaning changes made to those items will affect what 1.0.1 inherits from the baseline.
A team member reopens a Requirement (controlled in 1.0.0) to start work on version 1.1.0.
* The Requirement is outside the 1.0.1 scope filter, so Ketryx uses its record from the 1.0.0 baseline.
* Because 1.0.0 is unreleased, the reopened item's record is now uncontrolled in the baseline.
* Since 1.0.1 is baselined on 1.0.0, it now appears as uncontrolled in 1.0.1.
**Resolution:** Lock the last controlled record of the affected item(s) to the 1.0.0 baseline using any of the methods described above. This way, 1.0.1 inherits the correct controlled record from that baseline, and the edits only take effect in future versions.
The same approach works for deferred anomalies. If a team member removes a deferral reason to begin fixing an anomaly for a future version, lock the record at the state where the deferral was still present.
#### 5.4.3. Item variants
Ketryx allows you to create **variants** of an item. This is a powerful feature for managing situations where an item's content needs to be different in separate versions, enabling you to work on multiple versions in parallel without affecting each other.
For instance, the impact of a vulnerability might be different in a new feature version compared to an older, stable version. By creating a variant of the *Vulnerability Impact Assessment*, each version can have its own independent assessment, without affecting the other.
Currently, this feature is available only for *Vulnerability Impact Assessments*. For a detailed walkthrough of how to use this functionality, see the [Vulnerability Management manual](/wZDI3WrsOK0i3HMp81Me/manuals/man-03-supply-chain-management-software-dependencies/vulnerability-management.md) or [WI-12 Variants and Versions](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-12-variants-and-versions.md).
#### 5.4.4. Monitoring
Ketryx supports three different monitoring options that you can adjust in the settings page of a version.
1. **Automatic** (Default): The release with the highest version number according to Semantic Versioning ([SemVer](https://semver.org/)) is considered currently active.
1. If the latest automatic release is unreleased, the most recent released version according to SemVer that was marked as automatic is considered the active version.
2. The only exception to this rule is if the previous release is manually marked as inactive. In this case, no previously automatic release is considered active, effectively disrupting the sequence.
2. **Active**: Manually marked active releases are always considered active.
3. **Inactive**: Manually marked inactive releases are always considered inactive.
For dependencies associated with active released versions, you will receive weekly and daily [vulnerability notifications](https://documentation.ketryx.com/wZDI3WrsOK0i3HMp81Me/manuals/pages/92YMV4cvA6PGb418IB4d#id-9.-vulnerability-notifications) via email. Setting the monitoring option to *active* is recommended in case you have multiple released versions of your product running in production in parallel.
Adjusting this setting will only have effect on released versions.
### 5.5. Building Products
Building validated systems that can turn into products that serve safety-critical functions is a complex, detailed, and challenging endeavor. Ketryx is built to reduce the complexity and cognitive load of building such products, allowing teams to focus on what matters most.
The sections provided below are simplifications of the activities needed to produce validated systems in different industries and jurisdictions. It is expected that the company building the system/product will have the knowledge, resources, and capabilities to build such a system. As a result, the below is only the explanation of Ketryx functions related to these activities and not a description of all the necessary activities.
Additional details about releasing software in Ketryx can be found in [MAN-02 Software Release Process](/wZDI3WrsOK0i3HMp81Me/manuals/man-02-software-release-process.md).
#### 5.5.1. Software Development Planning
**Deliverable:** Risk Management File draft
Once a new product is decided on, a project needs to be created to govern the system(s) that make up that project. As part of this process, a Product Leadership Team (PLT) shall be appointed, consisting of a *Member* of each of the following *Groups*:
* Product Management
* R\&D Leads
* Quality Management
Following the formation of the PLT, the project should start. The software development process will consist of the steps described in Figure 2. At each phase below, the activities listed will be conducted. The deliverables mentioned at the beginning of each phase can be generated, reviewed, and stored in the Ketryx Platform.
#### 5.5.2. Software Requirements Analysis
**Deliverable:** System Requirement Specification
**Tooling:** Requirement Traceability Matrix
*Members* create requirements that can describe a wide variety of systems, environments, contexts, and intended uses. Each requirement is captured in a *Requirement* type configuration item.
Requirements can be defined throughout the software development lifecycle but must be approved and under change control before any software verification and validation activities begin. Requirements can be developed and managed in the connected work item/task management platform.
Further details on the *Requirement* configuration item can be found in [WI-01 Requirement](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-01-requirement.md).
#### 5.5.3. Software Architecture Design
**Deliverable:** Software Design Structure Matrix, *Software Design Architecture Diagram*, *Software Item Specification* configuration item
**Tooling:** Architecture Module
*Members* realize requirements into software architecture. This can be done by creating Software Item type configuration items that fulfill the requirements and are combined together to perform different tasks and provide required features and functionalities.
Software Architecture can be defined through the software development lifecycle but must be approved and under change control before any verification and validation activities. Software architecture is defined through the *Software Item Specification* configuration item, and is developed and managed in the connected work item/task management platform.
Further details on the *Software Item Specification* configuration item can be found in [WI-02 Software Item Specification](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-02-software-item-spec.md).
#### 5.5.4. Software Detailed Design
**Deliverable:** *Software Design Specification*, *Software Item Specification* configuration item
The detailed software architecture design (i.e., the detailed design) is developed using the *Software Item Specification* configuration item and is developed and managed in the connected work item/task management platform.
Further details on the *Software Item Specification* configuration item can be found in [WI-02 Software Item Specification](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-02-software-item-spec.md).
#### 5.5.5. Software Unit Implementation and Verification
**Deliverable:** *Code Change Review report*, *Testing report*, *Test Plan*, *SOUP Dependencies report*
**Tooling:** Items screen with filter for specifications, *Task*, and *Test Case* configuration items
Software Items (i.e., blocks of code, units, modules, systems) are implemented using the *Task* configuration item. *Tasks* are created as units of work, to be assigned to a *Member*. For each *Task,* the *Implemented items* field shall contain which *Software Item Specification* or *Requirement* needs to be implemented during this *Task*. When a merge request is created, the *Task* item ID should be mentioned in the merge request description to create traceability between the specific merge request and the *Task*. When a merge request is not related to a particular *Task*, it may also reference the implemented *Software Item Specification*, *Requirement*, *Anomaly*, or other relevant configuration items directly.
Unit testing, module testing, and system testing are governed by the *Test Case* and *Test Execution* configuration items. Before the beginning of any verification and validation activities, a *Test Plan* can be created to define which *Test Cases* will be executed as part of the release. Note that if no *Test Plan* is configured, it is assumed that all *Test Cases* assigned to any CI in the release will be executed. At least all design endpoints (*Requirements* and *Software Item Specifications* with no children) will be executed.
*Tasks*, *Test Cases*, and *Test Executions* are developed and managed in the connected work /task management platform. Further details on the *Task*, *Test Case*, and *Test Execution* configuration items can be found in [WI-03 Task](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-03-task.md), [WI-04 Test Case](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-04-test-case.md), and [WI-05 Test Execution](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-05-test-execution.md), respectively.
#### 5.5.6. Software Integration and Integration Testing
**Deliverable:** *Verification and Validation Testing Report*
**Tooling:** Testing Module
Software integration and integration testing can be performed using the same functionality described in the previous section. Further details on testing can be found in [WI-04 Test Case](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-04-test-case.md), and [WI-05 Test Execution](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-05-test-execution.md).
#### 5.5.7. Software System Testing
**Deliverable:** *Verification and Validation Testing Report*
**Tooling:** Testing Module
Software system testing can be performed using the same functionality described in the previous section. Further details on testing can be found in [WI-04 Test Case](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-04-test-case.md), and [WI-05 Test Execution](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-05-test-execution.md).
#### 5.5.8. Software Release
Software release should be conducted for each new product version. All configuration items should be placed under change control and approved. Once unit, module, and system testing are performed, all unresolved anomalies should be documented, with their *Rationale for deferring resolution* field filled in.
The release can only be approved if all configuration items are controlled, required records, deliverables, and artifacts have been generated and approved, and the PLT approves the release. For further information, please refer to [MAN-02 Software Release Process](/wZDI3WrsOK0i3HMp81Me/manuals/man-02-software-release-process.md).
### 5.6. Maintaining Products
At the core of Ketryx and safety-critical software regulations is the concept of change management and maintenance. While change management is addressed in earlier sections of this manual, due to its criticality to validated systems, it is again reviewed here in the context of maintenance.
Maintenance is a core part of safety-critical regulatory requirements and is commonly identified as a source of adverse events and harm. As a result, Ketryx requires that maintenance be performed in a controlled manner, using a risk-based approach through traceable configuration items. The main configuration items used as part of maintenance activities are:
* *Complaint*
* *Anomaly*
* *Change Request*
* *Corrective And Preventative Action (CAPA)*
Combined with Ketryx’s deep integration with source code, cloud, and task management systems, these four configuration items provide powerful tools for change management in complex validated systems, like cloud-based, data-driven medical software and robotics systems.
Typically, a *Complaint* can lead to one or more *Anomalies*. As part of each *Anomaly* activity, a problem report is documented. This problem report might lead to a *Change Request* or *CAPA*. These can get implemented across the product (e.g., source code), design controls, and the QMS through additional configuration items, like *Tasks* or *Requirements*.
**Software Maintenance Planning**
Software maintenance will be done on a version basis, with internal and external information and feedback leading to maintenance and modifications in the validated system.
Software maintenance (i.e., software change management) can be done on three tiers:
1. Configuration Item Level
2. Structured Change Control through a Change Request configuration item
3. Structured Action through a CAPA configuration item
Software maintenance can happen as a result of a wide range of factors. Additional features (i.e., requirements), also known as enhancements, maintenance to existing code, or as a response to external product feedback or adverse events. Among many things, the reason for change and approval of change depends on the intended use, the use environment, and the quality system of the system manufacturer or user. The decision to implement a change can be a result of multiple factors, for example, a desire to mitigate a source of adverse events (i.e., harm), to enhance the system with new functionality, or to correct a design flaw.
While Ketryx can be used to perform change management, the system manufacturer still must utilize their software maintenance plan for their intended use and use Ketryx’s different tools to implement the change.
#### 5.6.1. Problem and Modification Analysis
**Deliverable:** Release notes, *Anomaly* configuration item record
In Ketryx, changes can result from external factors (e.g., customer feedback, adverse events, etc.) or internal factors (e.g., internal feedback, failed testing, etc.). These can be captured using different configuration items, most commonly the *Complaint* and *Anomaly*, but in some cases (e.g., enhancements) as a *Requirement*. As a result of software problems, modifications will be implemented to mitigate and, if possible, eliminate the problem. While the source of the problem can dramatically affect its criticality and priority, the process for modification is generally the same.
1. External problem reports will be recorded using *Complaints*, internal problem reports can be recorded using *Anomalies*. If a problem starts as a *Complaint* an *Anomaly* should be created to resolve that *Complaint*.
2. For each *Anomaly* a root cause investigation should be conducted. Once the root cause of the problem is discovered, a *Change Request(s)* or *CAPA* shall be created.
3. Following the *Change Request* or *CAPA,* *Members* shall modify different configuration items.
4. As needed, *Tasks* will be created for required source code modification.
5. Periodically, modifications should be reviewed.
**Post-Market Surveillance**
**Deliverable:** *Complaint* records in Ketryx and other change-related CI records
**Tooling:** *Complaint* configuration item
Post Market Surveillance (PMS) is the process of recording, investigating, mitigating, and responding to feedback and information about products in the market. Depending on your quality system and process, this might take various forms.
In Ketryx, the PMS can be performed using the *Complaint* configuration item and other maintenance and change-related activities. The generic process could involve:
1. Recording the product feedback or adverse event using the *Complaint* configuration item
2. Depending on the type of complaint, create one or more *Anomaly* type configuration items related to the complaint and investigate the root cause(s) of the anomaly(s).
3. Utilize a risk-based change control activity to mitigate the anomaly. This would usually be done through a Change Request or CAPA configuration item.
The specific application of Ketryx tools for PMS depends on the manufacturer’s quality system.
**Anomalies and Problem Reports**
Anomalies (and other deviation types) and problem reports are managed as part of the *Anomaly* configuration item. This configuration item contains fields to both report and analyze the anomaly, as well as the underlying problem, root cause, and potential solution.
Further details on the *Requirement* configuration item can be found in [*WI-06 Anomaly*](/wZDI3WrsOK0i3HMp81Me/work-instructions/wi-06-anomaly.md).
#### 5.6.2. Modification Implementation
After modifications have been implemented, each change request can be verified using a *Test Case* to show the change resolved the root cause.
### 5.7. Systems of Systems
Ketryx can be used to manage a *System of Systems* by structuring work into several projects and creating references across those projects. Consider watching this [training on cross-project references](https://ketryx-docs.gitbook.io/ketryx-training/uFu2zWhZZG0zASudME6B/ketryx-video-guides/cross-project-references-in-ketryx).
#### 5.7.1. Cross-Project References
Before items from one project can cross-reference items in another project, the *referenced* project (the "target" of the relation) needs to be added in the *References* settings of the *referencing* project (the "source" of the relation). Each reference can define a particular set of *referencable* and *incorporated* items and give fine-grained control on what items are available to the referencing project.
The following sections will outline the general concepts of the *referencable space* and *incorporated pool*, including the configuration via different selection modes.
**5.7.1.1. Incorporated and Referenceable items**
{% hint style="success" %}
Cross-project referencing is fully supported for Git-based items.
{% endhint %}
A project reference differentiates between a set of **incorporated** and **referenceable** items:
* The *referenceable items* represent the *space of items* that can be used as a reference within the referencing project
* Referenceable items will be selectable as a relation within Ketryx and other third party systems (e.g., Jira)
* As far as third party systems are concerned, only references between two Jira-connected Ketryx projects are possible currently.
* The *referenceable space* also includes all items that belong to the referencing project
* Referenceable items *will not* show up on the *All items* page
* The *incorporated items* represent the *pool of items* that are listed and accessible via the *All items* page in the referencing project
* Items within this pool are treated as if they would be part of the referencing project and will show up in all parts of the Ketryx app (Risk management, Test management, Traceability, etc.) and also be rendered in related evidence documents
* Incorporated cross-referenced items are still complying to the same approval rules and risk configuration settings of the project they are primarily contained in
* In the case cross-referenced Test Cases, the test management system will consider all incorporated Test Executions (of the referencing project as well as the referenced project) to calculate the latest effective Test Execution
In regular system-of-a-system setups, the *referenceable space* is commonly defined as a superset of *incorporated items*, but depending on the system's needs, it is also possible to define arbitrary sets based on KQL filters.
The project reference may be configured via two different configuration modes:
1. **Filter-based selection** of items in referenced projects: This mode allows defining a fine-grained scope of *incorporated* and *referenceable* items via [*Simplified KQL*](/wZDI3WrsOK0i3HMp81Me/reference/ketryx-query-language.md) queries.
2. **Legacy type-based selection** of items in referenced project: This mode allows defining the scope of *referenceable* items via pre-defined item type and relation options. This mode has been superseded by the more powerful filter-based selection mode and should not be used in new project references.
Independent of the selected mode, a referencing project may also incorporate the release documents of a referenced project, which exposes those documents in the release and the Design History File. When including *transitive* documents, the documents of any referenced projects of the referenced project (etc.) are also exposed.
Note that cross-project references are *directed*, allowing references *from* the referencing project (A) *to* the referenced project (B). To also allow references in the other direction, a "reciprocal" relation from project B to project A needs to be added.
Software Item Specs in the referencing project may refer to a referenced project as a *used service*, which declares a dependency on the whole service without specifying which item within the referenced project is used exactly.
**5.7.1.2. Incorporating Dependencies and Vulnerabilities**
By default, incorporating dependencies and vulnerabilities across projects is disabled. To incorporate dependencies and vulnerabilities across projects, the "Incorporate dependencies and vulnerabilities..." setting must be enabled in the References settings.
**5.7.1.3. Filter-Based Selection**
By default, when the filter-based selection mode has been enabled, *all* items of the referenced project will be part of the *referenceable* space (filter defaults to `*`), and *no items* will be part of the *incorporated pool* (filter defaults to `none`). The filters for *referenceable* and *incorporated* items can be defined as a *simplified KQL* statement (i.e. may filter items based on the item types, item relations and core field values only).
**Note:** If either filter field is left blank (or cleared), it behaves as `*` — matching all items from the referenced project.
Additionally, a filter-based project reference may be configured to include *items from projects that are transitively referenced* by the referenced project (as defined by the references within the referenced project).
**5.7.1.4. Legacy Type-Based Selection**
{% hint style="info" %}
This section is intended to document legacy behavior of existing projects. For new project references, or for complete cross-project traceability across non *Test Case* / *Test Execution* items, use the filter-based selection mode instead.
{% endhint %}
By default, when the type-based selection mode has been enabled, *all* items of the referenced project will be part of the *referenceable space*, including cross-project references to Anomalies and Risks; but it is also possible to define a more granular set of relation targets:
* Requirements (as *parent requirements* or *fulfilled requirements*)
* Software/Hardware Item Specs (as *used items*)
* Tested items
* Tests
When tests from another project are included as referenced items, they are treated as *incorporated* items, and show up on the *All items*, *Test management*, and *Traceability* pages of the referencing project. They can also be used to create *Test Executions*. By default, they are *not* included in the referencing project's release test plan, though.
#### 5.7.2. Cross-Project Referenced Risks and Risk Controls
Given a project (A) that references another project (B), Ketryx will include any references and item details of risks and risk controls from project B in project A in the following areas, depending on the selected project reference mode:
* Web pages
* Risk management page
* **Filter-based selection mode:** All the risks that are part of the *incorporated pool* are shown
* **Type-based selection mode:** All the risks of the referencing project are shown
* Risk controls page
* **Filter-based selection mode:** All the items that are part of the *incorporated pool* and are considered a risk control based on the risk items found in the *referenceable space* are shown
* **Type-based selection mode:** All the items that are considered a risk control based on the risk items found in the *referenceable space* are shown
* Risk form
* **Filter-based selection mode:** All the risks that are part of the *incorporated pool* are shown
* **Type-based selection mode:** All the risks of the referencing project are shown
* Documents: The information shown in web pages is also reflected in the corresponding evidence documents, including:
* Risk matrix
* Risk control matrix
* Risk management file
* Cyber risk management file
Ketryx includes risks and risk controls from project B in project A by principle of tracing, i.e. identifying relevant items to include by following a chain of risk control and 'introduces risk' relations that originate in project A (as defined by its configured *referenceable space* of items). Furthermore, any *referenceable* Test Cases (and resulting Test Executions) that test an item in this relations chain will be included in project A.
#### 5.7.3. Version-specific Settings
For each version of the referencing project, a specific used version of each referenced project can be defined in the (referencing) version settings. This allows "locking in" a particular used version, and informs which record to show for each referenced item (which is particularly relevant if the *title* of the item changes over time). By default (if no specific used version is explicitly defined), the referenced project's latest version in version-number order is used. Note that this is the last version by version number and is not necessarily a released version, so a draft or in-progress version can be the effective one.
The version picker labels this default as *Latest*. When a default applies, the picker also shows the version it currently resolves to in parentheses, for example *Latest (1.4.0)*, so you can see the effective referenced version without leaving the settings page. If the referenced project has no visible versions at all, the picker shows *Latest* with no version in parentheses.
When showing cross-project references in release documents, the referenced project along with its used version (if explicitly defined) is shown as well.
#### 5.7.4. Systems, Sub-systems, Services
Complex systems are usually structured in several layers, as follows (from higher to lower level):
1. a **System** consisting of one or more of the processes, hardware, software, facilities, and people, that provide a capability to satisfy a stated need or objective
2. **Sub-systems**, integrated collections of software items or hardware items organization to accomplish a specific function or set of functions
3. **Services**, self-contained and validated systems with specific predefined interface requirements
Typically,
* higher-level ("parent") projects would incorporate the release documents of lower-level projects and reference used items in the lower-level ("child") projects (or reference a lower-level project "as a whole", i.e., as an opaque service), while
* lower-level projects might reference requirements in the higher-level projects.
See the step-by-step guide about [Setting up Cross-Project References](#id-6.4.-setting-up-cross-project-references-for-a-system-of-systems) for detailed instructions.
### 5.8. Differentiating Regulatory Regions
Ketryx supports building products for different regulatory regions, and similar cases where different variations of quality documents need to be produced. A "region" could be a geographic region such as *EU* vs. *US*, or a more abstract distinction such as *Customer X* vs. *Customer Y*.
At a higher level, different projects can be used for different regions, each having their own lifecycle and release documents. For instance, an EU-specific service could be maintained as its own project, with other projects referencing it as a *used service* as described [above](#id-5.7.1.-cross-project-references).
At a lower level, individual configuration items can be "labelled" with one or more regions, which makes them specific to those regions. Moreover, certain release documents can be configured to be region-specific. Region-specific release documents only contain items that are explicitly marked for their respective region, as well as region-independent items (not marked with any region).
The relevant [advanced settings](/wZDI3WrsOK0i3HMp81Me/reference/advanced-settings.md) are [Select text field options](/wZDI3WrsOK0i3HMp81Me/reference/advanced-settings.md#select-text-field-options) (to define the set of available regions in a project) and [Region-specific documents](/wZDI3WrsOK0i3HMp81Me/reference/advanced-settings.md#region-specific-documents). For other use cases, the field *Regions* can also be renamed, using the advanced setting [Field names](/wZDI3WrsOK0i3HMp81Me/reference/advanced-settings.md#field-names).
### 5.9 Audit change logs
Besides tracking changes of the actual work items, Ketryx is also capable of tracking changes to the Ketryx configuration itself to establish audit trails on the process administration level.
Audit change logs are captured either on the Ketryx organization or project level and include the following information:
1. **Date and time** of the change
2. **Author** of the change
3. **Change type** category
4. **Change content** to describe the details of the change (as JSON)
To view and download the Audit change logs for the current organization, navigate to *Organization >> Audit change logs*.
To view and download the Audit change logs for a project, navigate to *\[Project] >> History >> Audit change logs*.
On each page, the data can be downloaded as a separate Excel file.
## 6. Step-by-step starter guide
### 6.1. Setting up an Organization
#### 6.1.1. Step 1. Log into Ketryx
Log into the Ketryx platform (e.g., [app.ketryx.com](https://app.ketryx.com))
#### 6.1.2. Step 2. Add members
1. Go to *Organization*.\
2. Here you can change your organization name.\
3. Go to *Members*. Here you can add users to your organization using the *Invite member* button. You will need a member's full name, email address, and role in the organization to invite them.\
#### 6.1.3. Step 3. Create groups
1. Go to *Groups*. You can add Groups as needed using the *Create group* button, but the default configuration comes with six Groups that would fit most software development workflows.\
#### 6.1.4. Step 4. Assign members to groups
1. Go to a specific group's edit page using the *Edit* button.\
2. You can add users to the groups using the *Add user or group* button and selecting the desired user or group from the dropdown menu.\
### 6.2. Setting up a Project
#### 6.2.1. Step 1. Create a project with repositories
1. In the Ketryx Projects dashboard, select the *Create project* button.\
2. Fill out the *Name* field for the project.\
3. Fill out the *Repository URL* field. You can add an additional repository using the *Add another repository* button or add multiple repositories simultaneously using the *Add batch* button.\
4. Select the *Create project* button.\
#### 6.2.2. Step 2. Add a repository to an existing project
1. In an existing project, navigate to *Settings*.\
2. For projects that already have repositories, use the *Add another repository* or *Add batch* button. For projects without repositories, use the *Add repository* or *Add batch* button.\
3. Use the *Save* button to save the changes.\
### 6.3. Connecting to Task/Work Item Management Tool
#### 6.3.1. Step 1. Log into Ketryx and Jira
Log into your Ketryx organization
Log into your Jira organization (e.g., *your-company.atlassian.net*)
#### 6.3.2. Step 2. Get the Ketryx app
1. Go to *Explore more apps* in the *Apps* dropdown menu.\
2. Search for 'Ketryx'.\
3. Add the *Ketryx for Jira* App.
4. Once the app has been added, click on *Get started*.\
5. Select the *Complete installation in Ketryx* button. You will be redirected to the Ketryx platform.\
6. Select the *Connect Jira organization* button.\
#### 6.3.3. Step 3. Connect a project to a specific Jira space
1. In the Ketryx Project dashboard, select the *Create project* button.\
2. Fill out the name of the project.\
3. Select the specific Jira space from the dropdown menu.\
\
\
Note that a Jira company-managed space must be used when integrating with Ketryx - Ketryx does not support integration with Jira team-managed Projects.
4. Select the *Create project* button.\
### 6.4. Setting up Cross-Project References for a System of Systems
This guide shows how to set up an interconnected System with a Sub-system and a Service used by it, and generating documents as described by section [System of Systems](#id-5.7.-systems-of-systems).
#### 6.4.1. Step 1. Create and connect projects
1. Create a Jira space for the *System* and a corresponding Ketryx project connected to it.\
2. Create a Jira space for a *Sub-system* and a corresponding Ketryx project connected to it.\
3. Create a Jira space for a *Service* and a corresponding Ketryx project connected to it.\
4. In the project settings for the *System* under *References*, add the *Sub-system* as a referenced project.
* When using the ***filter-based selection***, set the *Referencable items* and *Incorporated items* filter to `none`, then select the options *Incorporate the release documents...* and *Include transitive release documents...* (to expose the release documents from both the *Sub-system* and the *Service* in *System* releases).\
* When using the ***Legacy type-based selection***, unselect all referenced items, then select *Incorporate the release documents of ...* and *Include transitive release documents...* (to expose the release documents from both the *Sub-system* and the *Service* in *System* releases).\
5. In the project settings for the *Sub-system* under *References*, add the *Service* as a referenced project.
* When using the ***filter-based selection***, set the *Referencable items* and *Incorporated items* filter to `none`, then select *References from ... as a used service*, and *Incorporate release documents ...*
* When using the ***Legacy type-based selection***, unselect all referenced items, then select *References from ... as a used service*, and *Incorporate release documents ...*
6. In the project settings for the *Sub-system* under *References*, also add the *System* as a referenced project.
* When using the ***filter-based selection***, set the *Referencable items* filter to *RQ* and *Incorporated items* filter to `none`
* When using the ***Legacy type-based selection***, unselect all referenced items, and select only *references to requirements*.\
#### 6.4.2. Step 2. Create and connect items
1. In the *System* Jira space, create a Requirement *System Requirement*.\
2. In the *Sub-system* Jira space, create a Requirement *Sub-system Requirement*.\
3. Add the *System Requirement* to the *Parent requirements* of the *Sub-system Requirement*.\
4. In the *Sub-system* Jira space, create a Software Item Spec *Sub-system Spec*.\
5. Add the *Sub-system Requirement* to the \_Fulfilled requirements of the *Sub-system Spec*, and the *Service* to its *Used services*.\
#### 6.4.3. Step 3. Create and associate versions
1. In the *Service* Ketryx project under *Releases*, create new versions *1.0*, *1.1*, and *2.0*.\
2. In the *Sub-system* Ketryx project under *Releases*, create a new version *1.0*.\
3. In the *Settings* for the Sub-system version *1.0*, set the referenced project version for the *Service* to *1.1*, to point to that particular version of the used service. Otherwise, by default, the latest version would be chosen. You could also set a fixed version for the "parent" *System* project, but usually the *Latest* option should be fine.\
4. In the *System* Ketryx project under *Releases*, create a new version *1.0*.\
5. In the *Settings* for the System version *1.0*, set the referenced project version for the *Sub-system* to *1.0*.\
#### 6.4.4. Step 4. Create release documents
1. On the *Documents* page for the Service version *1.1*, generate the *System Design Specification*. (This document will essentially be empty, since the project does not contain any items. This is just to highlight that the document will also be exposed in the other projects.)\
2. On the *Documents* page for the Sub-system version *1.0*, generate the *System Requirements Specification* and the *System Design Specification*.\
3. Note that the documents contain cross-project references, along with version numbers where specified.\
 
4. Note the referenced document from the Service at the bottom of the page.\
5. On the *Documents* page for the System version *1.0*, generate the *System Requirements Specification*.\
6. Note that the document contains the cross-project reference to the sub-system requirement, along with the version number.\
7. Note the referenced documents from the other projects (including the "transitive" document from the *Service*) at the bottom of the page.\
### 6.5. Connecting to Cloud Provider
Further detail on connecting to a cloud provider (currently, Ketryx only supports AWS) can be found in [MAN-04 Supply Chain Management: Cloud Dependencies](/wZDI3WrsOK0i3HMp81Me/manuals/man-04-supply-chain-management-cloud-dependencies.md).
### 6.6. Setting up Git-based configuration items
Please see [MAN-09 Git-Based Configuration Items](/wZDI3WrsOK0i3HMp81Me/manuals/man-09-git-based-configuration-items.md) for step-by-step instructions on how to set up Git-based configuration items.
## 7. Records and Artifacts
Through Ketryx, teams can collect evidence and establish processes across their IT systems to meet regulatory requirements. Part of this regulatory requirement is to produce records and artifacts that proper design, development, distribution, deployment, and maintenance processes have been conducted.
This can include Quality Management System artifacts as well as Design Control artifacts and Change Control artifacts. The diagram below shows which artifacts can be created. The list below provides further detail about each artifact that can be automatically produced in Ketryx. Many other artifacts are possible to create, and the Ketryx team would be happy to support your journey of building. Please [reach out](https://www.ketryx.com/contact-us) for further information about artifacts.
### 7.1. SOUP dependencies
The Software Bill of Material Report covers software application dependencies both from open-source package managers and internally or manually entered information.
### 7.2. Traceability matrix
The Requirement Traceability Matrix shows that all tested requirements are traced to specifications and test cases.
### 7.3. Risk management file
Risk management plan, risk assessment demonstrating that risks have been appropriately mitigated, and risk management report.
### 7.4. System requirements specification
The complete documentation describing the needs or expectations for a system or software, presented in an organized format and with sufficient information to understand the traceability of the information with respect to the other software documentation elements (e.g., risk management file software design specification, system and software architecture design charts, software testing as part of verification and validation).
### 7.5. Software Design Architecture Diagram
The software design architecture diagram displays *Software Item Spec* and *Hardware Item Spec* Configuration Items and their relationships. Child-Parent relationships between *Software Item Specs* are defined by the *Parent software items* field and represented as solid arrows. Child-Parent "uses" relationships between *Software Item Specs* and between Software Item and Hardware Item Specs are defined by the *Used items* field and represented by a dotted arrow annotated with "uses". The color coding of the blocks in the architecture diagram is defined below.
The Graph page opens on an interactive graph view by default. In this view you can pan and zoom the canvas, click a node to open its record details in a side panel, click a relation edge to focus on that relationship, and collapse or expand a node to hide or reveal its descendants. Use the toolbar to zoom, fit the whole graph, fit the current selection, or center the selected node, and use the **Levels** control to limit how many levels of the hierarchy are shown.
The **View** control lets you switch between the interactive graph and the earlier layered and tree layouts. The layered layout is where the drawio and image exports are available, from the **Download** menu.
### 7.6. System design specification
The complete documentation, including sufficient information that would allow the FDA to understand the technical design details of how the software functions, how the software design completely and correctly implements all the requirements of the SRS, and how the software design traces to the SRS in terms of intended use, functionality, safety, and effectiveness.
### 7.7. System design structure matrix
### 7.8. Unresolved anomalies
List of remaining software anomalies (e.g., bugs, defects) annotated with an explanation of the impact on safety or effectiveness, including operator usage and human factors, workarounds, and timeframe for correction.
### 7.9. Test plan
The test plan a validated system was tested against. The test plan must be approved before testing should start.
### 7.10. Testing report
Description of the testing activities at the unit, integration, and system levels. System level test case including expected results, observed results, pass/fail determination, and system level test report. unit and integration level test cases, including expected results, observed results, pass/fail determination, and unit and integration level test reports.
### 7.11. Cloud configuration report
The Software Bill of Material Report covers cloud dependencies and their exact configuration during V\&V.
### 7.12. Code review report
Report with all the code comments.
[^1]: ISO 14971: 2019 Medical devices — Application of risk management to medical devices
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.ketryx.com/wZDI3WrsOK0i3HMp81Me/manuals/man-01-ketryx-lifecycle-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.