Document Management Guide

Learn how to upload, organize, and manage all project documentation including work sheets, custody chains, and shipping guides in Mantis.

Overview

Mantis provides a comprehensive document management system organized as a hierarchical tree structure:

Work Sheets (Planillas) → Contains sheet PDFs and custody chains
Custody Chains (Cadenas de Custodia) → Individual chain PDFs for each work order
Shipping Guides (Guías de Remisión) → Equipment transfer documentation

All documents support PDF format. The system tracks upload status and provides merge functionality for generating consolidated reports.

Document Tree Structure

Overview Panel

The Documents tab displays a collapsible tree view with: Progress Bar:

Visual indicator of document completion (X/Y archivos - Z%)
Updates in real-time as documents are uploaded

Action Buttons:

Expandir todo: Expand all tree nodes
Colapsar todo: Collapse all tree nodes
Descargar Todo: Download all documents merged into a single PDF

Tree Hierarchy

📂 Planillas de Trabajo (Work Sheets)
  ├─ 📄 Planilla #1 - Periodo 01/03 - 15/03
  │   ├─ ✅ PDF Planilla (uploaded)
  │   ├─ ❌ Firma Técnico (missing)
  │   └─ 🔗 Cadenas de Custodia
  │       ├─ ✅ Cadena #1 - 01/03/2024
  │       └─ ❌ Cadena #2 - 08/03/2024
  ├─ 📄 Planilla #2 - Periodo 16/03 - 31/03
  └─ ...
📂 Guías de Remisión (Shipping Guides)
  ├─ ✅ Guía #001 - 01/03/2024
  └─ ❌ Guía #002 - 15/03/2024

✅ Green checkmark: File uploaded and available
❌ Red X: File missing or pending upload
🔵 Blue badge: File count (e.g., “3/5 archivos”)

Uploading Individual Documents

Navigate to Documents Tab

From the project detail view, click on the Documentos tab.

Locate the Document Node

Expand the tree to find the specific document you want to upload:

Click the arrow icon to expand work sheets
Work sheets contain both sheet-level documents and nested custody chains

Click Upload Button

Click the upload icon button (blue outline) next to the document name.If a file already exists, the button will show as “Reemplazar” (Replace).

Select File

In the upload modal:

Document name is displayed at the top
If replacing, current filename is shown
Click the file input and select your PDF file
Maximum file size: Check with system administrator (typically 10MB)

Confirm Upload

Click Subir to start the upload.During Upload:

Progress bar animates
“Subiendo…” message displays
Upload button becomes disabled

After Upload:

Success message: “Archivo subido correctamente”
Tree refreshes automatically
Icon changes from ❌ to ✅
Modal closes automatically after 1.2 seconds

You can view uploaded documents by clicking the eye icon (Ver) button. This opens the PDF in a new browser tab.

Bulk Upload: Custody Chains

When you have multiple custody chain PDFs in a single document, use the bulk upload feature.

How Bulk Upload Works

The system:

Takes a single PDF with multiple pages
Splits the PDF (one page per custody chain)
Assigns each page to selected custody chains in order
Saves individual PDFs for each chain

Bulk Upload Process

Open Bulk Upload Modal

From the Documents tab, locate a work sheet with custody chains.Click the Masiva button (accent color) next to the work sheet name.

Select Custody Chains

The modal shows all custody chains for that work sheet.Selection Options:

Todas: Select all chains
Ninguna: Deselect all
Pares: Select even-numbered chains (2, 4, 6…)
Impares: Select odd-numbered chains (1, 3, 5…)

Check/uncheck individual chains as needed.

Chains already with files show a green checkmark ✅ but can be reselected to replace.

Upload PDF File

Click the file input and select your PDF.File Requirements:

Must be PDF format
Page count must EXACTLY match selected chain count
Pages are assigned in order: Page 1 → Chain 1, Page 2 → Chain 2, etc.

Page Counter: The system automatically detects page count:

Shows “Páginas detectadas: X”
Green checkmark if X matches selected chains
Red error if counts don’t match

Verify and Submit

Before uploading:

Verify page count matches: “deben ser X”
Ensure chains are in correct order
Check that the PDF pages correspond to the right chains

Click Subir X archivo(s) when ready.

Upload Processing

The system:

Shows progress: “Procesando carga masiva…”
Splits the PDF into individual pages
Assigns each page to the corresponding custody chain
Saves files to storage
Updates database records

Success Message: “Se asignaron X archivo(s) correctamente.”

Critical: Page Order MattersThe bulk upload assigns pages sequentially. If your PDF pages are out of order, the wrong documents will be assigned to chains. Always verify PDF page order before bulk upload.

Bulk Upload Example

Scenario: Work sheet has 5 custody chains:

Cadena #101 - 01/03/2024
Cadena #102 - 03/03/2024
Cadena #103 - 05/03/2024
Cadena #104 - 07/03/2024
Cadena #105 - 09/03/2024

You have: A 5-page PDF where:

Page 1 = Signed custody chain for 01/03
Page 2 = Signed custody chain for 03/03
Page 3 = Signed custody chain for 05/03
Page 4 = Signed custody chain for 07/03
Page 5 = Signed custody chain for 09/03

Process:

Click “Masiva” on the work sheet
Click “Todas” to select all 5 chains
Upload the 5-page PDF
System detects “Páginas detectadas: 5” ✓
Click “Subir 5 archivo(s)”
System assigns Page 1→Chain 1, Page 2→Chain 2, etc.
All 5 chains now have PDFs attached ✅

PDF Generation and Merging

Mantis can generate and merge PDFs for comprehensive reporting.

Individual Document PDFs

Custody Chain Reports: The system auto-generates custody chain PDFs from database records. To view/download:

Navigate to custody chain view (via Planillas tab)
Click Descargar PDF button on the chain
PDF is generated on-the-fly with:
- Project information header
- Technical and vehicle details
- Resource list table
- Signature fields
- Totals (gallons, cubic meters, barrels)

PDF Template Source: /api/custody-chain/<id>/pdf/

Merged Document Download

Combine multiple documents into a single PDF for archival or client delivery. Download All Documents:

Click 'Descargar Todo'

From the Documents tab header, click the Descargar Todo button.

PDF Generation

The system:

Collects all uploaded documents
Merges them in hierarchical order:
1. Work Sheet PDFs
2. Custody Chain PDFs (grouped by work sheet)
3. Shipping Guide PDFs
Adds bookmarks for navigation
Generates table of contents

Download

The merged PDF opens in a new tab. Use browser download to save.Filename format: proyecto_<id>_documentos_completos.pdf

Download Work Sheet Documents: To download documents for a specific work sheet:

Locate the work sheet in the tree
Click the download icon next to the work sheet name
System merges only that work sheet’s documents

PDF merging preserves document quality and metadata. Bookmarks allow easy navigation in the merged document.

Document Validation

Mantis validates uploads to ensure document integrity.

File Format Validation

Accepted Formats:

✅ PDF (.pdf)
❌ Word documents (.doc, .docx)
❌ Images (.jpg, .png) - unless converted to PDF first

Why PDF only?

Consistent rendering across devices
Preserves signatures and formatting
Supports merging and splitting
Industry standard for legal documents

File Size Limits

Individual Upload:

Typical limit: 10MB per file
For larger files: Compress PDF or split into multiple documents

Bulk Upload:

Typical limit: 25MB per merged file
Number of pages: Recommended max 50 pages

Use online PDF compression tools to reduce file size without losing quality. Aim for 300 DPI for scanned documents.

Bulk Upload Validation

Page Count Matching:

// System validates:
if (pdf_page_count !== selected_chains.length) {
  return error("Page count must match selected chains");
}

Error Messages:

“Deben ser X páginas” - PDF has wrong page count
“No se seleccionó ninguna cadena” - Must select at least one chain
“Error al procesar PDF” - File is corrupted or invalid PDF

Document Organization Best Practices

File Naming Conventions (Before Upload)

While Mantis assigns filenames automatically, organizing files before upload helps: Work Sheets:

planilla_proyecto123_periodo_01-15mar.pdf
planilla_proyecto123_periodo_16-31mar.pdf

Custody Chains:

custodia_proyecto123_cadena101_01mar.pdf
custodia_proyecto123_cadena102_03mar.pdf

Shipping Guides:

guia_proyecto123_001_salida_01mar.pdf
guia_proyecto123_002_entrada_15mar.pdf

Upload Workflow

Recommended Order:

Create work sheets first (via Planillas tab)
Generate custody chains for each sheet
Get physical signatures on printed documents
Scan signed documents to PDF
Upload to Documents tab (use bulk for chains)
Verify completion (check progress bar = 100%)

Quality Standards

Scanning Guidelines:

Resolution: 300 DPI minimum
Color mode: Grayscale or color (avoid black & white)
Orientation: Correct (not rotated)
Cropping: Remove blank borders
Clarity: Ensure signatures and text are legible

PDF Guidelines:

Single document per file (no multi-document PDFs)
Correct page order (especially for bulk uploads)
Unlocked (no password protection)
No form fields (flatten forms before upload)

Managing Uploaded Documents

Viewing Documents

Locate Document

Expand the tree to find the document (must have ✅ icon).

Click View Button

Click the eye icon (Ver) button.

Review

PDF opens in new browser tab. Use browser PDF viewer to:

Zoom in/out
Navigate pages
Print
Download to local machine

Replacing Documents

To replace an incorrect or outdated document:

Click Upload Button

On an already-uploaded document (with ✅ icon), click the upload icon button.Button text shows “Reemplazar” instead of “Subir”.

Confirm Replacement

The modal shows:

“Archivo actual: [filename] (se reemplazará)”
This warns you that the existing file will be overwritten

Upload New File

Select the new PDF and click Subir.The old file is replaced immediately. Previous file cannot be recovered.

Replacement is permanent. There is no version history. Ensure the new file is correct before uploading.

Deleting Documents

To remove an uploaded document:

Click Delete Button

Click the trash icon (red) next to the document.

Confirm Deletion

Browser confirmation dialog: “¿Eliminar ‘[filename]’?”Click OK to confirm.

Document Removed

File is deleted from storage
Database record is cleared
Icon changes from ✅ to ❌
Progress bar decreases

You can only delete documents if the project is still open. Closed projects lock all documents.

API Endpoints for Document Management

Get Document Tree

GET /api/projects/<project_id>/documents/tree/

Response Structure:

{
  "success": true,
  "data": {
    "sheets": [
      {
        "id": 1,
        "label": "Planilla #1",
        "period": "01/03 - 15/03",
        "files": [
          {
            "field_name": "pdf_sheet",
            "field_label": "PDF Planilla",
            "has_file": true,
            "file_url": "/media/...",
            "file_name": "planilla_1.pdf"
          }
        ],
        "custody_chains": []
      }
    ],
    "shipping_guides": [],
    "stats": {
      "total": 15,
      "loaded": 12
    }
  }
}

Upload Individual File

POST /api/load-files/
Content-Type: multipart/form-data

file: [PDF binary]
model_type: "SheetProject"
object_id: 1
field_name: "pdf_sheet"

Bulk Upload Custody Chains

POST /api/projects/<project_id>/bulk-custody-upload/
Content-Type: multipart/form-data

file: [PDF binary]
chain_ids: [1, 2, 3, 4, 5]

Response:

{
  "success": true,
  "message": "Se asignaron 5 archivo(s) correctamente",
  "saved": 5
}

Download Merged PDF

GET /api/projects/<project_id>/documents/merge/?scope=all
GET /api/projects/<project_id>/documents/merge/?scope=all&sheet_id=1

Query Parameters:

scope: “all” (entire project) or “sheet” (single work sheet)
sheet_id: Required if scope=sheet

Response: Binary PDF stream

Common Issues and Solutions

Upload fails with 'Error al subir'

Possible Causes:

File size exceeds limit
File is not a valid PDF
File is password-protected
Network interruption during upload

Solution:

Check file size (should be under 10MB)
Verify file opens correctly in PDF viewer
Remove password protection
Retry upload with stable connection
Try compressing the PDF

Bulk upload page count mismatch

Problem: “Deben ser X páginas” errorCause: PDF page count ≠ selected chains countSolution:

Check PDF page count in a PDF viewer
Adjust chain selection to match:
- If PDF has 3 pages, select exactly 3 chains
- Use “Ninguna” then manually select correct chains
Alternatively, add/remove pages from PDF to match chains
Ensure PDF doesn’t have blank pages

Cannot delete document

Problem: Delete button disabled or missingCauses:

Project is closed (documents locked)
User lacks delete permission

Solution:

For closed projects: Cannot delete (by design for data integrity)
For permission issues: Contact administrator for role adjustment
Alternative: Replace document instead of deleting

Document tree not loading

Problem: “Error de conexión” or infinite loadingCauses:

Server error
Network connectivity
Browser cache issue

Solution:

Refresh the page (F5)
Clear browser cache (Ctrl+Shift+Delete)
Check browser console for errors (F12)
Verify server is running
Try different browser

Progress bar stuck below 100%

Problem: Some documents showing ❌ but you’ve uploaded everythingCauses:

New work sheets/chains created after initial review
Deleted documents not reflected
Cache issue

Solution:

Use “Expandir todo” to see all nodes
Check for new work sheets at bottom of tree
Verify each custody chain (they can be hidden in collapsed sheets)
Refresh page to reload tree data
Check stats: “X/Y archivos” to see exact counts

Merged PDF missing documents

Problem: Downloaded merged PDF doesn’t include all documentsCause: Only uploaded documents are included in mergeSolution:

Check progress bar before downloading
Ensure all required documents have ✅ icons
Upload missing documents
Re-download merged PDF
Note: System merges only documents with has_file=true

Document Checklist

Use this checklist before closing a project:

Pre-Closure Document Verification

Progress bar shows 100%
All work sheets have PDF documents uploaded
All custody chains have signed PDFs
All shipping guides (if any) are uploaded
Downloaded and verified merged PDF
All PDFs are legible with clear signatures
Document dates match work sheet periods
Client sign-off obtained on all custody chains
Archive copy saved to company file system

Document Types by Project Phase

During Setup (Week 1):

Initial shipping guides (equipment delivery)

During Operations (Ongoing):

Biweekly work sheet PDFs
Custody chain PDFs for each work order
Mid-project shipping guides (equipment additions)

At Project Completion:

Final work sheet PDF
Final custody chain PDFs
Return shipping guides (equipment pickup)
Merged consolidated PDF for archival

Project Management

Learn about project lifecycle and closure

Resource Allocation

Manage resources tracked in custody chains

Calendar Scheduling

Schedule work orders and maintenance

Get Started

Core Features

User Guides

​Document Management Guide

​Overview

​Document Tree Structure

​Overview Panel

​Tree Hierarchy

​Uploading Individual Documents

​Bulk Upload: Custody Chains

​How Bulk Upload Works

​Bulk Upload Process

​Bulk Upload Example

​PDF Generation and Merging

​Individual Document PDFs

​Merged Document Download

​Document Validation

​File Format Validation

​File Size Limits

​Bulk Upload Validation

​Document Organization Best Practices

​File Naming Conventions (Before Upload)

​Upload Workflow

​Quality Standards

​Managing Uploaded Documents

​Viewing Documents

​Replacing Documents

​Deleting Documents

​API Endpoints for Document Management

​Get Document Tree

​Upload Individual File

​Bulk Upload Custody Chains

​Download Merged PDF

​Common Issues and Solutions

​Document Checklist

​Pre-Closure Document Verification

​Document Types by Project Phase

​Related Guides

Project Management

Resource Allocation

Calendar Scheduling

Build docs developers (and LLMs) love

Document Management Guide

Overview

Document Tree Structure

Overview Panel

Tree Hierarchy

Uploading Individual Documents

Bulk Upload: Custody Chains

How Bulk Upload Works

Bulk Upload Process

Bulk Upload Example

PDF Generation and Merging

Individual Document PDFs

Merged Document Download

Document Validation

File Format Validation

File Size Limits

Bulk Upload Validation

Document Organization Best Practices

File Naming Conventions (Before Upload)

Upload Workflow

Quality Standards

Managing Uploaded Documents

Viewing Documents

Replacing Documents

Deleting Documents

API Endpoints for Document Management

Get Document Tree

Upload Individual File

Bulk Upload Custody Chains

Download Merged PDF

Common Issues and Solutions

Document Checklist

Pre-Closure Document Verification

Document Types by Project Phase

Related Guides