Eve library

ISIS v2 External Workflow Trigger APIs (WS10-006)

Guide

Revision 1

On this page

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.
  • 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/workflows namespace,
  • expose typed SDK methods for batch and chained triggering.

Delivered API Surface#

Added external trigger endpoints:

  • POST /api/v1/workflows/triggers/batch
  • POST /api/v1/workflows/triggers/chained

Enhanced existing workflow run endpoint:

  • POST /api/v1/workflows/:workflowId/run
    • now accepts explicit idempotencyKey in body
    • also honors Idempotency-Key request header when body key is absent

Idempotency Strategy#

  • deterministic per-trigger keys are generated using a stable SHA-256 hash of:
    • trigger mode (batch or chained),
    • root external idempotency key,
    • normalized trigger descriptor (workflowId, index/step, request payload).
  • 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,
  • idempotencyKey support in run(...) 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