Tasks, messages and scheduling
Inbox notifications (NotificationClient) are immutable fact alerts (read/unread), whereas unified tasks (TodoClient) represent actionable items whose lifecycle stays tied to business state. Business services open, update, and close tasks idempotently by (project, bizKey, assignee) so approved items vanish automatically from the workbench without forcing every app to build its own task inbox. Both share the same delivery credential and log failures without blocking domain transactions. SDK configuration
Track an approval
String key = "approval:" + order.getNo();
todoClient.open(approverId, key, "Order awaiting approval");
// Any-one approval: close(key) clears all assignees; countersign: close one assignee
todoClient.close(key, approverId);Keep the same business key across retries to update rather than duplicate tasks. This natively models any-one approval (close(key)), countersigning (close(key, userId)), withdrawal (cancel(key)), overdue pinning, and automatic retention cleanup. Sign in as the approver, repeat delivery and check the open count, then close the task and verify it leaves the list. Use NotificationClient to send an inbox message and check its title, body and read state as the recipient. To-do contract
Schedule a job in a business service
The scheduler never dispatches arbitrary class names, shell scripts, or URLs—only fixed handlers registered by the business service, protected by central lease claiming and cooperative fencingToken() / assertLeaseActive() fencing so handlers can stop further writes after losing the lease:
- Implement
ProjectScheduledTaskHandlerin the backend. Return a stable type such asreport.dailyfromtaskType()and call domain code fromexecute(context). - Set
kaiwu.starter.scheduler.enabledand configure the project identity and scheduler credential. The service registers its handler on startup. - Declare the same type in
kaiwu/jobs.ymland preview and sync the manifest. Check the cron expression and time zone in the scheduler before enabling the job. - Inspect the execution history and the resulting business record. Delivery is at least once. Deduplicate by
context.executionId()or job ID and scheduled time. For long jobs callcontext.assertLeaseActive()between batches. Scheduling and leases