feat(iot-hub): drop itemId-based deep links, keep only version URL
Consolidates to a single deep-link shape: /iot-hub/version/{itemVersionId}.
A specific version snapshot is a more useful sharable link than
"latest of item" — stable, unambiguous, and fits creator review
workflows ("please look at exactly this draft").
Removes /iot-hub/{itemId} and /iot-hub/{itemId}/preview routes, the
getPublishedVersion and getLatestVersion API methods (now unused), the
byVersion and preview route-data flags, and the iot-hub.item-preview
i18n key. Simplifies the resolver to a single getVersionInfo call with
the same warning-if-unpublished gate.
Big win for the IoT Hub backend contract: no new endpoints needed, only
a behavior guarantee on existing /api/versions/{versionId}.
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Ship `/iot-hub/{itemId}` (published), `/iot-hub/{itemId}/preview` (unpublished-with-warning), and `/iot-hub/version/{itemVersionId}` (stable version snapshot, warning if unpublished) deep links that resolve a version, navigate to its type-specific browse page, and open the existing detail dialog.
**Goal:** Ship `/iot-hub/version/{itemVersionId}` deep links that resolve a specific version, gate unpublished versions behind a security warning, navigate to the type-specific browse page, and open the existing detail dialog.
**Architecture:** A router-reachable `TbIotHubItemResolverComponent` owns resolution: fetch by itemId, (optionally) gate on a blocking warning dialog, then `router.navigate` to `/iot-hub/{typeSegment(type)}` carrying the version in `history.state`. The target type-page consumes the state once and opens the existing `TbIotHubItemDetailDialogComponent` via `IotHubActionsService`, with a new `preview` flag that adds an "Unpublished preview" badge. Zero ThingsBoard backend changes — install flows reuse existing versionId endpoints.
@ -924,14 +924,15 @@ If the smoke test uncovered issues that required fixes, stage and commit them wi
## IoT Hub-side changes required (recap)
From the design doc, the following IoT Hub (external) backend work is needed to ship the full deep-link feature end-to-end:
No new endpoints. Only behavior + CORS contracts on the existing `/api/versions/{versionId}` family:
1. **New endpoint**`GET /api/items/{itemId}/published` — latest PUBLISHED version as `MpItemVersionView`, 404 if none. Anonymous cross-origin.
2. **New endpoint**`GET /api/items/{itemId}/latest` — latest version regardless of state, preferring non-published and falling back to published. Anonymous cross-origin.
3. **Existing `GET /api/versions/{versionId}`** must return unpublished versions when queried directly by id (powers the `/iot-hub/version/{itemVersionId}` URL). Anonymous cross-origin, soft-secret authorization via versionId.
4. **`MpItemVersionView`**: for unpublished versions, either keep `publishedTime` falsy (`0`/`null`) or add an explicit `state` field. The frontend's `isPublished()` uses `publishedTime > 0` today.
5. **By-versionId endpoints** (`GET /api/versions/{versionId}`, `/readme`, `/fileData`, `POST /install`) must all serve unpublished versions when queried by ID — the install flow proxied from TB depends on this.
7. **CORS** on `/api/items/{itemId}/published`, `/api/items/{itemId}/latest`, and the by-versionId endpoints must permit cross-origin GET from any origin.
1. **`GET /api/versions/{versionId}`** must return the requested version regardless of state (PUBLISHED / DRAFT / PENDING_REVIEW / …). Anonymous cross-origin; versionId UUID is the soft-secret gate.
2. **`MpItemVersionView`** must allow the frontend to tell published from unpublished. Either `publishedTime` must be falsy (`0`/`null`) for non-published versions, or add an explicit `state` field. Frontend's `isPublished()` uses `publishedTime > 0` today.
3. **Related by-versionId endpoints** must also serve unpublished versions (required for install-from-deep-link):
Allow URLs of the form `http://<tb-host>/iot-hub/{itemId}`, `/iot-hub/{itemId}/preview`, and `/iot-hub/version/{itemVersionId}` to open the detail view for any IoT Hub item or specific version. The preview and by-version variants support creators testing unpublished content on any ThingsBoard instance; both gate unpublished versions behind a security warning before the detail view opens.
Allow a URL of the form `http://<tb-host>/iot-hub/version/{itemVersionId}` to open the detail view for a specific IoT Hub item version. The link works for published and unpublished versions alike; unpublished versions are gated behind a security warning before the detail view opens. Intended for creators sharing stable snapshots ("review exactly this draft") and for bookmarkable deep links to any version.
## Goals
- Shareable, bookmarkable deep links to IoT Hub items and versions.
- Three URL shapes with distinct semantics:
- `/iot-hub/{itemId}` — always latest published version of the item.
- `/iot-hub/{itemId}/preview` — latest version regardless of state (draft-first, falling back to published), gated by a security warning when unpublished.
- `/iot-hub/version/{itemVersionId}` — a specific version (stable snapshot, ideal for "review exactly this draft" links), gated by the same warning when unpublished.
- A single shareable, bookmarkable deep link shape: `/iot-hub/version/{itemVersionId}`.
- Published versions open directly.
- Unpublished versions (DRAFT / PENDING_REVIEW / …) open only after the user acknowledges a security warning, and the detail dialog then shows an "Unpublished preview" badge.
- Zero backend changes in ThingsBoard. Install/update flows reuse the existing versionId-based pipeline.
## Non-goals
- Authenticated access to unpublished content. Authorization is "public-by-link": whoever has the item UUID can fetch it.
- Authenticated access to unpublished content. Authorization is "public-by-link": whoever has the version UUID can fetch it.
- Full standalone page for item detail. The detail view stays as an Angular Material dialog; the deep link navigates to the type-specific browse page (`/iot-hub/widgets`, `/iot-hub/dashboards`, etc.) and opens the dialog over it.
- Preview-specific install semantics. Install from preview reuses the same flow as a normal install; only the counter policy on the IoT Hub side may differ (see IoT Hub-side changes).
- Install-specific semantics for unpublished versions. Install reuses the normal flow; only the IoT Hub-side install counter policy may differ (see IoT Hub-side changes).
- Item-level "latest" shorthand links (no `/iot-hub/{itemId}` or `/iot-hub/{itemId}/preview`). Creators share specific version ids; stable links are preferred over moving-target "latest" semantics.
4. On success, resolver navigates to `/iot-hub/{typeSegment(item.type)}` with router state `{ openItem: { version, preview: false } }` and `replaceUrl: true`.
5. `TbIotHubItemsPageComponent.ngOnInit` consumes `history.state.openItem`, resolves installed state, and calls `IotHubActionsService.openItemDetail(...)`.
6. The existing detail dialog opens with no visual changes.
7. On 404 or other error, resolver shows a toast and redirects to `/iot-hub`.
### Preview link: `/iot-hub/{itemId}/preview`
1. User pastes or clicks `/iot-hub/{itemId}/preview`.
2. `TbIotHubItemResolverComponent` mounts with `route.data.preview === true`.
4. If the resolved version `isPublished()` returns true (no draft exists; endpoint fell back to published), behave exactly like the published flow — no warning, no badge.
5. If the resolved version is unpublished, resolver opens `TbIotHubUnpublishedWarningDialogComponent` (`disableClose: true`).
- Cancel → `router.navigate(['/iot-hub'])`.
- "I understand the risk, continue" → resolver navigates to `/iot-hub/{typeSegment(item.type)}` with router state `{ openItem: { version, preview: true } }` and `replaceUrl: true`.
6. Type-page opens the detail dialog with `preview: true`; dialog renders an "Unpublished preview" badge next to the version in the sticky meta bar.
7. Install / Update / Remove / Open-entity actions behave identically to a published item. The preview badge is informational.
### Version link: `/iot-hub/version/{itemVersionId}`
1. User pastes or clicks `/iot-hub/version/{itemVersionId}`.
2. `TbIotHubItemResolverComponent` mounts with `route.data.byVersion === true`.
4. If the returned version is published → identical to the published flow (no warning, no badge). A published version link is a stable snapshot.
5. If unpublished → same warning-dialog gate as the preview flow; on confirm, navigates to `/iot-hub/{typeSegment(item.type)}` with `{ openItem: { version, preview: true } }`; dialog renders the "Unpublished preview" badge.
6. Install / Update / Remove / Open-entity actions behave as usual — all operate on the versionId already fetched, so install-from-version works end-to-end.
4. If the returned version is published → resolver navigates directly to `/iot-hub/{typeSegment(item.type)}` with router state `{ openItem: { version, preview: false } }` and `replaceUrl: true`. Detail dialog opens with no badge.
5. If the returned version is unpublished → resolver opens `TbIotHubUnpublishedWarningDialogComponent` (`disableClose: true`).
- Cancel → `router.navigate(['/iot-hub'])`.
- "I understand the risk, continue" → navigates to `/iot-hub/{typeSegment(item.type)}` with `{ openItem: { version, preview: true } }`; detail dialog opens with the "Unpublished preview" badge.
6. `TbIotHubItemsPageComponent.ngOnInit` consumes `history.state.openItem`, resolves installed state, and calls `IotHubActionsService.openItemDetail(...)`.
7. Install / Update / Remove / Open-entity actions behave as usual — all operate on the versionId already fetched, so install-from-version works end-to-end.
8. On 404 or other error, resolver shows a toast and redirects to `/iot-hub`.
## Angular routing
Three routes added to `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts`. All must come **after** existing named child routes (`widgets`, `dashboards`, `solution-templates`, `calculated-fields`, `rule-chains`, `devices`, `search`, `installed`, `creator/:creatorId`). Among the three new routes, the literal `version/:itemVersionId` must come **before** the `:itemId` wildcards so it matches first:
One route added to `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts`, placed after the existing named child routes (`widgets`, `dashboards`, `solution-templates`, `calculated-fields`, `rule-chains`, `devices`, `search`, `installed`, `creator/:creatorId`):
A UUID-shape check runs inside the resolver (not as a `UrlMatcher`) so an invalid id — in either param — produces a friendly toast instead of a generic not-found page.
A UUID-shape check runs inside the resolver (not as a `UrlMatcher`) so an invalid id produces a friendly toast instead of a generic not-found page.
public getPublishedVersion(itemId: string, config?: IotHubRequestConfig): Observable<MpItemVersionView> {
return this.http.get<MpItemVersionView>(
`${this.baseUrl}/api/items/${itemId}/published`,
{ params: this.buildParams(config) }
);
}
public getLatestVersion(itemId: string, config?: IotHubRequestConfig): Observable<MpItemVersionView> {
return this.http.get<MpItemVersionView>(
`${this.baseUrl}/api/items/${itemId}/latest`,
{ params: this.buildParams(config) }
);
}
```
Both accept `{ ignoreErrors: true }` so the resolver can handle failures inline rather than surfacing the global interceptor toast.
No new methods. The resolver uses the existing `getVersionInfo(versionId, config)` which calls `GET /api/versions/{versionId}` on IoT Hub. The resolver passes `{ ignoreErrors: true }` so it can handle failures inline rather than surfacing the global interceptor toast.
### ThingsBoard backend
Unchanged. `IotHubController.installVersion` and `IotHubController.updateInstalledItem` already operate on versionIds; the preview flow funnels into them without modification.
Unchanged. `IotHubController.installVersion` and `IotHubController.updateInstalledItem` already operate on versionIds; the version-link flow funnels into them without modification.
## i18n
Add to `ui-ngx/src/assets/locale/locale.constant-en_US.json` (and mirror into other locales):
- `iot-hub.unpublished-warning-text` — "This is a preview of unpublished content. It has not been reviewed by IoT Hub. Installing unverified content can introduce security and stability risks — only continue if you trust the creator."
- `iot-hub.unpublished-warning-confirm` — "I understand the risk, continue"
@ -239,24 +197,22 @@ Add to `ui-ngx/src/assets/locale/locale.constant-en_US.json` (and mirror into ot
## Edge cases
- **Invalid UUID shape**(either `itemId` or `itemVersionId`) → `iot-hub.deep-link-invalid-id` toast + redirect to `/iot-hub`.
- **404 from IoT Hub** → `iot-hub.deep-link-not-found` toast + redirect.
- **Preview URL resolves to a published version** (no draft exists) → no warning, no badge. Behaves identically to the published URL.
- **Version URL resolves to a published version** → no warning, no badge. Serves as a stable snapshot link to that version.
- **Unsupported `ItemType`** (future value not in `typeSegment`) → treated as `iot-hub.deep-link-fetch-failed`.
- **User hits Browser Back from the warning dialog** → dialog destroys with the resolver component; no zombie dialog.
- **User lacks `TENANT_ADMIN`** → the `/iot-hub` parent route guard blocks; no additional guard needed.
- **Preview or version URL for an already-installed item** → detail dialog shows its usual "Installed / Update / Open entity" actions against the resolved versionId. Creators can test update and install-one-more flows end-to-end.
- **Version URL for an already-installed item** → detail dialog shows its usual "Installed / Update / Open entity" actions against the resolved versionId. Creators can test update and install-one-more flows end-to-end.
- **Refresh after deep link has been resolved** → URL is now `/iot-hub/{typePage}`; `history.state.openItem` is cleared; user sees the type-page with no dialog (expected).
## Testing
- `TbIotHubItemResolverComponent` unit tests with mocked `IotHubApiService` and `Router`:
- published version happy path (no warning, no badge)
- unpublished version happy path (warning → confirm → dialog with badge)
- unpublished version, warning cancel → redirect to `/iot-hub`
- invalid UUID
- 404
- 5xx / network error
@ -289,26 +245,13 @@ Modified:
## IoT Hub-side changes required
These live in the IoT Hub repository, not ThingsBoard CE. The frontend deep-link feature cannot ship end-to-end until they land.
The three URL shapes depend on three data-access patterns: "item → latest published", "item → latest regardless of state", and "version by id". The first two need new endpoints. The third relies on the *existing*`/api/versions/{versionId}` endpoint but requires that it serve unpublished versions when queried by id — that's a behavior contract, not a new endpoint.
- Returns `MpItemVersionView` for the most relevant version regardless of state.
- Ordering: prefer the latest non-published (DRAFT / PENDING_REVIEW / …) version; fall back to the latest published version if none is in flight.
- `404` when the item has no versions at all.
- Anonymous cross-origin access.
- Soft-secret authorization model: the item UUID alone grants access.
3. **Behavior contract on existing `GET /api/versions/{versionId}`**: must return the requested version regardless of its state (PUBLISHED, DRAFT, PENDING_REVIEW, …). This powers the new `/iot-hub/version/{itemVersionId}` deep link. Anonymous cross-origin; the versionId UUID itself is the soft-secret gate.
4. **`MpItemVersionView` response for unpublished versions** must allow the frontend to tell published from unpublished. Either `publishedTime` must be falsy (`null` / `0`) for non-published versions, or an explicit `state` field must be added. Pick one; the frontend uses `isPublished(v)` based on `publishedTime` today. **This applies to all three endpoints above** — the frontend decides whether to show the warning by inspecting the payload it received.
5. **By-versionId endpoints must all serve unpublished versions** when queried directly by ID (required by the version URL + the install flow proxied through TB):
- `GET /api/versions/{versionId}`
These live in the IoT Hub repository, not ThingsBoard CE. No new endpoints are required — only behavior and CORS contracts on the existing `/api/versions/{versionId}` family.
1. **Behavior contract on existing `GET /api/versions/{versionId}`**: must return the requested version regardless of its state (PUBLISHED, DRAFT, PENDING_REVIEW, …). This powers the `/iot-hub/version/{itemVersionId}` deep link. Anonymous cross-origin; the versionId UUID itself is the soft-secret gate.
2. **`MpItemVersionView` response for unpublished versions** must allow the frontend to tell published from unpublished. Either `publishedTime` must be falsy (`null` / `0`) for non-published versions, or an explicit `state` field must be added. Pick one; the frontend uses `isPublished(v)` based on `publishedTime` today.
3. **Related by-versionId endpoints must also serve unpublished versions** (required by the install flow proxied through TB):
- `GET /api/versions/{versionId}/readme`
- `GET /api/versions/{versionId}/fileData`
- `POST /api/versions/{versionId}/install`
6. **Install counter policy**: decide whether `POST /api/versions/{versionId}/install` against an unpublished version increments counters. Recommended: skip, to avoid inflating published install metrics with creator self-tests. Note that creators can now install an unpublished version via *either* the preview URL *or* the version URL — the counter policy should treat them identically.
7. **CORS**: ensure `/api/items/{itemId}/published`, `/api/items/{itemId}/latest`, and the full`/api/versions/{versionId}/...` family permit cross-origin GET from any origin.
4. **Install counter policy**: decide whether `POST /api/versions/{versionId}/install` against an unpublished version increments counters. Recommended: skip, to avoid inflating published install metrics with creator self-tests.
5. **CORS**: ensure the `/api/versions/{versionId}/...` family permits cross-origin GET from any origin (same policy as `/api/versions/published`).
"unpublished-warning-text":"This is a preview of unpublished content. It has not been reviewed by IoT Hub. Installing unverified content can introduce security and stability risks — only continue if you trust the creator.",
"unpublished-warning-confirm":"I understand the risk, continue",
Andrii Shvaika
5 months ago