Assemble canvases for your users

A canvas gives an audience a convenient starting point for its reporting. For example, a service team can see a workload dashboard and a small set of KPIs together rather than searching for each resource separately.

Prepare the content and audience first

Create or select the dashboards, KPIs and access groups before creating the canvas. Confirm that the underlying content and data permissions are appropriate for the intended readers.

A canvas assignment is part of the reader experience. It is not a substitute for customer-data isolation or permissions on the reporting resources it contains.

Create an explicit configuration

Canvas Save takes a CanvasClientModel. The main configuration includes:

Use a user identity: canvas operations can require the authenticated current user ID. Retain the GUID returned in Data and read the canvas back. The Create a canvas for an existing customer group recipe in Recipes demonstrates the sequence.

Preserve assignments when updating

Canvas Update accepts the complete client model and relationship lists. Maintain a complete intended configuration rather than sending an incomplete patch.

The canvas GET shape differs from the save/update shape. It includes nested kpis, dashboards and groups, while the write model uses ID lists. The documented read model does not expose a direct UserIds list. Do not reconstruct an update from that GET alone and silently clear direct-user assignments. Reconcile the complete assignment configuration before saving.

Offer a useful user preference

List canvases for the current user returns a bare array. Set Favorite For User saves a preference for that authenticated user; it does not grant access or set another user’s preference.

Canvas refresh behaviour and dataset freshness are separate concerns. See refresh history and data freshness, then verify the finished canvas using an intended reader account.