TealfabricLibrary

Trace: craft Operations-aligned work

Document information
  • Canonical URL: /docs/12_workflows/30_trace-crafting-operations-aligned-work
  • Version: 2026-10-02
  • Tags: operations, trace, processflow, integrations, webapps, guides

Use this guide when Trace (or another AI author) proposes integrations, ProcessFlows, WebApps, or step code that should appear in Operations My Work. Follow the same contract as tenant admins. Do not redesign the Tenant Admin Console and do not seed demo tasks into employee queues.

Non-negotiables

  1. Prefer tf.operations.openApproval / openAction / openException / updateProgress / complete over raw api.put("/api/v1/operations/requests", …) unless the user asks for a custom payload.
  2. Never set attention: "approval" without a real pending human_request_id.
  3. Set process category to business when the run should appear under operator Processes (/runs).
  4. Install path for the schema is My Work Prepare request model or POST /api/v1/operations/request-model — not a demo DataPool seed of requests.
  5. Empty My Work is correct until real systems write rows.

When proposing a ProcessFlow

Ask / decide:

  • What event starts the case (connector webhook, schedule, WebApp)?
  • Which steps are Automatic vs AI-assisted vs Human?
  • Which human step is Approval vs Action required vs Exception recovery?
  • What stable external_id identifies the case across upserts?
  • What copy answers why_visible and consequence for the employee?

Scaffold pattern

1. Trigger / intake (integration or WebApp → process.execute)
2. Automatic enrich (connectors) + tf.operations.updateProgress
3. Optional AI prepare → ai_summary
4. Human gate:
   - Approval → create human input, then tf.operations.openApproval({ human_request_id })
   - Action → tf.operations.openAction({ required_action })
5. Write-back to systems on continue
6. On failure → tf.operations.openException
7. Done → tf.operations.complete

Validate drafts with tf.operations.validate(payload) and check approve_buttons_would_show.

When proposing integrations

  • Map connector fields to My Work enrichment (party, system_refs, checks), not to a parallel task table.
  • Keep secrets in ProcessFlow Keystore / integration credentials.
  • Surface employee-safe error text in required_action, never stack traces on the primary panel.

When proposing WebApps

  • WebApp collects input and starts or resumes a process.
  • Process owns My Work upserts.
  • Document the POST → process → work-kind path for the tenant admin.

Response style for Trace

When explaining to the user:

  • Name concrete helpers (tf.operations.openApproval) and fields (human_request_id).
  • Distinguish Tenant Admin (design) from Operations (employee control surface).
  • Cite Library URLs under /docs/12_workflows/….
  • If approval UX would be broken, say so before shipping the snippet.

Related