Added Add Device to Inventory Capability

Author: Karthik Satheesh Kumar

msp-onboarding/README.md

@@ -1,9 +1,10 @@
 # MSP onboarding workflow
 
-Automate the two most common MSP onboarding workflows using MSP API Credentials:
+Automate the three most common MSP onboarding workflows using MSP API Credentials:
 
 - **Create tenants**: Create new MSP tenants and provision a Central service in each.
 - **Assign devices to tenants**: Assign MSP-owned devices in an existing tenant's Central application and attach the subscription each device needs.
+- **Add devices to inventory**: Add new devices (serial number and MAC address) to the MSP workspace inventory.
 
 Devices and tenants details can be entered individually or uploaded in bulk via CSVs. It ships in two forms: a **guided web workflow** and a **Python CLI** (`onboarding.py`) for scripted, manifest-driven runs.
 
@@ -15,8 +16,9 @@ Devices and tenants details can be entered individually or uploaded in bulk via
 ## Features
 
 - **Create tenants**: create one or more new MSP tenants and provision a Central service in each, in the region you choose.
+- **Add devices to inventory**: add devices to the MSP workspace by serial number and MAC address, in batches of five, with per-device results; devices already in inventory are reported rather than re-added.
 - **Assign devices to tenants**: for each MSP-owned device, pick the tenant, the Central application within it, and the subscription to attach, the workflow submits the device assignment and the seat assignment together.
-- **CSV upload**: bulk-load tenants to create, or devices with their tenant and subscription mapping, from a CSV file. Rows are validated and errors are reported per row before anything is submitted.
+- **CSV upload**: bulk-load tenants to create, devices to add, or devices with their tenant and subscription mapping, from a CSV file. Rows are validated and errors are reported per row before anything is submitted.
 - **Bulk seat assignment**: apply one subscription key to every eligible device of a type, with the key's expiry shown first.
 - **Demo mode**: a deterministic catalog for exploring both journeys without credentials.
 
@@ -82,12 +84,20 @@ All calls go to the GreenLake Platform (GLP) API. Read calls run during discover
 | 1 | GLP | `GET` | `workspaces/v1/msp-tenants` | Lists managed tenants |
 | 2 | GLP | `POST` | `{base_url}/{workspace_id}/token` | Token exchange (MSP token → tenant-scoped token) |
 | 3 | GLP | `GET` | `service-catalog/v1/service-manager-provisions` | Central applications provisioned in the tenant |
-| 4 | GLP | `GET` | `devices/v1/devices` | MSP-owned device inventory (by serial, MAC, or ID) |
+| 4 | GLP | `GET` | `devices/v1/devices` | MSP-owned device inventory (by serial or ID) |
 | 5 | GLP | `GET` | `subscriptions/v1/subscriptions` | Subscription keys, capacity, and expiry |
 | 6 | GLP | `PATCH` | `devices/v1/devices` | Assigns devices to the tenant's Central application (batches of five) |
 | 7 | GLP | `PATCH` | `devices/v1/devices` | Assigns the subscription to those devices (batches of five) |
 | 8 | GLP | `GET` | `devices/v1/async-operations/{transaction_id}` | Polls each write to completion (up to 2 minutes) |
 
+### Add devices to inventory
+
+| Step | Service | Method | Endpoint | Description |
+|------|---------|--------|----------|-------------|
+| 1 | GLP | `GET` | `devices/v1/devices` | Checks which serials are already in the MSP inventory |
+| 2 | GLP | `POST` | `devices/v1/devices` | Adds devices to the MSP inventory (batches of five) |
+| 3 | GLP | `GET` | `devices/v1/async-operations/{transaction_id}` | Polls each add to completion |
+
 ## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/getting-started/installation/) — the workflow requires Python 3.10+, which uv installs on demand
@@ -106,7 +116,6 @@ All calls go to the GreenLake Platform (GLP) API. Read calls run during discover
 
    ```bash
    uv venv --python 3.12
-   source .venv/bin/activate
    uv pip install -r requirements.txt
    ```
 
@@ -147,7 +156,7 @@ uv run python server.py
 A run walks through:
 
 1. **Sign in** — live credentials, or demo mode
-2. **Choose a journey** — onboard new tenants, or add devices to existing tenants
+2. **Choose a journey** — onboard new tenants, add devices to inventory, or add devices to existing tenants
 3. **Setup, Devices, Review** — pick tenants and services, map every device to a tenant and subscription key, then review the read-only preflight
 4. **Confirm once** — the job starts, and the Review screen switches to live per-device and per-tenant results
 5. **Stop safely if needed** — the in-flight batch finishes, the rest is skipped, nothing is rolled back
@@ -183,6 +192,7 @@ The web workflow surfaces the plan and the run in one place:
 - **Setup stage**: tenant picker with per-tenant service and region discovery; tenants without an eligible service are set aside with the reason shown.
 - **Devices stage**: dense inventory table with CSV import, per-device or bulk subscription mapping, and seat capacity and expiry checks.
 - **Preflight review**: every tenant, device, and seat assignment with its validation result, plus an impact ledger of what will and will not run.
+- **Inventory add**: editable serial and MAC grid with CSV import, row-level validation, preflight, then per-device results.
 - **Live run**: the same review switches to per-device status chips (Writing, Complete, Already satisfied, Failed) and per-tenant progress as the job runs.
 
 <!-- screenshot: sign-in screen (docs/sign-in.png) -->

msp-onboarding/docs/onboarding-flow.mmd

@@ -9,22 +9,32 @@ flowchart LR
         b3["     Assign subscription     "]
     end
 
+    subgraph ai["Add devices to inventory"]
+        direction LR
+        c1["    Enter serials & MACs    "]
+        c2["Add devices to inventory"]
+    end
+
     subgraph ct["Create tenants"]
         direction LR
         a1["        Create tenant        "]
         a2["  Provision Central service  "]
     end
 
     creds -->|Authenticate| b1
+    creds -->|Authenticate| c1
     creds -->|Authenticate| a1
-    a1 -->|" Token exchange "| a2
+    c1 --> c2
+    a1 -->|"⇄ Token exchange"| a2
     b1 --> b2 --> b3
 
     classDef msp fill:#0f2a1c,stroke:#22c55e,color:#86efac
     classDef tenant fill:#0c2540,stroke:#3b82f6,color:#93c5fd
     classDef root fill:#1e293b,stroke:#60a5fa,color:#bfdbfe
-    class a1,b1,b2,b3 msp
+    class a1,b1,b2,b3,c1,c2 msp
     class a2 tenant
     class creds root
     style ct fill:#111827,stroke:#475569,color:#e2e8f0
     style ad fill:#111827,stroke:#475569,color:#e2e8f0
+    style ai fill:#111827,stroke:#475569,color:#e2e8f0
+    

msp-onboarding/docs/onboarding-flow.svg

@@ -20,6 +20,7 @@
 WRITE_LIMITS = {
     "v1": {"batch": 5, "requests_per_minute": 40},
 }
+INVENTORY_ADD_BATCH_SIZE = 5
 
 WORKSPACE_NAME_CONFLICT_MESSAGE = (
     "This workspace name is already in use globally across HPE GreenLake. "
@@ -39,6 +40,10 @@ def write_endpoint_path() -> str:
     return "devices/v1/devices"
 
 
+def inventory_add_batch_size() -> int:
+    return INVENTORY_ADD_BATCH_SIZE
+
+
 class AdapterError(Exception):
     def __init__(
         self,
@@ -96,9 +101,9 @@ def resolve_devices(
         glp_ids: Optional[list[str]] = None,
     ) -> list[DeviceInfo]: ...
     def resolve_device_by_serial(self, serial: str) -> DeviceInfo: ...
-    def resolve_device_by_mac(self, mac: str) -> DeviceInfo: ...
     def resolve_device(self, glp_id: str) -> DeviceInfo: ...
     def list_available_devices(self) -> list[DeviceInfo]: ...
+    def add_devices(self, devices: list[tuple[str, str]]) -> dict[str, str]: ...
     def resolve_subscription(self, key: str) -> SubscriptionInfo: ...
     def list_subscriptions(self) -> list[SubscriptionInfo]: ...
     def assign_devices(
@@ -116,3 +121,12 @@ def transaction_origin(self, transaction_id: str) -> Optional[str]: ...
     def poll_transaction(
         self, transaction_id: str, origin: Optional[str] = None
     ) -> TransactionResult: ...
+
+
+# Live 2026-08-28: GLP reports inventory-add failures only as serials in
+# `failedDevicesSerial` with no reason text, so this mapped message is the
+# per-device note for every rejection (invalid serial, wrong MAC, other owner).
+INVENTORY_ADD_REJECTED_ERROR = (
+    "GreenLake rejected this serial: not a valid serial/MAC pair, "
+    "or the device is owned by another workspace"
+)

msp-onboarding/msp_onboarding/adapter.py

@@ -24,7 +24,9 @@
 
 from .adapter import (
     AdapterError,
+    INVENTORY_ADD_REJECTED_ERROR,
     WORKSPACE_NAME_CONFLICT_MESSAGE,
+    inventory_add_batch_size,
     write_batch_size,
 )
 from .models import (
@@ -61,6 +63,13 @@
 DEVICE_D8_ID = "cccccccc-0008-0008-0008-000000000008"
 DEVICE_D9_ID = "cccccccc-0009-0009-0009-000000000009"
 
+ADD_ALREADY_PRESENT_SERIAL = "CNADD00001"
+# Live 2026-08-28: GLP returns MACs uppercase; the parser lowercases manifest MACs.
+ADD_ALREADY_PRESENT_MAC = "AA:BB:CC:DD:EE:01"
+ADD_REJECTED_SERIAL = "CNADD00003"
+ADD_REJECTED_MAC = "aa:bb:cc:dd:ee:03"
+PARTIAL_ADD_PLACEHOLDER_ERROR = INVENTORY_ADD_REJECTED_ERROR
+
 SUB_KEY_A = "KEY_A"
 SUB_KEY_B = "KEY_B"
 SUB_KEY_C = "KEY_C"
@@ -103,6 +112,7 @@ def utcnow(self) -> datetime:
     "bulk-partial",
     "tenant-name-conflict",
     "tenant-creation-systemic",
+    "partial-add",
 )
 
 # ---------------------------------------------------------------------------
@@ -225,18 +235,6 @@ def utcnow(self) -> datetime:
             management="MSP", assigned_state="UNASSIGNED", device_type="SWITCH",
         ),
     },
-    # MAC → serial (look up by serial to get full DeviceInfo)
-    "devices_by_mac": {
-        "aa:bb:cc:00:00:01": "CNXA001",
-        "aa:bb:cc:00:00:02": "CNXA002",
-        "aa:bb:cc:00:00:03": "CNXA003",
-        "aa:bb:cc:00:00:04": "CNXA004",
-        "aa:bb:cc:00:00:05": "CNXA005",
-        "aa:bb:cc:00:00:06": "CNXA006",
-        "aa:bb:cc:00:00:07": "CNXA007",
-        "aa:bb:cc:00:00:08": "CNXA008",
-        "aa:bb:cc:00:00:09": "CNXA009",
-    },
     "subscriptions": {
         SUB_KEY_A: SubscriptionInfo(
             subscription_id=SUB_A_ID, key=SUB_KEY_A,
@@ -308,6 +306,14 @@ def __init__(self, scenario: str = "success") -> None:
             }
             for info in CATALOG["devices_by_serial"].values()
         }
+        present = DeviceInfo(
+            glp_id="demo-inventory-add-present",
+            serial_number=ADD_ALREADY_PRESENT_SERIAL,
+            mac_address=ADD_ALREADY_PRESENT_MAC,
+            management="MSP",
+            assigned_state="UNASSIGNED",
+        )
+        self._inventory_add_devices = {present.serial_number: present}
         self._subscription_assignments: dict[str, str] = {}
         self._created_tenants: dict[str, TenantInfo] = {}
         self._provisioned_services: dict[str, list[ServiceInfo]] = {}
@@ -323,6 +329,7 @@ def __init__(self, scenario: str = "success") -> None:
         self._tenant_creation_failure_name: Optional[str] = None
         self.submitted_device_batches: list[list[str]] = []
         self.submitted_subscription_batches: list[list[tuple[str, str]]] = []
+        self.submitted_add_batches: list[list[tuple[str, str]]] = []
 
     def now(self) -> datetime:
         return FIXED_CLOCK
@@ -518,6 +525,9 @@ def resolve_devices(
         return resolved
 
     def resolve_device_by_serial(self, serial: str) -> DeviceInfo:
+        inventory_device = self._inventory_add_devices.get(serial)
+        if inventory_device is not None:
+            return replace(inventory_device)
         device = CATALOG["devices_by_serial"].get(serial)
         if device is None:
             raise AdapterError(
@@ -527,17 +537,17 @@ def resolve_device_by_serial(self, serial: str) -> DeviceInfo:
             )
         return self.resolve_device(device.glp_id)
 
-    def resolve_device_by_mac(self, mac: str) -> DeviceInfo:
-        serial = CATALOG["devices_by_mac"].get(mac)
-        if serial is None:
-            raise AdapterError(
-                path="devices",
-                code="device_not_found",
-                message=f"Device not found for MAC: {mac!r}",
-            )
-        return self.resolve_device(CATALOG["devices_by_serial"][serial].glp_id)
-
     def resolve_device(self, glp_id: str) -> DeviceInfo:
+        inventory_device = next(
+            (
+                device
+                for device in self._inventory_add_devices.values()
+                if device.glp_id == glp_id
+            ),
+            None,
+        )
+        if inventory_device is not None:
+            return replace(inventory_device)
         for device in CATALOG["devices_by_serial"].values():
             if device.glp_id == glp_id:
                 state = self._device_states[glp_id]
@@ -559,6 +569,32 @@ def list_available_devices(self) -> list[DeviceInfo]:
             and not self._device_states[device.glp_id]["subscription"]
         ]
 
+    def add_devices(self, devices: list[tuple[str, str]]) -> dict[str, str]:
+        batch_size = inventory_add_batch_size()
+        if len(devices) > batch_size:
+            raise AdapterError(
+                "execution.devices",
+                "batch_too_large",
+                f"At most {batch_size} devices are allowed",
+            )
+        self.submitted_add_batches.append(list(devices))
+        failures: dict[str, str] = {}
+        for serial, mac in devices:
+            if self._scenario == "partial-add" and serial == ADD_REJECTED_SERIAL:
+                failures[serial] = PARTIAL_ADD_PLACEHOLDER_ERROR
+                continue
+            present = self._inventory_add_devices.get(serial)
+            if present is not None and present.mac_address.lower() == mac.lower():
+                continue
+            self._inventory_add_devices[serial] = DeviceInfo(
+                glp_id=f"demo-inventory-{serial.lower()}",
+                serial_number=serial,
+                mac_address=mac,
+                management="MSP",
+                assigned_state="UNASSIGNED",
+            )
+        return failures
+
     def resolve_subscription(self, key: str) -> SubscriptionInfo:
         sub = CATALOG["subscriptions"].get(key)
         if sub is None: