Visual assets

A custom visual reads pictures, fonts and data files by name, in the form asset://file-name. This page covers how those files are stored, uploaded, copied, downloaded and deleted, with the rules and the messages behind each step; for the visual itself, see Custom visuals and the visual library.

Where a visual's files live

A report keeps one set of files. Everything in the report that references a file by name reads the same file.
A visual in the visual library keeps files of its own, separate from any report's. When you add a tile to the library with Add to visual library and it uses files, they are copied to the library visual, and the confirmation adds "its assets were copied to the library visual."
A report that inserts a library visual needs its own copies of the files the visual uses. The picker warns Assets missing from this report, names the files, and adds that the visual shows them as missing until they are uploaded to the report's assets.
Copies keep the file names, so the asset:// references in the code do not change when files move with a visual.

Upload files

Open the report in edit mode, open the visual's Studio (Edit code), and select assets/ in the file tree. The Visual assets dialog opens. The dialog's own controls are described on Report assets and Custom visual Studio, assets and diagnostics.
Drop files onto the dialog, or click to pick them. The area reads Drop files here, or click to pick them, and shows Uploading... while a file goes up. Files upload one at a time.
A file that lands confirms Asset uploaded and shows its reference, in the form Reference it as asset://file-name. A file that fails confirms Asset not uploaded, and the other files carry on.

The dialog takes any file up to 20 MB, at most 20 files per drop, as its own line says: Any file up to 20 MB, at most 20 files per drop.
A larger file is refused with File too large. Maximum size for visual assets is 20MB.
Pictures, WOFF2 fonts and JSON or GeoJSON are read from their bytes, so the check uses the content and not the extension. An SVG is sanitised on upload. Everything else is stored under its declared or extension type, and anything that could run as a web page, such as HTML, is never stored as one.
A name already in use gets a numbered suffix, such as -2: logo.png becomes logo-2.png, and the existing file is never overwritten. Names are compared without regard to case.
A name that cannot be used is refused with Invalid file name.
A library visual's own files follow the same rules. For the transfer budget and the other caps a visual carries, see Custom visual options, data and limits.

Name a file in your code

Markup and CSS refer to a file as asset://file-name; a uni.assets call takes the file name.
Every card in the dialog shows its file's reference. Copy reference to {fileName} puts it on the clipboard and confirms Reference copied; when the clipboard is not available, it reads Reference not copied.
How the code reads a file, as a URL or as bytes, is on Custom visual Studio, assets and diagnostics.

Copy files with the visual

Pasting a custom visual into another report copies its files into that report, under the same names. The paste reports the outcome, for example Assets: 2 copied, 1 already present, 1 missing on the source. In the message, "copied" counts the files added to this report; "already present" counts names the report already held, whose file is kept; and "missing on the source" counts names the code uses that the source report did not have. If the files cannot be copied, the tile still lands and the paste reports Assets not copied.
A .dpvisual bundle does not carry uploaded files. For what a bundle contains, see Copy and share custom visuals.

Delete a file

On the file's card, choose Delete {fileName}. The confirmation reads Delete this asset? and names the file: "logo.png" will be removed from this report. Visuals referencing asset://logo.png will show it as missing.
Confirm to remove the file.

Deleting removes the stored file and frees its name; a later upload may use that name again. Everything that referenced the file shows it as missing until a file with that name is uploaded again.
The delete cannot be undone. Download a copy of the file first if you may need it later.

The messages you may see

A refused upload or a file that cannot be reached answers with one of these messages.

The message	What it means
`File too large. Maximum size for visual assets is 20MB.`	The file is over the size cap. Upload a smaller version.
`The file content does not match its declared type or extension.`	The bytes do not match the file's name or type. Rename or repair the file.
`The SVG could not be sanitised into a renderable document.`	The SVG cannot be cleaned into an image the app can store. Export it again, or upload a PNG instead.
`Invalid file name`	The file's name cannot be used. Rename the file and upload it again.
`No file was uploaded.`	The upload arrived without a file. Pick the file again.
`Could not find a free name for this file. Try renaming it and uploading again.`	Every numbered suffix for this name was taken. Rename the file.
`The file was not stored: the file storage did not accept it. Try again, and tell an administrator if it keeps failing.`	The file did not reach storage. Upload it again.
`The asset could not be copied: the file storage did not accept it. Try again, and tell an administrator if it keeps failing.`	A copied file did not reach storage. Paste the visual again.
`Asset not found`	The file is not there. Reload the dialog; if a visual shows it as missing, upload the file again.
`Asset content not found`	The file's entry exists, but its stored bytes are gone. Upload the file again under the same name.
`The file could not be read from file storage. Try again, and tell an administrator if it keeps failing.`	The file exists but could not be read right now. Try again.
`Could not load the assets`	The dialog could not read the list of files. Reopen it, or reload the report.
`DataPrism Custom Visuals is disabled on this deployment.`	Custom visuals are switched off for the whole deployment, so nothing new can be stored; reading and deleting keep working. Ask an administrator.
`Report not found` / `Visual not found`	The report or the library visual is gone, or your account cannot see it; a report or visual you cannot reach answers the same as a missing one.
`You do not have edit access to this report.`	You can see the report, but you cannot change it. This action needs edit access.
`Report access could not be verified with the reporting service. Try again.` / `Visual access could not be verified with the reporting service. Try again.`	The access check did not answer. Try again.

Permissions

Reading a report's files: anyone who can open the report.
Uploading a file to a report, copying files into a report, or deleting a file from a report: Author DataPrism Custom Visuals, together with edit access to the report.
Reading a library visual's files: anyone who can see the visual; uploading or deleting them: Publish Organization Visuals.
When custom visuals are switched off for the whole deployment, uploads are refused; reading and deleting keep working.

See Who can do what in DataPrism.

Questions, answered

Are a report's files and a library visual's files the same set?

No. A report keeps its own set, and a library visual keeps its own. When you paste a visual into another report, its files are copied with it; when a report inserts a library visual, the report still needs its own copies, and the picker warns Assets missing from this report until the files are uploaded to the report's assets.

What do the numbers in the paste message mean?

The message reads like Assets: 2 copied, 1 already present, 1 missing on the source. "Copied" counts the files added to this report; "already present" counts names the report already held, whose file is kept; "missing on the source" counts names the code uses that the source report did not have.

Do two visuals in one report share one uploaded file?

Yes, when they reference the same name. The files belong to the report, one file per name, so two visuals that use asset://logo.png read the same file. Replacing or deleting it affects both.

I deleted a file by mistake. Can I get it back?

The delete itself cannot be undone. Upload the file again under the same name, and everything that referenced it works again. The same path changes a file's contents: delete it, then upload the replacement under the same name, and the code needs no changes.

Who can upload or delete a library visual's files?

Publish Organization Visuals. On a report, uploading and deleting need Author DataPrism Custom Visuals together with edit access to the report. Reading follows the access you already have to the report or the visual. See Who can do what in DataPrism.

What should I do when an upload says the file was not stored?

The message means the file did not reach storage. Upload it again; if the same file keeps failing, tell an administrator.

What does "Invalid file name" mean?

The file's name cannot be used, so the upload is refused with Invalid file name. Rename the file on your computer and upload it again.

The dialog says it could not load the assets. Are my files gone?

No. The dialog could not read the list of files, so it shows the error in place of the list. Reopen the dialog or reload the report and try again; if it keeps failing, ask an administrator.