Outcome
Read the Forms workspace collection widget and interpret its aggregate metrics and action descriptors.
GET /api/widget
Before you start
Use the original authorized identity/organization and discover the canonical accessible Forms workspace. Published action input is exactly{}; bind the workspace separately through the supported resource context, not an invented action field. The catalog requires workspace:read.
The published widget-server verifies Auth for the resolved application, obtains accessible workspaces for the original organization and chooses an active workspace. No app-owned full workspace list or new workspace lifecycle is implied. Actual Auth denial is authoritative.
All examples are synthetic UNRUN from immutable Forms source and exact published widget-server0.7.2/SDK0.23.22 artifacts matching its lockfile. No app imports/tests, actual widget query, response/subject read, create action, provider/key or business operation was performed.
Request
Action: app_topolo_forms.widget.get. Input is {}. Bind the discovered workspace separately. This read needs no mutation confirmation; descriptors in its output do not authorize their actions.
Response and metric semantics
Forms returns one forms.collection-operations stats widget, draft descriptor version2.0.0 inside the SDK response contractVersion3.0.0. Published SDK addsappId/serviceName/lastUpdated and validates the whole response; the shared server appends activeworkspace and accessibleworkspaces only when it obtained a nonempty list. A draft object alone is not the final wire response.
Workspace selector comes from the supported requested-workspace binding or widget query selectors. The wrapper picks a matching accessible requested workspace; if none matches, it falls back to default then first. Therefore compare returned workspace.id with the intended target; a successful response does not prove the requested id was used. Workspace-catalog exceptions degrade to no workspace dimension rather than an independently explained access failure.
Builder uses2SQLCOUNT/SUM aggregates, onecontrolstore and onesubmissionstore, both scoped to organization+selectedworkspace. Rows/answers are not materialized or decrypted by these aggregate queries. Queries are independent, not one cross-store consistent snapshot; indexed aggregates are not constant-time latency or database-health certification.
Seven metrics are totalforms,publishedforms,draftforms,totalresponses,responsestoday,responseslast7days,responsesperpublishedform. Today starts00:00UTC; trailing7days startsnow-minus7x24hours. Queries use submitted_at>=start with no upper-time predicate, so future timestamps could count. Counts are stored rows, not unique people, completed journeys or delivery outcomes.
responses_per_published_form divides all selected-workspace responses by the number of currentlypublished forms, rounded1decimal, or0ifno published forms. It is not a cohort mean limited to responses belonging to published forms. Do not derive completion/conversion/compliance rates.
Missingorganization/workspace produces widgetstateempty with explanatorycopy; missingstorebinding producesunavailable/forms_database_unavailable; otherwise nonzeroform/responsecountproducesready, successfulzeroresultsproduceempty. Numeric/nullaggregatefallbacks can yield0 and no exception; zero/lastSuccessfulAt is not independent completeness or key-health proof. Aggregate exceptions instead reach the wrapper500catch.
When workspacecontext and both storebindings are present, source advertises the confirmed create-draft-form control and matching contributiondataset action. The builder checks those conditions, not a freshcallerwritegrant; descriptor presence is not permission. Actual forms.create must be independently discovered/validated/planned/authorized; reading the widget executes none of its controls or compensating deletion.
Contribution metadata uses catalog icon identity, required singleworkspace selector,7metricdefinitions,3dimensions,3lifecyclelabels,3events and2datasets. It is declarative dashboard composition. The closed lifecyclelabel does not establish an app closed-state transition, and listed events/drilldowns are not event emission or navigation execution. With no createcontrol the actions visualization/actionIds are omitted accordingly.
Refresh values60/10/120/120seconds are descriptor policy; the HTTP response sets private,max-age15 and wrapperidentity/request headers. These values do not prove a browser poller, datafreshness, cacheisolation acrossclients or end-to-end timing. Actual loaded translationrelease and locale can change labels; the English fixture is conditional, not runtimeproof.
Complete worked responses
One complete workspace widget
Complete source-derived synthetic UNRUN HTTP200. Original Auth and accessible-workspace resolution succeed; this fictional workspace is selected and both bound stores answer. Exactly2forms (1published,1draft),3responses (1at/aftertodayUTCstart,2at/aftertrailing7daystart),nonefuture-dated. Packaged English translations are assumed to match pinned authored strings; no deployed translation/runtime proof. SDKgeneratedAt is1millisecond after builderobservedAt. All controls are descriptors, not executed.
Input:
{}
Response:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_forms",
"serviceName": "Forms",
"generatedAt": "2026-10-21T12:00:00.001Z",
"widgets": [
{
"id": "forms.collection-operations",
"version": "2.0.0",
"type": "stats",
"presentation": {
"title": "Collection operations",
"description": "Form readiness and response activity for this workspace.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_forms_docs_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-21T12:00:00.000Z",
"lastSuccessfulAt": "2026-10-21T12:00:00.000Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 120,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "heroMetricKey",
"label": "Primary metric",
"type": "select",
"required": true,
"options": [
{
"value": "forms",
"label": "Forms"
},
{
"value": "published_forms",
"label": "Published forms"
},
{
"value": "draft_forms",
"label": "Draft forms"
},
{
"value": "responses",
"label": "Responses"
},
{
"value": "responses_today",
"label": "New today"
},
{
"value": "responses_last_7_days",
"label": "Responses in 7 days"
},
{
"value": "responses_per_published_form",
"label": "Responses per published form"
}
]
}
],
"defaults": {
"heroMetricKey": "responses_today"
}
},
"drilldowns": [
{
"id": "forms",
"label": "Review forms",
"href": "/dashboard/forms"
},
{
"id": "new-form",
"label": "Create a form",
"href": "/dashboard/forms/new"
},
{
"id": "responses",
"label": "Review responses",
"href": "/dashboard/responses"
},
{
"id": "insights",
"label": "Open response insights",
"href": "/dashboard/insights"
},
{
"id": "publish",
"label": "Review publishing",
"href": "/dashboard/publish"
}
],
"controls": [
{
"id": "create-draft-form",
"label": "Create draft form",
"actionId": "app_topolo_forms.forms.create",
"resourceType": "workspace",
"resourceId": "ws_forms_docs_fixture",
"input": {
"title": "Untitled form",
"status": "draft"
},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates an unpublished draft form in the selected Forms workspace.",
"The draft accepts no public responses until it is published."
],
"verification": [
"Read the returned form identifier and confirm its status is unpublished.",
"Read the form and review its fields before publishing it."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_forms.forms.delete",
"instructions": "Delete the draft while it is still unpublished and has no responses."
}
}
],
"localization": {
"locale": "en",
"titleKey": "forms.widget.collectionOperationsTitle",
"descriptionKey": "forms.widget.collectionOperationsDescription"
},
"accessibility": {
"label": "Forms collection and response operations",
"description": "Selectable workspace metrics with direct links to create, publish, review, and analyze forms."
},
"contribution": {
"summary": "Form publishing readiness and bounded response activity for the selected Forms workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Forms workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "forms",
"label": "Forms",
"description": "Forms in the selected Forms workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "published_forms",
"label": "Published forms",
"description": "Forms currently open for responses.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "draft_forms",
"label": "Draft forms",
"description": "Forms that have not been published.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "responses",
"label": "Responses",
"description": "All responses recorded in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "responses_today",
"label": "Responses today",
"description": "Responses submitted since the current UTC day began.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "responses_last_7_days",
"label": "Responses in 7 days",
"description": "Responses submitted during the trailing seven-day period.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "responses_per_published_form",
"label": "Responses per published form",
"description": "All recorded responses divided by the current number of published forms.",
"unit": "responses/form",
"semantic": "rate",
"aggregation": "average"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"description": "The workspace whose forms and responses are included.",
"valueType": "string"
},
{
"key": "form_status",
"label": "Form status",
"description": "Whether a form is in draft or published.",
"valueType": "string"
},
{
"key": "response_period",
"label": "Response period",
"description": "The bounded period represented by a response count.",
"valueType": "string"
}
],
"lifecycleStages": [
{
"key": "draft",
"label": "Draft",
"order": 0,
"terminal": false
},
{
"key": "published",
"label": "Published",
"order": 1,
"terminal": false
},
{
"key": "closed",
"label": "Closed",
"order": 2,
"terminal": true
}
],
"events": [
{
"key": "form_created",
"label": "Form created",
"description": "A draft form was created in the workspace."
},
{
"key": "form_published",
"label": "Form published",
"description": "A form began accepting public responses."
},
{
"key": "response_submitted",
"label": "Response submitted",
"description": "A response was submitted to a published form."
}
],
"datasets": [
{
"id": "form_inventory",
"label": "Form inventory",
"description": "Current form inventory by publishing state.",
"grain": "One aggregate row per Forms workspace and form status.",
"metricKeys": [
"forms",
"published_forms",
"draft_forms"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"form_status"
],
"eventKeys": [
"form_created",
"form_published"
],
"actionIds": [
"create-draft-form"
]
},
{
"id": "response_activity",
"label": "Response activity",
"description": "Lifetime and bounded response counts plus the current responses-per-published-form ratio.",
"grain": "One aggregate row per Forms workspace and response period.",
"metricKeys": [
"responses",
"responses_today",
"responses_last_7_days",
"responses_per_published_form"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"response_period"
],
"eventKeys": [
"response_submitted"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"donut",
"table",
"actions"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "forms",
"label": "Forms",
"value": 2,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
}
]
},
{
"key": "published_forms",
"label": "Published forms",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
},
{
"key": "form_status",
"label": "Form status",
"value": "published"
}
]
},
{
"key": "draft_forms",
"label": "Draft forms",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
},
{
"key": "form_status",
"label": "Form status",
"value": "draft"
}
]
},
{
"key": "responses",
"label": "Responses",
"value": 3,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
}
]
},
{
"key": "responses_today",
"label": "New today",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-21T00:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
},
{
"key": "response_period",
"label": "Response period",
"value": "today_utc"
}
]
},
{
"key": "responses_last_7_days",
"label": "Responses in 7 days",
"value": 2,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-14T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
},
{
"key": "response_period",
"label": "Response period",
"value": "trailing_7_days"
}
]
},
{
"key": "responses_per_published_form",
"label": "Responses per published form",
"value": 3,
"unit": "responses/form",
"semantic": "rate",
"aggregation": "average",
"period": {
"start": "2026-10-21T12:00:00.000Z",
"end": "2026-10-21T12:00:00.000Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Forms workspace",
"value": "ws_forms_docs_fixture"
}
]
}
],
"appId": "app_topolo_forms",
"serviceName": "Forms",
"lastUpdated": "2026-10-21T12:00:00.001Z"
}
],
"workspace": {
"id": "ws_forms_docs_fixture",
"name": "Fixture Forms"
},
"workspaces": [
{
"id": "ws_forms_docs_fixture",
"name": "Fixture Forms",
"isDefault": true
}
]
}
Confirm actual app/workspace/metrics and their semantics. Do not run create-draft-form merely because its descriptor is present.
Builder or widget validation failed
Complete synthetic UNRUN HTTP500 from the published widget-server catch boundary after a builder/contract exception. The current action success schema does not describe this failure envelope; it is an HTTP error example, not a validated success. No failing query or app was executed.
Input:
{}
Response:
{
"success": false,
"contractVersion": "3.0.0",
"appId": "app_topolo_forms",
"serviceName": "Forms",
"generatedAt": "2026-10-21T12:00:00.001Z",
"widgets": [],
"error": {
"code": "widget_contract_invalid",
"message": "Widget contract invalid",
"retryable": false
}
}
Preserve actual request/status/code. This catch does not uniquely diagnose a schema defect: a builder/database exception can reach it too.
Canonical app identity unavailable
Complete synthetic UNRUN HTTP503 before Auth/workspace/build when the wrapper appId resolver throws or returns an invalid id. This carrier is distinct from the v3builder-error envelope.
Input:
{}
Response:
{
"error": "App identity unavailable"
}
Retain the actual failure; do not infer no records, use an alternate app identity or change access to force a response.
Verify and recover
-
Compare actual outerappId,contractVersion,activeworkspace.id and eachwidgetresource.id with the approved target. A selectorfallback or missingworkspace is not success for the intended workspace.
-
Check exactcountsemantics,observedAtvsoutergeneratedAt/lastUpdated,selectedscope and two-store consistency limits. readydoesnotproveprivatecontentdecryption/downstreamhealth.
-
Do not execute embedded controls or autoaccept recoverydeletion. Actual auth500/503/unavailableerrors retain their owncarrier/requestid; avoid repeated expensivepolling or changingkeys/grants as readrecovery.
Read only: no data rollback is needed. Preserve actual denial/error and reconcile the original target; never create a form, change workspace/grants, trigger a delivery or provision keys to make a widget nonempty.
Related actions
Change log
- 2026-10-21: Added exact published v3wrapper and Forms draftdescriptor, workspacefallback/state/aggregate semantics, descriptor authorization limits and complete source-derived responses. All examples remain synthetic and unrun.