# ISIS v2 External Workflow Trigger APIs (WS10-006)

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
```
