Add documentation about related items in solution template guide - #637
Conversation
Explain the automatic widget FQN resolution that IoT Hub performs when a solution template ZIP is uploaded: - new "Related Items" section: how FQNs resolve against system bundles, that relations are derived from dashboard exports with nothing to declare, that unresolved FQNs block the upload wizard, and how users see and receive related widgets on install - install flow now mentions the related items list and lists related widgets as the first provisioning stage - pre-upload checklist requires every non-system widget to be published with an approved version - link the Widget Contribution Guide from See Also
There was a problem hiding this comment.
Pull request overview
Adds contributor-facing documentation to the IoT Hub Solution Template Contribution Guide explaining how dashboard widget dependencies are detected and handled as “related items” during upload and installation, helping prevent failed uploads and broken dashboards in published templates.
Changes:
- Documented the “Related Items” mechanism, including validation behavior and remediation options for unresolved widget FQNs.
- Updated the install flow to mention related items and clarify that related widgets are provisioned before other entities.
- Extended the pre-upload checklist and “See Also” references to include widget publication guidance.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
vvlladd28
left a comment
vvlladd28
left a comment
There was a problem hiding this comment.
Review summary
Reviewed 1 changed file in Add documentation about related items in solution template guide. Left 10 comment(s) inline.
No spelling or grammar errors — the prose is clean. Every finding below was checked against the iot-hub implementation.
The substantive ones are in How the Check Works and Unknown FQNs Block the Upload, which describe a mechanism that differs from solution-template-scan.service.ts / related-items-scan.ts / version-drawer.component.ts on four points: the scan reads every .json entry in the archive rather than only dashboards/; the key is typeFullFqn, not fqn; system widgets are excluded by a system. prefix test rather than by comparison against widget bundles; and the "cannot be saved or submitted" guarantee is contradicted by the replace-package path, which the implementation deliberately leaves non-blocking. The rest are house-style and readability notes, marked where they're subjective.
Additional findings
Three claims could not be verified against /home/vladyslav/Documents/work/iot-hub — not errors, just flagged for someone with access to the platform repo, where DefaultIotHubService.resolveInstallPlan lives:
solution-template.mdx:28— the provisioning order ("Related IoT Hub widgets … first") is decided byresolveInstallPlan. Theiot-hubside only recordsrelatedItemson the version; nothing here pins the order.solution-template.mdx:465— "The public solution template page lists the related widgets". This repo is the Creator Portal plus backend;hub-related-items-listis rendered only in the creator dialogs and the version drawer, and thelistingmodule has no related-items surface. No public catalog page exists here to confirm against.solution-template.mdx:468— "every installation gets the latest approved version". The relation storing an item id rather than a version id checks out (relatedItems: relatedItemsOf(this.relatedItemsScan.itemIds)), but which version the platform resolves at install time is again outside this repo.
This review was auto-generated. Findings may contain errors — please verify before applying changes.
Address review on #637. The section described a mechanism that differed from solution-template-scan.service.ts on four points, all verified against the iot-hub sources: - the scan reads every .json entry in the archive, not only dashboards/ - the key collected is typeFullFqn, not fqn - system widgets are dropped by a `system.` prefix test before any lookup, not compared against widget bundles; note that this makes the test a spelling test a hand-edited export can defeat - the blocking guarantee holds only for the create / add-version wizard; replacing the package on an existing version is deliberately non-blocking, and a failed scan leaves the step valid Also: - drop the claim that the public listing page shows related widgets and the related-widgets-first provisioning order — neither is backed by this repo or the creator portal - note that the wizard labels the step "Required items" - settle on "system widget" / "IoT Hub widget" throughout - record that a suspended creator's widget stops resolving - rename the blocking subsection to a noun phrase, bold the in-page link - make the checklist item actionable by naming typeFullFqn - reconcile ${item-link} guidance: widgets are derived automatically, so reserve the card for dependencies the platform cannot detect
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.
What
Documents IoT Hub's related items mechanism in the Solution Template Contribution Guide.
Why
Contributors had no way to know that dashboard widget FQNs are validated on upload, or that an unpublished widget blocks the wizard.
Changes
src/content/docs/docs/iot-hub/contribution-guides/solution-template.mdx## Related Itemssection:dashboards/, collects widget FQNs, and resolves each against the system widget bundles: system → nothing, published Hub widget → relation recorded, unresolved → validation error.solution.jsonorentities/*.json; relations are derived from dashboard exports automatically.