Skip to main content

Task Templates & Groups (Developer)

This doc describes the implemented Task Templates and Task Template Groups system: data model, endpoints, ordering, and tenant scoping.

Mental Model​

  • TaskTemplate: Reusable definition for a single task.
  • TaskTemplateGroup: Ordered list of templates (group-defined ordering). Templates can belong to multiple groups.
  • Task: The actual task instance attached to a Job or Leg.

Data Model​

TaskTemplate​

Key fields:

  • name (required): internal key
  • title (required): display title
  • description
  • scope: system | company
  • parentCompany: null for system templates
  • appType: trucking | serviceRepair | all
  • industry: trucking | service_repair | general
  • appliesTo: job | leg | both
  • category, order
  • requirement flags: required, requiresPhoto, requiresSignature, requiresNote
  • autoApply (template-level)
  • active

TaskTemplateGroup​

Key fields:

  • groupKey (unique per scope+tenant usage)
  • scope: system | company
  • parentCompany (required for company-scoped groups)
  • targeting: appType, industry, appliesTo
  • active
  • ordered members: templates: [{ templateId, order }]
  • auto-apply: autoApply, autoApplyMode, triggerRules

Ordering Rules​

  • Group ordering is defined by TaskTemplateGroup.templates[].order.
  • When a group is applied, each created Task.order uses:
    • member.order ?? template.order ?? 0

API Endpoints (v1)​

Templates​

  • POST /api/v1/tasks/templates
  • GET /api/v1/tasks/templates
  • PUT /api/v1/tasks/templates/:templateId
  • DELETE /api/v1/tasks/templates/:templateId

Groups​

  • GET /api/v1/tasks/template-groups
  • POST /api/v1/tasks/template-groups
  • PUT /api/v1/tasks/template-groups/:groupId
  • DELETE /api/v1/tasks/template-groups/:groupId

Apply Group​

  • POST /api/v1/tasks/job/:jobId/apply-group
  • POST /api/v1/tasks/leg/:legId/apply-group

Body:

{
  "groupKey": "pickup_checklist",
  "appType": "trucking",
  "mode": "dedupe"
}

Modes:

  • dedupe: skip templates already applied to that job/leg (by templateId)
  • override: delete existing tasks for those templates on that job/leg then recreate

Tenant Isolation / Scope Resolution​

When applying a group, the API prefers:

  1. Company-scoped group: { scope: "company", parentCompany }
  2. Otherwise fallback to system-scoped group: { scope: "system", parentCompany: null }

Backwards Compatibility Notes​

  • Some older template data may not have title; group-apply uses template.title || template.name as a safe fallback when creating Task.title.