Incident Management — Common Cases

How to read each case: start with the symptom/question, then read the expected behavior, how to verify it in the UI/API/data/code, the source anchor, and the Real-world example. These cases prioritize running behavior; open the linked spec/code when you need the original contract.

1. User Sees No Incidents

Check:

1. Does the user have an operational permission: INCIDENT_MANAGEMENT_VIEW, INCIDENT_MANAGEMENT_CREATE, or INCIDENT_MANAGEMENT_FULL_CONTROL. INCIDENT_MANAGEMENT only enables the menu; it does not grant view access.
2. If the user only has create-level access, was the incident created by that user.
3. Is the record inside the user's current Business Unit + Org access scope (view/full-control are limited by scope).
4. Is the user on the Active or Closed tab; Closed only includes Closed and Cancelled.
5. Are filters too narrow: date range, site, type, subtype, severity, status, attendee, account, creator, acknowledgement/signature requirement, search text.

Real-world example: A teacher opens the Incident menu but the list is empty. → Distinguish "no view permission" from "filters too narrow". → The user only has INCIDENT_MANAGEMENT (menu only, no view grant) → add ..._VIEW before records appear.

2. Cannot Edit Incident

Incidents are only editable in allowed statuses, commonly:

Status	Edit?	Note
Draft	Yes	Creator/create-level acts on their own record.
Changes Requested	Yes	Edit based on reviewer comment, then submit again.
Reopened	Yes by allowed actions	After reopen, edit/submit/cancel may be available.
Submitted, Under Review, Approved, Sent To Customer, Closed	Usually no	Use workflow action instead of editing fields.

If the UI does not show an action, check GetAllowedActions and permission level.

3. Manager Cannot Approve/Request Changes

Requires INCIDENT_MANAGEMENT_FULL_CONTROL (note: INCIDENT_MANAGEMENT only enables the menu, not governance) and a valid status:

• Submitted: Start Review, Request Changes, Approve, Cancel.
• Under Review: Request Changes, Approve, Cancel.
• Approved: Send To Customer, Close.

Create-only users cannot perform governance actions for incidents created by other users.

Real-world example: A shift lead needs to approve an incident report submitted by a teacher. → Ensure only users with governance permission can approve/request changes. → Requires INCIDENT_MANAGEMENT_FULL_CONTROL and status Submitted/Under Review before the action appears.

4. Sending to Customer Does Not Create Expected Acknowledgement

Check:

1. Is the incident already Approved.
2. Does recipient list contain valid contacts.
3. Which contact is primary contact; only primary carries acknowledgement responsibility.
4. Does the incident have RequiresAcknowledgement / RequiresSignature as expected.
5. Does a duplicate acknowledgement already exist for the contact/incident.
6. If attaching latest document, does the incident have a valid generated document.

Real-world example: Sending an incident report to the family does not create an acknowledgement request. → Ensure the right person is asked to acknowledge. → Incident must be Approved and have a valid primary contact before acknowledgement is created for the primary contact.

5. Customer Cannot See Incident in Portal

Check:

• Customer is in the correct account.
• FormAcknowledgement belongs to that account.
• Acknowledgement is not NotificationOnly; notification-only does not appear in the actionable list.
• Detail link passes the correct ackId.
• Generated document is attached to the correct acknowledgement/attendee document.

6. PDF Report Missing File or Attendee

Debug direction:

1. Check generate PDF request: mode, attendeeRecordIds, internalOnly.
2. Check whether BuildPdfDatasetAsync collects the correct attendee/body marker/acknowledgement.
3. If PDF attachment merge is needed, check whether the attachment is a PDF and eligible by scope.
4. Check whether the generated document BlobName exists and can be downloaded.

7. Was Notification Sent?

In staff detail, view Notification History:

Signal	Check
No job	Did the business action create a notification job; did the event/action run.
Job exists but no message	Worker Generator/Distributor and template/config.
Customer did not receive	Contact email/SMS, delivery channel, suppression/provider status.
Acknowledgement is not Sent	Did the notification handler update acknowledgement after processing.
BU has no configured template	Worker must fall back to built-in default template, not skip/fail job.

8. Description Does Not Prefill or Is Overwritten

Check:

1. Has incident type been selected; Description only prefills when the field is empty and type is selected.
2. Does the type have a saved template; if not ⇒ use built-in default.
3. Has the user manually edited Description — once edited, the system does not auto-refresh when type/date/site/attendee changes.
4. If raw tokens like appear, that is a materialize bug; placeholders must resolve to readable text.

9. Generate PDF: Wrong Visibility / Content

• Uncheck Internal Use Only ⇒ always one PDF per attendee, customer-visible, does not ask combined/per-attendee.
• Check Internal Use Only ⇒ only then show the choice to combine into one report (default) or generate one PDF per attendee.
• Customer-visible PDF must not contain Created By, Internal Notes, attendee Description, or acknowledgements from another account.

Real-world example: An incident involves three children, and each family needs a copy without exposing the others. → Separate customer copies from the internal report. → Leave Internal Use Only unchecked → generate one customer-visible PDF per attendee, without internal notes or acknowledgements from another account.

10. Cannot Open Settings / Template

• Settings icon and settings API are only available to INCIDENT_MANAGEMENT_FULL_CONTROL; other permissions are denied.
• Saving a template writes blob form-config-json and sets PrefillBlobName for the active version of that type, scoped by Business Unit.

“PDF is blocked by CSP or loses context on return”

Use PdfDocumentPreview for generated PDF and check that incident routing preserves onsite/app query context. Do not add a new inline iframe or widen access scope to fix a display issue.

Real-world example: The webview cannot render the PDF but the download endpoint returns a valid file. → Keep the generated document; fix the CSP-safe preview and preserve query context during navigation.