Date: 2026-02-24
Owner: @oshun/isis-team
Checklist: WS10-006
Ticket: ISIS2-00114
Objective#
Implement explicit idempotent external trigger APIs for batch and chained workflow orchestration, with deterministic replay behavior and full SDK/contract parity.
Existing Implementations Reviewed#
Before implementation, these in-repo implementations were analyzed:
apps/isis/generation-api/src/routes/workflows.ts- existing workflow run RBAC and execution-history endpoint patterns.
apps/isis/generation-api/src/services/job.service.ts- existing idempotent submit behavior keyed by
idempotencyKey.
- existing idempotent submit behavior keyed by
libs/isis/client/src/resources/workflows.ts- current workflow run/execution SDK surface for extension.
Design decisions from this analysis:
- reuse existing job-level idempotent submit guarantees,
- add external trigger contracts that deterministically derive per-trigger idempotency keys,
- preserve existing RBAC model for run operations,
- keep all routes in generation-api
/api/v1/workflowsnamespace, - expose typed SDK methods for batch and chained triggering.
Delivered API Surface#
Added external trigger endpoints:
POST /api/v1/workflows/triggers/batchPOST /api/v1/workflows/triggers/chained
Enhanced existing workflow run endpoint:
POST /api/v1/workflows/:workflowId/run- now accepts explicit
idempotencyKeyin body - also honors
Idempotency-Keyrequest header when body key is absent
- now accepts explicit
Idempotency Strategy#
- deterministic per-trigger keys are generated using a stable SHA-256 hash of:
- trigger mode (
batchorchained), - root external idempotency key,
- normalized trigger descriptor (workflowId, index/step, request payload).
- trigger mode (
- repeated external trigger requests with equivalent payloads produce the same per-item idempotency keys and replay the same jobs via existing job service idempotent submission behavior.
- chain steps include explicit dependency metadata (
dependsOnStepId,dependsOnJobId) for downstream orchestration systems.
SDK Parity#
WorkflowsResource now supports typed external trigger methods:
triggerBatch(request)triggerChain(request)
New typed request/response contracts include:
- batch trigger request/result/error contracts,
- chained trigger request/step/error contracts,
idempotencyKeysupport inrun(...)options and result shape.
Verification Commands#
bash
pnpm --filter @isis/generation-api exec vitest run src/routes/workflows.spec.ts src/app.auth.spec.ts src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/client exec vitest run src/resources/workflows.route-parity.spec.ts --reporter=dot
node scripts/isis/generate_generation_api_openapi.mjs --check
pnpm --filter @isis/generation-api run openapi:check