Required Role: Workspace Manager (to configure reason definitions)
Applies to: All users who perform tracked document actions
Reason Definitions let you control what users must record when they take key actions in Kivo: approving or rejecting a document, accepting or rejecting a review, excluding a placeholder, deleting a document, and more. This article explains why you'd configure them, how to set them up, and how the Allow Other option works.
Why configure reason definitions?
In regulated environments, the why behind a decision is often as important as the decision itself. Auditors and inspectors reviewing a document trail need to understand not just that a reviewer accepted a document, but why — was it a scheduled periodic review, a correction, a regulatory submission deadline? Without structured reasons, users either skip the field or write inconsistent free-text that is difficult to trend or report on later.
Configuring reason definitions lets you:
Standardize the language used across your team for each action type
Make trending and root cause analysis easier by keeping reasons consistent
Reduce the cognitive load on users, they select from a list rather than composing free text
Support compliance with 21 CFR Part 11, EU Annex 11, and ISO 13485, which require traceability of document decisions and the rationale behind them
If no reasons are configured for an action, Kivo still captures the action itself in the audit trail — but no reason prompt is shown. Adding even a short list of predefined reasons, or enabling Allow Other, immediately adds a reason field to that action for all users.
Where reason definitions apply
Reason definitions are configured per action type. The following action types are available:
Reason type | When it appears |
Deletion | When a user deletes a document. Also has its own toggle to make deletion reasons required (see below). |
Approval | When an approver approves a document version. |
Approval Rejection | When an approver rejects a document version. |
Approval on Upload | When a document is approved directly on upload (workflow bypass). |
Review Acceptance | When a reviewer accepts a document during a review step. |
Review Rejection | When a reviewer rejects a document during a review step. |
Periodic Review Acceptance | When a reviewer accepts a document during a periodic review. |
Periodic Review Rejection | When a reviewer rejects a document during a periodic review. |
Periodic Review Extensions | When a reviewer accepts a periodic review on a document whose Review By date has already passed. Kivo prompts for an additional reason explaining why the expired review is being extended and accepted. |
Exclusion | When a user excludes a placeholder document from a folder or cabinet. |
Metadata Change on Approved Document | When a Workspace Manager edits metadata on an already-approved document (requires the Change Approved Metadata feature). |
Training Course Progress | When a user marks a training course document complete or moves through course progress steps. |
Retire Version | When a Workspace Manager retires a document version (requires Version Labels feature). |
Document Control Number Change | When a Workspace Manager updates a document's control number via Document Controls (requires Document Controls feature). |
Version Label Change | When a Workspace Manager updates an effective date, review-by date, or periodic review date via Document Controls (requires Document Controls feature). |
Note: Some reason types are only available on workspaces with specific features enabled (Document Controls, Version Labels, Change Approved Metadata). You will only see the action types relevant to your workspace configuration.
How to configure reason definitions
Go to Workspace Settings and select Reason Definitions from the left navigation.
Use the Reasons Type dropdown to select the action you want to configure.
The current reasons list for that action appears below the dropdown. If no reasons have been defined, the list is empty.
Click Add Reason to enter a new predefined reason and save it.
Repeat for each reason you want to add. You can edit or delete any reason at any time.
To allow users to type a custom reason instead of choosing from the list, enable Allow "Other" reasons (see below).
Changes take effect immediately for all users. There is no publish step.
The "Allow Other reasons" option
Each reason type has an Allow "Other" reasons checkbox at the bottom of the list. This controls whether users can type a custom free-text reason in addition to, or instead of, selecting from the predefined list.
Here is how the combination of predefined reasons and the Allow Other toggle affects what users see:
Predefined reasons | Allow Other | What the user sees |
None | Off | No reason prompt. The action proceeds without capturing a reason. |
None | On | A free-text field only. The user must type a reason before proceeding. |
One or more | Off | A dropdown with your predefined reasons only. Users must select one. |
One or more | On | A dropdown with your predefined reasons plus an "Other" option at the bottom. Selecting "Other" reveals a free-text field. Users must either select a predefined reason or complete the free-text field before proceeding. |
Tip: "Allow Other only" (no predefined list, Allow Other enabled) is a good starting point if you want to capture reasons immediately but haven't yet decided on your standard vocabulary. You can add predefined reasons later without losing any previously recorded free-text entries.
The Deletion reason type
Deletion reasons work the same way as other reason types, but have one additional setting: Require Reason for Deletion. This toggle appears at the top of the Deletion reasons list.
When the toggle is off, the deletion reason field follows the same logic as other action types: it only appears if you have predefined reasons or Allow Other enabled.
When the toggle is on, users cannot delete a document without providing a reason. This is enforced even if no predefined reasons are configured, the free-text field becomes mandatory.
Enable this toggle if your quality system requires documented justification for every document deletion.
How reasons appear in the audit trail
Every reason a user provides is recorded in the document's audit trail alongside the action, the user's name, and a timestamp. This makes reasons fully traceable and exportable for inspection or CAPA activities.
If a user selects "Other" and types a custom reason, the free-text entry is recorded exactly as typed. There is no distinction in the audit trail between a predefined reason and a custom one — both are stored as the reason text.
Configuration tips
Start with your most-used actions. Approval and Review Acceptance/Rejection reasons tend to have the highest audit trail value. Start there before configuring less frequent action types.
Keep predefined reasons short and scannable. Reasons are selected from a dropdown, so long sentences create friction. Aim for five to ten words per reason.
Align reasons with your SOP language. Use the same terminology your team uses in deviation reports, CAPA records, and quality manual language so reasons remain meaningful in context.
Enable Allow Other for edge cases. Even with a complete predefined list, unusual situations arise. Enabling Allow Other gives users an escape hatch without removing the structure your predefined list provides.
Review your lists periodically. As your quality system matures, retire reasons that are no longer used and add new ones that reflect current practice. Editing or deleting a reason only affects future entries — existing audit trail records are not changed.