Asset-Lebenszyklus & Tracking-Modi
Das Asset-Modell unterscheidet zwei Dinge: den Tracking-Modus des Asset-Typs (PERSON / LOCATION / CONSUMABLE) und den Lebenszyklus-Status des einzelnen Assets. Der Modus bestimmt den Anker (Person oder Standort) und welche Aktionen möglich sind; der Status beschreibt den aktuellen Lebenszyklus-Zustand. Bei jedem Schreibvorgang prüft der Server, dass Modus, Status und Anker zueinander passen. Diese Seite ist die konzeptionelle Grundlage; die konkreten Endpunkte stehen in der Assets API.
🧭
Leitprinzip
Der Status erlaubt oder verbietet einen Anker — aber die AKTION setzt oder leert ihn, nie der Status als Nebenwirkung. Anker-Felder (assignedToId, locationId) werden nur durch Handlungen verändert (Ausgabe, Rücknahme, Install, Deinstall, Verloren-melden, Ausmustern). Lagerbestand ist der Status AVAILABLE (verfügbar/einsatzbereit). Der physische Ort (locationId) ist unabhängig vom Status und bei jedem Status erlaubt.
Tracking-Modi (AssetType.trackingMode)
Der Modus wird am Asset-Typ festgelegt und gilt für alle Assets dieses Typs. Er bestimmt, ob es sich um Verbrauchsmaterial handelt und ob Assets an Personen oder an Standorte gebunden werden. Solange der Typ keine Assets hat, ist der Modus frei änderbar; danach antwortet die API mit HTTP 409.
| Modus | Anker | User erlaubt? | Ausgabe-Weg | Besonderheit |
|---|---|---|---|---|
PERSON | User | ✅ | Checkout / Handover | Unikat; locationId zusätzlich möglich (Lager-/Büroort) |
LOCATION | Standort | ❌ nie | Install / Deinstall | kein Handover (Standort kann nicht bestätigen) |
CONSUMABLE | Menge | ❌ nie | Mengen-Zuweisung (ConsumableAssignment) | reduzierte Statusmenge; keine CMDB-Relations/Handover; immer standalone |
Standort ≠ „installiert": Ein AVAILABLE-Asset darf einen Standort (Lagerort) haben. „Installiert" ist der Status IN_USE, nicht „hat eine locationId".
Status-Taxonomie (11 Status)
Jedes Asset hat genau einen der folgenden 11 Status.
| Status | Bedeutung | User erlaubt? | typischer Anker |
|---|---|---|---|
ORDERED | bestellt, nicht geliefert | ❌ | — |
RECEIVED | geliefert, noch nicht einsatzbereit | ❌ | — |
AVAILABLE | verfügbar/einsatzbereit (Lager), frei zuweisbar | ❌ | optional locationId |
RESERVED | vorgemerkt — noch keine Ausgabe („reserviert für X" ist fachlich PENDING_ACCEPTANCE) | ❌ | — |
PENDING_ACCEPTANCE | Personen-Handover läuft, Bestätigung offen | ✅ (recipient) | User |
IN_USE | in Betrieb — PERSON: beim User / LOCATION: am Standort installiert | modus-abhängig | User oder Standort |
MAINTENANCE | in Wartung/Reparatur — Anker kann bleiben | ja (behält User) | evtl. User |
RETURN_PENDING | Rückgabe läuft, User hat es noch, wartet auf IT | ✅ (User) | User |
RETIRED | außer Betrieb (reaktivierbar) | ❌ | — |
LOST | verloren/gestohlen (Pflicht-Grund) | ❌ | locationId bleibt (letzter Ort) |
DISPOSED | entsorgt (final) | ❌ | — |
Status-Gruppen und ihre Regeln
| Gruppe | Mitglieder | Zweck |
|---|---|---|
| Ohne Benutzer | ORDERED, RECEIVED, AVAILABLE, RESERVED, RETIRED, LOST, DISPOSED | kein User erlaubt |
| Anker erforderlich | IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING | mind. ein Anker (User/Standort) |
| Ausgabe möglich aus | AVAILABLE, RESERVED, MAINTENANCE | Ausgangsstatus für Ausgabe/Installation |
| Rückgabe-Ziel | AVAILABLE, MAINTENANCE, RETIRED | Zielstatus bei Rücknahme (Checkin/confirmReturn) |
| Außer Betrieb | DISPOSED, RETIRED, LOST | keine neuen Lizenz-/Vertrags-Verknüpfungen; die Zuweisung muss aufgehoben sein |
| Begründung erforderlich | LOST | Pflicht-Kommentar (statusNote) |
| Verbrauchsmaterial | ORDERED, RECEIVED, AVAILABLE, RETIRED, DISPOSED | erlaubte Status für CONSUMABLE-Typen |
| Manuell setzbar | 9 (alle außer PENDING_ACCEPTANCE, RETURN_PENDING) | per Formular/Update/Bulk wählbar |
| Per Bulk setzbar | ORDERED, RECEIVED, AVAILABLE, RESERVED, MAINTENANCE, RETIRED, DISPOSED | per Bulk setzbar; nicht enthalten sind IN_USE (braucht ein Übergabeprotokoll) und LOST (braucht eine Begründung) |
| Endstatus | DISPOSED | keine weiteren Übergänge |
MAINTENANCE gehört bewusst weder zu „Ohne Benutzer" noch zu „Anker erforderlich": ein PERSON-Gerät in Wartung behält seinen User, ein LOCATION-Gerät seinen Standort. PENDING_ACCEPTANCE und RETURN_PENDING entstehen nur durch Aktionen — sie stehen nicht im manuellen Status-Dropdown, sondern werden ausschließlich über Übergabe und Rückgabe erreicht. IN_USE lässt sich manuell setzen (z. B. „Wartung beenden" für ein Gerät, das seinen User behalten hat); eine neue Zuweisung läuft dabei aber nur über Ausgabe, Installation oder Übergabe (siehe Regel unten).
Anker-Regeln
Der Server prüft bei jedem Schreibvorgang (Anlegen, Ändern, Bulk sowie Ausgabe, Rücknahme, Installation, Deinstallation, Übergabe) den resultierenden Zustand. Die erste verletzte Regel wird mit HTTP 400 und dem folgenden Fehlercode gemeldet:
| Regel | Bedingung | Fehlercode |
|---|---|---|
| Consumable ohne User | CONSUMABLE ⟹ assignedToId == null | CONSUMABLE_NO_DIRECT_ASSIGNEE |
| Consumable-Status | CONSUMABLE ⟹ status ∈ {ORDERED, RECEIVED, AVAILABLE, RETIRED, DISPOSED} | CONSUMABLE_INVALID_STATUS |
| LOCATION ohne User | LOCATION ⟹ assignedToId == null | LOCATION_ASSET_CANNOT_HAVE_USER |
| Status ohne Benutzer | Status der Gruppe „Ohne Benutzer" ⟹ kein User | ASSET_STATUS_ASSIGNED_CONFLICT |
| Anker-Pflicht | status ∈ {IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING} ⟹ User und/oder Standort | ASSET_STATUS_NEEDS_ANCHOR |
| PERSON strikt | PERSON ∧ status ∈ {IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING} ⟹ User (Standort reicht nicht) | PERSON_ASSET_NEEDS_USER |
| Notiz-Pflicht | status = LOST ⟹ Kommentar | ASSET_LOST_REQUIRES_NOTE |
Flow-Only-Regel: Ein PATCH /api/assets/:id darf assignedToId nicht im selben Aufruf mit dem Übergang nach IN_USE ändern → ASSET_ASSIGN_VIA_FLOW_ONLY. Zuweisung läuft ausschließlich über Checkout/Handover/Install. (Ein IN_USE→IN_USE-Besitzerwechsel und status-only-Änderungen bleiben erlaubt.)
Übergangsmatrix
Unikate (PERSON/LOCATION):
| Von | Nach |
|---|---|
ORDERED | RECEIVED, DISPOSED |
RECEIVED | AVAILABLE, MAINTENANCE, DISPOSED |
AVAILABLE | RESERVED, PENDING_ACCEPTANCE, IN_USE, MAINTENANCE, RETIRED, LOST, DISPOSED |
RESERVED | AVAILABLE, PENDING_ACCEPTANCE, IN_USE, LOST |
PENDING_ACCEPTANCE | IN_USE, AVAILABLE |
IN_USE | AVAILABLE, RETURN_PENDING, MAINTENANCE, RETIRED, LOST, DISPOSED |
MAINTENANCE | AVAILABLE, IN_USE, PENDING_ACCEPTANCE, RETURN_PENDING, RETIRED, LOST, DISPOSED |
RETURN_PENDING | AVAILABLE, MAINTENANCE, RETIRED, IN_USE |
RETIRED | AVAILABLE, DISPOSED |
LOST | AVAILABLE, DISPOSED |
DISPOSED | — (terminal) |
Verbrauchsmaterial (CONSUMABLE) — reduzierte Matrix:
| Von | Nach |
|---|---|
ORDERED | RECEIVED, DISPOSED |
RECEIVED | AVAILABLE, DISPOSED |
AVAILABLE | RETIRED, DISPOSED |
RETIRED | AVAILABLE, DISPOSED |
DISPOSED | — (terminal) |
Die drei Lebenszyklen
PERSON — Anker = User
- Direkt-Checkout: → IN_USE + User, sofort, CHECKOUT_DIRECT-Protokoll. Externe Empfänger: User anlegen + Mail. Kein Bestätigungsschritt.
- Handover mit Bestätigung: → PENDING_ACCEPTANCE + Recipient + Mail; Accept → IN_USE; Reject/Cancel → Revert auf Vorzustand.
- Rücknahme: Checkin / confirmReturn → AVAILABLE | MAINTENANCE | RETIRED, User geleert.
LOCATION — Anker = Standort (kein Handover)
- Installieren: → IN_USE + locationId (kein User), deployedAt gesetzt. Direkte IT-Aktion + Activity-Log.
- Deinstallieren: → AVAILABLE | MAINTENANCE, locationId geleert (Historie im Log), deployedAt geleert. Option keepLocation lässt den Standort stehen.
CONSUMABLE — Menge
Der Status hängt nicht an einem Anker: i. d. R. AVAILABLE, dazu quantity und Mengen-Zuweisungen (ConsumableAssignment, an einen User ODER einen Standort). Reduzierte Statusmenge, kein Handover, keine CMDB-Relations.
Feld-Wahrheitstabelle (was jede Aktion setzt/leert)
| Aktion | status | assignedToId | locationId | deployedAt | Protokoll |
|---|---|---|---|---|---|
| Direkt-Checkout (PERSON) | IN_USE | → User | — | → now | CHECKOUT_DIRECT; Mail extern |
| Handover erstellen | PENDING_ACCEPTANCE | → recipient | — | — | Mail an Empfänger |
| Handover Accept | IN_USE | (bleibt) | — | → now | Mail an Initiator |
| Install (LOCATION) | IN_USE | null | → Standort | → now | Activity |
| Checkin / confirmReturn | AVAILABLE|MAINTENANCE|RETIRED | → null | (bleibt) | → null | RETURN; Mail |
| Deinstall (LOCATION) | AVAILABLE|MAINTENANCE | null | → null | → null | Activity |
| Wartung setzen | MAINTENANCE | unverändert | unverändert | unverändert | Activity (statusNote optional) |
| Verloren melden | LOST | → null | bleibt (letzter Ort) | → null | Activity (statusNote Pflicht) |
| Retire / Dispose | RETIRED / DISPOSED | → null | bleibt | (retiredAt/disposedAt) | Activity; blockt bei aktiven Vertrags-/Lizenz-Links |
Felder (API)
AssetType
| Feld | Typ | Beschreibung |
|---|---|---|
trackingMode | Enum (Default PERSON) | PERSON | LOCATION | CONSUMABLE. Unveränderlich, sobald der Typ Assets hat (sonst 409). |
standalone | Boolean (Default true) | false = Einbau-Komponente (z.B. RAM/SSD): keine eigenständige Ausgabe/Handover, folgt dem Container via Co-Move. CONSUMABLE ist immer standalone. |
requiresConfirmation | Boolean (Default false) | Handover mit Empfänger-Bestätigung als Default für diesen Typ. |
hasTypePermissions | Boolean | Typ-Sperre: für Assets dieses Typs gelten nur die typbezogenen Berechtigungen (siehe Permissions). |
Asset
| Feld | Typ | Beschreibung |
|---|---|---|
statusNote | String? (Text) | Grund/Kommentar des aktuellen Status. Pflicht bei LOST, optional bei RESERVED/MAINTENANCE; beim Status-Wechsel ersetzt/geleert. Wird im Overview-Tab angezeigt und koexistiert mit dem Handover-damageReport (getrennte Fakten). |
quantity | Int (Default 1) | Menge — nur bei CONSUMABLE-Typ relevant. |
deployedAt | DateTime? | Zeitpunkt der Inbetriebnahme; außerhalb aktiver Zustände geleert. |
Verwandte Dokumentation
Endpunkte & Beispiele
Assets API — Checkout/Install/Handover, Relations, Impact
Inventory
Inventory API — Aktionsmodell, Missing/LOST, Auto-Account
Permissions
Permissions & RBAC — Typbezogene Berechtigungen