Troubleshooting and deployment safety
Troubleshooting and deployment safety
Section titled “Troubleshooting and deployment safety”Rollout states
Section titled “Rollout states”| State | Meaning | Recommended action |
|---|---|---|
| Legacy active | New enrollments use deployed legacy settings. | Finish the global blueprint and compatibility report. |
| Ready to activate | Global policy and validations are ready. | Run representative simulations, then activate deliberately. |
| Policy engine active | New enrollments use matching published policies. | Monitor events and keep legacy aliases for the compatibility release. |
Common operator problems
Section titled “Common operator problems”“Publish the global blueprint first”
Section titled ““Publish the global blueprint first””A scoped inheriting draft needs an active published global ancestor. Create or publish the global blueprint, then retry the scoped policy.
Inherited value is not what I expected
Section titled “Inherited value is not what I expected”Check the source badge and the strict ancestor list. Then run a simulation with the actual school, student type, program, period, and year level to see every matching layer.
Simulation says a required fact is unavailable
Section titled “Simulation says a required fact is unavailable”The rule failed closed. Confirm that the representative student has the data and that its integration handler is registered. Remove or override the rule only if the school intentionally does not enforce it.
Simulation checksum changed
Section titled “Simulation checksum changed”The saved draft, an inherited active version, or publication permission candidate changed. Save and run simulation again. Never reuse an older checksum.
Workflow validation reports a cycle or unreachable step
Section titled “Workflow validation reports a cycle or unreachable step”Keep all destinations forward, confirm the entry is the first card, make at least one final card, and ensure each non-final card has the protected Otherwise destination.
Extension is read-only
Section titled “Extension is read-only”The handler is compatible but does not implement operator metadata. It can run and be restored from backup. Ask the extension maintainer to implement EnrollmentOperatorSchemaProvider.
Deployment-safety checklist
Section titled “Deployment-safety checklist”- Apply additive migrations before enabling UI access.
- Keep the Pennant rollout flag off during import and backfill.
- Confirm original
student_enrollment.statusstrings are unchanged. - Review unknown-status and duplicate-enrollment migration warnings.
- Publish and simulate a legacy-compatible global preset.
- Test public, continuing, administrator, API, Filament, College, and TESDA paths while legacy remains active.
- Activate only after the compatibility report is clear.
- Monitor workflow failure and retry events after activation.
- Keep legacy route adapters and read-only settings for the compatibility release.
The enrollment revamp migration creates an unpublished compatibility draft with the explicit default actions. It does not publish that draft, change the active version, or activate DynamicEnrollmentPolicies. Review and simulate it like any other draft.
Runtime guarantees
Section titled “Runtime guarantees”- Existing rows default to
legacy. - Rollout changes only the runtime assigned to future enrollments.
- Every policy enrollment pins an immutable compiled snapshot.
- Controllers and Filament actions advance through the coordinator; they do not directly mutate workflow state.
- The legacy
statusvalue remains the API/reporting projection. - Legacy department and cashier routes adapt to semantic policy actions for one compatibility release.
- No-receipt and quick-enroll behavior on the policy runtime exists only when the current blueprint has an authorized payment transition configured for it; the transition requires an audited reason.
- New payments link directly to one enrollment. Legacy payment backfill links only unambiguous matches, and destructive reversal fails closed when an exact enrollment payment cannot be established.
Production operations
Section titled “Production operations”After configuration or code deployment, restart long-running processes (queue workers, scheduler) so new registry metadata and environment-backed documentation URLs are visible. Cache only immutable compiled snapshots; publication invalidates policy-list metadata.
Set the contextual help base URL with:
DOCUMENTATION_URL=https://your-docs.example.eduThe default points to the hosted KoAkademy documentation. Self-hosted schools can override it without changing application code.
Escalation evidence
Section titled “Escalation evidence”When reporting a failure, include the enrollment ID, workflow runtime, snapshot/version ID, current step, event type, handler key, retry count, actor, and structured failure metadata. Do not include student secrets in public issue reports.