Status templates and todo - KayanOS Documentation

A status template is a controlled graph: it contains statuses, one default status, and permitted transitions between them. It gives a service or task workflow a shared language for what can happen next. A task helps a person complete work; it does not by itself sign, approve, or close a citizen-service decision. For the Directorate of Citizen Services, use a small lifecycle that shows who owns the next step and what evidence must exist before a transition. Keep the service record’s formal decision controls separate from everyday task progress.

Require evidence and separate transition decisions

In a status template’s transition controls, require a reason or attachment when the decision needs it. Separation-of-duties rules can exclude the record creator or someone who performed a specified earlier transition. Record-type lifecycle rules can add a condition or exclude members named in selected fields. These checks supplement the transition permission; they do not grant it. Publish the intended template and record-type settings, then test the transition with an eligible member and an excluded member. The action explains a blocked transition and collects required inputs before submission. A condition that cannot be evaluated blocks the transition. Correct the rule or data instead of removing the check to force a decision. Use a transitions-only status field when members must follow these actions rather than edit the status directly. Configure status locks and frozen versions in the record type as described in Entity fields and layouts.

Goal

Create and publish a reviewable status template, configure task terminology around it, and test both the allowed and disallowed paths before a live team depends on it.

Find the settings in Builder

Status and task configuration now lives under Builder, not Administration. Open Builder → Status templates to work with lifecycle graphs. That item appears only when the member has at least one scoped create, update, delete, or share verb for status templates. Open Builder → Task settings to manage task categories, task types, and record relationships; its navigation requires at least one corresponding management verb for task categories or task types. Old Administration links redirect to these Builder routes, but saved links are not an access grant. Organization-wide record-relation definitions and task-type record rules have an additional server-side boundary: only the organization owner or an organization administrator can change them. A member who can open Task settings but cannot save one of those organization-wide controls should ask an authorized owner to review the exact change, not request broader record access.

The model: status, category, transition, action

Term	Meaning	Directorate example
Status	A named state in a workflow	Received or Decision review
Category	The broad work state assigned to a status: todo, in_progress, or done	Received is todo; Inspection scheduled is in progress; Closed is done
Default status	The first status applied when the configured workflow starts	Received
Transition	A permitted directed move from one status to another	Completeness review → Ready for inspection
Transition action	A configured follow-up that runs as part of an allowed transition where the template supports it	Create a controlled follow-up or require the configured workflow evidence
Draft content	The design being edited	A proposed new transition not yet relied on by users
Published content	The released graph used by configured work	The approved lifecycle currently in use

Statuses do not replace data fields. Put the actual inspection finding, decision reason, document, or citizen communication outcome on the record or controlled form. A status tells people where the work is; it is not all of the evidence for why it is there.

Before changing a live template

Name the business owner for the workflow and the technical administrator who can publish it.
List the entry state, every expected next state, the person accountable at each state, the required evidence, and the customer-facing meaning where applicable.
Identify every entity, task type, form action, dashboard, document, or automation that reads the existing status values. Renaming or removing a state can affect filters, calculations, templates, and reports.
Decide which users may trigger each transition. Role access and record scope still apply even when a transition exists in the graph.
Build and test the change on controlled non-production work before publishing it to a live service.
Prepare a rollback: retain the known published graph and a note describing how active records will be handled if a proposed transition is withdrawn.

Do not edit a live lifecycle merely to resolve one stuck request. Diagnose that record’s scope, required evidence, or missing transition first.

Organize templates in folders

Use status-template folders to organize administrative configuration by service, directorate, or lifecycle family. Create folders and nested subfolders, open them through the breadcrumb path, and create or import a template into the current folder. Move templates or folders with the move action or supported drag interaction. Folder placement changes where administrators find the template; it does not change the template’s ID, publication state, references, or permissions. Before deleting a folder, read the confirmation counts. An empty folder can be deleted directly. For a folder containing templates or subfolders, deliberately choose whether to move its contents to the parent or delete the complete contained tree. Never use folder deletion as a shortcut for retiring a live workflow: inventory entity/task references and preserve the published lifecycle under normal change control first.

Build the Citizen Service Request lifecycle

Open Builder → Status templates and create or edit the template. Build a small graph before adding optional branches.

Status	Category	Accountable next responsibility	Minimum evidence before leaving
Received	todo	Registry Officer checks intake	Required intake values and attachments recorded
Completeness review	in_progress	Registry Officer confirms or returns missing information	Completeness outcome recorded on the request
Ready for inspection	todo	Service Manager allocates field work	Owner/assignee and service location confirmed
Inspection scheduled	in_progress	Field Inspector prepares/attends the visit	Event/inspection context and required preparation recorded
Decision review	in_progress	Authorized Reviewer checks evidence	Inspection result and required documents available
Closed	done	Service Manager confirms no operational follow-up remains	Final outcome and required communication/retention step recorded

Configure these elements in order:

Create the template name and description so administrators understand the service it governs.
Add each status with an approved title, optional description/icon/color, and the correct category. Categories affect how tasks and boards summarize work; they do not grant permission.
Select exactly one default status. Test that a new controlled work item starts where the team expects.
Draw the allowed transitions. Keep return/rework paths explicit. For example, Completeness review can return to Received or a defined missing-information state if the policy needs that distinction. Turn on Require a reason for this transition when the move needs an accountable explanation. The member must enter a non-blank reason before the status change can complete, and the reason is retained with the transition history.
Configure an allowed transition’s follow-up action only when the service owner understands its side effect. An action may create or change related work, so test it as carefully as the status move itself.
Save the draft, review the graph with the service owner, then publish the approved content.

The editor keeps draft and published content separately. Do not assume an unsaved or draft-only graph changes live work. Likewise, do not publish a graph solely because it looks visually complete; verify the actual transitions and roles.

Configure todo conventions

Open Builder → Task settings for task categories, types, and organization record relationships. Tasks can use collections, categories, types, priorities, assignees, owners, contributors, informed members, due dates, and a configured status lifecycle. Use task settings to make work clear, not to recreate the service record. For the Directorate:

Use a task title that names the outcome: Verify address evidence for the request, not Check request.
Assign one next actor; use owner, contributor, and informed roles only when they have distinct responsibilities.
Use due dates and priority for service targets, not as a replacement for the request’s legal/business status.
Use personal collections for individual organization and shared collections for a legitimate team queue.
Record the authoritative result on the request or inspection. Closing the task only shows task progress unless a configured formal form/action/signature path records the decision.

Task status templates, categories, and types should change under the same review discipline as a service lifecycle: understand active use, make one controlled change, test it, and communicate it.

Govern task-to-record relationships

An organization owner or administrator can define localized labels for how a relationship reads from the task and from the record, decide whether it appears in the task header, and decide whether it contributes to the record’s open-task count. Use a stable lowercase key and a specific meaning such as About, Evidence, Blocked by, or Produces. Archiving a custom relationship prevents new configuration from relying on it; do not use archiving as a substitute for reconciling existing task links. For each task type, a record rule selects one relationship, one or more allowed entity types, and a minimum/maximum count. A zero minimum is optional and has no enforcement stage. A positive minimum must be enforced either at creation or completion. Creation requirements are checked in the same transaction as the new task and its links, while completion requirements stop a move to a done status until the required records from the allowed entity types are linked. Keep one rule per relationship and test the minimum, maximum, wrong-entity, and unlink paths before publishing the task type.

Govern task-to-task relations

Open Builder → Task settings → Task relations to manage how tasks relate to each other. Every organization starts with Blocked by, Follows, Child of, Relates to, and Duplicate of. Each relation has a stable key, a label for each side in every organization language, and a kind that decides what it can enforce:

Kind	Reads as	Can enforce
Dependency	This task waits on the other one	Refuse or warn on completion, affect Ready to start, notify followers when the last blocker completes, reject loops
Sequence	This task comes after the other one	The same options, usually set to warn
Association	Context in one or both directions	Nothing; it never gates work
Hierarchy	Parent and child tasks	Stored in the task hierarchy; labels only

Write the label from the waiting task’s side, such as Blocked by, and the other side’s label as it should read on the blocking task, such as Blocks. A symmetric association, such as Relates to, uses one label for both tasks. Built-in relations can be relabeled, adjusted, or archived but not deleted. Archiving stops new links and keeps existing ones visible. Changing a completion guard affects every existing link of that type at once. Before switching a relation from Warn to Refuse, check which open tasks already use it and tell the teams involved. In each task type, Task relation rules choose which relations tasks of that type use, which task types may sit on the other side, and minimum and maximum counts. A positive minimum is enforced at creation or completion, like record rules. Turn on Only listed relations to reject relations that have no rule for the type.

Validate before publishing

Test	Expected result
Default status	A new controlled item receives the approved first status
Allowed transition	Authorized member moves a record along the graph and the configured result/evidence appears
Disallowed transition	The member cannot jump from Received directly to Closed when no such transition is published
Scope boundary	A member with a valid transition but no update access to the record cannot use it outside their scope
Rework path	Returned work follows the explicit return transition without losing the record’s evidence
Required reason	A transition configured to require a reason rejects an empty response and records the supplied explanation in the record activity
Task boundary	Completing a task does not create a formal decision unless the configured decision workflow performs it
Dashboard/filter check	Status-based views show the expected category/status after the test

Use a non-production request and synthetic evidence. Keep a copy of the test graph and results in the change record.

Troubleshooting

Symptom	Check first	Safe response
A status does not appear in live work	Draft versus published content, template assignment, and page refresh	Publish only after review; verify the configured record/task actually uses the template
A user cannot move to a visible next status	Transition exists, update verb, record scope, and required form/action state	Correct the smallest missing condition; do not grant broad administration
A status move stops at the reason prompt	Whether the published transition requires a reason and whether the response is blank	Enter the factual approved reason. If the transition should not require one, change and republish the template through normal change control rather than entering placeholder text
A record is stuck	Current status, permitted outgoing transitions, missing evidence, and owner	Use an approved rework/exception path; do not edit database values or invent a status
A dashboard count changed after publish	Status categories, filters, and active records	Review the graph/category mapping and record the reporting impact
Task completion was treated as approval	The decision workflow was not configured or not used	Record the decision through the approved form/action/signature path
Task creation or completion says a record requirement is not satisfied	Task type rule, relationship, allowed entity type, and minimum/maximum count	Link the approved accessible record or correct the task-type rule through an authorized owner; do not attach an unrelated record merely to pass validation
Record-relation settings open but cannot be saved	The member can reach Task settings but is not the organization owner or an organization administrator	Ask an authorized owner to review the exact organization-wide relation/rule change; do not broaden operational record scopes
Delete is unavailable	Template delete permission or active references	Keep the template, retire its use through change control, and resolve references safely

Assign accountable operational work in Tasks and approvals.
Build decision evidence in Form actions, logic, and signatures.
Test access to transitions in Roles and scopes.
Report status-based workload with Dashboards.

​Require evidence and separate transition decisions

​Goal

​Find the settings in Builder

​The model: status, category, transition, action

​Before changing a live template

​Organize templates in folders

​Build the Citizen Service Request lifecycle

​Configure todo conventions

​Govern task-to-record relationships

​Govern task-to-task relations

​Validate before publishing

​Troubleshooting

​Related guides