Operational requests and My Work
Document information
- Canonical URL:
/docs/12_workflows/10_operational-requests-and-my-work - Version:
2026-10-02 - Tags:
operations,datapool,my-work,processflow,guides
Operational requests are the customer work items your operations team finishes in Tealfabric. They live in the DataPool schema operational_requests. Process runs write and refresh those rows from your support system, CRM, or ERP. My Work on / is the queue where people open a request, see where the company process is, finish the next human step, and hand work to another person or team.
What you get
| Surface | URL | Who uses it |
|---|---|---|
| My Work | / | Anyone with operations access. Needs action, Waiting, and Recently completed. |
| Request detail | /work/operational_request/{id} | Same people. Four questions, journey strip, approve/retry, and handover. |
| Team | /team | Leads and managers of an organization unit. Stuck handoffs first. |
| Processes | /runs and /runs/{executionId} | Operators watching live business process runs (category business). |
When My Work is empty, Tealfabric does not invent demo tasks. The page tells you to contact a workspace administrator or team lead so connections to company systems can be set up and real processes can write requests.
Prepare the request model (administrators)
My Work needs the operational_requests schema before processes can write rows.
- Sign in as a workspace administrator (tenant admin).
- Open My Work. If the model is missing, use Prepare request model.
- Connect integrations and publish business processes that call
tf.operations.*orPUT /api/v1/operations/requests.
Preparing the model does not seed sample requests. Full authoring guide: Publishing work for tenant admins.
Work a request in My Work
- Open
/. Prefer Needs action for work you must finish; use Waiting when the process is waiting on someone or something else; use Recently completed for a short history of finished items. - Open a card. Read the four sections: what is happening, why you are involved, what already happened, and what happens when you act.
- Take the primary action when available (Approve / Reject / Retry), or follow the instructions and use Pass / Escalate when needed.
Assign and hand over
Assignment fields stay on the request row (owner_user_id, owner_label, organization_unit_id, due_at, priority). Handovers also append handover_history and set handover_note.
| Action | Effect |
|---|---|
| Take | You become the owner |
| Pass to person | Directory search; sets owner (and optional team) |
| Pass to team | Sets organization unit and clears owner so the team can pick it up |
| Escalate | Clears owner and marks the request as needing a person |
API: POST /api/v1/work-items/operational_request/{id}/handover
Directory search: GET /api/v1/operations/directory/users?q=
Work kinds (process writer contract)
ProcessFlow owns request state. Operations only changes ownership via handover and completes human gates via Approve/Reject / Retry.
| Work kind | What the process wrote | What the employee sees | What they do |
|---|---|---|---|
| Approval | attention: "approval" and human_request_id set to a pending human-input id | Approve / Reject | Choose one. That responds to the process gate and the process continues. |
| Approval (not ready) | attention: "approval" but empty human_request_id | Warning: approval is not ready | Fix the process (pause with human input and write the id), or Pass / Escalate. |
| Action required | attention: "action_required" + required_action | Instructions only | Do the work in CRM/ERP/support. The process updates the request when it continues. |
| Exception | attention: "blocked" | Exception guidance | Clear the blocker, Retry when offered, or Pass / Escalate. |
Prefer helpers:
await tf.operations.openApproval({
external_id: "erp-supplier-10482",
subject: "Approve supplier onboarding",
process_name: "Supplier onboarding",
human_request_id: pending_human_id,
why_visible: "You own supplier activation for this account.",
consequence: "Approving activates the supplier in ERP.",
required_action: "Confirm documents and activate the supplier.",
journey_beat: "in_process"
});
Validate first with POST /api/v1/operations/requests/validate or tf.operations.validate(payload).
Allowed values
| Field | Allowed values |
|---|---|
status | open, waiting, blocked, done |
attention | approval, action_required, blocked, info |
checks[].state | verified, complete, needs_review, pending |
journey_beat | received, in_process, systems, done |
actor_hint | person, agent, system |
Canonical export: OPERATIONAL_REQUEST_PROCESS_CONTRACT in operational-requests.model.ts.
Field contract
Every request is one datapool_data row. Prefer tf.operations.* or PUT /api/v1/operations/requests (upsert by external_id).
Required: external_id, subject, process_name, attention
Required for approval: human_request_id
Recommended: party, required_action, consequence, why_visible, process_id, execution_id, ownership fields, due_at, source_system
Enrichment: journey_beat, journey_stage_label, checks, system_refs, actor_hint, awaiting_role, summary, ai_summary