Visual library

The visual library is where your organisation's custom visuals are published and kept. Publish a visual once, insert it into any report, and control which version each report uses. Every library starts with ten ready-made visuals; see Built-in library visuals. To build a visual of your own, see Custom visuals and the visual library.

Publish a tile to the library

You need the Author DataPrism Custom Visuals permission. Without Manage DataPrism Organization Visuals, what you publish stays a draft until a publisher publishes it.

1. In edit mode, choose Publish to library from the tile menu of a custom visual, or click Publish to library in the header of the tile's Studio. When there is something to publish, unapplied edits are applied and the report is saved first; while the report has unsaved changes, the menu entry reads Save report and publish to library.
2. A tile that is not in the library yet opens Add to visual library. Name is the name the library shows, up to 200 characters. Description says what the visual shows and when to use it, up to 2,000 characters. Family is one of Chart, Table, KPI, Map, Text, Navigation or Other.
3. Choose an Icon with Choose icon, or leave it empty to use the family icon; see Choose an icon. Under Docs, write the markdown readers see on the visual's Docs tab, up to 20,000 characters: what it shows, which fields to bind, how to read it.
4. For a visual that reads fields, leave Store the first 50 rows as sample data on. Sample rows drive the gallery thumbnail and preview, and every library reader sees them.
5. Choose Publish to library. The visual is published at version 1 and the tile is pinned to it. Without Manage DataPrism Organization Visuals the button reads Add as a draft, and the visual stays a draft that only you and publishers see.

The form refuses incomplete input with Name is required, Name is too long (200 characters max), Description is too long (2000 characters max) or Docs are too long (20,000 characters max). A disabled button carries its reason, such as Enter a name for the visual, Sample rows are still loading or Fix the blocking checks first.

Publish a new version from a tile

A tile that is already pinned to a library visual publishes its code as the next version of that same visual, instead of creating a second one.

• When no other tile uses the visual, the version is published straight away and the tile moves to it. A confirmation is all you see.
• When other tiles use it, the dialog Publish to "<name>" lists Other reports that use it and offers two choices:
  • Update everywhere (N reports) rewrites the other tiles as one labelled, restorable version per report.
  • Only this tile makes the version the library head and moves this tile only; the other tiles keep their version and show Update available.
• A version that changes the data roles or options is a Breaking change: Update everywhere is unavailable, and Only this tile is chosen for you.
• If you own the visual but do not hold Manage DataPrism Organization Visuals, the version is saved as a draft and only this tile moves to it; the confirmation reads Saved v<n> of "<name>" as a draft. A publisher can make it the library head later.
• If you cannot add versions to the visual, because you neither own it nor hold Manage DataPrism Organization Visuals, or if the visual is no longer available, the dialog opens as Publish as a new visual. The tile's code becomes a new library visual, and the tile is pinned to it.
• When the tile's code already matches its version, nothing is saved: Nothing to publish.

While a pinned tile's code differs from its library version, the tile shows the Modified chip.

Publish a version from the library

A draft is visible to its owner and to people who hold Manage DataPrism Organization Visuals. Everyone else sees the visual only after it is published.

1. Open DataPrism > Visuals and select the visual. The header reads Current v<n> once the visual has a published version, or Not published yet.
2. In Versions, choose Publish on the version that should become the library head.
3. Choose what happens to the reports that already use the visual, then confirm with Publish or Publish and replace.

The count covers only tiles that would really change. Tiles already on the version, detached copies and disabled tiles are listed under Left as they are. When no tile would change, the dialog offers a plain Publish: "No report tile would change: every tile that uses this visual is already on this version, detached or disabled."

Replace is preselected when the version is compatible with every pinned tile. When a version changes the data roles or options, replace is unavailable: Replace is unavailable: this version changes the data roles or options, so dependant tiles would lose their bindings. Publish it as a new version instead.

Publishing is also refused while the code uses literal colours. The checks a visual passes are described in Sandbox, network and the allowlist.

Insert a visual into a report

1. Open the report in edit mode, open Visualizations and choose Library in the Custom group. The picker reads Insert from the visual library.
2. Search by name, description or author; switch between Organization and This report (N); and sort by Recently updated or Name A to Z.
3. Select a visual. Details lists the roles it Expects in the Data well and the versions under Version to insert; Docs shows the visual's documentation.
4. Choose Insert v<n> onto page, then bind the fields the visual reads in the Data well.

The picker lists published visuals only. One that cannot be inserted stays listed, dimmed and last; hover it for the reason. When there is nothing to show, it offers Open the visual library, Browse the organization or Clear search.

A visual can reference uploaded files. When the report does not hold them, the picker warns Assets missing from this report; the visual shows them as missing until they are uploaded to the report's assets.

Pin visuals to the Visualizations pane

Pin the library visuals you use most, and they sit one click away in every report you edit.

1. Pin a visual from its card in the gallery or the picker (Pin to Visualizations), or with Pin in the visual's detail. Unpin removes it.
2. In edit mode, the Custom group of Visualizations shows a Pinned row with each pinned visual's icon. Hover an icon for its name.
3. Click a pinned visual:
   • With one visual selected on the page, the tile turns into the pinned visual at its published version. Its title, size, position, page, background, lock and cross-filter settings stay, and its fields are bound to the visual's roles by kind and order. The confirmation names the roles still to fill: "Still needed in the Data well: ...".
   • With nothing selected, a new tile is added to the page, as from Library.

• Pins are yours: they follow you on every device and nobody else sees them. You can pin up to 24 visuals.
• A pinned visual that is disabled or has no published version is dimmed in the row. A pin of a visual that no longer exists disappears.

Edit a visual's details

The visual's owner and people who hold Manage DataPrism Organization Visuals can change how it is listed.

1. Open the visual in the library and choose Edit details.
2. Change Name, Description, Family, Icon or Docs. Every version shares these details; code changes go through Edit code.
3. Choose Save details. The button stays disabled with Nothing changed yet until you change something.

The Docs tab, in the library's detail and in the insert picker, renders the markdown you write here. A visual without docs reads No documentation yet.

Choose an icon

The icon shows on library cards, in the picker, in the visual's detail and in the Pinned row. Choose icon opens Choose an icon, with three sources:

• Library: every icon of the built-in icon set. Search by name or synonym, browse by category, or open All icons or Recent.
• Generate with AI: Draw an icon with AI draws a single-colour line icon from the visual's name and description. Add an optional hint to steer it, then choose Generate; Regenerate keeps the last six drawings so you can go back.
• Upload SVG: your own single-colour SVG, up to 16 KB. Its colours are folded into one, and scripts, links and embedded images are removed.

Whatever the source, pick a Color (Default, Primary, a chart colour or a status colour) and a Shape (None, Circle or Square); the preview shows the icon as it appears in the Visualizations pane. Choose Use icon to keep it, or Use family icon to go back to the family's icon. Reset beside the icon field does the same.

Manage a published visual

Open DataPrism > Visuals to browse the gallery: one card per visual, with its icon and a preview drawn from sample data, and controls to filter by status (Published, Draft, Deprecated) or family. Select a visual to open its detail; an open visual has its own link you can share.

• Preview draws the shown version on its sample rows, and Docs shows the visual's documentation.
• Versions lists every version with the roles it declares, whether it is compatible or breaking, and when it was published. The current version is marked, and any version can be published from here.
• Used in lists the reports that pin the visual, for example Used in 3 reports (5 tiles, 1 detached), each with an Open link. When no report uses it yet, it says so.
• Export downloads the shown version as a .dpvisual bundle; the gallery's Import adds one as a new draft. See Copy and share custom visuals.
• Edit code opens the Studio on the visual, with the AI assistant and its sample data. Save to library there saves the next version and publishes it the same way a pinned tile does. See Custom visual Studio, assets and diagnostics.
• Deprecate marks a published visual as deprecated; reports keep working and show a Deprecated chip. Delete is offered only while no tile pins the visual, and detached copies keep working.

Edit details and Edit code appear for the visual's owner and for people who hold Manage DataPrism Organization Visuals; Edit code also needs Author DataPrism Custom Visuals.

Switch a visual off and back on

• Disable this visual in a tile's menu switches that tile off. Its viewers see the Disabled by an administrator placeholder, and an author of the visual must save it again to bring the tile back.
• Disable everywhere in the library switches the visual off in every report; Enable reverses it.
• When custom visuals are off for the whole deployment, the custom visual type is hidden from Visualizations. For every message a switched-off tile can show, see Troubleshooting custom visuals.
• Administrators also decide which external hosts a visual may reach; see Sandbox, network and the allowlist.

Chips you will see

Update a tile that is on an older version

• A tile pinned to an older version shows the Update available chip. Select it to open Review update, which renders Pinned v<n> (in this report) beside Library v<n> (candidate) on the tile's own rows.
• Choose Update to move this tile; Update all in report (N) when other tiles in the report are also behind; or Detach to stop this tile from following the library. Each action saves one labelled report version.
• Your fields, options and saved viewer selections stay with the tile. What changes is the visual's definition: its code, libraries, data roles, options, assets, export settings and SDK.
• If the newer version changed the data roles or options, the dialog's warning reads: The new version changes data roles or options: bindings may need attention after the update. Check the two panes before you choose.

Questions, answered

Can I choose an older version to insert?

Yes. Under Version to insert you choose any published version, and the button takes that exact version, so it reads Insert v<n> onto page. The tile stays pinned to that version until someone chooses Update.

What do "Compatible" and "Breaking" mean on a version?

A version is compatible when it keeps the same data roles and options as the version before it. A breaking version changes them: it can still be published, but it cannot replace pinned tiles, so each report moves to it only when someone reviews the update.

What happens to a detached tile?

It keeps working on the version it has and stops following the library. It shows the Detached copy chip, replacing never touches it, and the Used in list counts it separately.

Why is a visual dimmed in the library picker?

It cannot be inserted: it is Disabled by an administrator or has No published version yet. It stays listed and last; hover it to see the reason.

Do I need sample rows to publish a visual?

Yes, for a visual that reads fields: without a sample it is blocked with A data-bound visual needs sample rows for its gallery thumbnail and preview. The add form stores the first 50 rows of the tile by default, and a sample can hold up to 1,000 rows or 256 KiB. A data-free visual, such as a header or a logo, publishes without sample rows.

Can I make an older version the current one again?

Yes. Open the visual, choose Publish on that version in Versions, and decide what happens to the reports that use the visual; it becomes the library head again.

Who can publish a visual to the library?

Anyone with Author DataPrism Custom Visuals can use Publish to library, but only people with Manage DataPrism Organization Visuals publish; for everyone else the visual or version stays a draft. New versions of an existing visual come from its owner or a publisher; anyone else publishes their tile as a new visual. Switching a visual off everywhere needs Disable DataPrism Custom Visuals. See Who can do what in DataPrism.

Why did Publish to library not ask me where the new version goes?

No other tile uses the visual, so there is nothing to choose: the version is published and your tile moves to it. The choice between Update everywhere and Only this tile appears only when other tiles pin the visual.

Why does a tile show Modified?

Its code differs from the library version it is pinned to, for example after Edit code and Apply. Use Publish to library to make the code the next version, or update the tile to take the library's code again.

How many visuals can I pin, and who sees my pins?

Up to 24. Pins belong to you and follow you on every device; nobody else sees them. At the limit, pinning another reads You can pin up to 24 visuals: unpin one first.

Why did my pinned visual not replace the selected tile?

A pinned visual replaces a tile only when exactly one visual tile is selected. With nothing selected, or several tiles, it adds a new tile to the page instead.