Workflow & Tasks

What this module does

Workflows are the operational backbone of a fertility case. An agency defines templates — sequences of stages, sub-stages, and tasks — that get applied to a case to generate a to-do checklist. This ensures that every step in a fertility journey (from document collection to medical clearance to contract signing) is tracked and nothing falls through the cracks.

Business value

Without workflow management, agency staff track case progress in their heads, in spreadsheets, or in ad-hoc notes. Tasks get forgotten, documents don’t get collected, and clients are left without updates. Orchid’s workflow system makes the full checklist explicit and auditable.

Key files

• Directoryorchid/

  • Directorymodels/

    • workflow.py 31 KB — TemplateBase, TemplateStage, TemplateSubStage, TemplateTask, CustomSubStage, CustomTask, TemplateTaskDocument
    • tood.py 18 KB — CaseTask, ContactTask, ClinicTask, GeneralTask
    • date_tood.py 7 KB — DateBasedToDoSnippetTemplate, DateBasedToDoTemplate, CaseDateBasedToDoSnippet
    • milestone.py CaseMilestone, MileStone, MileStoneBase
  • Directoryapi/

    • workflow.py 51 KB — workflow operations API
    • date_tood_snippet_template.py 33 KB — date-based task template API
  • Directoryviews/

    • workflow.py 3 KB — workflow admin UI
    • date_tood_snippet_template.py date-based task template views

File naming: tood not todo

The model file is tood.py — this is a permanent legacy typo. All imports, references, and new code use this spelling. Do not create a todo.py.

Two task systems

There are two separate task systems that work alongside each other:

graph TD
    subgraph "Standard Workflow Tasks"
        TemplateBase["TemplateBase\n(workflow template)"]
        TemplateBase --> TemplateStage["TemplateStage"]
        TemplateStage --> TemplateSubStage["TemplateSubStage"]
        TemplateSubStage --> TemplateTask["TemplateTask"]
        TemplateTask --> |"applied to case"| CaseTask["CaseTask\n(the actual to-do)"]
    end

    subgraph "Date-Based Tasks"
        DateTemplate["DateBasedToDoTemplate"]
        DateTemplate --> DateSnippet["DateBasedToDoSnippetTemplate"]
        DateSnippet --> |"triggered by\ncycle date"| CaseSnippet["CaseDateBasedToDoSnippet"]
    end

Standard workflow tasks

The template hierarchy

TemplateBase (e.g., "Standard GC Journey")
└── TemplateStage (e.g., "Legal Phase")
    └── TemplateSubStage (e.g., "Contract Signing")
        └── TemplateTask (e.g., "IP signs surrogacy agreement")
            └── TemplateTaskDocument (optional: "Upload signed contract")

Agencies build these templates in the admin settings. When a template is applied to a case, all the tasks are copied from TemplateTask to CaseTask records.

CaseTask — the instance

CaseTask is what shows up in the actual case to-do list. Key fields:

• case_id — which case this task belongs to
• template_task_id — which template it was generated from (for traceability)
• is_complete — whether it has been checked off
• completed_by_id — who completed it
• due_date — optional due date
• assigned_to_id — which admin is responsible

Other task types

Model	Scope
CaseTask	Tasks on a specific case
ContactTask	Tasks on a contact (pre-case)
ClinicTask	Tasks related to a clinic
GeneralTask	Admin to-dos not tied to a specific case

Date-based tasks

Date-based tasks (DateBasedToDoTemplate and DateBasedToDoSnippetTemplate) automatically trigger based on medical dates — for example: “Remind IP 7 days before transfer.”

How they work:

1. Agency admin sets up a DateBasedToDoTemplate (e.g., “7 days before transfer”)
2. Each snippet in the template becomes a DateBasedToDoSnippetTemplate
3. When a Transfer date is set on a case, the system calculates trigger dates
4. At the right time, a CaseDateBasedToDoSnippet is created and shown to staff

These are managed through a separate UI at /date-to-do-snippet and separate API at /api/date-to-do-snippet.

Date-based tasks are a completely separate system

Date-based tasks and standard workflow tasks are independent. They are managed through different UI, different API endpoints, and different models. If a date-triggered to-do is missing, look in DateBasedToDoTemplate, not in TemplateTask.

Milestones

CaseMilestone records mark significant events in a case’s progression (e.g., “Matching complete”, “Legal complete”, “Medical cleared”). They provide a timeline view of case progress distinct from the granular task list.

Workview

orchid/views/admin_workview.py provides the “workview” dashboard at /admin/workview — a cross-case view that shows all open tasks across all cases, filterable by admin assignee and due date. This is how coordinators manage their daily workload.

Common operations

Apply a workflow template to a case: The API at /api/workflow/template/apply takes a template_id and case_id, then creates CaseTask records for all TemplateTask entries in the template.

Mark a task complete:

task = models.CaseTask.query.filter_by(id=task_id).first_or_404()
task.is_complete = True
task.completed_by_id = g.admin.id
task.completed_at = datetime.utcnow()
Crudler.update(task)
Crudler.commit()

Get all open tasks for a case:

tasks = models.CaseTask.query.filter_by(
    case_id=case.id,
    is_complete=False
).order_by(models.CaseTask.due_date).all()

Gotchas

Templates are copied at assignment time

When a workflow template is applied to a case, the TemplateTask records are copied to create CaseTask records. Modifying the template after it has been applied to a case does not update existing CaseTask records. If you need to add a task to an already-started case, add it directly as a CaseTask.

CustomSubStage and CustomTask

CustomSubStage and CustomTask allow agencies to add ad-hoc stages/tasks to a template without modifying the base template. These are stored separately and merged into the template view at render time.