FAQ & Troubleshooting

For everyone — quick answers, glossary & fixes

FAQ & Troubleshooting

This page collects the questions security teams, administrators, and support staff ask most about the ERPat Patrol module, along with a plain-language glossary and step-by-step fixes for the issues teams hit first. Start with the quick-fix table to match a symptom to a cause, read the grouped answers for the detail, and use the glossary when a term is unfamiliar. For end-to-end workflows see Daily Operations; for setup and controls see Administration.

Quick-fix table

Match the symptom, apply the fix. Detailed answers for each row are in the sections below.

General questions

What is Patrol, in one sentence?

Patrol is ERPat's security-operations module: a searchable digital blotter, visitor check-in/out, a formal incident register with evidence chain-of-custody, plus shifts and handover, patrol rounds, equipment tracking, reports, an account-free public reporting channel, a governance/retention layer, and optional AI-assist. It reuses ERPat's existing file storage, audit log, notifications, and core attendance rather than rebuilding them.

Do I need special hardware to use it?

No. Patrol is software. Checkpoint scan codes are printable and can be scanned as QR/NFC or entered manually; "on duty" is read from your existing attendance clock-in, not a new device. An optional device registry exists for teams that want to record scan hardware, but it is not required to run rounds, log the blotter, or manage visitors.

Does Patrol replace payroll attendance or clock-in?

No — it relates to core attendance, it never rebuilds it. The "On Duty Now" panel reads a guard's open attendance record directly, and assigning a guard to a shift links that live attendance record. Payroll and the kiosk stay the single source of truth for clock-in and clock-out.

We run several companies (tenants). How does Patrol handle that?

Each tenant database is fully self-contained — there is no cross-tenant identifier; within a tenant, site_id is the location key. Enable the module and run its migrations per tenant. See Administration → Enabling the module for the multi-tenant note.

Access, menus & permissions

I can't see Patrol in the left menu at all.

Two causes, in order of likelihood:

1. The module is off. An administrator must switch on Patrol in Settings → Manage Modules (this sets module_patrol to 1). While it is off, the whole module — menu, screens, public endpoint, and background jobs — goes dark.
2. You lack the base permission. The top-level Patrol menu is gated by the patrol key. Ask an administrator to grant your role the patrol permission (category "Security: Patrol" in the Roles editor).

Patrol is in the menu, but a page like Incidents or Governance is missing.

Each sub-page is gated by its own area permission, so you see only the areas you are allowed into. For example, Incidents needs patrol_incident, Governance needs patrol_retention, Public Reports needs patrol_public_report_triage, and the AI page needs both patrol_ai and the AI toggle on. Ask an administrator to grant the matching area key — the full list is on Administration → Permissions matrix.

I get "no permission" when I try to add, edit, or delete.

You almost certainly have the view permission for that area but not the action key. Viewing, creating, amending, and deleting are separate: each area has a base key plus a _create / _update / _delete family (for example patrol_log, patrol_log_create, patrol_log_update, patrol_log_delete). Ask an administrator to grant the specific action key you need.

Why do some colleagues see everything without extra permissions?

Full-account administrators bypass every permission check. That is expected. To keep access tight, grant scoped Patrol roles to everyone else rather than making people administrators.

Editing, versions & deletion

Why can't I edit a submitted blotter entry or incident?

Patrol records are append-only by design — this is what makes the blotter and incident register trustworthy in a dispute. You never overwrite a submitted record. Instead, use Amend (which needs the area's _update key): Patrol writes a new version, marks it current, keeps the original byte-for-byte, and shows a v2, v3… badge with the full history. An amendment reason is recorded in the audit trail.

I can't delete an incident.

Deleting an incident needs patrol_incident_delete, and even then two rules can block it: an incident under an active legal hold cannot be deleted, and a restricted incident is hidden from you entirely unless you also hold patrol_evidence_view. If deletion is genuinely required, release the legal hold first (Governance), then delete. Note deletion is always a soft delete — the record is retained for the audit trail.

I can't delete a piece of equipment (an "issued asset").

Deletion is blocked while any assignment for that asset is still out — you cannot delete a radio or key that is currently checked out to someone. Return it first on the Assets page (Return the assignment, which sets the asset back to available), then delete the asset record.

What are the reference numbers (EVT-, INC-, VIS-…) and the vN badges?

Every record gets a permanent reference number minted the moment it is submitted — EVT- blotter, INC- incident, VIS- visit, HND- handover, RUN- round, PSR- public report, and the governance prefixes LGH- / PRV- / DSC-. They are never reused, so you can cite one with confidence. A vN badge means the record has been amended N times; the number climbs with each version.

Alerts, overstays & overdue flags

I'm not getting any incident alerts.

This is the single most common "it's broken" report, and it is almost always configuration, not a fault. Check each of the following:

• Recipients. Patrol's two events — patrol_incident_raised and patrol_incident_escalated — ship with no default recipients, on purpose, so nobody is spammed. Until an administrator opens Settings → Notifications and assigns recipients (team members and/or teams), no alert reaches anyone.
• Channel. Both events default to in-app on, email off. Turn on email in the same screen if you need it.
• The "notify" box. The raised alert only fires if the person creating the incident ticks the notify option on the form.
• The core migration. Incident alerts depend on one core migration (php erpat migrate:latest). If it hasn't run, the deep-link column and the two events won't exist.

What exactly triggers an escalation alert?

The patrol_escalate_incidents job runs every five minutes and escalates an incident only when it is critical, still open (not yet acknowledged), and older than patrol_escalation_minutes (default 15). It records an escalation action, fires patrol_incident_escalated, and de-dupes so a given incident escalates only once. Acknowledge critical incidents promptly to stop the clock.

A visitor shows an "overstay" flag, or a round / asset shows "overdue." What do those mean?

These are flags that surface risk; they are computed differently:

• Visitor overstay is calculated live on the visitor list — a checked-in visitor past their expected departure time gets a warning badge and is counted in the overstay total. It is not a scheduled job, so it appears immediately.
• Round overdue is set by the patrol_missed_rounds job (every 15 min): an in-progress round past its route's estimated time plus patrol_round_grace_minutes (15) is flagged once and written to the audit log.
• Asset overdue is set by the patrol_asset_overdue job (hourly): issued equipment past its expected-return time is flagged once.

AI-assist

The AI page says AI-assist is off / disabled.

AI-assist ships switched off and needs three gates, all passing, before anyone can request a suggestion:

1. Permission. You hold patrol_ai (and the module itself is on).
2. module_patrol_ai = 1. While this setting is off, the page shows a "disabled" notice and the AI menu item is hidden.
3. patrol_ai_dpa = 1. A one-time Data Processing Agreement acknowledgement that only an administrator can accept, on the AI page. Until it is accepted, the page shows the DPA prompt instead of the tools.

See Administration → Enabling AI-assist responsibly for the full turn-on sequence.

Does the AI write or change incidents on its own?

No. AI-assist is strictly human-in-the-loop. It can draft a narrative, suggest a classification, or write a handover briefing, but the output is held pending explicit human approval. A reviewer with patrol_ai_approve approves it; only then can a user with patrol_incident_update apply it — and applying only ever adds an action note to the incident, never rewrites the record. Every step is audited, and text is PII-redacted before it leaves the tenant.

An AI request failed.

The most common cause is that the underlying AkbAI provider is not configured for the tenant — in that case the request fails gracefully rather than hanging. A job row is still created first, so the attempt is recorded in the audit trail even on failure. Confirm AkbAI is configured, then retry.

Public security reporting

A member of the public lost their tracking code — can we look it up?

No, and this is by design for privacy. When someone submits a public report, the raw tracking code is shown to them exactly once and never stored — Patrol keeps only a one-way SHA-256 hash of it, and status lookups are verified against that hash. There is no way to recover the original code from the system. Ask the reporter to submit a new report to get a fresh code.

Someone is flooding the public report form.

Patrol throttles submissions per IP: five per hour (session-backed), with a database backstop that blocks an address after ten submissions in sixty minutes. The reporter's IP is never stored in the clear — only a hash, used solely for this throttling. For persistent abuse, mark the offending reports as spam in the triage queue.

Where do public reports go, and can the public see incident details?

Submissions land in the Public Reports triage queue (gated by patrol_public_report_triage), where staff set status (new / triaged / closed / spam), reply to the reporter, or add internal-only notes. Convert to incident maps urgency to severity (low→low, normal→medium, high→high, emergency→critical) and links the two. The public status page is PII-free: it never shows reporter details or internal staff notes.

Privacy, retention & legal holds

Will Patrol automatically delete our data?

Not until a Data Protection Officer configures it. Patrol seeds four placeholder retention policies inactive and with a blank retention period, so the daily patrol_retention_sweep job does nothing until someone both sets a period and switches a policy to active. Nothing is ever aged out by accident.

What does a retention policy actually do when active?

For its record type (activity log, incident, visit, or public report) it applies one action to records older than the retention period: anonymize (null out the personal fields), soft delete, or purge (hard delete). Strong safety rails apply: it excludes anything under an active legal hold, it never purges a record that has a logged disclosure or (for incidents) still has evidence, it caps each run, and it writes a deletion certificate to the audit log. Start with anonymize or soft delete before ever using purge.

What is a legal hold and when do I use one?

A legal hold freezes records so the retention sweep can never anonymise, delete, or purge them — use it whenever records may be needed for litigation, an investigation, or a regulator. You can hold a specific record or a whole record type within a date range. A held incident also cannot be deleted. Place holds before letting a retention policy run.

How do we handle a data-subject (DSAR) request?

Log it on the Governance page's Data-subject requests tab (needs patrol_privacy_request): record the request type — access, correction, or erasure — set a due date, and track it through to fulfilled or rejected. Pair erasure requests with the retention/anonymize tools and a legal-hold check.

Glossary

Plain-language definitions of the terms used across this guide and in the app.

Support & escalation

When a question is not answered above, work through these in order before escalating:

• Check the audit trail first. Every action in Patrol is logged under system-log category Security, with old and new values. For a "why did this change / who did this?" question, the log usually answers it without anyone having to touch a record.
• Treat a chain_break alarm as urgent. A CRITICAL chain_break entry (from the daily patrol_chain_verify job) means a tamper-evident chain no longer validates — a record was deleted, reordered, or altered outside the normal flow. Escalate to your administrator/DPO immediately; do not try to "fix" records yourself.
• Confirm the scheduler if anything time-based is silent. Escalations, missed-round and overdue-asset flags, license reminders, the retention sweep, and chain verification are all background jobs — inspect them with php erpat cron:list and run one with php erpat cron:run <slug>.

Escalate by topic to the right owner:

Related pages

• Overview — what Patrol is and how its parts fit together.
• Getting Started — enable the module, grant permissions, make your first entry.
• Daily Operations — the guard-facing SOPs behind these answers.
• Administration — permissions, settings, alerts, governance, and cron jobs.
• Data & Screen Reference — every screen, field, status, and permission key.
• Research & Evidence — the source files each claim is grounded in.