Design a document retention workflow with Paperless-ngx
Design Paperless-ngx document intake, permissions and retention review with an editable policy worksheet, deletion checks and restore-aware safeguards.
Last updated
In short
- Retention periods come from the organization’s approved policy.
- Tags classify documents; object permissions control access.
- Deletion must consider trash, exports, backups and restored copies.
On this page (7)
Business workflows · Part of Paperless-ngx
Editable policy fields and synthetic cases; no legal retention periods are supplied.
Download the document lifecycle worksheetTurn retention policy into a reviewable lifecycle
Paperless-ngx can ingest documents, extract searchable text and attach metadata. A retention workflow adds organizational decisions: why a document is kept, who may access it, what starts its retention period and who authorizes disposal. The software does not choose those legal or business requirements for you.
This is a reference lifecycle and synthetic acceptance exercise. It is not a compliance certification or a tested automated deletion service. The source documentation reviewed here is pinned to Paperless-ngx v3.5.0; verify the corresponding capabilities and upgrade notes for the release you actually deploy.
Define the metadata contract
| Field | Purpose | Example value type |
|---|---|---|
| Document class | Select approved retention rule | Contract, invoice or general correspondence |
| Policy identifier | Link to authoritative internal policy | Controlled policy code and revision |
| Retention trigger | Identify the event that starts the period | Contract closure or another approved event |
| Trigger date | Date confirmed by the record owner | Explicit date, not guessed from OCR |
| Review date | Next authorized review | Calculated under the approved rule |
| Hold state | Prevent disposal while an exception applies | Active hold plus owner and reason |
| Record owner | Person or team accountable for the document | Controlled user/group reference |
| Disposal decision | Evidence of approved action | Reviewer, time and decision record |
Do not invent a universal retention period for invoices or employee documents. The organization must provide the applicable policy and jurisdiction-specific requirements. A missing policy or trigger date should route the document to review rather than select an arbitrary deletion date.
Separate classification from authorization
The Paperless-ngx usage documentation describes document types, tags, custom fields and global/object permissions. Use metadata to organize the lifecycle, and permissions to decide who can view or change a document. A tag named “confidential” is not evidence that access is restricted.
| Role | Intended capability | Negative check |
|---|---|---|
| Intake operator | Submit and classify incoming documents | Cannot browse unrelated restricted records |
| Record owner | Review assigned documents and policy metadata | Cannot change another team’s permissions |
| Retention reviewer | Approve eligible disposal under policy | Cannot bypass an active hold without authority |
| Administrator | Operate the platform | Privileged access is controlled and recorded |
| Ordinary reader | Read approved documents | Cannot discover restricted OCR text or downloads |
Test direct document links, search snippets, thumbnails, original downloads and API access. Extracted OCR text can contain the same sensitive information as the original scan and belongs inside the same access boundary.
Design intake with an exception queue
Ingest a document through the approved upload, mail or consumption path. Assign initial ownership and restricted default permissions, then classify it. Automated matching can suggest a correspondent or document type, but uncertain classifications should remain visible for human review.
A synthetic test set can include a clear invoice, an unreadable scan, a duplicate document, a contract with no closure date and a document under hold. Use fictional names and harmless content. Record the original-file digest, extracted text quality and classification outcome.
Do not assume OCR reliably determines the policy trigger. A date printed in a document might be an issue date, due date or signature date. The record owner must confirm which event the policy uses before a retention review is scheduled.
Make disposal a two-stage decision
First identify candidates whose approved review date has arrived and whose hold state permits review. Then have an authorized reviewer approve disposal or extend the record’s lifecycle with a reason. Keep the decision record separate from the content being removed where the policy requires evidence to survive.
The exact implementation can combine application filters, metadata and an external controlled process. Verify supported workflow actions before automating deletion; this reference does not claim that a policy-complete retention engine is built into every Paperless-ngx release.
| Disposal check | Required evidence |
|---|---|
| Correct candidate | Policy, trigger date and document identity match |
| Hold evaluated | No active approved hold blocks disposal |
| Reviewer authorized | Decision tied to named role and time |
| Active access removed | Search, direct URL and API no longer expose content |
| Trash behavior understood | Recovery period and final removal documented |
| Derived copies considered | Exports, mail copies and downstream systems identified |
| Backup treatment | Retention and restore reconciliation defined |
Test recovery without resurrecting disposed records
The administration documentation describes exporter/importer and volume/database backup approaches. It warns about version compatibility for exports and notes that API tokens are not included in the document export. Plan to restore with the matching release and recreate credentials through the approved process.
Keep a disposal ledger or equivalent record that can be applied after restoring an older backup. Otherwise, recovery can make a previously disposed document active again. Restore into an isolated environment, reconcile post-backup disposal and permission changes, then run the negative-access checks before enabling users.
A backup may retain historical content for its own approved period. Document that behavior honestly; deleting an active document is not a claim that every historical copy immediately disappears.
Introduce the process gradually
Start with one low-risk document class and a named record owner. Run candidate selection and review without automatic final deletion until the synthetic and representative cases have been accepted. Pin the application release, OCR dependencies and any external automation versions, and review licences for the actual components used.
For rollback, stop new disposal automation and preserve the decision ledger. Restore documents only through the approved recovery process and only when the policy permits it; indiscriminate restoration can undo legitimate disposal decisions. Acceptance means intake, classification, access, review, deletion and recovery behave as the organization’s documented policy requires.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
