Canonical page: https://tellenze.com/help/template-reference

# Template definition reference

Build reusable task hierarchies, milestones, labels, and knowledge with symbols and relative dates.

## Choose a definition shape

Use this reference with the [template walkthrough](https://tellenze.com/help/templates). Select the template’s type in the editor before pasting its definition. The chosen type controls which root fields are allowed.

| Template type | Structure |
| --- | --- |
| Project | Required `project` object; optional `labels`, `folders`, `tasks`, `milestones`, and `workflow_id`. |
| Milestone | A `milestone` object or `milestones` array, with optional `tasks`, `labels`, and `workflow_id`. |
| Task | A `task` object or `tasks` array, with optional `labels` and `workflow_id`. It cannot create milestones or folders. |

Use a single-object shorthand or the corresponding array, not both. The Task shorthand supplies the symbol `task`; the Milestone shorthand supplies `milestone`. For arrays, give every object its own symbol. Workspace templates support all three types; project templates support Milestone and Task. Only workspace Task templates can target a Team.

## Example: a reusable launch project

Choose **Project** and use this definition. It creates a documentation page, a label, a launch milestone, and a parent work item with a verification child:

```json
{
  "project": {
    "name": "Launch project",
    "description": "Prepare and verify a customer release."
  },
  "labels": [
    { "symbol": "release", "name": "Release", "colour": "#6366f1" }
  ],
  "folders": [
    {
      "symbol": "handbook",
      "name": "Release handbook",
      "pages": [
        {
          "symbol": "checklist",
          "title": "Release checklist",
          "body": "Record the release owner, verification results, and rollback steps."
        }
      ]
    }
  ],
  "milestones": [
    {
      "symbol": "launch",
      "title": "Customer launch",
      "target_date_offset_days": 14,
      "task_symbols": ["verify"]
    }
  ],
  "tasks": [
    {
      "symbol": "prepare",
      "title": "Prepare the release",
      "type": "story",
      "acceptance_criteria": "Verification is complete and the release owner approves launch.",
      "label_symbols": ["release"]
    },
    {
      "symbol": "verify",
      "title": "Verify the release",
      "type": "task",
      "complexity": "S",
      "parent_symbol": "prepare",
      "due_date_offset_days": 10,
      "label_symbols": ["release"]
    }
  ]
}
```

Generate a preview with an unused project key, a project name, and the intended workflow. Check the seven resolved objects, parent link, milestone membership, dates, and visibility before applying. No stage keys are hardcoded, so the tasks use the selected workflow’s initial stage.

## Work item fields

Each task array entry requires `symbol` and `title`. Optional `description` and `acceptance_criteria` hold reusable Markdown. Set `type` explicitly when helpful: `bug`, `story`, `task`, `discovery`, `incident`, `idea`, or `business_case`. The default is Story. `complexity` accepts `XS`, `S`, `M`, `L`, or `XL`.

| Field | Purpose |
| --- | --- |
| `parent_symbol` | Another task in this definition. Parent links cannot form a cycle. |
| `stage_key` | A stage in the destination workflow; omit it to use the initial stage. |
| `label_symbols` | Array of labels declared in this definition. |
| `milestone_symbols` | Array of milestones declared here, for Project or Milestone templates. |
| `due_date_offset_days` | Calendar days from the preview’s reference date. |
| `timebox_hours` | A Discovery’s planned timebox. |
| `severity` | Bug or Incident severity: `critical`, `high`, `medium`, or `low`. |
| `procedure_keys` | Published Required Context procedures, when that feature is enabled. |

Business Case templates support `estimated_impact`, `estimated_cost`, `benefit_period_start`, `benefit_period_end`, and `success_criterion`. Use the same value and cost basis described in [Business Cases](https://tellenze.com/help/business-cases). Benefit-period dates use explicit `YYYY-MM-DD` values, so review them when reusing a template. Actual impact and actual cost belong to the resulting work and are forbidden in reusable definitions. Type-specific fields still undergo normal validation.

## Labels, milestones, and knowledge

Labels require `symbol` and `name`; optional `colour` uses a six-digit hexadecimal value such as `#6366f1`. Milestones require `symbol` and `title`, with optional `description`, `target_date_offset_days`, and `task_symbols`. You can link work through milestone `task_symbols` or task `milestone_symbols`.

Project templates can include folders with `symbol`, `name`, and a `pages` array. Each page requires `symbol` and `title`, with optional Markdown `body` and `slug`. This definition format creates those folders at the project root; it does not include a nested-folder field.

The reusable `project` fields are `name`, `description`, `group`, `website_url`, `repository_url`, `default_branch`, and `colour`. Choose the actual project key, name, workflow, and visibility during application. Repository URLs identify a repository; they do not supply credentials or install an integration.

## Symbols, dates, and limits

Use lowercase symbols beginning with a letter, followed by letters, digits, hyphens, or underscores, up to 64 characters. Symbols must be unique within their object type and references must resolve inside the definition. They are not existing task identifiers or display names.

Date offsets accept integers from -3650 to 3650. Negative values are before the preview’s reference date; positive values are after it. Offsets count calendar days, including weekends. Preview resolves them into actual dates: inspect the dates shown rather than assuming they will be recomputed when you later press Apply.

A definition supports up to 200 tasks, 100 labels, 50 milestones, and, for Project templates, 50 folders with up to 100 pages each. Prefer a smaller structure people can review and adapt.

## Repair a rejected preview

Check JSON syntax and the root fields for the selected template type first. Unknown fields, unresolved symbols, circular parents, or unsupported type-specific values cause validation errors.

Definitions cannot carry visibility, sharing or membership lists, assignees, credentials, machine mappings, attachments, comments, completion history, or actual Business Case results. Configure people and access on the destination or resulting work.

If a stage does not exist in the destination workflow, choose a compatible workflow or publish a corrected template version. The current application dialog does not provide a stage/label mapping editor. Regenerate the preview after changing destination inputs, and again if it expires or the source changes. A successful preview is still subject to current access checks at application time.