> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Approval Workflow Guide

> Encore Health OS's document approval system enables multi-step review and approval processes for sensitive documents. Configure approval chains with specific a…

## Overview

Encore Health OS's document approval system enables multi-step review and approval processes for sensitive documents. Configure approval chains with specific approvers or roles, track approval progress, and receive notifications at each stage.

## Features

### Approval Chain Configuration

* Define sequential approval steps (up to 10 approvers)
* Assign specific users or roles as approvers
* Mark steps as required or optional
* Set due dates for each approval step

### Status Tracking

* Real-time approval progress visualization
* Pending, approved, rejected, and skipped statuses
* Approval history with timestamps and decision notes
* Dashboard widget for pending approvals

### Notification Integration

* Automatic notifications to next approver
* Reminders for overdue approvals
* Status change notifications to document owner
* Escalation notifications for critical documents

## Setting Up Document Approval

### Creating an Approval Chain

1. Open a document in edit mode
2. Navigate to **Approval Workflow** tab
3. Click **Add Approval Step**
4. Configure each step:
   * **Order**: Sequential position (1, 2, 3...)
   * **Approver**: Select user or role
   * **Required**: Mark if approval is mandatory
   * **Due Date**: Optional deadline for decision

**Example Approval Chain:**

```
Step 1: Department Head (Required, 3 days)
Step 2: Finance Director (Required, 5 days)
Step 3: CEO (Optional, 7 days)
```

### Initiating Approval

Once the approval chain is configured:

1. Click **Submit for Approval**
2. Document status changes to `pending_approval`
3. First approver receives notification
4. Document becomes read-only for submitter

## Approval Process

### For Approvers

#### Receiving Approval Request

Approvers are notified via:

* In-app notification (bell icon)
* Email (if enabled in preferences)
* Dashboard widget: "Pending Approvals"

#### Making a Decision

1. Open the document from notification or dashboard
2. Review document content and attachments
3. Click **Approve** or **Reject**
4. Add decision note (optional but recommended)
5. Submit decision

**Approve:**

* Document moves to next approval step
* Next approver is notified
* Status remains `pending_approval`

**Reject:**

* Document status changes to `rejected`
* Approval chain stops
* Document owner is notified with rejection note
* Owner can revise and resubmit

### For Document Owners

#### Tracking Approval Status

View approval progress on document detail page:

* ✅ Approved steps (green checkmark)
* ⏳ Current step (yellow pending)
* ⚪ Pending steps (gray)
* ❌ Rejected (red X)

#### After Rejection

If document is rejected:

1. Review rejection note
2. Make necessary revisions
3. Click **Resubmit for Approval**
4. Approval chain restarts from Step 1

#### After Final Approval

When all required steps are approved:

* Document status changes to `approved`
* Document owner receives notification
* Document can be marked as final/published

## Approval Chain Templates

### Common Templates

**Standard Document Review:**

```
1. Author's Manager (Required)
2. Department Head (Required)
3. Compliance Officer (Optional)
```

**Financial Document:**

```
1. Requestor's Manager (Required)
2. Controller (Required)
3. CFO (Required if amount > $10,000)
```

**Policy Document:**

```
1. Policy Committee (Required)
2. Legal Review (Required)
3. Executive Director (Required)
4. Board of Directors (Required if major policy)
```

### Creating Reusable Templates

Org admins can create approval templates:

1. Go to **Settings** → **Documents**
2. Click **Approval Templates**
3. Create new template with steps
4. Users can apply template to documents

## Due Dates and Reminders

### Setting Due Dates

For each approval step:

* Set days after submission (e.g., "3 days")
* Or set specific calendar date

### Automatic Reminders

System sends reminders:

* **1 day before** due date
* **On** due date
* **1 day after** due date (overdue)

### Escalation (Optional)

Configure escalation rules:

* If no decision after X days → notify approver's manager
* If critical document → send daily reminders

## Dashboard Widget

### Pending Approvals Widget

Shows approvers:

* Documents awaiting their approval
* Due dates (color-coded by urgency)
* Quick approve/reject actions
* Overdue count

**Widget Location:** Main dashboard (visible to all users with pending approvals)

### My Documents Widget

Shows document owners:

* Documents in approval process
* Current approval step
* Days in approval
* Approval progress percentage

## Permissions

### Who Can Configure Approval Chains

* Document owner
* Org admins
* Users with "Manage Documents" permission

### Who Can Approve

* Users explicitly assigned in approval chain
* Users with roles matching approval step role
* Org admins (override capability)

### Approval Override

Org admins can:

* Skip approval steps
* Fast-track documents
* Override rejections
* Modify approval chains on active approvals

## Best Practices

1. **Keep Chains Short**: 3-5 steps maximum for efficiency
2. **Use Roles When Possible**: Avoid dependency on specific users
3. **Set Realistic Due Dates**: Allow adequate review time
4. **Add Decision Notes**: Document reasoning for future reference
5. **Monitor Overdue Approvals**: Review dashboard weekly
6. **Template Common Workflows**: Reduce configuration time

## Reporting

### Approval Metrics

Track approval performance:

* Average approval time by step
* Rejection rate by approver
* Documents stuck in approval
* Compliance with due dates

**Access:** Settings → Documents → Approval Analytics

### Audit Trail

View complete approval history:

* All decision timestamps
* Approver names
* Decision notes
* Status changes

**Access:** Document detail page → Approval History tab

## Troubleshooting

### Approver Not Receiving Notifications

**Check:**

1. Approver has valid email address
2. Notification preferences enabled for "document\_approval"
3. User is active (not disabled)
4. Email not in spam folder

### Cannot Submit for Approval

**Possible Reasons:**

* No approval chain configured
* Missing required fields in document
* Document already in approval
* User lacks permission

### Approval Stuck

**Resolution:**

1. Identify current approver (dashboard)
2. Send manual reminder email
3. Escalate to approver's manager
4. Admin override if urgent

### Wrong Approver Assigned

**Resolution:**

1. Org admin can modify approval chain
2. Skip incorrect step
3. Add correct approver
4. Document in history why changed

## Security

### Access Control

* Approvers can only see documents in their queue
* Document content respects existing permissions
* Approval notes are visible to all approvers and owner
* Audit trail visible to org admins only

### PHI/PII Handling

* Approval notes should NOT contain PHI
* Documents remain encrypted at rest
* Email notifications don't include document content
* SMS notifications not used for approvals (security)

## Advanced Features

### Conditional Approvals

Configure approval routing based on:

* Document category
* Dollar amount
* Site/department
* Custom field values

**Example:** If budget > \$50,000, require CFO approval

### Parallel Approvals

Set multiple approvers for same step:

* All must approve (AND logic)
* Any can approve (OR logic)

**Example:** Any member of Finance Committee can approve Step 2

### Approval Delegation

Approvers can delegate to others:

1. Open pending approval
2. Click **Delegate**
3. Select substitute approver
4. Add reason for delegation

## Integration

### Notification System

* Approval requests → notification created
* Decision made → notification sent to owner
* Overdue → reminder notification

### Audit Logging

* All approval actions logged
* WHO approved/rejected
* WHEN decision made
* WHAT note was added

### Workflow Automation

* Trigger actions after final approval
* Auto-publish to specific sites
* Move document to "Published" folder
* Create follow-up tasks

## Related Documentation

* [Document Management](./document-management-guide.md)
* [Notifications System](./notifications-guide.md)
* [Advanced Document Features](./advanced-documents-guide.md)
* [Audit Logging](../architecture/integrations/EVENT_CONTRACTS.md) - See audit event contracts

***

**Version:** 1.0.0\
**Last Updated:** 2025-11-29