Document Control - Energy CMMS

Overview

Energy CMMS provides enterprise document control with revision management, AI-powered search, interactive PDF annotations, and full traceability.

Document Hierarchy

Documents are organized hierarchically:

Core Concepts

Document Types

Classify documents: Drawings, Manuals, Procedures, Certificates

Disciplines

Technical areas: Electrical, Mechanical, Civil, HVAC

Revisions

Version control with automatic tracking

Creating Documents

Navigate to Documents

Go to Documents > Documents

Add New Document

Click “Add Document” button

Basic Information

Code: Unique identifier (auto-generated or manual)
Title: Descriptive name
Type: Document classification
Discipline: Technical area

Upload File

Create first revision:

Upload PDF file
Set revision number (e.g., “A”, “Rev 0”)
Add revision notes
System triggers AI extraction

Configure Metadata

Fill dynamic fields:

Fields auto-created from document type
Can be filled manually
Or auto-extracted via AI

Document Model

documento = Documento.objects.create(
    codigo="DWG-ELEC-001",
    titulo="Substation A Single Line Diagram",
    tipo_documento=electrical_drawing_type,
    disciplina=electrical_discipline,
    estado_actual='EN_REVISION',
    responsable=engineer,
    fecha_inicio=date.today()
)

# Create first revision
revision = Revision.objects.create(
    documento=documento,
    numero_revision="A",
    archivo=uploaded_pdf,
    cambios="Initial issue"
)

Revision Control

Revision Workflow

Creating Revisions
Revision Numbering
Automatic Tracking

When document changes:

Upload new PDF version
Increment revision number
Document what changed
Previous revision marked as superseded
New revision becomes current

Accessing Revisions

# Get current revision
current = documento.ultima_revision

# Get all revisions chronologically
historial = documento.revisiones.all().order_by('-fecha_carga')

# Compare two revisions
rev_a = documento.revisiones.get(numero_revision='A')
rev_b = documento.revisiones.get(numero_revision='B')

All revisions are retained. You can always access previous versions for audit trails or rollback.

AI-Powered Features

Automatic Text Extraction

When PDF is uploaded, n8n workflow:

Upload Triggers Webhook

# Django sends webhook to n8n
payload = {
    'documento_id': doc.id,
    'filepath': revision.archivo.name,
    'callback_url': f"{settings.SITE_URL}/documentos/api/update-texto/{doc.id}/"
}
requests.post(settings.N8N_EXTRACT_TEXTO_WEBHOOK_URL, json=payload)

n8n Extracts Text

Workflow performs:

PDF to text conversion (OCR if needed)
Text cleanup and formatting
Page-by-page extraction

Callback with Results

n8n posts back:

{
  "documento_id": 123,
  "texto": "Full extracted text...",
  "pages": 45
}

Generate Embeddings

Django Celery task:

Chunks text into fragments
Generates vector embeddings via Gemini
Stores in pgvector for semantic search

Metadata Extraction

AI can auto-fill metadata fields:

# Trigger AI metadata extraction
webhook_url = settings.N8N_METADATA_SYNC_WEBHOOK
payload = {
    'documento_id': doc.id,
    'file_url': doc.ultima_revision.archivo.url,
    'metadatos': [
        {'nombre': 'project_number', 'etiqueta': 'Project Number'},
        {'nombre': 'drawing_scale', 'etiqueta': 'Scale'},
        {'nombre': 'date_issued', 'etiqueta': 'Date Issued'}
    ]
}
response = requests.post(webhook_url, json=payload)

AI extraction works best on structured documents like drawings with title blocks. Results may vary on handwritten or low-quality scans.

Dynamic Metadata

Customize metadata per document type:

Configuring Metadata Fields

Define Fields for Type

Go to Documents > Metadata Configurations:

Link to document type
Add field configurations

Field Configuration

For each field:

Name: Internal field name (e.g., project_number)
Label: Display name (e.g., “Project Number”)
Field Type: TEXT, NUMBER, DATE, SELECT, BOOLEAN, RELATIONAL
Required: Mandatory for approval
Order: Display sequence

Relational Fields

Link to other models:

Content Type: Select related model (Asset, Location, etc.)
Display Field: Which field to show
Creates dropdown with autocomplete

Example Metadata Config

# Drawing-specific metadata
configs = [
    MetadatoConfig(
        tipo_documento=drawing_type,
        nombre='drawing_number',
        etiqueta='Drawing Number',
        tipo_campo='TEXT',
        es_requerido=True,
        orden=1
    ),
    MetadatoConfig(
        tipo_documento=drawing_type,
        nombre='scale',
        etiqueta='Scale',
        tipo_campo='SELECT',
        opciones_select='1:50,1:100,1:200,NTS',
        orden=2
    ),
    MetadatoConfig(
        tipo_documento=drawing_type,
        nombre='related_equipment',
        etiqueta='Related Equipment',
        tipo_campo='RELATIONAL',
        content_type=ContentType.objects.get_for_model(Activo),
        campo_relacional='nombre',
        orden=3
    )
]

Interactive PDF Viewer

Annotate and collaborate on documents:

Pin System

Comment Pins

Add notes and discussions to specific locations on PDF

Markup Pins

Highlight areas for review or clarification

Issue Pins

Flag errors or required changes

Link Pins

Connect to other documents or assets

Adding Annotations

Open Document Viewer

Click document to open interactive PDF viewer

Select Pin Type

Choose annotation type from toolbar

Place Pin

Click on PDF where comment applies:

Point pin: Single click
Area pin: Click and drag rectangle

Add Content

Fill in annotation:

Text comment
Assign to responsible person
Attach images
Link to other documents

Pin Features

comentario = ComentarioDocumento.objects.create(
    documento=doc,
    revision=current_revision,
    usuario=request.user,
    responsable=assigned_engineer,
    texto="Verify transformer rating matches spec",
    tipo='ISSUE',
    posicion_x=450.5,
    posicion_y=320.8,
    pagina=3,
    resuelto=False
)

# Attach image
ComentarioImagen.objects.create(
    comentario=comentario,
    imagen=uploaded_photo
)

# Link to related document
comentario.vinculos.add(related_spec_document)

Pins are tied to specific revisions. When document is revised, pins from previous revisions remain visible but are marked as “from superseded revision”.

Document Traceability

Track document relationships and history:

Relationship Types

Parent-Child
Cross-References
Temporal

Response documents:

RFI responses
Transmittals
Review comments

response_doc = Documento.objects.create(
    codigo="RFI-RESP-001",
    titulo="Response to RFI-001",
    respuesta_a=original_rfi  # Parent link
)

Traceability View

Visualize complete document network:

# Get full traceability tree
tree = build_traceability_tree(documento)

# Returns hierarchical structure:
{
    'documento': documento,
    'parent': parent_doc,
    'children': [child1, child2],
    'revisions': [rev_a, rev_b, rev_c],
    'linked_docs': [doc1, doc2]  # Via pins
}

Use the Traceability Viewer to see the complete document ecosystem. Helpful for impact analysis when making changes.

Search Capabilities

Standard Search

Quick lookup by code or title:

# Simple search
results = Documento.objects.filter(
    Q(codigo__icontains=query) | Q(titulo__icontains=query)
).select_related('tipo_documento', 'disciplina')[:20]

Advanced Filters

Multi-criteria search:

By Type & Discipline

Filter combination:

Document type (Drawing, Manual, etc.)
Discipline (Electrical, Mechanical, etc.)
Status (Draft, Approved, Superseded)

Date Range

Temporal filtering:

Created between dates
Modified after date
Issued in specific period

Metadata Search

Dynamic field filters:

Project number
Drawing number
Equipment tag
Any configured metadata

Semantic Search

AI-powered content search:

User Enters Query

Natural language question:

“transformer protection relay settings”
“fire pump installation procedure”
“electrical room ventilation requirements”

Generate Query Vector

import google.generativeai as genai

genai.configure(api_key=settings.GEMINI_API_KEY)
result = genai.embed_content(
    model="models/text-embedding-004",
    content=query,
    task_type="retrieval_query"
)
query_vector = result['embedding']

Search Vector Database

Find similar document fragments:

from pgvector.django import CosineDistance

fragments = DocumentoFragmento.objects.annotate(
    distance=CosineDistance('embedding', query_vector)
).order_by('distance')[:40]

Rank and Return

Results include:

Document metadata
Relevant excerpt
Similarity score
Page number

Hybrid Search

System combines exact matching (code/title) with semantic search (content) for best results.

# Hybrid search implementation
results = []

# 1. Exact matches (highest priority)
exact_matches = Documento.objects.filter(
    Q(codigo__iexact=query) | Q(titulo__icontains=query)
)[:5]

# 2. Semantic matches
vector_results = semantic_search(query, limit=15)

# 3. Merge without duplicates
for doc in exact_matches:
    results.append({'doc': doc, 'score': 1.0, 'match_type': 'exact'})

for item in vector_results:
    if item['doc_id'] not in [r['doc'].id for r in results]:
        results.append({
            'doc': item['document'],
            'score': item['similarity'],
            'match_type': 'semantic',
            'excerpt': item['fragment_text']
        })

Document Libraries

Organize documents into collections:

Creating Libraries

Define Library

Create named collection:

Name (e.g., “Project X Drawings”)
Description
Access permissions

Add Documents

Multiple selection methods:

Manual selection
Filter-based rules
Bulk import

Configure View

Library settings:

Default sort order
Visible columns
Export formats

Library Use Cases

Project Sets

All documents for specific project

Submittal Packages

Documents for client approval

As-Built Set

Final construction documents

O&M Manuals

Operations and maintenance docs

Document States

Workflow through document lifecycle:

Draft
In Review
Approved
Issued
Superseded

Initial creation:

Being prepared
Not for distribution
Can be freely edited

Bulk Operations

Mass Upload

Import many documents at once:

Prepare Package

Organize files:

Consistent naming convention
Metadata in filename or CSV
All PDFs in folder

Create Import Mapping

Define extraction rules:

# Filename format: PROJ-DISC-TYPE-NUM-REV.pdf
# Example: P001-ELEC-DWG-0001-A.pdf

pattern = r'(?P<project>\w+)-(?P<discipline>\w+)-(?P<type>\w+)-(?P<number>\d+)-(?P<revision>\w+).pdf'

Execute Import

System processes:

Extract metadata from filename
Create document records
Upload PDFs
Trigger AI extraction
Generate preview thumbnails

Batch Updates

Update multiple documents:

# Bulk state change
Documento.objects.filter(
    tipo_documento=drawing_type,
    proyecto='P001'
).update(
    estado_actual='ISSUED',
    fecha_emision=date.today()
)

# Bulk metadata update
for doc in Documento.objects.filter(codigo__startswith='ELEC-'):
    MetadatoValor.objects.update_or_create(
        documento=doc,
        config=project_field_config,
        defaults={'valor': 'Project Alpha'}
    )

AI Chat Assistant

Interactive document Q&A:

Using AI Chat

Open Document

View any document with extracted text

Click Chat Icon

Open AI assistant panel

Ask Questions

Examples:

“What is the maximum load on Bus A?”
“Summarize the testing procedure”
“List all protection relay settings”

Get Answers

AI responds with:

Answer based on document content
Specific page references
Relevant excerpts

Chat Implementation

# Proxy to n8n AI workflow
response = requests.post(
    settings.N8N_CHAT_WEBHOOK_URL,
    json={
        'documento_id': doc.id,
        'contenido_texto': doc.contenido_texto,  # Full text for context
        'pregunta': user_question,
        'historial': previous_chat_messages
    },
    timeout=60
)

ai_answer = response.json()['respuesta']

AI answers are generated from document content but may contain errors. Always verify critical information against the source PDF.

Access Control

Manage document visibility:

Permission Levels

Public
Department
Project
Restricted

Everyone can view:

Safety procedures
General manuals
Policy documents

Best Practices

Consistent Coding

Standardize document codes:

Project prefix
Discipline code
Document type
Sequential number

Example: P001-ELEC-DWG-0042

Meaningful Titles

Descriptive naming:

Include location/equipment
Specify what is shown
Avoid generic names

Good: “Substation A - 13.8kV Switchgear Single Line” Bad: “Electrical Drawing 1”

Regular Audits

Quality control:

Verify metadata completeness
Check for superseded docs still in use
Validate cross-references
Ensure AI extraction succeeded

Retention Policy

Lifecycle management:

Define retention periods
Archive inactive documents
Purge obsolete versions (keep one)
Backup critical documents

Integration Points

With Assets

Link drawings to equipment
Manuals attached to asset records
Certificates for compliance tracking

With Maintenance

Procedures linked to routines
Work instructions in work orders
As-built drawings for repairs

With Projects

Submittal tracking
RFI management
Change order documentation

Reporting

Standard Reports

Document Register

Complete listing with metadata

Transmittal Log

Documents sent/received tracking

Review Status

Pending approvals and comments

Superseded List

Documents ready for archival

Next Steps:

Overview

Getting Started

Core Modules

User Guides

Integration

​Overview

​Document Hierarchy

​Core Concepts

Document Types

Disciplines

Revisions

​Creating Documents

​Document Model

​Revision Control

​Revision Workflow

​Accessing Revisions

​AI-Powered Features

​Automatic Text Extraction

​Metadata Extraction

​Dynamic Metadata

​Configuring Metadata Fields

​Example Metadata Config

​Interactive PDF Viewer

​Pin System

Comment Pins

Markup Pins

Issue Pins

Link Pins

​Adding Annotations

​Pin Features

​Document Traceability

​Relationship Types

​Traceability View

​Search Capabilities

​Standard Search

​Advanced Filters

​Semantic Search

​Hybrid Search

​Document Libraries

​Creating Libraries

​Library Use Cases

Project Sets

Submittal Packages

As-Built Set

O&M Manuals

​Document States

​Bulk Operations

​Mass Upload

​Batch Updates

​AI Chat Assistant

​Using AI Chat

​Chat Implementation

​Access Control

​Permission Levels

​Best Practices

​Integration Points

​With Assets

​With Maintenance

​With Projects

​Reporting

​Standard Reports

Document Register

Transmittal Log

Review Status

Superseded List

Build docs developers (and LLMs) love

Overview

Document Hierarchy

Core Concepts

Creating Documents

Document Model

Revision Control

Revision Workflow

Accessing Revisions

AI-Powered Features

Automatic Text Extraction

Metadata Extraction

Dynamic Metadata

Configuring Metadata Fields

Example Metadata Config

Interactive PDF Viewer

Pin System

Adding Annotations

Pin Features

Document Traceability

Relationship Types

Traceability View

Search Capabilities

Standard Search

Advanced Filters

Semantic Search

Hybrid Search

Document Libraries

Creating Libraries

Library Use Cases

Document States

Bulk Operations

Mass Upload

Batch Updates

AI Chat Assistant

Using AI Chat

Chat Implementation

Access Control

Permission Levels

Best Practices

Integration Points

With Assets

With Maintenance

With Projects

Reporting

Standard Reports