Triggering K12 Workflows
Starting a Workflow
Every K12 workflow begins with a kickoff call. You provide the required payload (district, facility, annex identifiers, and any instructions), and the system responds with a request ID that uniquely tracks the job from that point forward.
When you call a kickoff endpoint, the following happens behind the scenes:
- The payload is validated against the expected schema.
- A new job record is created with a unique request ID and session ID.
- The workflow begins executing (either immediately or in the background, depending on mode).
- You receive a response confirming acceptance or, in synchronous mode, the final result.
The request ID is the key to everything that follows -- you use it to check status, retrieve results, and request cancellation.
Synchronous vs. Asynchronous Execution
K12 workflows support two execution modes. The mode you choose determines when you receive results and how you interact with the system while the job runs.
Asynchronous mode (default)
This is the recommended mode for most scenarios, especially when the workflow involves AI-powered operations that may take seconds to minutes.
When you call kickoff in asynchronous mode:
- The system immediately responds with an accepted status and the request ID.
- The workflow runs in the background.
- You poll separately for status and results using the request ID.
Asynchronous mode avoids timeout risks. Because the initial response returns quickly, there is no danger of gateway or HTTP timeouts cutting off a long-running operation.
Synchronous mode
When waitForResult is set to true in your kickoff payload, the system attempts to complete the entire workflow before returning a response. If the workflow finishes in time, you receive a success status with the full result payload in a single round trip.
Synchronous mode is useful for:
- Short operations where you want the result immediately.
- Testing and verification scenarios where polling adds unnecessary complexity.
However, synchronous mode carries a risk: if the workflow takes longer than the HTTP or gateway timeout allows, the connection may be dropped before the result is returned. The workflow still completes in the background, but you lose the direct response and must fall back to polling.
Synchronous mode is not recommended for QRG generation or any workflow that processes multiple annexes. These operations typically exceed HTTP timeout thresholds.
The Polling Pattern
When using asynchronous mode, you retrieve results through a two-step polling pattern:
Step 1: Check status
After receiving the request ID from kickoff, call the status endpoint with that request ID. The response tells you the current state of the job:
| Status | Meaning |
|---|---|
| Accepted | Job has been created and is queued or starting |
| In Progress | Workflow is actively running |
| Completed | Workflow finished successfully; results are available |
| Failed | Workflow encountered an error; check the error details |
| Cancelled | Job was cancelled before completion |
Step 2: Retrieve results
Once the status shows Completed, call the result endpoint with the same request ID to retrieve the full output payload.
Recommended polling strategy
- Wait a few seconds after kickoff before your first status check.
- Poll at regular intervals (every 3 to 5 seconds is typical).
- Stop polling when you reach a terminal state: Completed, Failed, or Cancelled.
- Set a maximum polling duration to avoid indefinitely waiting on a stuck job.
Cancellation
If you need to stop a running workflow, you can submit a cancellation request using the request ID. Cancellation works slightly differently for EOP editing and QRG generation workflows.
EOP editing cancellation
For EOP editing workflows, calling the cancellation endpoint:
- Marks the task request and its status records as cancelled.
- Records the cancellation timestamp.
- If workflow-level cancellation is enabled, attempts to stop the in-progress workflow execution.
- Returns a confirmation indicating whether the cancellation succeeded.
QRG generation cancellation
For QRG generation workflows, the same cancellation endpoint:
- Marks the generation request as cancelled.
- Stops processing any remaining annexes that have not yet started.
- Annexes that were already fully processed before the cancellation request arrived will retain their results.
- Returns a confirmation of the cancellation.
Cancellation is best-effort
Cancellation is a best-effort operation. If the workflow has already completed or is in its final moments, the cancellation request may arrive too late to prevent the result from being produced. This is expected behavior -- the system prioritizes data consistency over immediate cancellation.
After issuing a cancellation request:
- Always check the job status to confirm it shows Cancelled.
- If the status shows Completed instead, the workflow finished before your cancellation took effect, and the results are available normally.
- Do not assume cancellation succeeded based solely on the cancellation endpoint response.
The Full Async Lifecycle
The diagram below shows the complete lifecycle from kickoff through result retrieval or cancellation.
Practical Tips
- Prefer asynchronous mode for any workflow that processes multiple items or involves AI content generation. The added complexity of polling is far less costly than dealing with timeout failures.
- Always store the request ID returned from kickoff. Without it, you cannot check status, retrieve results, or cancel the job.
- Verify cancellation succeeded by polling status after issuing a cancel request. The cancellation endpoint confirms the request was received, but only the status endpoint confirms the job actually stopped.
- Set a polling timeout in your integration. If a job has not reached a terminal state after a reasonable duration (for example, 10 minutes for a large QRG generation run), investigate rather than polling indefinitely.
- Handle all terminal states in your polling logic. A robust integration checks for Completed, Failed, and Cancelled -- not just Completed.