Ví dụ: công việc

Danh sách My Work của một người, nhận một Workflow task và gửi bước của nó; và một chủ thể dịch vụ đọc một công việc như một bản ghi.

Công việc (task) là việc dành cho người, và nó là một bản ghi: mỗi bước Người dùng hoặc Chữ ký giao việc ra dưới dạng một bản ghi của thực thể dựng sẵn Workflow task. Vì vậy một công việc được liệt kê, nhận và trả lại bằng đúng các thao tác của mọi bản ghi công việc khác, còn những phần thuộc về bước (biểu mẫu, bản nháp, việc gửi) nằm dưới step của bản ghi. My Work, nhận, trả lại và gửi một bước đều là thao tác x-person-only: chủ thể dịch vụ gọi sẽ nhận 403 USER_IDENTITY_REQUIRED. Hiện cũng chưa có cách để một ứng dụng bên thứ ba đăng nhập người dùng rồi gọi thay họ — xem Xác thực.

Vì vậy trang này có hai phần:

Phần 1–3 là những yêu cầu ứng dụng AgentFlow gửi cho người đang đăng nhập, bằng cookie phiên của họ. Chúng được đưa ra để bạn thấy hình dạng của yêu cầu và phản hồi.
Phần 4 là việc một tích hợp làm được: đọc một công việc như một bản ghi.

Phản hồi đã được rút gọn; … đánh dấu phần lược bỏ. Khóa trường và id hành động là của một quy trình minh họa.

1. My Work

curl -sS -G "$ORIGIN/api/v1/work" \
  -b "session=$SESSION" \
  --data-urlencode "view=claimable" \
  --data-urlencode "live=true" \
  --data-urlencode "sort=due_at" \
  --data-urlencode "dir=asc" \
  --data-urlencode "limit=20"

{
  "items": [
    {
      "id": "5b90…",
      "entity_id": "e41c…",
      "title": "Duyệt ngân sách mua 10 laptop",
      "status": "active",
      "priority": null,
      "live": true,
      "claimed_by_user_id": null,
      "assigned_user_ids": ["9c3a…"],
      "due_at": "2026-09-15T10:00:00Z",
      "step": {
        "workflow": { "id": "3f8a…", "name": "Đề xuất mua sắm" },
        "step": { "key": "duyet_ngan_sach", "label": "Duyệt ngân sách" },
        "kind": "human",
        "signs": false,
        "subject": { "entity_id": "0a5f…", "record_id": "7d2e…", "label": "PO-1001" }
      },
      …
    }
  ],
  "next_cursor": "…",
  "prev_cursor": null
}

Mọi dòng đều là một bản ghi, nên cùng danh sách này cũng chứa việc không phải một bước quy trình, như một phiếu hỗ trợ. Dòng có step là một Workflow task; id là mã bản ghi của công việc, và cùng với entity_id là đủ cho các lệnh gọi bên dưới.
view là một trong all (mọi thứ bạn được xem), mine (việc bạn đang giữ) và claimable (việc chưa ai nhận mà bạn có thể nhận). live=true giữ việc còn mở; live=false giữ việc đã xong trong ba mươi ngày qua.
signs=true liệt kê các bước đang chờ chữ ký của bạn (thêm live=true cho những bước đang chờ lúc này).
sort là một trong due_at (mặc định), started_at, updated_at, priority. Không gửi dir thì due_at sắp tăng dần, các cách còn lại giảm dần.
Các bộ lọc khác: entity_id, q (từ trong tiêu đề), priority (nhiều giá trị, cách nhau bằng dấu phẩy), age_band và overdue.
Một giá trị lạ trong view, sort, dir, priority hoặc age_band trả 400 INVALID_QUERY_PARAMETER; một tham số mà danh sách không khai báo trả 400 UNKNOWN_QUERY_PARAMETER.
Quay lại trang trước: gửi prev_cursor làm before, như mọi danh sách khác. Xem Phân trang.

2. Nhận công việc, đọc bước của nó, trả lại

curl -sS -X POST "$ORIGIN/api/v1/entities/$ENTITY_ID/records/$RECORD_ID/work/claim" \
  -b "session=$SESSION"

Thành công trả về mục công việc:

{
  "record_id": "5b90…",
  "active": true,
  "assigned_user_ids": ["9c3a…"],
  "assigned_group_ids": [],
  "assigned_unit_ids": [],
  "claimed_by_user_id": "9c3a…",
  "claimed_at": "2026-09-14T08:02:11Z"
}

Bạn không nằm trong số người được đề nghị công việc: 403 WORK_NOT_ELIGIBLE.
Người khác nhận trước: 409 WORK_ALREADY_CLAIMED.
Bản ghi không phải bản ghi bạn được mở: 404, y như bản ghi không tồn tại.

Rồi đọc bước mà công việc đại diện:

curl -sS "$ORIGIN/api/v1/entities/$ENTITY_ID/records/$RECORD_ID/step" \
  -b "session=$SESSION"

{
  "record_id": "5b90…",
  "entity_id": "e41c…",
  "kind": "human",
  "signs": false,
  "step_status": "open",
  "signed": false,
  "run": {
    "id": "c04b…",
    "workflow_id": "3f8a…",
    "workflow_name": "Đề xuất mua sắm",
    "step_key": "duyet_ngan_sach",
    "step_label": "Duyệt ngân sách"
  },
  "subject": { "entity_id": "0a5f…", "record_id": "7d2e…", "label": "PO-1001" },
  "form_definition": { … },
  "prefill": { … },
  "draft_payload": null,
  "actions": [{ "id": "approve", "label": "Duyệt", … }],
  …
}

Bước mở cho những người làm nó — người đang giữ, những người được đề nghị công việc, và bất kỳ ai có quyền giao việc (assign) trên thực thể Workflow task — và trả 404 cho mọi người khác, kể cả người có quyền đọc bản ghi.

Người đang giữ trả công việc về hàng chờ bằng POST /api/v1/entities/{entity_id}/records/{record_id}/work/release. Trả lại công việc do người khác giữ cần quyền giao việc (assign), và những gì người giữ đã nhập bị xoá.

Gửi lại một lượt nhận

Nhận, trả lại, giao lại và giao việc không nhận Idempotency-Key. Sau khi quá thời gian chờ, hãy đọc lại bản ghi trước khi thử lại: gửi lại một lượt nhận bạn đã thắng trả 409 WORK_ALREADY_CLAIMED, và gửi lại lượt trả một việc không ai giữ trả 403 WORK_NOT_CLAIMANT. Chỉ việc gửi ở phần 3 nhận khóa; xem Thử lại an toàn.

3. Gửi một công việc

export IDEMPOTENCY_KEY=$(uuidgen)

curl -sS -X POST "$ORIGIN/api/v1/entities/$ENTITY_ID/records/$RECORD_ID/step/submit" \
  -b "session=$SESSION" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "payload": {
      "approved_amount": 12000000,
      "_action": "approve"
    }
  }'

Phản hồi là bước như ở phần 2, giờ với "step_status": "submitted".

payload mang giá trị của biểu mẫu công việc.
Khi bước có các nút hành động, payload._action là id của hành động được chọn, lấy từ actions trong bước. Bỏ trống trả 400 HUMAN_ACTION_REQUIRED; một id không khớp hành động nào trả 400 HUMAN_ACTION_UNKNOWN.
Dữ liệu không đạt biểu mẫu: 422 STEP_PAYLOAD_INVALID. Người gọi không phải người đang giữ: 403 WORK_NOT_CLAIMANT. Công việc đã xong: 409 WORK_NOT_ACTIVE.
Nếu biểu mẫu gắn với bản ghi mà quy trình nói tới, lượt gửi ghi các trường bạn đã đổi vào bản ghi đó, bằng quyền của quy trình, và lịch sử của bản ghi ghi tên bạn. Một từ chối từ bản ghi đó (ENTITY_ACCESS_DENIED, ENTITY_SENSITIVE_WRITE_DENIED, một quy tắc) từ chối cả lượt gửi và không làm mất khóa: hãy sửa nguyên nhân rồi gửi lại với cùng khóa. Bản ghi đã bị xoá từ khi công việc mở trả 409 WORKFLOW_TASK_SUBJECT_GONE.
Khi đã gửi, quy trình chạy tiếp.

Gửi lại đúng lệnh đó với cùng khóa sẽ nhận bước như hiện tại kèm Idempotent-Replayed: true, và không có gì bị gửi hai lần.

4. Một tích hợp đọc công việc như một bản ghi

My Work từ chối khóa của chủ thể dịch vụ, và nói rõ lý do:

curl -sS -i "$ORIGIN/api/v1/work" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{ "type": "USER_IDENTITY_REQUIRED", "status": 403, "request_id": "…", … }

Một công việc là bản ghi, nên khóa đọc một công việc như đọc mọi bản ghi, khi vai trò của chủ thể và các quyền trên thực thể Workflow task cho phép:

curl -sS "$ORIGIN/api/v1/entities/$ENTITY_ID/records/$RECORD_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

{
  "id": "5b90…",
  "entity_id": "e41c…",
  "body": {
    "title": "Duyệt ngân sách mua 10 laptop",
    "status": "open",
    "kind": "human",
    "workflow": "Đề xuất mua sắm",
    "step": "Duyệt ngân sách",
    "subject_label": "PO-1001",
    "work_state": "active",
    …
  },
  …
}

Không có quyền như vậy thì khóa nhận 404, y như bản ghi không tồn tại. Bản thân bước (…/step) chặt hơn bản ghi: chủ thể chỉ mở được khi có quyền giao việc (assign) chạm tới công việc, hoặc instance.admin. Nếu công việc hiển thị dữ liệu của bản ghi khác, các bản ghi đó vẫn được đọc theo quyền truy cập hồ sơ của chính chủ thể.