airqo-platform / airqo-platform/AirQo-frontend
Add "Decommission Device" action to Vertex
- Lenguaje dominante
- TypeScript
- Estrellas
- 23
- Forks
- 48
- Merge medio
- 15 h 24 min
- PR fusionados (30 d)
- 57
Descripción
# Add "Decommission Device" action to Vertex
## Summary
device-registry has a new endpoint that lets a device be permanently retired on the platform **without touching its upstream data provider (e.g. ThingSpeak)**. It's the safe alternative to the existing hard-delete flow, which removes a device from both the platform and ThingSpeak and is intentionally not exposed in the UI today — that's difficult to recover from for a device already deployed in the field.
Typical trigger: a hardware engineer finds a device's ThingSpeak channel was deleted and needs to mark it retired in our system, with zero risk of the action touching ThingSpeak.
Decommissioning preserves the full device record and its activity/readings history — it only changes the device's status and takes it out of rotation (off its site/grid, excluded from online-status checks).
## Endpoint
```
POST /api/v2/devices/activities/decommission?deviceName={name}
```
Same auth and request/response shape as the existing `recall` action, so this should be a quick add alongside it.
**Headers:** `Authorization: JWT `
**Request body:**
```json
{
"reason": "ThingSpeak channel deleted upstream",
"date": "2024-01-15T10:30:00.000Z",
"user_id": "60f1b2e4d4a5c123456789ab",
"firstName": "John",
"lastName": "Doe",
"userName": "johndoe",
"email": "john.doe@example.com"
}
```
| Field | Required | Notes |
|---|---|---|
| `reason` | No | Free text, max 500 chars |
| `date` | Yes | ISO 8601, ≤1 month past / ≤5 min future |
| `user_id` | Yes | Mongo ObjectId of the acting user |
| `firstName` / `lastName` / `userName` / `email` | No | Attribution fields |
**Success (200):** returns `createdActivity` and `updatedDevice` (with `status: "decommissioned"`, `isActive: false`).
**Failures (400):** device not found / device already decommissioned. **(500):** internal error — safe to retry, device state is auto-restored if this happens.
## Acceptance Criteria
- [ ] Add an API call for this endpoint alongside the existing `recall` call.
- [ ] Add a **"Decommission device"** action on the device details screen.
- [ ] Confirmation dialog treats this as permanent — there is currently no "undo"/reinstate endpoint.
- [ ] Prompt for the optional `reason` field — consider a short set of common causes (channel deleted, hardware lost/destroyed, end of life) plus free text.
- [ ] Surface this as the primary retire action for hardware engineers instead of any destructive delete option, since it can never touch ThingSpeak.
## Nice-to-have
Device list/detail responses may also carry two informational fields (no new endpoint needed):
| Field | Meaning |
|---|---|
| `channelStatus` | `"not_found"` when the backend's periodic check got a 404 from the upstream channel — almost always means it was deleted upstream |
| `channelStatusCheckedAt` | Timestamp of that check |
Worth optionally surfacing on the device details screen (e.g. "Channel not found since `channelStatusCheckedAt`") to prompt a hardware engineer toward decommissioning. It clears itself automatically once the channel responds again.
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.