Skip to main content

QRG Workflows

Overview​

The K12 Safety platform provides two QRG (Quick Reference Guide) workflows:

  • QRG Generation -- Creates a full set of role-specific guides from an Emergency Operation Plan.
  • QRG Editing -- Modifies a single section of an existing QRG.

Both are async-only. You kick off a job, poll for status, then fetch the result.

QRG Generation​

What Happens​

When you submit an EOP ID for QRG generation, the system performs a multi-stage pipeline for each functional annex in the plan:

  1. Annex classification -- Each annex is categorized (functionality-based vs. emergency-type).
  2. Audience extraction -- Target audiences are identified from the annex content.
  3. Role mapping -- Audiences are mapped to K12 role IDs (teachers, administrators, support staff). When the EOP has more than 12 role tags, the system automatically batches the mapping step in parallel and merges the results.
  4. Content generation -- Structured action items are generated for each role, organized into BEFORE, DURING, and AFTER phases.

The result is a collection of role-specific QRGs, each containing phased content blocks.

Generation Flow​

Tool Sequence​

  1. Call k12-qrg-generation-kickoff with the EOP ID, user, role, and optional parameters (target roles, custom prompt).
  2. Receive a requestId with status accepted.
  3. Poll k12-qrg-generation-status with the requestId.
  4. When status reaches SUCCESS, call k12-qrg-generation-result to retrieve the generated QRGs.

What Gets Created​

Each generated QRG includes:

ComponentDescription
RoleThe K12 role this guide targets (e.g., teacher, administrator)
AnnexThe source annex the guide was derived from
BEFOREPreparation actions to take before an emergency
DURINGActions to take while the emergency is active
AFTERRecovery and follow-up actions after the emergency

A single generation request can produce many QRGs -- one per role per annex.

Form Handling​

The generation pipeline processes all annex forms from the EOP. Forms are handled based on their state:

  • A form marked as in-progress with no content is flagged as an error (the user has not started filling it in).
  • A form marked as completed with no content is treated as valid (the user accepted defaults).
  • Any form with content is processed normally.

This gives you visibility into which annexes were processed, which were skipped, and which need attention.

QRG Editing​

What Happens​

QRG editing modifies a single section (BEFORE, DURING, or AFTER) of an existing Quick Reference Guide. You provide the current content, the section identifier, and a prompt describing the change. The system returns an updated version of that section.

Editing Flow​

Tool Sequence​

  1. Call k12-qrg-editing-kickoff with:
    • userId and roleId -- Who is making the edit
    • section -- Which phase to edit: BEFORE, DURING, or AFTER
    • content -- The current HTML content of that section
    • prompt -- What to change (e.g., "Add a bullet about checking fire extinguisher locations")
    • quickReferenceGuide -- Metadata object identifying the QRG (name, type, instructionFor)
    • sessionId -- Optional correlation ID (pass null to start a new session)
  2. Receive a requestId with status accepted.
  3. Poll k12-qrg-editing-status with the requestId.
  4. When status reaches success, call k12-qrg-editing-result to retrieve the edited content.

What the Result Contains​

FieldDescription
requestIdTracking ID for this edit job
sessionIdSession this edit belongs to
statusTerminal status (success or error)
messageThe edited section content (HTML)
isEditBoolean confirming the content was modified

Status Lifecycle​

QRG Generation (UPPERCASE statuses)​

StatusMeaning
acceptedJob received and queued
PROCESSINGPipeline is classifying annexes and generating content
SUCCESSAll QRGs generated; results available
ERRORGeneration failed; check the result for details
CANCELLEDJob was cancelled before completion

QRG Editing (lowercase statuses)​

StatusMeaning
acceptedJob received and queued
processingAI agent is editing the section
successEdit complete; result available
errorEdit failed; check the result message
cancelledJob was cancelled before completion
note

QRG Generation uses UPPERCASE status values (SUCCESS, ERROR, PROCESSING, CANCELLED). QRG Editing uses lowercase (success, error, processing, cancelled). Your polling logic must account for this difference.

Cancellation​

Both QRG workflows support cancellation via k12-qrg-cancel. Pass the requestId and the appropriate jobType (generation or editing) to cancel a pending or in-progress job. The system transitions the job to CANCELLED (generation) or cancelled (editing) and stops further processing on a best-effort basis.

A cancelled job will not produce a result.

note

EOP editing uses a separate cancellation tool (k12-cancel-task-request) instead of k12-qrg-cancel. See the EOP Workflow page for details.

Next Steps​

Tools Reference

Full request and response schemas for all K12 tools

QRG Generation Deep Dive

Detailed pipeline stages, per-annex tracking, and advanced generation options