Document Management

Secure, S3-backed file storage for employee compliance documents - with HR-controlled verification workflows, visibility controls, and strict tenant isolation.

How it works at a glance

HR creates document types → Employee uploads file (goes direct to S3) → HR verifies → Employee can download; HR can view HR-only docs

---

Prerequisites

From Core HR:

• ✅ Active employees - documents are always linked to a specific employee
• ✅ S3 storage configured - backend environment must have S3 bucket credentials set up (ask your system administrator)

---

👤 Role-Based Access

Action	SUPER_ADMIN	HR_ADMIN	EMPLOYEE
Create / edit document types	✅	✅	❌
Delete document types	✅	❌	❌
Upload documents (for any employee)	✅	✅	Own only
View HR_ONLY documents	✅	✅	❌
View EMPLOYEE_VISIBLE documents	✅	✅	✅ (own)
Verify documents	✅	✅	❌
Reject documents	✅	✅	❌
Download documents	✅	✅	✅ (own, if EMPLOYEE_VISIBLE)
Delete documents	✅	✅	❌

---

Admin Workflow

Step 1 - Configure Document Types

Document types define what kinds of files can be uploaded and whether HR approval is required.

Navigate to: Settings → Organization → Document Types → Add Document Type

Field	Description	Example
Name	Document category name	Passport
Description	Guidance for employees	Colour copy of government-issued passport
Requires Verification	If true, uploaded docs stay PENDING until HR approves	✅
Employee Can Edit	If true, employees can replace/update their upload	false (for official contracts)

Common document types to configure:

Document	Requires Verification	Employee Can Edit
Aadhaar Card	✅	❌
PAN Card	✅	❌
Passport	✅	❌
Signed Employment Contract	✅	❌
Educational Certificate	✅	❌
Bank Account Details	✅	✅
Address Proof	✅	✅

---

Step 2 - Review & Verify Documents

When employees upload documents that require verification, they appear in the HR queue.

Navigate to: HR Portal → Pending Verifications

For each document:

• Check the document number and expiry date
• Preview the file
• Click Verify (with optional notes) → status moves to VERIFIED
• Click Reject (with a reason) → status moves to REJECTED and the employee is notified to re-upload

---

Employee Workflow

Step 1 - Upload a Document

Navigate to: My Profile → Documents Tab → Upload Document

The upload uses a direct-to-S3 flow for efficiency:

1. You click Upload → the system generates a secure S3 upload URL
2. Your file is sent directly to S3 storage (not through the backend server)
3. The backend registers the file metadata (name, size, type, expiry)

Fill in the upload form:

Field	Description	Example
Document Type	Select from available types	Passport
File	PDF, JPG, or PNG only	passport_scan.pdf
Document Number	Passport/ID number	A1234567
Expiry Date	When the document expires	2031-05-15
Visibility	EMPLOYEE_VISIBLE or HR_ONLY	EMPLOYEE_VISIBLE

File constraints:

• ✅ Accepted formats: PDF, JPG, PNG
• ✅ Maximum file size: 10 MB
• ❌ Word documents, Excel files, and other formats are rejected

Caution

If the document type has requiresVerification: true, your uploaded file will show as PENDING until an HR admin reviews and approves it. This is expected behaviour.

---

Step 2 - Check Document Status

Navigate to: My Profile → Documents Tab

Status	Meaning
PENDING	Uploaded; waiting for HR verification
VERIFIED	Approved by HR
REJECTED	Rejected; re-upload required

If your document is rejected, you’ll see the rejection reason. Upload a corrected version.

---

Step 3 - Download Your Document

Navigate to: My Profile → Documents Tab → click document → Download

The system generates a temporary secure download link (presigned S3 GET URL). The link is valid for a limited time - download immediately.

Note

You can only download documents that are marked as EMPLOYEE_VISIBLE. HR-only documents are not accessible from the employee portal.

---

Visibility Controls

Visibility Setting	Who Can See It
EMPLOYEE_VISIBLE	The employee, HR_ADMIN, and SUPER_ADMIN
HR_ONLY	HR_ADMIN and SUPER_ADMIN only - hidden from the employee’s portal

Use HR_ONLY for sensitive documents like background check reports, disciplinary notices, or internal performance notes.

---

Tenant Isolation & Security

Every document operation is scoped to your organization’s tenant ID. This means:

• Employees from Company A cannot access documents belonging to Company B
• Even if someone guesses a valid document UUID, cross-tenant access returns 404 Document not found
• S3 keys are structured as tenants/{tenantId}/employees/{employeeId}/docs/{filename} to enforce physical storage separation

---

Common Troubleshooting

Problem	Solution
File upload rejected - “invalid file type”	Only PDF, JPG, and PNG are accepted
File upload rejected - “file too large”	Maximum is 10 MB; compress your file
Document stuck in PENDING for a long time	Contact HR to review the Pending Verifications queue
Document shows REJECTED	Check the rejection reason; re-upload a corrected version
Cannot see a document I uploaded	HR may have set it as HR_ONLY after upload
Download link expired	Generate a new download link by clicking Download again

---

← Core HR Employees must exist before uploading their documents.

Back to Home → View all modules and setup guides.