IoT alerts that create jobs
Who this is for: dispatchers, managers and administrators who receive device alerts.
What you will learn: how a device alert becomes a job in the queue, how to triage it, and how to keep device credentials safe.
How an alert arrives
A device sends an authenticated alert to:
POST /api/v1/iot/alerts
The alert creates an unassigned job with source IoT alert. The job is deliberately not assigned: a person decides who attends and when.
What the job contains
| Field | Meaning |
|---|---|
| Title | The alert title, or the device name and alert type |
| Priority | critical → Urgent, warning → High, info → Normal |
| Description | The alert text, device identity and sensor reading |
| Dispatch notes | The sensor reading at the time of the alert |
| Source | IoT alert |
| Status | The default new-job status, normally Pending |
| Assets | Linked when the alert identifies an asset |
The alert is also recorded as a job note, so the original device wording is never lost. A retried alert with the same alert_id returns the original job instead of creating a second one.
Triage the alert
- Open Jobs and filter Source: IoT alert.
- Open the job and read the device, sensor and reading.
- Check whether the site is safe and whether stock or customers are affected.
- Set the visit window and priority.
- Assign a worker, or raise a case if the alert is a safety event.
- Record what you found. The alert is not a diagnosis.
Warning: A device alert is not an emergency call. If there is a risk to life, follow the emergency procedure first, then record it.
Credentials and retries
- Each device has a serial and a secret. The secret is stored as a hash.
- A wrong secret returns
401and creates nothing. - The device may retry. Send the same
alert_idto stay idempotent. - Rotate the secret if a device is lost or replaced.
- Use HTTPS in production so the secret is never sent in clear text.
Example
php scripts/demo-iot-alert.php --serial=DEMO-DEVICE-002 \
--secret=demo-device-secret-DEMO-DEVICE-002 \
--severity=critical --alert-id=coldroom-2-001
The response includes the job public id, priority, status, whether it is assigned and whether it was a duplicate.
Check your understanding
- Why is an alert job left unassigned?
- How do you stop a retry from creating two jobs?
- What priority does a
warningalert get?
Related: Jobs and workflow · Scheduling and dispatch · Devices and sensors
Related articles
Who this is for: everyone in the office workspace. What you will learn: where the help centre lives, how to search it, and how to get from a screen to the right article. Open the h...
Who this is for: office administrators, dispatchers, managers and finance users. What you will learn: how to sign in to the right workspace, find your way around, and set up your p...
Who this is for: office administrators, dispatchers and managers. What you will learn: how FieldElite models a customer, its sites and the people on site — and how to give a custom...
Who this is for: office administrators, dispatchers, managers and supervisors. What you will learn: how to raise a job, assign it, move it through the status workflow, and close it...