CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-django-crm

Open Source CRM developed on Django framework with REST API for contact, lead, account, and opportunity management

Overview
Eval results
Files

documents.mddocs/

Document Management

File upload, storage, and sharing system with document organization, team-based sharing permissions, and attachment capabilities across all CRM entities.

Capabilities

Document Listing and Search

List and search documents with filtering options.

def list_documents(title: str = None, status: str = None, shared_with: str = None,
                   limit: int = 10, offset: int = 0) -> dict:
    """
    List documents with filtering and search.

    Args:
        title (str, optional): Filter by document title (partial match)
        status (str, optional): Filter by status ('active', 'inactive')
        shared_with (str, optional): Filter by shared team UUID
        limit (int): Number of results per page (default: 10)
        offset (int): Number of results to skip (default: 0)

    Returns:
        dict: Paginated documents with metadata

    Headers Required:
        Authorization: Bearer <access_token>
        organization-id: <org_uuid>

    Example:
        GET /api/documents/?status=active&limit=5

        Response:
        {
            "count": 18,
            "next": "/api/documents/?limit=5&offset=5",
            "previous": null,
            "results": [
                {
                    "id": "document-uuid",
                    "title": "Product Specification v2.1",
                    "document_file": "/media/documents/product_spec_v21.pdf",
                    "status": "active",
                    "shared_with": ["team1-uuid", "team2-uuid"],
                    "created_on": "2023-01-15T10:30:00Z",
                    "created_by": {
                        "id": "user-uuid",
                        "first_name": "John",
                        "last_name": "Smith",
                        "email": "john.smith@company.com"
                    }
                }
            ]
        }
    """

Document Upload and Creation

Upload and create new documents with sharing permissions.

def create_document(document_data: dict, document_file: file) -> dict:
    """
    Upload and create a new document.

    Args:
        document_data (dict): Document metadata and sharing information
        document_file (file): File to upload

    Returns:
        dict: Created document details

    Headers Required:
        Authorization: Bearer <access_token>
        organization-id: <org_uuid>
        Content-Type: multipart/form-data

    Example:
        POST /api/documents/
        Content-Type: multipart/form-data

        Form data:
        {
            "title": "Contract Template 2023",
            "status": "active",
            "shared_with": ["sales-team-uuid", "legal-team-uuid"],
            "document_file": <file upload>
        }

        Response:
        {
            "id": "new-document-uuid",
            "title": "Contract Template 2023",
            "document_file": "/media/documents/contract_template_2023.docx",
            "status": "active",
            "shared_with": ["sales-team-uuid", "legal-team-uuid"],
            "created_on": "2023-02-01T09:00:00Z",
            "created_by": {
                "id": "user-uuid",
                "first_name": "Alice",
                "last_name": "Johnson",
                "email": "alice.johnson@company.com"
            }
        }
    """

Document Details and Operations

Get comprehensive document information and perform updates.

def get_document(pk: str) -> dict:
    """
    Get detailed document information.

    Args:
        pk (str): Document UUID

    Returns:
        dict: Complete document details with sharing information

    Headers Required:
        Authorization: Bearer <access_token>
        organization-id: <org_uuid>

    Example:
        GET /api/documents/document-uuid/

        Response:
        {
            "document_obj": {
                "id": "document-uuid",
                "title": "Product Specification v2.1",
                "document_file": "/media/documents/product_spec_v21.pdf",
                "status": "active",
                "created_on": "2023-01-15T10:30:00Z",
                "created_by": "user-uuid"
            },
            "shared_with": [
                {
                    "id": "team1-uuid",
                    "name": "Product Team",
                    "users": [...team members...]
                },
                {
                    "id": "team2-uuid",
                    "name": "Sales Team",
                    "users": [...team members...]
                }
            ],
            "created_by": {
                "id": "user-uuid",
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@company.com"
            }
        }
    """

def update_document(pk: str, document_data: dict) -> dict:
    """
    Update document information and sharing permissions.

    Args:
        pk (str): Document UUID
        document_data (dict): Updated document information

    Returns:
        dict: Updated document details

    Headers Required:
        Authorization: Bearer <access_token>
        organization-id: <org_uuid>

    Example:
        PUT /api/documents/document-uuid/
        {
            "title": "Product Specification v2.2 - FINAL",
            "status": "active",
            "shared_with": ["product-team-uuid", "sales-team-uuid", "support-team-uuid"]
        }
    """

def delete_document(pk: str) -> None:
    """
    Delete a document.

    Args:
        pk (str): Document UUID

    Returns:
        None: 204 No Content on success

    Headers Required:
        Authorization: Bearer <access_token>
        organization-id: <org_uuid>

    Example:
        DELETE /api/documents/document-uuid/
    """

Document Data Types

class Document:
    """Document model for file storage and sharing"""
    id: str  # UUID
    title: str  # Required document title
    document_file: str  # File path/URL to uploaded document
    status: str  # 'active' or 'inactive'

    # Sharing and permissions
    shared_with: list[str]  # Team UUIDs that have access

    # Metadata
    created_on: datetime
    created_by: str  # User UUID
    org: str  # Organization UUID

class DocumentSharing:
    """Document sharing information with teams"""
    team_id: str  # Team UUID
    team_name: str  # Team name
    users: list[User]  # Team members with access

class DocumentCreator:
    """Document creator information"""
    id: str  # User UUID
    first_name: str
    last_name: str
    email: str

Document Management Features

File Upload Support

Documents support various file types including:

  • Office Documents: .docx, .xlsx, .pptx, .pdf
  • Images: .jpg, .png, .gif, .svg
  • Text Files: .txt, .csv, .json, .xml
  • Archives: .zip, .tar, .gz
  • Other formats: Based on organization settings and security policies

Document Status Management

Documents can be in different states:

  • Active: Document is available and accessible to shared teams
  • Inactive: Document is archived or temporarily unavailable

Team-Based Sharing

Documents use team-based permissions:

  • Shared Teams: Only members of shared teams can access the document
  • Creator Access: Document creator always has access
  • Organization Scoping: Documents are always scoped to the organization

Version Control

While not explicitly versioned, documents support:

  • Update Capability: Replace document content while maintaining sharing
  • Metadata Tracking: Creation date and creator information
  • Title Updates: Modify titles to indicate versions (e.g., "v2.1", "FINAL")

Search and Filtering

Documents support multiple search and filter options:

  • Title Search: title parameter for partial text matching
  • Status Filter: Filter by active or inactive documents
  • Team Sharing: shared_with filter for team-based access
  • Creator Filter: Filter documents by creator (implicit)
  • Date Range: Filter by creation date (implicit)

All text-based filters support partial matching and are case-insensitive.

Document Integration

Documents can be used across CRM entities as attachments:

  • Account Attachments: Link documents to customer accounts
  • Contact Attachments: Associate documents with individual contacts
  • Lead Attachments: Attach documents to sales leads
  • Opportunity Attachments: Include proposals, contracts in opportunities
  • Task Attachments: Add supporting files to tasks
  • Event Attachments: Meeting materials and agendas
  • Case Attachments: Support documentation and screenshots

Security and Access Control

Organization Isolation

  • All documents are scoped to the user's organization
  • Cross-organization access is not permitted

Team-Based Permissions

  • Only users in shared teams can access documents
  • Document creators always retain access
  • Team membership changes affect document access

File Security

  • Uploaded files are stored securely with unique identifiers
  • File access is controlled through API authentication
  • Direct file URLs may require additional authorization

Best Practices

Document Organization

  • Use descriptive titles with version information
  • Organize documents by sharing them with relevant teams
  • Keep document status updated (active/inactive)

Sharing Management

  • Share documents with the minimum required teams
  • Review sharing permissions regularly
  • Use team structure to manage document access efficiently

File Management

  • Use appropriate file formats for the intended use
  • Keep file sizes reasonable for performance
  • Include version information in filenames when appropriate

Install with Tessl CLI

npx tessl i tessl/pypi-django-crm

docs

accounts.md

authentication.md

cases.md

contacts.md

documents.md

events.md

index.md

invoices.md

leads.md

opportunities.md

tasks.md

teams.md

tile.json