ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2#389
ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2#389ViacheslavKlimov wants to merge 21 commits into
Conversation
Adds a consolidated single-page user guide for the ThingsBoard CLI as a shared MDX include rendered by thin product stubs for PE, Cloud, and Cloud EU, and wires it into the AI sidebar group of each product (gated by isPE so CE does not pick it up).
Adds a "Pulling changes back from ThingsBoard" subsection covering the three calling shapes, the --solution / --dry-run / --with-credentials / --force flags, and the git-clean default safety. Also points the "UI edits are overwritten" caution and Limitations entry at tb pull as the recovery path.
ViacheslavKlimov
changed the title
The Java and Python clients track the ThingsBoard server release line, so a single TB_VER alias of CE_FULL_VER avoids the maintenance overhead of bumping per-client constants in lockstep with the platform.
Both guides are reorganized into eight task-oriented sections (Installation, Quickstart, Authentication, Rate-limit handling, Working with entities, Telemetry and attributes, Listing and querying entities, Entity groups [PE-gated], Error handling, More examples) and API signatures are verified against the live client repos. Helpers encode the CE/PE/PaaS divergence (e.g. saveDevice arity, entity group methods) so the same include serves all editions without conditional UI.
Drop the legacy REST client entries from the sidebar and card (they remain reachable via the cross-link on each new client guide), rename "Server-side Clients" to "Clients & CLI", add the CLI link with a "New" badge, and reference the CLI via slug (not raw link) so the per-version sidebar filter keeps it within its own sidebar instead of duplicating "APIs & SDKs" groups across editions.
The CLI is a separate command-line tool, not a built-in feature, so the default peFeature wording reads wrong here. Banner now supports a slot override that replaces (not appends to) the default sentence, and the new CE CLI stub uses it to render "ThingsBoard CLI works only with ThingsBoard Professional and ThingsBoard Cloud." Existing peFeature callers all use the self-closing form, so the change is backward- compatible.
ViacheslavKlimov
changed the title
The PE entity-groups Aside in the Java and Python REST client guides pointed at user-guide/entity-groups and user-guide/role-management, which don't exist — the canonical pages live at user-guide/groups and user-guide/roles.
ViacheslavKlimov
left a comment
ViacheslavKlimov
left a comment
There was a problem hiding this comment.
Review summary
Reviewed 30 changed files in ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2. Left 14 comments inline. The PR is largely well-structured — new content is thorough, the peFeature banner refactor is clean, and the release-notes/upgrade-instructions/releases-table updates are internally consistent. Main areas to double-check before merging: (1) MDX rendering bug where JSX expressions inside backticks won't evaluate, (2) whether the new edition-specific Maven/PyPI artifacts actually exist at TB_VER for PE/PaaS, (3) the test.pypi.org install command for a page marketed as New.
Additional findings
Observations about behavior outside the immediate diff lines:
src/content/_includes/docs/edge/reference/java-rest-client.mdxandpython-rest-client.mdx— The edge sidebar'sServer-side REST Clientssection is removed (bothedgeSidebarandedgePeSidebar), but the include files and their edge / edge-PE stubs still exist. They're now orphaned in the edge sidebar — reachable only by direct URL. If the intent is to retire them on the edge side, follow up with stub-file removal + redirects insrc/data/redirects.ts. If they should stay, restore the sidebar section (the deprecation<Aside>at the top of each include already steers readers to the new client).src/models/upgrade-instructions.ts:74,140— Marking only 4.3.1.1 and 4.2.2.1 asvulnerable: truewhile older 4.3.0.1 and 4.2.1.2 still don't carry the flag may be intentional (those families pre-date the CVE list in this patch), but worth a sanity check — most of the CVEs in the security section look like things older patches would also be exposed to.
This review was auto-generated. Findings may contain errors — please verify before applying changes.
|
|
||
| <Code lang="bash" code={pipInstall(props.product)} /> | ||
|
|
||
| Snippets below import models from `{importModule(props.product)}.models` and exceptions from `{importModule(props.product)}.exceptions`. Each snippet is self-contained — open it inside a `with ThingsboardClient(...) as client:` block, replace placeholders like `YOUR_API_KEY_VALUE` and `YOUR_DEVICE_ID` with real values, and run it. The client is synchronous and not thread-safe — create one instance per worker. |
There was a problem hiding this comment.
MDX inline code spans don't evaluate JSX expressions inside them — the rendered page will show the literal text {importModule(props.product)}.models instead of e.g. tb_pe_client.models. Same problem for {importModule(props.product)}.exceptions on this line. Either drop into JSX (<code>{${importModule(props.product)}.models}</code>), precompute the strings as another export const and interpolate them with {...} outside backticks, or move this guidance into a <HostCode> block where template literals do interpolate.
| 2. **Install the CLI.** | ||
|
|
||
| ```bash | ||
| uv tool install thingsboard-cli --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match |
There was a problem hiding this comment.
This points users to https://test.pypi.org/simple/ — the test PyPI mirror — with --index-strategy unsafe-best-match. For a page marketed with a New badge in the sidebar (suggesting GA), pointing to test PyPI is a red flag. If the CLI is still preview-only, the doc should say so loudly (status callout, version qualifier). If it's released, this should point to the production index without the unsafe-best-match strategy.
There was a problem hiding this comment.
Addressed in abf51370c — test.pypi.org was a temporary publishing target; the CLI is now published to production PyPI, so the install command uses the default index.
| import { Products } from '~/models/site.models'; | ||
| import { Steps, Aside } from '@astrojs/starlight/components'; | ||
|
|
||
| <Banner variant="peFeature" product={props.product} path="user-guide/cli"><Fragment>ThingsBoard CLI works only with <DocLink product={Products.PE} path="user-guide/cli" target="_blank">ThingsBoard Professional</DocLink> and <a href="/installations/?product=thingsboard-cloud" target="_blank" rel="noopener noreferrer" class="tb-banner-ext"><b>ThingsBoard Cloud</b></a>.</Fragment></Banner> |
There was a problem hiding this comment.
Now that Banner.astro uses the slot as an override, the path="user-guide/cli" prop has no effect here (only the default peFeature sentence consumes it). Safe to drop. The <Fragment> wrapper is also redundant — components accept multiple children directly, so the content can sit inline.
There was a problem hiding this comment.
Fixed in abf51370c.
| - <DocLink product={props.product} path='reference/java-rest-client' bold={false}>Java REST Client</DocLink> | ||
| - <DocLink product={props.product} path='reference/python-rest-client' bold={false}>Python REST Client</DocLink> | ||
| <ListCard headingLevel={3} title="Clients & CLI" icon="puzzle"> | ||
| <ul> |
There was a problem hiding this comment.
This card uses explicit <ul><li> markup, but every other ListCard in the file uses markdown bullets (- <DocLink ...>). The edge variant (edge/reference/apis-and-sdks.mdx:49) renders the same CLI + Badge combination with - bullets and that works fine — switching this to markdown bullets keeps the card spacing/styling consistent with its neighbors. ListCard's global :global(li) styles apply to both forms, so there's no functional reason for the difference here.
| --- | ||
|
|
||
| {show && ( | ||
| <aside class="tb-banner" data-variant={variant}> | ||
| <div class="tb-banner-content"> | ||
| <p> | ||
| {variant === 'peFeature' && ( | ||
| {hasSlotOverride ? ( |
There was a problem hiding this comment.
Worth documenting the new semantic in the Props JSDoc above (line 7-17): default slot now replaces the standard peFeature sentence rather than appending to it. Before this change, callers like <Banner variant="peFeature" ...>Extra context...</Banner> would see both. A short note (/** Optional override for the default sentence. */) on the implicit slot would prevent surprise for the next person who wants to extend, not replace, the standard wording.
There was a problem hiding this comment.
Fixed in abf51370c.
| * Fixed custom menu dashboard re-initializing on internal navigation | ||
|
|
||
| * Edge | ||
| * Fixed integration loosing metadata placeholder on sync |
There was a problem hiding this comment.
Typo: "loosing" → "losing". Same fix needed in pe/releases/v4-3-x.mdx:23 (identical line).
| * [#15362](https://github.com/thingsboard/thingsboard/pull/15362) Hidden "Add Telemetry" button for Entity view by @mtsymbarov-del | ||
| * [#15373](https://github.com/thingsboard/thingsboard/pull/15373) Added '@angular/core/rxjs-interop' to modules map by @vvlladd28 | ||
| * [#15399](https://github.com/thingsboard/thingsboard/pull/15399) Fixed select options being clipped in widget settings form by @vvlladd28 | ||
| * [#15408](https://github.com/thingsboard/thingsboard/pull/15408) Fixed display long texts in Alarm asignee panel by @mtsymbarov-del |
There was a problem hiding this comment.
Typo: "asignee" → "assignee". The duplicate appears in releases/v4-3-x.mdx:50. Even if these mirror the upstream PR titles, release notes get more eyeballs than a PR title and are worth polishing.
There was a problem hiding this comment.
Fixed in abf51370c — and applied the same rewording to the awkward aggregation-keys line on the same files (see #3280184629).
| * [#15427](https://github.com/thingsboard/thingsboard/pull/15427) Adjusted size of entity type select to fit error message by @mtsymbarov-del | ||
| * [#15430](https://github.com/thingsboard/thingsboard/pull/15430) Fixed show/hide of custom header actions when using function to control visibility by @mtsymbarov-del | ||
| * [#15433](https://github.com/thingsboard/thingsboard/pull/15433) Fixed not set pageSize to child nodes in Entities hierarchy widget by @mtsymbarov-del | ||
| * [#15434](https://github.com/thingsboard/thingsboard/pull/15434) Fixed not process aggregation keys in Entities hierarchy widget by @mtsymbarov-del |
There was a problem hiding this comment.
Double space after "Fixed" plus awkward phrasing — "Fixed not process aggregation keys in Entities hierarchy widget" reads oddly. Suggest "Fixed aggregation keys not being processed in Entities hierarchy widget". Same item appears in releases/v4-3-x.mdx:58.
There was a problem hiding this comment.
Addressed in abf5137 — reworded both occurrences to "Fixed aggregation keys not being processed in Entities hierarchy widget".
| collapsed: true, | ||
| items: ['docs/edge/reference/java-rest-client', 'docs/edge/reference/python-rest-client'], | ||
| }, | ||
| { |
There was a problem hiding this comment.
Dropping Server-side REST Clients from the edge sidebar leaves the four content pages (src/content/docs/docs/edge/reference/{java,python}-rest-client.mdx and the edge/pe/ variants) reachable only via direct URL. The apis-and-sdks card in the edge include now links to the new clients under the non-edge prefix (/docs/reference/java-client/) — which is fine — but the legacy edge pages are now orphans. Either keep them in the sidebar (with their deprecation <Aside> doing the steering) or remove the files and add redirects to the new clients in src/data/redirects.ts. Same applies to the matching removal in edgePeSidebar (around line 2805).
There was a problem hiding this comment.
Addressed in abf5137. Iterated quite a bit; final shape:
- Added a
Clients & CLIsection to bothedgeSidebarandedgePeSidebarviaslug:references (not rawlink:, to keep the per-version filter insrc/routeData.tsfrom leaking entries across sidebars — first attempt with raw links caused a duplicateAPIs & SDKstab on/docs/apis-and-sdks/). - Created 6 new Edge stubs for the auto-generated clients with edge-flavored frontmatter descriptions:
docs/edge/{,pe/}user-guide/cli.mdxdocs/edge/{,pe/}reference/java-client.mdxdocs/edge/{,pe/}reference/python-client.mdx
- Kept the legacy edge REST-client stubs as-is (not orphaned anymore — they live in the new
Clients & CLIflow indirectly via the "Looking for legacy" Aside on the new client pages). - Updated the shared
_includes/docs/reference/{java,python}-client.mdxsoProducts.EDGEbehaves likeProducts.CEandProducts.EDGE_PElikeProducts.PEfor package selection (pipPackage,artifactId,saveDeviceCall) and PE-only conditional sections. - Added edge-aware intro wording: on Edge pages the intro now reads "wraps the Edge REST API" and "manage entities on your Edge node — connect it directly to the Edge node's local REST endpoint."
- Routed shared core DocLinks (
user-guide/security/api-keys,user-guide/groups,user-guide/roles) throughuseTbDocsso Edge users land on the existing CE/PE pages instead of 404-ing on/docs/edge/.../. - Added a deprecation Aside at the top of the legacy Edge REST-client includes pointing to the new Edge clients (matches the CE/PE pattern).
- Updated the Edge
apis-and-sdks.mdxClients & CLI card to use product-aware DocLinks so it lands on the new Edge stubs instead of CE/PE.
|
|
||
| ### Paginated tenant list | ||
|
|
||
| Use `getTenantDevices` (and its equivalents for other entity types) to walk every entity on the tenant. The return type is `PageDataDevice` — the generated per-entity page type; there's `PageDataAsset`, `PageDataDashboard`, etc. |
There was a problem hiding this comment.
PageDataDevice is an unusual class name for an OpenAPI-generated wrapper — the openapi-generator default for PageData<Device> is PageDataDevice, but some configurations emit PageDataOfDevice or DevicePage. If the actual generated class differs, both this paragraph and the snippet below (PageDataDevice devices; at line 186) won't compile. Worth a quick check against the latest published thingsboard-java-client artifact to confirm the exact symbol names — same goes for the asserted PageDataAsset/PageDataDashboard companions.
There was a problem hiding this comment.
Verified PageDataDevice, PageDataAsset, PageDataDashboard etc. against the published thingsboard-java-client artifact — these are the actual generated symbol names (openapi-generator default for PageData<T>). No code change.
- Fix MDX JSX interpolation in Python client snippets (r3280184553) - Drop test.pypi index from CLI install command (r3280184586) - Drop unused Banner prop and Fragment wrapper in CLI page (r3280184590) - Convert APIs & SDKs Clients ListCard to markdown bullets (r3280184598) - Document slot-override semantic in Banner props; render peFeature banner on Edge CE too (r3280184605) - Fix "loosing" typo in PE release notes (r3280184613) - Fix "asignee" typo and reword aggregation-keys line in release notes (r3280184618, r3280184629) - Mirror Clients & CLI on Edge sidebars with new Edge stubs; add deprecation notice on legacy Edge REST clients; add edge-aware intro wording; route shared core DocLinks via useTbDocs so Edge users land on existing pages (r3280184632) - Mark 4.3.0.1 and 4.2.1.2 as vulnerable in upgrade-instructions (pullrequestreview-4335788404)
Addressed in abf5137 — added |
Addressed in abf5137 — see the F3 reply for the full plan. The legacy Edge REST-client pages stay (now with a deprecation Aside pointing to the new Edge clients), and the new Edge sidebars have a |
There was a problem hiding this comment.
Pull request overview
Adds end-user documentation for the ThingsBoard CLI and introduces new edition-aware, OpenAPI-generated Java/Python REST client docs, while also bumping site version/release metadata for the 4.3 and 4.2 release trains.
Changes:
- Add new CLI documentation pages (CE/PE/PaaS/Edge variants) backed by a shared include.
- Add new Java/Python REST client docs and mark legacy REST client pages as deprecated.
- Update version constants, release tables/notes, sidebar navigation, banner behavior, and redirects for the new docs.
Reviewed changes
Copilot reviewed 37 out of 37 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/models/upgrade-instructions.ts | Adds upgrade entries for 4.3.1.2 and 4.2.2.2 and marks several versions as vulnerable. |
| src/models/releases-table.ts | Updates latest patch metadata and patch lists for 4.3 and 4.2 families. |
| src/data/versions.ts | Bumps CE/PE full versions and introduces TB_VER alias. |
| src/content/docs/docs/user-guide/cli.mdx | New CE CLI doc entrypoint that mounts the shared CLI include. |
| src/content/docs/docs/reference/python-client.mdx | New CE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/reference/java-client.mdx | New CE Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/pe/user-guide/cli.mdx | New PE CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/pe/reference/python-client.mdx | New PE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/pe/reference/java-client.mdx | New PE Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/user-guide/cli.mdx | New PaaS CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/paas/reference/python-client.mdx | New PaaS Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/reference/java-client.mdx | New PaaS Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/eu/user-guide/cli.mdx | New PaaS EU CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/paas/eu/reference/python-client.mdx | New PaaS EU Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/paas/eu/reference/java-client.mdx | New PaaS EU Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/user-guide/cli.mdx | New Edge CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/edge/reference/python-client.mdx | New Edge Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/reference/java-client.mdx | New Edge Java client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/pe/user-guide/cli.mdx | New Edge PE CLI doc entrypoint mounting the shared CLI include. |
| src/content/docs/docs/edge/pe/reference/python-client.mdx | New Edge PE Python client doc entrypoint mounting the shared include. |
| src/content/docs/docs/edge/pe/reference/java-client.mdx | New Edge PE Java client doc entrypoint mounting the shared include. |
| src/content/_includes/docs/user-guide/cli.mdx | Adds the main CLI user guide content (shared across editions). |
| src/content/_includes/docs/releases/v4-3-x.mdx | Adds CE release notes for v4.3.1.2. |
| src/content/_includes/docs/releases/v4-2-x.mdx | Adds CE release notes for v4.2.2.2. |
| src/content/_includes/docs/reference/python-rest-client.mdx | Deprecates legacy Python REST client doc and updates install snippet. |
| src/content/_includes/docs/reference/python-client.mdx | Adds new edition-aware Python REST client documentation. |
| src/content/_includes/docs/reference/java-rest-client.mdx | Deprecates legacy Java REST client doc and updates dependency snippet. |
| src/content/_includes/docs/reference/java-client.mdx | Adds new edition-aware Java REST client documentation. |
| src/content/_includes/docs/reference/apis-and-sdks.mdx | Updates “REST Clients” card to “Clients & CLI” and links to new pages. |
| src/content/_includes/docs/pe/releases/v4-3-x.mdx | Adds PE release notes for v4.3.1.2. |
| src/content/_includes/docs/pe/releases/v4-2-x.mdx | Adds PE release notes for v4.2.2.2. |
| src/content/_includes/docs/edge/reference/python-rest-client.mdx | Adds deprecation note pointing to the new Python client docs. |
| src/content/_includes/docs/edge/reference/java-rest-client.mdx | Adds deprecation note pointing to the new Java client docs. |
| src/content/_includes/docs/edge/reference/apis-and-sdks.mdx | Updates Edge “REST Clients” card to “Clients & CLI” and links to new pages. |
| src/components/Banner.astro | Extends peFeature visibility to Edge CE and adds slot override behavior. |
| public/redirects.json | Adds redirects for new Edge PE CLI/client pages under legacy /docs/pe/edge/... paths. |
| astro.sidebar.ts | Adds CLI entries and replaces legacy REST client links with new client pages in sidebars. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| releaseDate: 'May 28 2026', | ||
| upgradableFrom: '4.2.1.x', | ||
| prevVersionAnchor: 'v4-3-0-1', | ||
| lts: true, | ||
| patch: true, |
There was a problem hiding this comment.
Follows the existing pre-PR convention used across 4.3.1.x patches: prevVersionAnchor: 'v4-3-0-1' paired with upgradableFrom: '4.2.1.x' to point readers at the stepping-stone version (4.3.0.1) in the upgrade chain — see the matching 4.3.1 and 4.3.1.1 entries. The new 4.3.1.2 entry is consistent with that pattern, so no change here.
| releaseDate: 'May 28 2026', | ||
| upgradableFrom: '4.2.0', | ||
| prevVersionAnchor: 'v4-2-1-2', | ||
| lts: true, | ||
| patch: true, |
There was a problem hiding this comment.
Follows the existing pre-PR convention used across 4.2.2.x patches: prevVersionAnchor: 'v4-2-1-2' paired with upgradableFrom: '4.2.0' to point readers at the stepping-stone version in the upgrade chain — see the matching 4.2.2 and 4.2.2.1 entries. The new 4.2.2.2 entry is consistent with that pattern, so no change here.
| upgrade: true, | ||
| manualVersionUpgrade: false, | ||
| windowsZip: true, | ||
| anchor: 'v4-3-1-1', | ||
| vulnerable: true, |
There was a problem hiding this comment.
Pre-existing entry — this PR only added vulnerable: true. The prevVersionAnchor/upgradableFrom pair follows the long-standing 4.3.1.x convention (stepping-stone anchor, not the floor of upgradableFrom).
| upgrade: true, | ||
| manualVersionUpgrade: false, | ||
| windowsZip: true, | ||
| anchor: 'v4-2-2-1', | ||
| vulnerable: true, |
There was a problem hiding this comment.
Pre-existing entry — this PR only added vulnerable: true. The prevVersionAnchor/upgradableFrom pair follows the long-standing 4.2.2.x convention (stepping-stone anchor, not the floor of upgradableFrom).
| patch: true, | ||
| x: true, | ||
| upgrade: true, | ||
| manualVersionUpgrade: false, | ||
| windowsZip: false, | ||
| anchor: 'v4-2-1-2', | ||
| vulnerable: true, |
There was a problem hiding this comment.
Misread — the 4.2.1.2 entry's prevVersionAnchor is 'v4-2-0' (matching upgradableFrom: '4.2.0'). v4-2-1-2 is the entry's own anchor field, not its prevVersionAnchor.
ViacheslavKlimov
left a comment
ViacheslavKlimov
left a comment
There was a problem hiding this comment.
Review summary
Reviewed 37 changed files in ThingsBoard CLI User Guide + new REST Clients + Releases 4.2.2.2 and 4.3.1.2. Left 7 comment(s) inline plus a couple of observations below.
Overall the new CLI guide and the auto-generated Java/Python REST client docs are well-structured, and the release notes additions are consistent with the existing format. The main things worth a second look are (a) the cross-cutting effect of the peFeature banner now also rendering on Edge CE pages, (b) whether the CLI doc really applies to Edge PE given the explicit Limitations wording, and (c) inconsistencies between the Edge and non-Edge variants of the new pages.
Additional findings
These are about lines outside this PR's diff, but they line up naturally with changes this PR is making:
src/content/_includes/docs/edge/reference/java-rest-client.mdx(~line 26) — still has<version>4.3.0.1</version>hardcoded. The non-Edge counterpartsrc/content/_includes/docs/reference/java-rest-client.mdxwas migrated to${TB_VER}in this PR; the Edge equivalent should follow the same migration or it'll silently fall out of sync each release. Same applies to displaying a non-current version (4.3.0.1) on a page that's now also flagged as deprecated.src/content/_includes/docs/edge/reference/python-rest-client.mdx(~line 20) —pip3 install tb-rest-clientis still unpinned. The non-Edge counterpart now pins via==${TB_VER}; same migration would keep Edge consistent.upgrade-instructions.ts—4.3.1.1,4.3.0.1,4.2.2.1, and4.2.1.2are newly markedvulnerable: true.4.2.0(an olderlts/patch: falsebaseline) is not marked. If this is the intended convention (only patch-level entries carryvulnerable), looks fine; if4.2.0should be flagged too, it's missing.
This review was auto-generated. Findings may contain errors — please verify before applying changes.
| const { variant, product, path } = Astro.props; | ||
|
|
||
| const show = variant === 'peFeature' ? product === Products.CE : true; | ||
| const show = variant === 'peFeature' ? (product === Products.CE || product === Products.EDGE) : true; |
There was a problem hiding this comment.
Expanding the peFeature show-condition to product === Products.EDGE is a global behavior change: every existing peFeature banner (~40 pages — groups.mdx, all integrations/*.mdx, white-labeling*.mdx, scheduler.mdx, secrets-storage.mdx, etc.) will now also render on the Edge CE pages that share those includes. Was that cross-cutting effect intended, or only meant for the new CLI page?
If intentional, the standard banner text — "available in ThingsBoard Professional and ThingsBoard Cloud only" — may be misleading for Edge CE readers, since the right upgrade path for them is Edge PE, not the central PE server or Cloud. Consider either (a) special-casing the standard sentence on Edge CE to point to Edge PE, or (b) keeping the condition CE-only and using the new slot-override mechanism on just the CLI page.
There was a problem hiding this comment.
Addressed in 52f84d3 — reverted the EDGE expansion; peFeature now renders on CE only. Custom slot content on the CLI page still shows on CE; Edge CE readers no longer see this banner.
| const linkPath = path || 'installation'; | ||
| // A slot override replaces the default `peFeature` sentence (rather than appending to it), | ||
| // so callers can substitute custom wording while keeping the same color/visibility logic. | ||
| const hasSlotOverride = Astro.slots.has('default'); |
There was a problem hiding this comment.
Subtle backwards-incompatible semantics change worth noting in the comment: previously slot content was appended after the standard peFeature sentence; now it replaces it. No current caller relies on appending (I grepped — only the new cli.mdx uses slot content with peFeature), so no regression, but a future maintainer trying to add a footnote to the standard sentence will be surprised. The current code comment explains the intent — maybe also mention "prior behavior appended; this replaces" so the design choice is explicit.
There was a problem hiding this comment.
The current code comment already says "replaces the default `peFeature` sentence (rather than appending to it)" — explicit enough; adding a separate "previously appended, now replaces" line would be redundant. Keeping as-is.
| label: 'Server-side REST Clients', | ||
| label: 'Clients & CLI', | ||
| collapsed: true, | ||
| items: [ |
There was a problem hiding this comment.
The CLI page is wired into the Edge PE sidebar, but the shared CLI include explicitly excludes Edge in both Prerequisites ("ThingsBoard Cloud, ThingsBoard Cloud EU, or self-hosted PE") and Limitations ("Works with ThingsBoard PE and Cloud"). And the peFeature banner inside cli.mdx won't render for EDGE_PE (only CE / EDGE), so Edge PE readers land on the full guide with no disclaimer that it doesn't apply to them.
Either the CLI actually supports Edge PE (and the doc's Prerequisites/Limitations should say so), or this sidebar entry — plus the matching stub at src/content/docs/docs/edge/pe/user-guide/cli.mdx — shouldn't exist. Same question applies to the Edge CE entry at line 3060 in the diff: there the banner does show, but it tells the user to use PE/Cloud rather than Edge PE.
There was a problem hiding this comment.
CLI is intended to support Edge — keeping both Edge CE and Edge PE sidebar entries (and the matching stubs). Reworking the Prerequisites/Limitations wording in the shared CLI include to acknowledge Edge is out of scope for this PR; will follow up separately.
| - <DocLink product={props.product} path='reference/java-rest-client' bold={false}>Java REST Client</DocLink> | ||
| - <DocLink product={props.product} path='reference/python-rest-client' bold={false}>Python REST Client</DocLink> | ||
| <ListCard headingLevel={3} title="Clients & CLI" icon="puzzle"> | ||
| - <DocLink product={props.product} path='user-guide/cli' bold={false}><span>ThingsBoard CLI <Badge text="New" class="tb-badge" /></span></DocLink> |
There was a problem hiding this comment.
The three list items here use bold={false} with no target attribute, but the corresponding Edge file (_includes/docs/edge/reference/apis-and-sdks.mdx:48-50) uses target="_blank" with no bold={false}. So Edge readers get bold links that open in a new tab, while non-Edge readers get non-bold same-tab links — for the same three new entries. The pre-existing Edge file used raw <a target="_blank"> anchors, so the inconsistency carried over from before, but this PR is the natural place to align them since it rewrites both blocks.
There was a problem hiding this comment.
Fixed in 52f84d3 — aligned Edge Clients & CLI list items to the CE style (bold={false}, no target). The surrounding REST API anchors were left as-is (pre-existing, out of scope).
| (product === Products.CE || product === Products.EDGE) | ||
| ? 'thingsboard-ce-client' | ||
| : (product === Products.PE || product === Products.EDGE_PE) | ||
| ? 'thingsboard-pe-client' |
There was a problem hiding this comment.
Nested ternaries with positional null arguments (saveDeviceCall further down has five trailing nulls for CE/EDGE and seven for the rest) are awkward to read. A small object/map keyed by Products would make both artifactId and saveDeviceCall clearer and easier to extend if a new edition is added. Same comment applies to python-client.mdx:8-13 for pipPackage.
There was a problem hiding this comment.
Skipping the refactor — current ternaries work and the cost of changing them isn't justified in this PR. Will consider it if a new edition gets added.
| export const CE_FULL_VER = '4.3.1.1'; | ||
| export const CE_FULL_VER = '4.3.1.2'; | ||
|
|
||
| export const TB_VER = CE_FULL_VER; |
There was a problem hiding this comment.
TB_VER = CE_FULL_VER (so 4.3.1.2) is used as the Maven <version> and the pip == pin for all editions of the new clients — including thingsboard-pe-client and tb-pe-client. Worth confirming the PE auto-generated clients really publish under the bare CE version (e.g. 4.3.1.2) and not under 4.3.1.2PE like the platform PE artifacts do — otherwise the dependency snippet would resolve to a non-existent artifact. If it's intentional, a more specific name (CLIENT_VER or REST_CLIENT_VER) would read better, since TB_VER aliased to CE_FULL_VER reads like "the ThingsBoard version" while the contract is actually "version string the generated clients ship under."
There was a problem hiding this comment.
TB_VER name is fine for the current setup — the PE auto-generated clients (thingsboard-pe-client, tb-pe-client) ship under the bare CE version string (not PE-suffixed like platform PE artifacts), so the alias applies cleanly across all editions.
| import { Products } from '~/models/site.models'; | ||
| import { Steps, Aside } from '@astrojs/starlight/components'; | ||
|
|
||
| <Banner variant="peFeature" product={props.product}>ThingsBoard CLI works only with <DocLink product={Products.PE} path="user-guide/cli" target="_blank">ThingsBoard Professional</DocLink> and <a href="/installations/?product=thingsboard-cloud" target="_blank" rel="noopener noreferrer" class="tb-banner-ext"><b>ThingsBoard Cloud</b></a>.</Banner> |
There was a problem hiding this comment.
Two things on this banner:
- The custom message inside the slot says "ThingsBoard CLI works only with ThingsBoard Professional and ThingsBoard Cloud." — but with the Banner change in this same PR, this banner now also renders on the Edge CE page. For an Edge CE reader, "Professional" and "Cloud" don't really name their upgrade path (which would be Edge PE). Consider tailoring the wording when
props.product === Products.EDGE, or pointing them to the Edge PE doc instead. - The
DocLinktoProducts.PEuser-guide/cliopens in a new tab, but the Cloud<a>also hastarget="_blank". Fine, just noting both are external-style — verify that's the desired UX for an in-doc "this is a PE feature" hint (the standardpeFeaturesentence usestarget="_blank"for the PE link too, so it's consistent).
There was a problem hiding this comment.
Sub-point 1 is moot — the peFeature EDGE expansion was reverted in 52f84d3, so this banner no longer renders on Edge CE. The slot wording (PE + Cloud) is correct for the CE reader, which is now the only audience that sees it. Sub-point 2 is observational only — the target="_blank" UX matches the standard peFeature link, so it's consistent.
- Revert peFeature banner EDGE expansion; render only on CE (#3281128479)
- Migrate legacy edge Java REST client install snippet to ${TB_VER} (#pullrequestreview-4336868594)
- Migrate legacy edge Python REST client install to ==${TB_VER} (#pullrequestreview-4336868594)
- Align edge apis-and-sdks Clients & CLI links to CE style (bold={false}, no target) (#3281128499)
Fixed in 52f84d3 — migrated the snippet to |
Fixed in 52f84d3 — pinned to |
Convention is correct — only patch-level entries carry |
Description
Type of change
src/content/docs/**)src/content/_includes/**)src/components/**,src/styles/**)src/pages/**,src/data/**)src/data/redirects.ts)releaseskill)Affected products
Related issues
Checklist
pnpm checkpasses (Astro / TypeScript)pnpm lint:eslintpassespnpm lint:slugcheckpasses (required if pages were added/renamed/moved across languages)pnpm lint:linkcheckpasses locally — required to merge; run it before requesting review (usepnpm lint:linkcheck:nobuildif you already ran a build)src/data/redirects.ts, andpnpm generate:redirectswas runsrc/data/versions.ts