Workflow Template Schema Documentation

This guide provides comprehensive documentation for the workflow template JSON structure used in dot-cOS. Workflow templates define compliance workflows that can be instantiated for specific tenants and entities.

Overview

Workflow templates are stored in the WorkflowTemplate model in the database. They define:

• When a workflow is required (applicability rules)
• How to schedule and track deadlines (timeline logic)
• What tasks need to be completed (phases and tasks)
• How to validate completion (validation rules)
• What guidance to provide users (advisory prompts)

Template Types

Global Templates

• tenantId: null
• Available to all tenants
• Created by Super Admin
• Examples: AGM, DIR-3 KYC, DPT-3, Board Meetings

Tenant-Specific Templates

• tenantId: Set to specific tenant UUID
• Only available to that tenant
• Created by tenant users for custom workflows
• Examples: Custom compliance procedures, internal processes

Complete Schema Structure

{
  "id": "uuid",
  "tenantId": "uuid | null",
  "country": "India",
  "workflowName": "string",
  "legalReference": "string | null",
  "applicabilityRules": {
    "entityTypes": ["string"],
    "excludes": ["string"],
    "listingRequired": "boolean",
    "description": "string"
  },
  "timelineLogic": {
    "triggerDate": "string",
    "triggerEvent": "string",
    "deadlineDays": "number",
    "deadlineDaysAfterTrigger": "number",
    "deadlineDate": "string",
    "frequency": "string",
    "maxGapDays": "number",
    "reminderDaysBefore": ["number"],
    "penaltyDescription": "string",
    "q4DeadlineDays": "number"
  },
  "phases": [
    {
      "name": "string",
      "order": "number",
      "tasks": [
        {
          "name": "string",
          "mandatory": "boolean",
          "daysBeforeDeadline": "number",
          "advisory": "string"
        }
      ]
    }
  ],
  "validationRules": {
    "requiresAuditedFinancials": "boolean",
    "requiresBoardApproval": "boolean",
    "requiresQuorum": "boolean",
    "requiresDSC": "boolean",
    "requiresAuditorCertificate": "boolean",
    "requiresAuditorReview": "boolean",
    "requiresComplianceOfficerCertification": "boolean",
    "interestedDirectorAbstains": "boolean",
    "maxGapDays": "number"
  },
  "advisoryPrompts": {
    "stampPaper": "string",
    "professionalCertification": "string"
  },
  "completionCriteria": {
    "allMandatoryTasksCompleted": "boolean",
    "filingConfirmation": ["string"]
  },
  "isAdhoc": "boolean",
  "isActive": "boolean",
  "isArchived": "boolean",
  "createdAt": "datetime",
  "updatedAt": "datetime"
}

Field Definitions

Core Fields

workflowName (string, required)

The display name of the workflow template.

Examples:

• "Annual General Meeting (AGM)"
• "Director KYC — DIR-3 KYC"
• "Return of Deposits — DPT-3"

country (string, default: "India")

The country for which this workflow applies.

legalReference (string, optional)

The legal statute, section, or regulation that mandates this workflow.

Examples:

• "Companies Act 2013, Section 96; SS-2"
• "Companies (Acceptance of Deposits) Rules, 2014 — Rule 16 and 16A"
• "SEBI LODR Regulation 33, 32"

isAdhoc (boolean, default: false)

Flag to indicate if this workflow can be manually triggered on-demand rather than automatically assigned by the system.

Use cases:

• Resignation of Director
• Change of Registered Office
• One-time compliance events

isActive (boolean, default: true)

Whether this template is currently active and available for use.

isArchived (boolean, default: false)

Whether this template has been archived (soft delete).

Applicability Rules

The applicabilityRules object defines when this workflow is required for an entity.

{
  "entityTypes": ["PRIVATE_LIMITED", "PUBLIC_LIMITED", "LLP"],
  "excludes": ["OPC"],
  "listingRequired": true,
  "description": "All companies except OPC must hold AGM within 6 months of financial year end."
}

entityTypes (array of strings, required)

List of entity types for which this workflow applies.

Valid values:

• "SOLE_PROPRIETORSHIP"
• "PARTNERSHIP"
• "LLP"
• "PRIVATE_LIMITED"
• "PUBLIC_LIMITED"
• "OPC" (One Person Company)
• "SECTION_8" (Non-profit company)
• "TRUST"
• "SOCIETY"
• "HUF" (Hindu Undivided Family)
• "ALL" (applies to all entity types)

excludes (array of strings, optional)

Entity types to explicitly exclude even if they match entityTypes.

listingRequired (boolean, optional)

If true, this workflow only applies to listed companies (stock exchange).

description (string, optional)

Human-readable explanation of when this workflow applies.

Timeline Logic

The timelineLogic object defines when the workflow is triggered and when it must be completed.

{
  "triggerDate": "financial_year_end",
  "deadlineDays": 180,
  "reminderDaysBefore": [60, 30, 14, 7],
  "penaltyDescription": "₹1 lakh on company + ₹5,000/day of default on every officer."
}

Trigger Types

Option 1: Fixed Date Trigger

{
  "triggerDate": "1st April",
  "deadlineDate": "30th September"
}

Used for annual recurring workflows with fixed calendar dates.

Option 2: Relative Date Trigger

{
  "triggerDate": "financial_year_end",
  "deadlineDays": 180
}

Used for workflows triggered relative to a business event.

Option 3: Event-Based Trigger

{
  "triggerEvent": "AGM date",
  "deadlineDaysAfterTrigger": 60
}

Used for workflows triggered by completion of another workflow.

Option 4: Recurring Frequency

{
  "frequency": "quarterly",
  "deadlineDays": 45,
  "maxGapDays": 120
}

Used for periodic workflows (quarterly board meetings, quarterly financial results).

Timeline Fields

• triggerDate (string): Calendar date or business event that starts the workflow
• triggerEvent (string): Event name that triggers the workflow
• deadlineDays (number): Days from trigger to deadline
• deadlineDaysAfterTrigger (number): Days after trigger event to deadline
• deadlineDate (string): Fixed calendar deadline date
• frequency (string): Recurrence pattern ("quarterly", "monthly", "annual")
• maxGapDays (number): Maximum days allowed between instances (for recurring workflows)
• reminderDaysBefore (array of numbers): Days before deadline to send reminders
• penaltyDescription (string): Description of penalties for non-compliance
• q4DeadlineDays (number): Special deadline for Q4 (used in quarterly workflows where Q4 has different timeline)

Phases and Tasks

The phases array defines the sequential stages of the workflow, each containing tasks.

{
  "phases": [
    {
      "name": "Pre-AGM Preparation",
      "order": 1,
      "tasks": [
        {
          "name": "Finalize audited financial statements",
          "mandatory": true,
          "daysBeforeDeadline": 45,
          "advisory": "Balance Sheet, P&L, Cash Flow Statement must be approved by the Board before AGM notice is sent."
        },
        {
          "name": "Prepare Directors' Report (Section 134)",
          "mandatory": true,
          "daysBeforeDeadline": 45,
          "advisory": "Must include: state of affairs, dividend declaration, material changes, CARO comments, CSR report if applicable."
        }
      ]
    },
    {
      "name": "Conducting the AGM",
      "order": 2,
      "tasks": [
        {
          "name": "Verify quorum (Section 103)",
          "mandatory": true,
          "advisory": "Pvt Ltd: 2 members; Public Ltd: 5 members (up to 1000), 15 (1001-5000), 30 (above 5000)."
        }
      ]
    }
  ]
}

Phase Fields

• name (string, required): Display name of the phase
• order (number, required): Sequential order (1, 2, 3, ...)
• tasks (array, required): List of tasks in this phase

Task Fields

• name (string, required): Display name of the task
• mandatory (boolean, required): Whether this task must be completed for workflow completion
• daysBeforeDeadline (number, optional): Suggested days before workflow deadline to complete this task
• advisory (string, optional): Contextual guidance and tips for completing this task

Validation Rules

The validationRules object defines requirements that must be met for workflow completion.

{
  "requiresAuditedFinancials": true,
  "requiresBoardApproval": true,
  "requiresQuorum": true,
  "requiresDSC": true,
  "requiresAuditorCertificate": true,
  "requiresAuditorReview": true,
  "requiresComplianceOfficerCertification": true,
  "interestedDirectorAbstains": true,
  "maxGapDays": 120
}

Available Validation Rules

• requiresAuditedFinancials (boolean): Audited financial statements must be attached
• requiresBoardApproval (boolean): Board resolution must be passed
• requiresQuorum (boolean): Meeting quorum must be verified
• requiresDSC (boolean): Digital Signature Certificate required for filing
• requiresAuditorCertificate (boolean): Auditor certificate must be attached
• requiresAuditorReview (boolean): Auditor review report required
• requiresComplianceOfficerCertification (boolean): Compliance officer must certify
• interestedDirectorAbstains (boolean): Interested directors must abstain from voting
• maxGapDays (number): Maximum days between recurring instances

Advisory Prompts

The advisoryPrompts object provides additional contextual guidance.

{
  "stampPaper": "Not required for AGM resolutions.",
  "professionalCertification": "CS certification needed for MGT-8 if company meets thresholds."
}

Common Advisory Fields

• stampPaper (string): Guidance on stamp paper requirements
• professionalCertification (string): Requirements for professional certification (CS, CA, etc.)

Completion Criteria

The completionCriteria object defines what constitutes a completed workflow.

{
  "allMandatoryTasksCompleted": true,
  "filingConfirmation": ["AOC-4", "MGT-7"]
}

Completion Fields

• allMandatoryTasksCompleted (boolean): All tasks marked mandatory: true must be completed
• filingConfirmation (array of strings): List of MCA/SEBI forms that must be filed

Complete Example: AGM Workflow

{
  "workflowName": "Annual General Meeting (AGM)",
  "legalReference": "Companies Act 2013, Section 96; SS-2",
  "applicabilityRules": {
    "entityTypes": ["PRIVATE_LIMITED", "PUBLIC_LIMITED", "LLP", "SECTION_8"],
    "excludes": ["OPC"],
    "description": "All companies except OPC must hold AGM within 6 months of financial year end."
  },
  "timelineLogic": {
    "triggerDate": "financial_year_end",
    "deadlineDays": 180,
    "reminderDaysBefore": [60, 30, 14, 7],
    "penaltyDescription": "₹1 lakh on company + ₹5,000/day of default on every officer."
  },
  "phases": [
    {
      "name": "Pre-AGM Preparation",
      "order": 1,
      "tasks": [
        {
          "name": "Finalize audited financial statements",
          "mandatory": true,
          "daysBeforeDeadline": 45,
          "advisory": "Balance Sheet, P&L, Cash Flow Statement must be approved by the Board before AGM notice is sent."
        },
        {
          "name": "Prepare Directors' Report (Section 134)",
          "mandatory": true,
          "daysBeforeDeadline": 45,
          "advisory": "Must include: state of affairs, dividend declaration, material changes, CARO comments, CSR report if applicable."
        },
        {
          "name": "Dispatch AGM notice to all members",
          "mandatory": true,
          "daysBeforeDeadline": 21,
          "advisory": "Minimum 21 clear days notice required under Section 101."
        }
      ]
    },
    {
      "name": "Conducting the AGM",
      "order": 2,
      "tasks": [
        {
          "name": "Verify quorum (Section 103)",
          "mandatory": true,
          "advisory": "Pvt Ltd: 2 members; Public Ltd: 5 members (up to 1000), 15 (1001-5000), 30 (above 5000)."
        },
        {
          "name": "Present and adopt financial statements",
          "mandatory": true
        },
        {
          "name": "Ratify/appoint statutory auditor",
          "mandatory": true
        }
      ]
    },
    {
      "name": "Post-AGM Filings",
      "order": 3,
      "tasks": [
        {
          "name": "File AOC-4 (Financial Statements) within 30 days of AGM",
          "mandatory": true,
          "advisory": "Section 137. ₹100/day penalty for delay."
        },
        {
          "name": "File MGT-7 (Annual Return) within 60 days of AGM",
          "mandatory": true,
          "advisory": "Section 92. Companies with paid-up capital ≥ ₹10 Cr or turnover ≥ ₹50 Cr need CS certification via MGT-8."
        }
      ]
    }
  ],
  "validationRules": {
    "requiresAuditedFinancials": true,
    "requiresBoardApproval": true,
    "requiresQuorum": true
  },
  "advisoryPrompts": {
    "stampPaper": "Not required for AGM resolutions.",
    "professionalCertification": "CS certification needed for MGT-8 if company meets thresholds."
  },
  "completionCriteria": {
    "allMandatoryTasksCompleted": true,
    "filingConfirmation": ["AOC-4", "MGT-7"]
  },
  "isAdhoc": false,
  "isActive": true,
  "isArchived": false
}

Workflow Instance Relationship

When a workflow template is instantiated for a specific entity, a WorkflowInstance is created:

{
  "id": "uuid",
  "tenantId": "uuid",
  "templateId": "uuid",
  "entityId": "uuid",
  "status": "DRAFT | IN_PROGRESS | COMPLETED",
  "financialYear": "2024-2025",
  "customLabel": "Mumbai Office Address Change",
  "currentData": {
    "phases": [
      {
        "name": "Pre-AGM Preparation",
        "order": 1,
        "tasks": [
          {
            "name": "Finalize audited financial statements",
            "mandatory": true,
            "completed": true,
            "completedAt": "2024-03-15T10:30:00Z",
            "completedBy": "user-uuid"
          }
        ]
      }
    ]
  },
  "certificateUrl": "https://storage.supabase.co/...",
  "createdAt": "datetime",
  "updatedAt": "datetime"
}

Instance-Specific Fields

• currentData: Real-time state of the workflow with task completion status
• status: Current workflow status (DRAFT, IN_PROGRESS, COMPLETED)
• financialYear: For recurring workflows, which FY this instance belongs to
• customLabel: User-provided label for ad-hoc workflows
• certificateUrl: Link to generated compliance certificate PDF

Dynamic Field Substitution

Workflow templates support dynamic field substitution using the entity's profileData:

Example: Entity Profile Data

{
  "cin": "U74999MH2020PTC123456",
  "pan": "AABCU1234C",
  "directors": [
    {
      "name": "John Doe",
      "din": "01234567",
      "designation": "Managing Director"
    }
  ],
  "registeredOffice": {
    "address": "123 Main Street",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001"
  }
}

Usage in Advisory Text

Advisory prompts can reference entity data using {{field}} syntax:

{
  "advisory": "File Form DIR-12 for {{directors[0].name}} (DIN: {{directors[0].din}}) within 30 days."
}

This will render as:

"File Form DIR-12 for John Doe (DIN: 01234567) within 30 days."

Conditional Logic and Branching

Entity Type Conditions

Use applicabilityRules to define entity-specific variations:

{
  "applicabilityRules": {
    "entityTypes": ["PUBLIC_LIMITED"],
    "listingRequired": true
  }
}

Task Conditionality

Tasks can be marked as optional (mandatory: false) to create branching logic:

{
  "name": "Declare dividend (if applicable)",
  "mandatory": false,
  "advisory": "Only required if Board decides to declare dividend."
}

Phase Dependencies

Phases are executed sequentially based on order. The system can enforce that Phase 2 cannot start until all mandatory tasks in Phase 1 are completed.

Best Practices

Template Design

1. Clear Naming: Use descriptive workflow names that include the legal form number
2. Comprehensive Advisory: Provide detailed guidance in advisory fields
3. Realistic Timelines: Set daysBeforeDeadline based on actual compliance requirements
4. Mandatory vs Optional: Mark tasks as mandatory only if legally required
5. Penalty Clarity: Include specific penalty amounts and consequences

Applicability Rules

1. Be Specific: Define exact entity types rather than using "ALL" when possible
2. Document Exclusions: Clearly state why certain entity types are excluded
3. Listing Requirements: Always specify if workflow applies only to listed companies

Timeline Logic

1. Multiple Reminders: Set reminders at 60, 30, 14, and 7 days before deadline
2. Buffer Time: Build in buffer time for task completion
3. Penalty Documentation: Always include penalty descriptions for compliance motivation

Validation Rules

1. Enforce Requirements: Use validation rules to enforce legal requirements
2. Document Attachments: Specify required documents in validation rules
3. Approval Workflows: Use requiresBoardApproval for governance compliance

API Endpoints

Create Template

POST /api/v1/workflows/templates
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "workflowName": "...",
  "legalReference": "...",
  ...
}

Get All Templates

GET /api/v1/workflows/templates
Authorization: Bearer <jwt_token>

Get Template by ID

GET /api/v1/workflows/templates/:id
Authorization: Bearer <jwt_token>

Update Template

PUT /api/v1/workflows/templates/:id
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "isActive": false
}

Delete Template (Soft Delete)

DELETE /api/v1/workflows/templates/:id
Authorization: Bearer <jwt_token>

Related Documentation

• API Reference - Complete API endpoint documentation
• Multi-Tenant Isolation - Tenant data scoping patterns
• Testing Strategy - How to test workflow templates
• Local Development Setup - Running workflow service locally

Seeding Templates

The platform includes 8 pre-built compliance templates that can be seeded using:

cd dot-cos-workflow-service
node scripts/seed-compliance-templates.js

This seeds:

1. Annual General Meeting (AGM)
2. Director KYC — DIR-3 KYC
3. Return of Deposits — DPT-3
4. Board Meeting Compliance
5. Annual Return Filing — MGT-7
6. Related Party Transaction Approval
7. SEBI LODR — Quarterly Financial Results
8. SEBI LODR — Corporate Governance Report

Troubleshooting

Template Not Appearing for Tenant

Check:

1. Is isActive set to true?
2. Does entity type match applicabilityRules.entityTypes?
3. Is entity type in applicabilityRules.excludes?
4. For listed company workflows, is listingRequired satisfied?

Timeline Not Triggering

Check:

1. Is triggerDate or triggerEvent properly formatted?
2. Does entity have required profile data (e.g., financial_year_end)?
3. Is workflow instance status set to IN_PROGRESS?

Tasks Not Validating

Check:

1. Are all mandatory: true tasks marked as completed?
2. Are required documents attached per validationRules?
3. Is completionCriteria.allMandatoryTasksCompleted set to true?