Micro-application Data and Resources

This guide targets developers of campus, building and business-space applications using the 2.00.083 source contract. Confirm deployed frontend/backend and database capabilities before enabling it. Publishing documentation does not upgrade the platform.

Scope and minimal fields

Overview screens primarily need alarms, online/offline status and a few business states such as running, occupied or faulted. Establish the current organization, formal location scope or actual device bindings before calling POST /thinklink/device/find-page-by-fields.

{
  "current": 1,
  "pageSize": 50,
  "location_code_subtree": "<building-location-code>",
  "fields": ["online"],
  "alarm_detail": false
}

Replace the placeholder with an actual location in the current organization. Every row includes eui, alarm_status and alarm_desc; select other fields as needed. Request id explicitly for later editing, and name or location_code only when needed for labels or grouping.

• fields selects base fields, calculated online, or the complete transform_3d. Attributes and telemetry have separate selectors; do not treat telemetry_data as a physical column in fields.
• server_attrs, shared_attrs and process_data accept field-name arrays or true for the whole group. Select telemetry by thing-model ID, for example {"<thing-model-id>":["temperature"]}. Omit an unused selector; false and null are not substitutes for omission.
• Overviews should not request full configuration, attribute groups, all telemetry or alarm_detail:true by default. Load details after a building, space or device is selected.
• Use the existing list's location_code for the current location; use location_code_subtree for descendants as well. Subtrees use complete path boundaries, not code-prefix matching. Business spaces use their actual device bindings.
• Ordinary queries retain current-organization and PUBLIC visibility; the subtree branch additionally restricts to the current organization. Enforce the intended scope and never fall back from an empty binding or unknown location to the whole organization.

Complete pagination and failure states

The response is {data,total,current,pageSize}. For whole-building or whole-space summaries, fetch all pages according to total, deduplicate by EUI and verify scope coverage. A first page is not a complete summary. Failed pages, stale results or a scope change invalidate completeness.

alarm_status counts each device's current alarms by severity; alarm_desc contains descriptions. Neither is a subtree aggregation endpoint. online uses active_time and twice heart_period, returning false when either is absent; it is not automatically equivalent to a custom _online attribute.

Preserve distinct unrequested, unloaded, failed, stale and missing-field states. Do not replace them with healthy, no alarms, zero or false. Key projection omits JSON null; read a complete group or dedicated endpoint when null must be distinguished from a missing key. This paginated endpoint reads persisted data, whereas find-device-data reads current cache, so values can temporarily differ after script updates.

Reuse data and cache resources

Reuse requests across cards and views for the same organization, scope and selected fields. Include these in cache keys; switching organization or scope must not reuse old summaries. Load names, models, spatial bindings and transform_3d separately from frequent status refreshes. Merge updates only where a reliable subscription exists; do not assume new fields already have MQTT delivery.

Upload and replace models, textures, images, videos and documents through the File Management API. Check quota, persist file IDs, obtain and renew access-ticket values as needed, and read /v/:ticket. Both the single-file and organization-total limits are 50 MiB. Load resources by scene and reuse them across status refreshes. Invalidate caches using update_time or a resource version after replacement. Anonymous access requires explicitly enabled sharing.

Application acceptance

Check actual fields, scope, every page, empty bindings, missing fields and failures. Inspect duplicate requests across cards, expired tickets, sharing disabled, and rendering after replacement. Preserve existing application IDs, configuration, routes, menus and business permissions. Verify the actual hosted page; a local build or successful upload is insufficient.