# Document Management

## Purpose

Document Management provides a central register for files associated with clients, matters, litigation cases, and responsible lawyers. It supports controlled versioning, document review and approval, finalization, reusable templates, matter-data merge fields, signature tracking, graphical signatures, retention controls, legal holds, and authorized access.

The module remains the authoritative location for document files and versions. Litigation, Evidence & Exhibits, Witness Management, Court Docket, communications, and other modules link to existing document records rather than storing separate copies.

## Permissions and Matter Access

| Activity | Required permission |
| --- | --- |
| View documents and their details | View Documents (`documents_read`) and access to the linked matter |
| Upload documents | Upload Documents (`documents_upload`) |
| Edit document metadata | Update Documents (`documents_update`) |
| Upload a new version | Create Document Versions (`documents_create_versions`) |
| Make an earlier version active | Roll Back Document Versions (`documents_version_rollback`) |
| Submit a document for review | Submit Documents for Review (`documents_submit_review`) |
| Review a submitted document | Review Documents (`documents_review`) |
| Finalize an approved document | Finalize Documents (`documents_finalize`) |
| Manage templates | Manage Document Templates (`documents_manage_templates`) |
| Create signature requests | Request Document Signatures (`documents_request_signatures`) |
| Cancel or administratively manage a signature request | Manage Signature Status (`documents_manage_signature_status`) |
| Draw, upload, save, or apply a graphical signature | Apply Document Signatures (`documents_apply_signatures`) |
| Manage retention dates and legal holds | Manage Document Retention (`documents_manage_retention`) |
| Grant direct document access | Share Documents (`documents_share`) |
| Delete an eligible document | Delete Documents (`documents_delete`) |

Document access continues to respect matter-level restrictions, confidentiality, direct access grants, and the signed-in user's role. Hiding an action in the interface is not the only control: the server applies the same authorization rules to direct requests.

## Open the Document Register

1. Open **Documents** from the main navigation.
2. Select **Documents** from the submenu.

The register displays:

- document title;
- linked matter and client;
- document category;
- workflow status;
- responsible lawyer;
- active version; and
- available actions.

Select the document title or the eye icon to open the dedicated document details page. The page retains the register actions for editing metadata, managing access, and deleting an eligible document, and also provides the applicable workflow actions.

## Search and Filter Documents

Use the controls above the register to search or filter by:

- title, client, matter reference, case number, or case title;
- document category;
- workflow status;
- client;
- matter;
- litigation case;
- responsible lawyer; and
- creation date range.

Use the pagination controls below the table to move between pages. Search results only include documents the signed-in user is authorized to view.

## Upload a Document

1. Select **Upload document**.
2. Enter the document title.
3. Enter the document type or category.
4. Select the existing matter.
5. Select the litigation case where applicable.
6. Select the responsible lawyer.
7. Choose the confidentiality classification.
8. Enter a description.
9. Indicate whether the document requires signatures.
10. Select the file and choose **Upload document**.

The initial upload creates version **v1** and gives the document the **Draft** status.

### Document Category and File Type

The document category describes the legal or operational purpose of the document, such as an agreement, affidavit, pleading, client letter, or memorandum. It is not the file's MIME type.

The actual file type is determined by the uploaded file. For example:

- category: **Agreement**; file type: PDF;
- category: **Correspondence**; file type: DOCX; or
- category: **Photograph**; file type: PNG.

Documents generated from rich-text templates are created as PDF files.

## Document Details

The document details page is organized into tabs. Its header shows the document status, matter reference, category, active version, and the actions permitted for the signed-in user.

| Tab | Information and actions |
| --- | --- |
| Overview | Matter, litigation case, responsible lawyer, active version, confidentiality, source template, dates, and description. |
| Versions | Complete version history, the person who caused each version, active and finalized indicators, file preview, version reactivation, and new-version upload. Signing-created versions appear here with every other version. |
| Approval | Current workflow status, reviewer, approver, and chronological approval decisions. |
| Signatures | Signature requests, intended signatories, and request statuses. Resulting files are managed in the single Versions history. |
| Retention | Retention date and legal-hold information. |

## Version Management

### Upload a New Version

1. Open the document details.
2. Select **Versions**.
3. Under **Upload a new version**, choose the replacement or revised file.
4. Complete the upload.

The system preserves all earlier files and marks the new version as active. It does not overwrite the prior version. The **Created by** column identifies the uploader, staff signer, or email-verified external signatory whose action produced that version.

A document awaiting review cannot receive another version until that review is completed. Uploading a successor version after finalization preserves the finalized version and starts a new draft approval cycle.

### View a Version

Select the eye icon beside a version. Previous versions remain available to authorized users even when they are no longer active.

### Make an Earlier Version Active

1. Open **Versions**.
2. Find the required earlier version.
3. Select the history icon.
4. Confirm the change.

The selected version becomes active, but newer versions remain in the history. If the selected version was produced by signing, finalization, or approval, its recorded workflow state is restored. Other historical versions become Draft when activated so they can follow the normal review process.

An active signature request must be completed or cancelled before another version can be made active. This prevents an outstanding one-use signing link from applying a signature to a document version that the legal team has replaced.

## Review, Approval, and Finalization

The controlled workflow is:

1. **Draft**.
2. **Pending Review**.
3. **Approved** or **Changes Requested**.
4. **Finalized** after approval.

### Submit for Review

1. Open a Draft or Changes Requested document.
2. Select **Submit for review** in the modal footer.
3. Select an authorized reviewer.
4. Add submission comments where useful.
5. Submit the document.

The reviewer receives the review request through the existing notification infrastructure.

### Review a Document

1. Open a document with **Pending Review** status.
2. Select **Review**.
3. Choose **Approve** or **Request changes**.
4. Enter comments. Comments are required when requesting changes.
5. Save the decision.

Every decision records the user, timestamp, active document version, previous status, new status, and comments.

### Finalize a Document

1. Open an approved document.
2. Select **Finalize**.
3. Confirm the action.

Only the approved active version can be finalized. Finalization records the responsible user and timestamp and protects the finalized version from ordinary metadata editing. Finalization is not the same as signing or court filing.

## Document Templates

Templates allow authorized users to compose reusable rich-text content and generate matter-aware PDF documents.

### Open Template Management

1. Open the Document register.
2. Select **Templates**.

The left side lists existing templates and supported merge fields. The right side contains the template form.

### Create a Template

1. Select **New template**.
2. Enter the template name.
3. Select a **Document category**.
4. Enter a description.
5. Compose the template in the rich-text editor.
6. Insert merge fields where matter information should appear.
7. Keep **Available for document generation** selected if users should be able to generate documents from it.
8. Select **Save template**.

### Available Template Categories

The preconfigured categories are:

- Agreement;
- Affidavit;
- Court application;
- Client letter;
- Contract;
- Correspondence;
- Court order;
- Legal opinion;
- Memorandum;
- Notice;
- Petition;
- Pleading;
- Policy;
- Report;
- Written submissions; and
- Other.

Existing templates that use an older custom category retain that category when edited.

### Rich-Text Formatting

The template editor supports:

- heading levels;
- bold, italic, underline, and strikethrough;
- numbered and bulleted lists;
- left, centre, right, and justified alignment;
- block quotations;
- links; and
- removal of formatting.

The generated PDF preserves supported formatting. Unsafe scripts, embedded frames, event handlers, and unsupported HTML attributes are removed when the template is saved. Remote images and arbitrary embedded content are not part of the template workflow.

### Insert a Merge Field

1. Position the cursor where the system value should appear.
2. Select a field from **Select a merge field**.
3. Select **Insert field**.

You may also type a supported field exactly as shown, including both pairs of braces. For example:

```text
{{client.name}}
```

Do not change the text inside the braces. `{{client.name}}` works, but `{{client full name}}` is unsupported.

### Supported Merge Fields

| Area | Merge field | Value inserted |
| --- | --- | --- |
| Client | `{{client.name}}` | Client name |
| Client | `{{client.email}}` | Client email address |
| Client | `{{client.phone}}` | Client telephone number |
| Matter | `{{matter.reference}}` | Matter reference |
| Matter | `{{matter.title}}` | Matter title or type |
| Matter | `{{matter.practice_area}}` | Practice area |
| Matter | `{{matter.statute_of_limitations_date}}` | Recorded limitation date |
| Lawyer | `{{assigned_lawyer.name}}` | Assigned matter lawyer |
| Lawyer | `{{assigned_lawyer.email}}` | Assigned lawyer's email |
| Firm | `{{firm.name}}` | Configured firm name |
| Firm | `{{firm.email}}` | Configured firm email |
| Firm | `{{firm.phone}}` | Configured firm telephone number |
| Litigation | `{{litigation.case_number}}` | Court case number |
| Litigation | `{{litigation.case_title}}` | Court case title |
| Litigation | `{{litigation.court}}` | Court or tribunal |
| Litigation | `{{litigation.filing_date}}` | Recorded filing date |
| Generation | `{{generated.date}}` | Date the document is generated |
| Generation | `{{generated.datetime}}` | Date and time the document is generated |

### Generate a Document from a Template

1. Open the Document register.
2. Select **Generate**.
3. Select an active template.
4. Select the matter.
5. Enter the document title.
6. Select the responsible lawyer or use the matter's lead lawyer.
7. Choose the confidentiality classification.
8. Enter a description where needed.
9. Select **Generate document**.

The system resolves the merge fields using information from the selected matter and its authorized related records. It then creates a PDF document under that matter, links it to its source template, and registers it as version **v1** with **Draft** status.

If required values are missing, generation is blocked and the missing fields are listed. Select **Generate even when optional system values are missing** only when blank values are acceptable.

## Template Content Examples

The following examples are starting points. Apply formatting with the editor toolbar rather than typing HTML.

### Example 1: Client Matter Opening Letter

Recommended category: **Client letter**

Formatting suggestions:

- centre and bold the firm name;
- use Heading 2 for the subject;
- bold the matter reference; and
- use a bulleted list for contact details.

```text
{{firm.name}}
{{firm.email}} | {{firm.phone}}

{{generated.date}}

Dear {{client.name}},

RE: {{matter.title}} — {{matter.reference}}

We confirm that our firm has opened the above matter on your behalf. The matter is recorded under reference {{matter.reference}} and falls within our {{matter.practice_area}} practice area.

Your assigned lawyer is {{assigned_lawyer.name}}. You may contact the lawyer at {{assigned_lawyer.email}}.

Please quote the matter reference in all future correspondence.

Yours faithfully,

{{assigned_lawyer.name}}
For {{firm.name}}
```

### Example 2: Internal Legal Memorandum

Recommended category: **Memorandum** or **Legal opinion**

Formatting suggestions:

- use Heading 1 for “Legal Memorandum”;
- format the metadata as separate bold labels; and
- use numbered headings for the issue, facts, analysis, and recommendation.

```text
LEGAL MEMORANDUM

Matter: {{matter.title}}
Matter reference: {{matter.reference}}
Client: {{client.name}}
Practice area: {{matter.practice_area}}
Prepared by: {{assigned_lawyer.name}}
Date: {{generated.date}}

1. Issue

[State the legal issue to be considered.]

2. Relevant Facts

[Summarize the material facts and identify any facts that still require confirmation.]

3. Analysis

[Set out the applicable law and analysis.]

4. Recommendation

[State the recommended action and any immediate deadlines.]
```

### Example 3: Litigation Filing Cover Page

Recommended category: **Pleading**, **Petition**, **Court application**, or **Written submissions**

Formatting suggestions:

- centre the court, case number, and case title;
- use Heading 1 for the document name; and
- use a horizontal visual break created with spacing rather than unsupported embedded elements.

```text
IN THE {{litigation.court}}

CASE NO. {{litigation.case_number}}

{{litigation.case_title}}

WRITTEN SUBMISSIONS

Matter reference: {{matter.reference}}
Filing date: {{litigation.filing_date}}

1. Introduction

[Insert the introductory submissions.]

2. Background

[Insert the relevant procedural and factual background.]

3. Submissions

[Insert the substantive submissions in numbered paragraphs.]

DATED {{generated.date}}

Prepared by {{assigned_lawyer.name}}
{{firm.name}}
```

If the matter is not linked to a litigation case, litigation merge fields will be missing and generation may be blocked.

### Example 4: Client Litigation Status Update

Recommended category: **Correspondence** or **Report**

```text
Dear {{client.name}},

RE: STATUS UPDATE — {{litigation.case_title}}
Case number: {{litigation.case_number}}
Court: {{litigation.court}}
Our reference: {{matter.reference}}

We provide the following update on your matter as at {{generated.date}}.

Current position

[Summarize the current litigation stage and the most recent material development.]

Next actions

• [First action]
• [Second action]
• [Third action]

Information required from you

[List any documents, instructions, or confirmations required from the client.]

Please contact {{assigned_lawyer.name}} at {{assigned_lawyer.email}} if you require clarification.

Yours faithfully,

{{firm.name}}
```

Use the editor's bullet-list control for the **Next actions** list instead of manually typing bullet characters.

### Example 5: Basic Agreement Introduction

Recommended category: **Agreement** or **Contract**

```text
AGREEMENT

Matter reference: {{matter.reference}}

This Agreement is prepared on {{generated.date}} in connection with {{matter.title}}.

BETWEEN

{{client.name}}, whose recorded contact details are {{client.email}} and {{client.phone}}, referred to in this Agreement as “the Client”;

AND

[Insert the other party's complete legal name and details], referred to in this Agreement as “the Other Party”.

1. Background

[Insert the relevant background.]

2. Terms

2.1 [Insert the first term.]

2.2 [Insert the second term.]

3. Execution

[Insert the execution and signature provisions appropriate to the jurisdiction and transaction.]
```

Template examples are drafting aids only. Review all generated content for legal accuracy, jurisdiction-specific requirements, names, dates, numbering, and execution formalities before approval or finalization.

## Graphical Signatures

An authorized user can place a graphical signature on an approved PDF. Signing creates a new document version but does not introduce or change the document lifecycle status.

1. Open the document details.
2. Select **Sign document**.
3. Choose one of the following methods:
   - **Saved**: select one of your previously stored signatures;
   - **Drawn**: draw with a mouse, stylus, or finger; or
   - **Uploaded**: select a PNG signature file.
4. For a drawn or uploaded signature, select **Save this signature for future documents** if required and enter a recognizable name.
5. Select the PDF page.
6. Select the placement: bottom left, bottom centre, or bottom right.
7. Select the signature size.
8. Link an open signature request where applicable.
9. Select **Apply signature**.

The system stores the signed PDF as the next active version of the same document. The previously active file remains unchanged in version history. The signature record identifies the signer, timestamp, placement, signature method, source version, resulting signed version, and preserved signature snapshot.

Uploaded signatures must be PNG files between 20×10 and 2000×1000 pixels and cannot exceed 2 MB. An image of approximately 900×300 pixels with a transparent background is recommended for a clear result.

Saved signatures are private to their owner. Deleting a saved signature does not remove it from signed documents that already contain it.

A staff-applied graphical signature is distinct from the email-verified signature-request process described below. The organization remains responsible for determining whether either signing method satisfies its legal, evidential, and regulatory requirements.

## Electronic Signature Requests

Use **Send signature request** to invite an external signatory to review and sign a PDF without creating a system account.

1. Open an approved document. Finalized documents cannot receive new signature requests.
2. Select **Send signature request**.
3. Enter the signatory's name, email address, and role.
4. Add an optional message for the signatory.
5. Send the request.

The system emails a unique, expiring signing link to the signatory. The invitation link must not be forwarded because it identifies the request and intended recipient.

### Sign a Document from the Email Invitation

The signatory does not need to log in.

1. Open the signing link in the invitation email.
2. Select **Send verification code**.
3. Retrieve the one-time password (OTP) sent to the same email address.
4. Enter the six-digit code to unlock the document.
5. Review the document preview and request details.
6. Choose a signature method:
   - **Saved**: select a signature previously saved for the same verified email address;
   - **Draw**: create a signature with a mouse, stylus, or finger; or
   - **Upload**: upload a valid PNG signature image.
7. Optionally save a drawn or uploaded signature for later requests sent to the same email address.
8. Select the PDF page and configure the signature position and size.
9. Confirm the electronic-signing consent statement.
10. Select **Sign document**.

Submission does not immediately create a document version. The system applies the signature to a temporary pending PDF at the page, position, and size selected by the signatory. Where several signatories are requested, their signatures accumulate on that pending PDF.

When all signatories have submitted, the request changes to **Awaiting Confirmation**. The system sends the original requester both an in-app notification and an email containing a link to the document review page.

### Requester Confirmation or Rejection

The requester must review the fully stamped pending PDF before it becomes part of document version history.

1. Open the email notification or the document details page.
2. Select **Signatures**.
3. Find the request marked **Awaiting Confirmation**.
4. Select **Preview submission** and verify every signature and its placement.
5. Choose one of the following actions:
   - **Confirm and approve**: creates the next active version of the same document using the pending PDF with all signatures appended. The confirmation is recorded as the approval for that new version and the document remains Approved.
   - **Reject**: records the required rejection reason and creates no document version.

There is no Approval Carried Forward action. The requester's confirmation is the approval decision for the newly created version. Until confirmation, the current active document version remains unchanged.

The signature record captures each signatory's name and email, signature method, placement, timestamp, and the resulting version after confirmation.

The invitation becomes unusable immediately after a successful signature. It also stops working when its configured expiry time is reached or when the request is cancelled. A signing session is temporary and is valid only after successful OTP verification.

### Saved External Signatures

External signatures are stored against the normalized, verified email address rather than a HealthInspector/Law Firm Management System user account. A saved signature is offered only after a future request for that same email address has passed OTP verification.

Saved signatures are convenience images, not authentication credentials. OTP verification is still required for every signing invitation. Removing or replacing a saved signature does not alter confirmed document versions that already contain a preserved signature snapshot.

The internal signing workflow records consent and verification activity but does not claim third-party certification or guarantee legal validity in every jurisdiction. Apply the organization's approved signing policy and legal requirements.

## Retention and Legal Holds

Retention controls how long a document and its versions must be preserved before ordinary deletion is permitted.

- A future **retention date** prevents ordinary deletion until that date has passed.
- A **legal hold** prevents ordinary deletion regardless of the retention date. It is commonly used when a document must be preserved for litigation, an investigation, or another legal obligation.
- The **legal-hold reason** explains why the hold was applied.
- Changes to retention controls and legal holds are recorded in the audit history with the responsible user and timestamp.

Retention does not archive, hide, finalize, or automatically delete a document. It does not change document access permissions or workflow status. The document and all its versions remain available to authorized users. Passing the retention date only removes that particular time-based deletion restriction; it does not delete the document automatically.

### Set Retention Controls

1. Open the document details.
2. Select **Retention**.
3. Enter the retention date where applicable.
4. Select **Place this document on legal hold** where required.
5. Enter the legal-hold reason.
6. Save the changes.

A document under legal hold cannot be deleted through ordinary deletion. A future retention date also prevents ordinary deletion before that date. Finalization and signing do not bypass these controls. Removing a legal hold or reaching the retention date does not guarantee deletion is allowed because matter status, permissions, or other protections may still prevent it.

## Direct Access Grants

The users icon in the document register opens direct access management.

1. Select the users icon for the document.
2. Review existing direct grants.
3. Select an eligible matter participant.
4. Choose **View** or **Edit**.
5. Select **Grant access**.

Use the revoke icon to remove a direct grant. Revoking a direct grant does not remove access the user still receives through another valid role, matter assignment, or permission.

## Important Distinctions

| Concept | Meaning |
| --- | --- |
| Document category | The legal or operational classification, such as Agreement or Pleading. |
| MIME type | The technical file format, such as `application/pdf` or `image/png`. |
| Approved | A reviewer approved the active version. |
| Finalized | The approved version was locked as the controlled final version. |
| Signature application | An action that produces the next ordinary document version with the signature applied; it does not create a separate document or a separate versioning system. |
| Signature request | A secure email invitation for an intended signatory to verify their email with an OTP and sign a PDF. |
| Signing link | A unique, expiring, one-use URL sent to the intended signatory. |
| Saved external signature | A reusable signature image associated with a verified email address. |
| Court filed | A separate Court E-Filing outcome; approval, finalization, or signing does not mean filed. |

## Troubleshooting

| Issue | Resolution |
| --- | --- |
| Templates or template actions are not visible | Confirm the user has `documents_manage_templates`. |
| A merge field is rejected | Select it from the merge-field dropdown and ensure its spelling and braces have not been changed. |
| Generation reports missing values | Complete the source client, matter, lawyer, firm, or litigation information, or allow optional values to remain blank where appropriate. |
| Generated formatting is different from the editor | Use supported toolbar formatting. Unsupported HTML, scripts, embedded objects, and unsafe attributes are removed. |
| A generated document is not editable as text | Template generation creates a PDF. Revise the template and generate a new document, or upload a new version through the normal version workflow. |
| A new version cannot be uploaded | Confirm the document is not Pending Review and that the user has permission to create document versions. |
| Finalize is unavailable | Confirm the active version has been approved and the user has finalization permission. |
| Sign document is unavailable | Confirm the active file is a PDF, the workflow status is Approved or Finalized, and the user has `documents_apply_signatures`. Signing does not create a separate Signed document status. |
| A PNG signature is rejected | Confirm it is a valid PNG, is within the dimension limits, and is no larger than 2 MB. |
| The signing link is expired or unavailable | Ask the document owner to create a new signature request. A completed, cancelled, or expired link cannot be reused. |
| The OTP does not arrive | Confirm the invitation email address, check spam or junk mail, wait briefly, and use the resend option. Repeated requests are rate limited. |
| The OTP is rejected | Use the latest code sent to the invitation email. Codes expire and have a limited number of attempts. |
| A saved signature is missing | Confirm the current invitation was sent to the same email address and that OTP verification succeeded. |
| A document cannot be deleted | Check for a legal hold, future retention date, active matter restriction, finalized protection, or a legacy document lock. |

## Recommended Template Practices

1. Use a clear name that identifies the document's purpose.
2. Choose the correct document category; do not use a MIME type as the category.
3. Insert merge fields from the dropdown rather than retyping them.
4. Keep jurisdiction-specific legal language under review by authorized lawyers.
5. Use headings and lists consistently so generated PDFs remain readable.
6. Avoid adding confidential information directly to a general-purpose template.
7. Generate a test document before making a new template widely available.
8. Review every generated document before submitting it for approval.
9. Use versioning for revisions instead of overwriting files.
10. Finalize, sign, and file documents as separate controlled actions.