Incident Management — Core Concepts
Aggregate: IncidentFormInstance
Incident Management uses the shared Forms infrastructure, but the domain boundary is clear:
| Component | Meaning |
|---|---|
| IncidentFormInstance | Readable aggregate name; implementation is FormInstance with FormCategoryId = IncidentManagement. |
| FormTypeId | Classifies Incident (101), Accident (102), Illness (103). |
| StatusId | Incident workflow status. |
| BusinessUnitId | Data and configuration boundary. |
| OrgId / Site | Site where the event happened. |
The aggregate root is the incident. Attendee links, acknowledgements, generated documents, notification flags, and history all revolve around the incident id/guid.
Status Lifecycle
| Status | Meaning | Usual handler |
|---|---|---|
| Draft | Being drafted, not yet sent for review. | Creator |
| Submitted | Submitted, waiting for review. | Manager/full-control |
| Under Review | Being reviewed. | Manager/full-control |
| Changes Requested | Changes were requested. | Creator |
| Approved | Approved, can be sent to customer. | Manager/full-control |
| Sent To Customer | Acknowledgement was created and notification enqueued. | System/customer |
| Partially Acknowledged | Some acknowledgements are complete. | Customer |
| Acknowledged | All actionable acknowledgements are complete. | Customer/system |
| Closed | Finished. | Manager/full-control |
| Reopened | Reopened after close. | Manager/full-control |
| Cancelled | Cancelled before completion. | Manager/full-control |
Permission Levels
| Permission | Behaviour |
|---|---|
INCIDENT_MANAGEMENT | Only controls menu/entry point visibility; by itself it does not grant create/view/full-control. |
INCIDENT_MANAGEMENT_CREATE | Create, save draft, update, submit, and delete incidents created by the current user (when status allows). |
INCIDENT_MANAGEMENT_VIEW | View list/detail within Business Unit + Org access scope, read-only. |
INCIDENT_MANAGEMENT_FULL_CONTROL | Full control: review, request changes, approve, send, close, reopen, cancel, settings. |
Important rules:
- Create-only users only see/edit their own incidents; they cannot perform governance actions.
- View and full-control are limited by current Business Unit + Org access scope; filters outside scope must not expose records.
- Without any operational permission (
CREATE/VIEW/FULL_CONTROL), list/detail/mutations and settings are denied. - Settings icon and settings API are only available to
INCIDENT_MANAGEMENT_FULL_CONTROL.
Attendee and Body Marker
An incident can involve multiple attendees. Each attendee record can have:
| Field | Used for |
|---|---|
| Account / Attendee | Identifies the customer account and affected attendee. |
| Role | Attendee role in the event. |
| Staff description | Internal note. |
| Customer-visible note | Content visible to the customer. |
| Body marker JSON | Marks a position on the body map when needed for medical/accident reports. |
Customer detail only shows attendees/notes related to that customer's acknowledgement; it does not need to expose other attendees.
Attachment and Generated PDF
| File type | Source | Stored where | Used when |
|---|---|---|---|
| Attachment | Staff upload | Blob + attachment record | Images, PDFs, internal documents, or attendee-linked files. |
| Generated PDF | Reporting service | Generated document Blob + GeneratedAttachment | Report for internal viewing or sending to customer. |
| Signature | Customer submit | Blob signature | When acknowledgement requires a signature. |
The Generate PDF popup controls output with one visibility choice:
- Checkbox Internal Use Only is unchecked by default ⇒ report is customer-visible, always generates one PDF per attendee (does not ask combined/per-attendee).
- When Internal Use Only is checked ⇒ shows a second choice: combine all attendees into one report (default) or one PDF per attendee, both marked internal-use-only.
PDFs include acknowledgement status and signature by attendee depending on visibility mode:
- Internal report: includes all active acknowledgements for the attendee (except notification-only) — contact name, account name, status, acknowledgement time, signature (base64) if any.
- Customer-visible report: includes only acknowledgements whose
AccountIdmatches the attendee account; it does not expose acknowledgements from other accounts. - No signature ⇒ the entry still shows status + time, signature field is null, and the template does not render the signature block.
Acknowledgement
FormAcknowledgement connects an incident to a customer contact.
| Acknowledgement type | Meaning |
|---|---|
| Acknowledged | Primary contact must confirm they have read/accepted. |
| Signed | Primary contact must sign confirmation. |
| NotificationOnly | Contact is notified but is not responsible for submitting acknowledgement. |
When a customer acknowledges/signs, incident status is updated to PartiallyAcknowledged or Acknowledged based on all actionable acknowledgements.
Customer Visibility of Fields
Each incident field is classified as customer-visible or internal-only, with a clear label on the staff form:
| Group | Customer-visible | Internal-only |
|---|---|---|
| Incident | Title, Description, Action Taken | Created By, Internal Notes |
| Attendee | Role, Customer Visible Notes | Description |
| Body marker | Body Part, Injury Type, Note, Diagram | — |
- Internal Notes: internal-only field directly below Action Taken; stored with the incident and returned to admin/staff, but not returned to customer.
- Customer Portal and customer-use PDFs expose only customer-visible fields; admin/staff and internal-use PDFs see both.
Description Template & Materialize
| Concept | What it is |
|---|---|
| Description template | Default Description template per incident type (Incident/Accident/Illness), edited in settings (full-control). |
| PrefillBlobName | Points to a form-config-json blob (field-prefill format) that stores the template on the active FormTemplateVersion for the type, by Business Unit. |
| Materialize | On create/edit, Description is pre-filled as plain editable text — placeholders are resolved, raw tokens are not shown. |
- Type has no saved template ⇒ use the built-in default for that type.
- Placeholders:
,,,,; missing values ⇒ replace with readable text, do not leave raw tokens. - Description auto-refreshes when type/date/time/site/attendee changes only if the user has not edited it manually; once edited manually ⇒ keep it, do not overwrite.
Access from Onsite App
Incident Management is available from the Onsite App (tablet/mobile webview):
- Entry "Incident" on the landing page only appears when the user has incident permission; without permission it is hidden (not "coming soon").
- List is limited by the site identifier provided by the wrapper: one site ⇒ hide site selector; multiple sites ⇒ selector only lists granted sites.
- Viewing/downloading/uploading attachments (PDF, image) works inside the webview; list and form adapt to tablet/mobile viewports.
Notification and History
- IncidentSubmitted: async job when staff submit; sends email to configured staff/manager recipients for the Business Unit (does not create acknowledgement/portal message). No recipient ⇒ job completes without sending.
- IncidentSentToCustomer: job when sending report to customer contact; creates email/SMS according to selected channels and portal user message if the contact has a portal user id.
- Template fallback: Business Unit has no template configured for the event type ⇒ worker uses built-in default template, does not skip/fail the job.
- Unified customer template: one template for Incident/Accident/Illness; the concrete type renders through an incident type placeholder.
- After recipient processing completes, acknowledgement moves to status Sent.
- EntityHistory: audit timeline by incident guid; snapshot is written at major milestones (submit, approve, send, close).
- Notification history: staff can review notification jobs, event type, recipient, and delivery method.
Next: Architecture & data.