You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(iot-hub): write related items at the contributor's level
Rewrite the Related Items section so it describes what a creator does and
sees rather than how the scanner works, and fix three reader-facing errors.
- Missing widgets on a package replace render as the same red error, not a
warning; only the title changes. "Warning" names a different state in the
same panel (package unreadable / marketplace unreachable).
- The pre-upload checklist told contributors to search the dashboard export
for typeFullFqn, contradicting the scan's actual scope; it now says every
.json file in the package.
- Standardise on Published for the live version status, matching the Status
column in the Creator Portal. Corrects the status tables in all six
contribution guides, which called it Approved.
Also drop implementation detail with no reader consequence (request batching,
what is retained when a scan fails), rewrite the system. prefix aside as an
instruction not to hand-edit typeFullFqn, replace internal component names
(version drawer, stepper) with the labels shown on screen, un-wrap the
platform's scan steps from <Steps> which elsewhere marks reader actions, and
reduce the "widgets are derived automatically" fact from four restatements to
one canonical section plus cross-references.
Copy file name to clipboardExpand all lines: src/content/docs/docs/iot-hub/contribution-guides/solution-template.mdx
+13-17Lines changed: 13 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,15 +24,13 @@ Create a free **Creator account** on the <a href="https://iot-hub.thingsboard.io
24
24
When a user clicks **Install** on your solution template in IoT Hub:
25
25
26
26
1. They review the **description** (from `description.md`) and preview gallery (from `imageUrls` in `solution.json`).
27
-
2. They confirm installation — the platform atomically provisions every entity in your template:
27
+
2. They confirm installation — the platform atomically provisions every entity in your template, along with any IoT Hub widget the dashboards use (see **[Related items](#related-items)**), in this order:
- Devices, assets, customers, dashboards (next, referencing the profiles)
30
30
- Device emulators (last, seeded with telemetry)
31
31
3. They are redirected to the **main dashboard** with live data already flowing.
32
32
4. The **post-install instructions** (from `instructions.md`) are shown alongside the dashboard — telling them how to inspect the setup, connect real hardware, customize widgets, and so on.
33
33
34
-
Any IoT Hub widget your dashboards use is installed along with the template — see **[Related items](#related-items)**.
35
-
36
34
Your job as a creator is to describe the complete solution declaratively in the archive so that a single installation produces a working end-to-end demo.
37
35
38
36
## Quick Start
@@ -433,17 +431,15 @@ The `entityNameFilter` must exactly match a device `name` from `entities/devices
433
431
434
432
Dashboards in a solution template often use widgets that do not ship with ThingsBoard — **IoT Hub widgets** published by you or by another contributor. IoT Hub derives those dependencies from your package and stores them on the version as **related items**, so they install together with the template.
435
433
436
-
In the upload wizard and in the version drawer, this step (and the corresponding tab) is called **Required items**.
434
+
In the upload wizard and on the **Versions** page, this step (and the corresponding tab) is called **Required items**.
437
435
438
436
### How the Check Works
439
437
440
438
When you upload the ZIP, IoT Hub scans the archive:
441
439
442
-
<Steps>
443
440
1. It collects every `typeFullFqn` value found in **any**`.json` file in the package — not only the files under `dashboards/`. `typeFullFqn` is the key a ThingsBoard export writes a widget type reference under, so a reference sitting in a rule chain export or in `entities/dashboards.json` is picked up the same way.
444
441
2. It drops every FQN starting with `system.` — those widgets ship with ThingsBoard, exist on every instance, and are never a marketplace dependency.
445
-
3. It looks the remaining FQNs up in the IoT Hub catalog in a single request. A dashboard export scopes a widget type by its owner (`tenant.john_doe.air_quality_card`) while IoT Hub stores the bare FQN (`john_doe.air_quality_card`), so both readings are tried.
446
-
</Steps>
442
+
3. It looks the remaining FQNs up in the IoT Hub catalog. A dashboard export scopes a widget type by its owner (`tenant.john_doe.air_quality_card`) while IoT Hub stores the bare FQN (`john_doe.air_quality_card`), so both readings are tried.
447
443
448
444
Every FQN that resolves to a published IoT Hub widget is recorded as a related item of this template version. Every FQN that does not resolve is reported as a missing widget.
449
445
@@ -452,7 +448,7 @@ You never declare related items yourself. There is no field for them in `solutio
452
448
</Aside>
453
449
454
450
<Asidetype="caution">
455
-
The system-widget test is a spelling test on the FQN, not a lookup against the widget bundles. An FQN hand-edited to start with `system.` is accepted silently and installs as a broken widget.
451
+
When you rewrite a dashboard export, leave every `typeFullFqn` value exactly as ThingsBoard wrote it. IoT Hub treats any FQN beginning with `system.` as a widget that ships with ThingsBoard without checking further, so a hand-edited value is accepted silently and installs as a broken widget.
456
452
</Aside>
457
453
458
454
### If an FQN Does Not Resolve
@@ -461,18 +457,18 @@ The **Required items** step lists the unresolved FQNs and explains that the dash
461
457
462
458
| Where | Behavior |
463
459
|---|---|
464
-
| Create item / add version wizard | The step is invalid: the stepper will not advance and the version cannot be created until every FQN resolves |
465
-
| Replacing the package on an existing version | The new package is saved with the dependencies actually detected and the missing widgets show up as a warning — **submittingfor review is not blocked**|
460
+
| Create item / add version wizard | The step is invalid: the wizard will not let you continue, and the version cannot be created until every FQN resolves |
461
+
| Replacing the package on an existing version | The new package is saved with the dependencies actually detected, and the missing widgets show up as the same red error — reworded from **cannot continue** to **publish these before submitting**. Submitting for review is not blocked |
466
462
467
-
Treat the wizard as a guard rather than a guarantee: a version whose package was replaced can reach review with unresolved widgets, so fix them before you submit. A scan that fails outright — an unreadable archive, or the catalog not answering — does not block anything either; IoT Hub says which of the two happened and keeps the previous dependency list instead of replacing it with an empty one.
463
+
Treat the wizard as a guard rather than a guarantee: a version whose package was replaced can reach review with unresolved widgets, so fix them before you submit. And if IoT Hub reports **Could not read the package**or **Could not check the marketplace**, the check did not run at all — that does not block you either, so upload the package again and confirm the widget list before you submit.
468
464
469
465
There are three ways to resolve a missing widget:
470
466
471
-
-**Publish the widget to IoT Hub first.** Upload it as a separate IoT Hub item and wait for its version to be**approved** — a version still pending review does not resolve the FQN. See the <ahref="/docs/iot-hub/contribution-guides/widget/"target="_blank"rel="noopener noreferrer"><strong>IoT Widget Contribution Guide</strong></a>. Then re-upload the template ZIP.
467
+
-**Publish the widget to IoT Hub first.** Upload it as a separate IoT Hub item and wait for review to complete — its version must reach**Published**; a version still pending review does not resolve the FQN. See the <ahref="/docs/iot-hub/contribution-guides/widget/"target="_blank"rel="noopener noreferrer"><strong>IoT Widget Contribution Guide</strong></a>. Then re-upload the template ZIP.
472
468
-**Swap it for a system widget.** Rebuild that part of the dashboard with a widget bundled with ThingsBoard and re-export the dashboard.
473
469
-**Remove the widget from the dashboard** and re-export the dashboard.
474
470
475
-
Any published IoT Hub widget resolves — it does not have to be one of your own. The one exception is a widget whose creator has since been suspended: it stops resolving even though its version is still approved.
471
+
Any published IoT Hub widget resolves — it does not have to be one of your own.
476
472
477
473
### What Gets Installed
478
474
@@ -652,7 +648,7 @@ These placeholders are resolved at install time:
652
648
|`${MAIN_DASHBOARD_URL}`| Deep link to the solution's main dashboard |
653
649
|`${DOCKER_CONFIG}`| Full `docker-compose.yml` content for the gateway, pre-filled with host, port, and token. Usually wrapped in a `bash` code block |
654
650
|`${DOCS_BASE_URL}`| Base URL of the ThingsBoard documentation — use for links that should work on both ThingsBoard Cloud and on-prem |
655
-
|`${item-link:<item-uuid>}`| Renders a link card pointing at another IoT Hub item the user can install in one click. Use for dependencies the platform cannot derive from your package — widgets are handled automatically, see **[Related items](#related-items)**|
651
+
|`${item-link:<item-uuid>}`| Renders a link card pointing at another IoT Hub item. Use for dependencies IoT Hub cannot derive from your package — see **[Related items](#related-items)**|
656
652
657
653
### Code Block Tags
658
654
@@ -679,7 +675,7 @@ A good `instructions.md` follows this flow:
679
675
${item-link:d93b9a1a-1c07-408c-bb86-743bbcb36832}
680
676
```
681
677
682
-
Widgets are the exception: the widgets your dashboards use are detected and installed automatically as **[related items](#related-items)**, so they need no `${item-link}` card.
678
+
Widgets are the exception — they need no `${item-link}` card. See **[Related items](#related-items)**.
683
679
684
680
3.**Launch the emulator** — copy-paste Docker commands.
685
681
4.**Launch the gateway** — use `${DOCKER_CONFIG}` to give them a ready-to-run config.
@@ -768,7 +764,7 @@ Every upload creates a new version of your template. Bump the version in the upl
768
764
-[ ] No hardcoded UUIDs remain in any `singleEntity.id` or similar references
769
765
-[ ] Dashboard titles match the names in `entities/dashboards.json`
770
766
-[ ] Every widget displays data from a telemetry key that an emulator actually produces — nothing should be empty after installation
771
-
-[ ] Every widget that does not ship with ThingsBoard is already published to IoT Hub with an**approved** version, so its `typeFullFqn` resolves as a **[related item](#related-items)** — search the dashboard export for `typeFullFqn` to enumerate them
767
+
-[ ] Every widget that does not ship with ThingsBoard is already uploaded to IoT Hub with a**Published** version, so its `typeFullFqn` resolves as a **[related item](#related-items)** — search every `.json` file in the package for `typeFullFqn` to enumerate them
772
768
773
769
### Device Profiles and Asset Profiles
774
770
@@ -802,7 +798,7 @@ To see the current status of your submission, open the Creator Portal and go to
802
798
| Status | Meaning |
803
799
|---|---|
804
800
|**Pending Review**| Your version is in the review queue and has not been evaluated yet |
805
-
|**Approved**| Your version passed review and is now live on IoT Hub |
801
+
|**Published**| Your version passed review and is now live on IoT Hub |
806
802
|**Rejected**| Your version did not pass review — see the reviewer comment for details |
0 commit comments