How to generate the Design History File for your medical device
Overview
Creating a Design History File for regulatory submission requires systematic documentation of every development decision. This How-to Guide shows you exactly how to do it in Ketryx, providing step-by-step instructions for creating the design documentation required to build your medical device. By following this guide, you will generate the necessary technical documents and compile a complete Design History File (DHF) required for FDA submissions and other regulatory approvals.
What You'll Create
How to Use This Guide
This guide is broken into eleven steps that mirror the medical device development lifecycle by creating and mapping Ketryx Configuration Items to key release documents. In addition to step-by-step instructions on how to populate key information for each type of Configuration Item, the final section of this guide provides an overview of additional default release documents and the key types of Configuration Items that they contain.
Sections include:
While many of these Configuration Items can be created in parallel using Ketryx, it is recommended to follow this guide in order (or to at least fully understand why the steps are written in this order) and to diligently populate item metadata and traceability. Once you create your DHF, Ketryx enables you to work in agile, continuously updating and testing individual Configuration Items in parallel.
This structured approach not only streamlines the generation of essential technical documents like the SRS, SDS, Risk Management File, and Test Reports, but also helps ensure compliance with regulatory requirements from bodies such as the FDA. The continuous use of the Traceability Matrix and incremental versioning practices will further support your organization’s ability to maintain a controlled, traceable, and auditable record throughout the entire medical device lifecycle.
Tracking Progress
Continuous Verification with the Traceability Matrix
It is recommended that you review the Traceability Matrix (see MAN-07 Traceability) early and often and use it as a guide throughout the full lifecycle of Configuration Items being managed in Ketryx. It will help you visualize the relationships required by 21 CFR 820 and ISO 13485 for design controls and also see if anything is missing and what to fix. This is also why it is a required artifact in many regulatory regions.
Release Progress Check
The release screen also provides a consolidated view of your readiness, showing which design control activities are complete and which documents are generated (see MAN-02 Software Release Process). Use it as a quick dashboard to identify gaps in your DHF.
Leveraging AI with Ketryx Assistant
The Ketryx Assistant can accelerate a variety of tasks and document creation throughout this process. It can analyze existing Configuration Items, identify traceability gaps, and generate drafts of items based on your specific project context.
Examples of when to use the Assistant:
Initial Creation
Generating first drafts of requirements from user needs
Identifying risks based on existing requirements and specifications
Creating test cases for verification or validation
Drafting initial vulnerability impact assessments
Analysis & Review
Finding traceability gaps
Checking for missing risk controls
Identifying untested requirements
Reviewing completeness of your DHF
Examples of how to use it effectively include:
Requirements & Specification Generation: “Draft user requirements for [my device] that [have these key functions]”
Risk Analysis: “Review all requirements and specifications in this project and draft potential risks”
Test Case Creation: “Suggest test cases for requirements RQ-001 through RQ-010”
Traceability Review: “Check traceability gaps between requirements and test cases and suggest fixes”
Prerequisites
Before starting, ensure you have:
Essential:
Understanding of your device’s intended use and user needs
Recommended:
Team members assigned with appropriate roles
Quality Management System (QMS) procedures established for:
Risk management approach
Connection to your version control system (e.g. GitHub) for code traceability
Getting Started
With prerequisites in place, you’re ready to begin creating Configuration Items that will form your DHF. The following sections guide you through each type of configuration item in a recommended sequence.
Begin with section 1 (Requirements) as these form the foundation for everything else.
1. Requirements
Key resulting document: System/Software Requirement Specification
Document description: Provides a written definition of the software functions, which is essential for validation and regulatory submissions.
Start with:
Create Use Case Requirements - see WI-01 Requirement
Configuration Item Type: Requirement (with Requirement Type = "Use case")
Purpose: Captures user needs and high-level functional goals.
Ketryx Traceability column: Use Cases
Then:
Create Design Inputs: System/Software Requirements - also WI-01 Requirement
Configuration Item Type: Requirement (all other types except "Use case")
Purpose: These are actionable, detailed requirements derived from use cases that explain how a software system can perform the use cases
Traceability: Relate to one or more applicable Parent Requirements of Type “Use case”
Ketryx Traceability column: Design Inputs
All Requirements: Populate Requirement Type and Context
Design Inputs / System-type Requirements: Populate Context where applicable (for example cyber or safety)
Why:
Requirements are the foundation for all design, risk, and test activities. They drive traceability and are central to the SRS and traceability matrix documents
Context is used to flag items that should be considered for any associated Risks
2. Design Specifications
Creation of Design Specifications and Risk items will often be performed by different people within an organization and can be done in parallel.
Key resulting document: Software Design Specification / Software Detailed Design
Document description: Describes the technical implementation of software functions, outlining how the software design fulfills the requirements of the Software Requirements Specification (SRS) and detailing software units, interfaces, and data flow
Software & Hardware Item Specs:
Create Software Item Specs and Hardware Item Specs (if applicable) - see WI-02 Software Item Spec
Configuration Item Types: Software Item Spec and Hardware Item Spec
Traceability: Relate to one or more applicable Parent Requirements
Traceability: Relate to other applicable SW items to start building the architecture of the device
Context: Populated where applicable to flag items to be considered for any associated Risks
Why:
Design specs show how requirements are implemented and are needed for the SDS and architecture documents
Note about Configuration Item Type: Tasks - see WI-03 Task
Tasks are a way to assign team members work. They can provide all the context needed to users to perform the work (e.g. the RQ or SW item to be implemented) and help track that the work is done
While Tasks are not the primary Configuration Item type included in any Release Documents, Tasks that trace back to Requirements, Software Item Specs, CAPAs, and other Configuration Items may appear in Release Documents
The use of Tasks within an organization is optional. A common reason to use the Task configuration item in Ketryx is to provide developers with additional information on how to perform an implementation that will not show up in regulatory submissions, and/or to track that the information was implemented
3. Risk-related Items
Key resulting document: Risk Management File
Document description: A comprehensive collection of records documenting all risk management activities undertaken throughout the entire lifecycle of a medical device
Risk Analysis & Management Items:
Create Risks, analyze Risks, and define Risk Controls - see MAN-08 Risk Management and WI-10 Risk
Configuration Item Types: Risk, Requirement, Software Item Spec, Hardware Item Spec
Metadata:
Traceability: Relate Risks to applicable Requirements where the risk is introduced. Requirements with context Safety, as marked in the above steps, are a good example of where to establish this traceability
Traceability: Relate to Requirements and Software Item Specs that Control each Risk
For Requirement, Software Item Spec, Hardware Item Spec:
Context: Only items with Context = Safety are included in the “Identification of characteristics related to safety” section of your Risk Management File
Why:
Early risk management is required by ISO 14971 and FDA
Risks and controls must be traceable to requirements and design
4. Versioning
Key resulting document: The Version configuration item is the central organizing entity for all Release documentation
Particularly during the development process, it can be useful to iterate items often and save pieces of documentation to points in time of your development/testing. To do so:
Control all of your Configuration Items created so far
Create a Release as a “snapshot”, for example, v0.0.1
Generate Release Documents of interest, e.g., SRS and SDS
Repeat for successive iterations
Create:
Configuration Item Type: Version - see MAN-02 Software Release Process
Why:
All default Release Reports are generated for a specific version of the product
When ramping up with Ketryx at your company, within a new area of your company, etc., it is good practice to regularly review and Approve Configuration Items, per your QMS, rather than creating all Configuration Items and then having to later review and Approve large numbers of items at once. For example, the following can be an effective way for your organization to incrementally adopt Ketryx.
Create the first round of Requirements, Software Item Specs, Risks, etc.; create Release Version v0.0.1
Work through the process of Releasing v0.0.1 as a non-production version, which will require you to exercise your release process including: Approving each Configuration Item, conducting Risk Management, confirming proper traceability is established, and generating Release Documents
As additional Configuration Items are created - creating more Items as described in the above sections as well as additional Types of Items per the following sections of this guide - repeat the above to generate successive non-production snapshot Releases (v0.0.2, etc)
5. Test Cases, Test Plan, & Test Executions
Key resulting documents: Test Plan and Testing Report
Document description: A Test Plan outlines the strategy, scope, objectives, and methodology for software testing, while a Testing Report documents the results, detected defects, and overall outcome of the executed tests
See MAN-06 Test Management for additional information.
After creation of Design Specifications and Risk-related items:
Create Test Cases
Configuration Item Type: Test Case - see WI-04 Test Case
Metadata:
Traceability: Relate to one or more applicable Requirements and Software / Hardware Design Specs
Why:
Test Cases demonstrate that Requirements and Risk Controls are verified and/or validated, supporting the Testing Report and Traceability Matrix
After creation of Test Cases:
Decide which Test Cases are included and excluded for the given Release Version
Configuration Item Type: Test Plan
Metadata:
Populate the Rationale for exclusion for any excluded Test Cases
Why:
The Test Plan specifies which Test Cases are required for a particular release. It serves a number of purposes, including traceability and compliance as well as forming part of the documentation required for audits and regulatory submissions
After creation of Test Cases:
Create Test Executions
This can be done by creating an independent Configuration Item, from individual Test Cases within Ketryx or Jira, or in bulk from the Ketryx Test Module
Configuration Item Type: Test Executions - see WI-05 Test Execution
Metadata
Traceability: Relate to applicable Test Cases. This traceability will be automatically created if the Test Execution is generated directly from a Test Case item or in bulk from the Ketryx Test Module
Why:
Test Executions provide objective evidence for verification and validation for a particular Release, which is required for FDA submissions and other purposes
6. Dependencies
Key resulting documents: SBoM - SOUP - Software Configuration Report
Document description: An SBoM - SOUP - Software Configuration Report identifies and details all software components including commercial, open-source, and Software of Unknown Provenance (SOUP), their dependencies, and configuration settings within the medical device
See MAN-03 Supply Chain Management: Software Dependencies for additional information.
Create:
Connect GitHub repository to Ketryx or submit dependencies via a supported format, such as SPDX or CycloneDX - see, e.g., MAN-03 and Working with CycloneDX
Metadata
Traceability: Relate to applicable Configuration Items, such as Software Item Specs; available metadata fields are described in MAN-03
Why:
Dependencies in Ketryx are used to manage and track all third-party and internal software components (including open-source and SOUP) that your system relies on
7. Vulnerabilities & Vulnerability Impact Assessments
Key resulting document: Vulnerability Report
Document description: Documents identification, assessment, and summary of known security vulnerabilities in device software, including their potential impact and mitigation status
Context:
Note that a Vulnerability is not a standard Ketryx Configuration Item type in the same way as Requirements, Risks, or Software Items, but it is managed as a first-class record within the Ketryx platform
It is highly recommended to enable the Enable Vulnerabilities as Configuration Items setting in your project's Advanced Settings. This ensures that vulnerability impact assessments are treated as full configuration items, requiring them to be controlled before a release, which is critical for regulated environments. See WI-12 Variants and Versions
Creation:
When a Ketryx Project contains dependencies, Ketryx automatically detects vulnerabilities and presents them on the Vulnerabilities page within the SBOM module - see Vulnerability Management
Alternatively, vulnerabilities from a scanning tool that you already use can be reported via SPDX or CycloneDX
Vulnerabilities are not available in the standard "Create item" dropdown on the All Items page, and cannot be edited in the same way as other configuration items (like Requirements or Risks)
Impact assessments should be created for each vulnerability that shows up on the vulnerability page
Metadata
Traceability: Relate to applicable Configuration Items, such as Risks and Risk Controls such as Software Item Specs; available metadata fields are described in MAN-03 - Vulnerability Management
Why
Each Vulnerability is linked to the affected dependencies and can be connected to Requirements, Software Item Specs, Risks, and Test Cases, enabling you to align cybersecurity risk management with your overall product development and compliance processes
8. Change Requests & CAPAs
Key resulting documents: Change Request Verification Report and Change Management File - note that these reports are not default Release Documents
Document description: A Change Management File systematically documents all changes to a medical device software throughout its lifecycle. A Change Request Verification Report confirms that implemented changes have been successfully verified and validated to meet their intended requirements
Create:
Configuration Item Type: Change Request/CAPA
Metadata:
Traceability: Relate to affected items, such as Anomalies and Software Item Specs - see WI-08 Change Request and WI-09 CAPA
Why:
Change Requests and CAPAs in Ketryx ensure that all changes and corrective actions are managed in a controlled, traceable, and compliant manner, supporting both product quality and regulatory requirements
9. Anomalies & Complaints
Key resulting document: Problem Report
Document description: Documents identified software issues or defects, detailing their impact, severity, and resolution, and is used to track the problem's lifecycle
Create:
Configuration Item Type: Anomaly - see WI-06 Anomaly
Metadata
Traceability: Relate to applicable items such as CAPAs, Change Requests, and other Items
Why:
The Problem Report in Ketryx is a document that provides a comprehensive overview of anomalies (problems, bugs, defects) associated with a particular software version
It typically includes both new unresolved anomalies and resolved anomalies relevant to the release
10. Documents as Items
You may choose to turn on "documents as items" in Ketryx to manage documents from your eDMS with the same Configuration Item system used for your other artifacts. This enables documents to leverage features like custom fields and customer relations, allowing for more granular control, traceability, and integration with your quality management workflows. For example, you can define long-lived or point-wise document types, add custom metadata, and create direct relationships between documents and other configuration items (such as requirements or change requests).
Key Release Documents that can contain references to Document Configuration Item Types: Release Notes, Traceability Matrix, System Requirements Specification / System Design Specification
Create:
Configuration Item Type: Documents - see WI-11 Document and Document Templating
11. Additional Ketryx default Release Documents
The Configuration Items described above also populate into a number of additional Ketryx default Release Documents. We describe these documents in this section and list key Configuration Item types that populate each.
Traceability Matrix
Document description: Regulatory standards, such as FDA requirements, ISO 13485, and IEC 62304, require clear evidence that requirements are fulfilled and verified. The Traceability Matrix provides this evidence in a structured, reviewable format - see MAN-07 Traceability
Release Notes
Document description: Summary of the changes, enhancements, and fixes introduced in a new version of device software, providing clear information for users and regulators about updates relevant to safety and effectiveness
Example: Ketryx's Release Notes
System Architecture Chart
Document description: Diagrammatic representation that illustrates the major software components, their relationships, and interactions within the device system to support understanding of the software’s structure and data flow - see MAN-01 Ketryx Life Cycle Management
Training Status Report
Document description: Overview of the training status and compliance of users within a project, showing which team members have completed required training on controlled documents
Context:
The Training Status Report primarily contains information about Users and their acknowledgement of having trained on training-related Documents
Note that Users are not a standard Ketryx Configuration Item type in the same way as Requirements, Risks, or Software Items, but it is managed as a first-class record within the Ketryx platform
Provides a summary of the training status of all project members, documenting which users have acknowledged and completed training on required documents to ensure compliance with organizational and regulatory requirements - see WI-11 Document
Conclusion
By following this guide, you've created the foundation for a complete DHF that meets FDA requirements.
Final Checklist
Moving Forward
For Production Release: Your non-production iterations have prepared you for a smooth production release. Continue using the same approach for final validation and release activities. Consider following semantic versioning (e.g., 1.0.0 for initial release, 1.1.0 for minor updates, 2.0.0 for major changes) to clearly communicate the scope of changes to regulators and users.
For Post-Market Surveillance: The configuration items and processes you've established will support ongoing maintenance, complaint handling, and future iterations. Continue to:
Log and assess all anomalies
Maintain vulnerability monitoring
Process changes thorugh formal change control
Update documentation with each release
Need Help?
If you encounter challenges or have questions about specific regulatory requirements:
Consult your QMS or quality management team
Review the applicable standards and guidance documents
Contact Ketryx support for platform-specific questions
Remember: A maintained Design History File is not just a regulatory requirement, it's your demonstration of systematic design controls and commitment to patient safety. The effort you invest in proper documentation today prevents costly remediation tomorrow.
Last updated
Was this helpful?