Custom Visualization+

Overview

When to use it

Use this symbol when you need to:

• Show process values in a form no other symbol offers, such as a tank, a mimic or a plant-specific status board.
• Have an AI write the visualization from a description, without programming skills.
• Reuse one visualization on many displays and assets, with settings per placement.
• Let a click in the visualization zoom the display to a period or filter other symbols.
• Give operators buttons and entry fields that write values to PI.

Choose a ready-made symbol, such as Combo Chart+ or KPI Card+, when it already shows what you need. For the rows of AF tables, choose Custom SQL Visualization+.

Before you begin

• The administrator has installed the frames folder with Vision Library+. Without it the symbol stays empty. See "Install the Vision Library+ Files" in the installation and administration guide.
• The administrator can limit the code editor to PI Vision administrators and can block writes for the whole site. See "Configure Custom Visualization+" in the installation and administration guide.
• Any PI Point or AF attribute can be a data source.
• To store the code in AF, use a String attribute without data reference. Saving code there needs AF write permission.
• To write values, operators need write permission on the PI Points or AF attributes.

Add and set up the symbol

1. Select Custom Visualization+ in the PI Vision symbol gallery and drag one or more data sources onto the display. The symbol shows a starting example: a table of the data sources with value, units and time.
2. Right-click the symbol and select Configure Custom Visualization+....
3. Under Code, select Edit code. The code editor shows the document (1), a Preview (3) and an Output console (4).
4. Replace the code with your document, for example one an AI wrote for you (see the next task).
5. Select Run (2) or press Ctrl+Enter. The preview runs the draft on the symbol's current data, and messages and errors appear under Output.
6. Select Apply (5), close the pane and save the display. The symbol now shows your visualization.

Common tasks

Get a document from an AI

Use this when you can describe the visualization in words but do not want to write the code.

1. Right-click the symbol, select Configure Custom Visualization+..., and select Edit code.
2. Select Copy AI prompt. When the code area holds your own document, the button is split into Copy AI prompt (change) (1) and Copy AI prompt (new) (2).
3. Paste the copied text into your AI chat and add your request, for example "A tank that fills with the level of the first source, with the limits as colored bands."
4. Paste the AI's answer into the code area, select Run, and check Output for errors.
5. Select Apply, close the pane and save the display.

Copy AI prompt (change) adds your current document, so the AI changes it instead of starting over. On an error, Copy error report (3) copies the document and the output console for the AI to fix. The document reference shows the copied text.

Write a request that gets a good result

Use this when you add your request to the copied prompt. The prompt already carries the labels, units, states and limits of the data sources, the theme, and the viewer's formats and time zone, so do not repeat them.

1. Name the data sources by position or label: "the first source", "the source Feed flow".
2. Say what to show and over which period: the current value, the trend over the display time range, or the hourly average.
3. Name every value that should be adjustable per symbol, such as a title, limits or a color. The AI declares them as settings, which appear under Parameters.
4. Say what a click does: zoom the display to a day, select a source for other symbols, or nothing.
5. Say whether the document writes, and to which source.
6. Name the caption languages and the rough size, for example "English and German, a 300 by 200 tile".

Example requests:

• "Daily average bars of every source. A click on a day zooms the display to that day and selects that source for other symbols."
• "A set point panel for the second source: an entry field and a Write button that shows the result. Make the title adjustable."
• "The hourly minimum, average and maximum of the first source as a band, the running hour dashed."

To refine a document, ask for one change at a time with Copy AI prompt (change). Test buttons and clicks in the preview, which never writes, and compare a few numbers with a PI Vision trend before you apply.

A document loads nothing from the network, so ask for drawings in SVG instead of external images or fonts. Nothing animates when data updates. A document reads only the symbol's own data sources over the display time range: at most 5,000 history values per source and 1,000 summary intervals per call, so ask for daily figures over long periods.

An AI wrote all documents below.

Store the code in an AF attribute

Use this to keep one document for many displays, to let the code follow the display asset, or for a document longer than 256,000 characters.

1. Right-click the symbol and select Configure Custom Visualization+....
2. Under Code, select AF attribute for Code source (1).
3. Drag the String attribute from the asset tree or the search results onto Code attribute (2), or paste its path and press Enter.
4. Turn Relative to the display asset on (3) when each asset carries its own code.
5. To change the code, select Edit code (4), then Save to AF, and confirm.

The symbol now runs the code stored in the attribute. Save to AF changes every display that uses the attribute, which is why it asks first; open displays read the change when they are opened again or switch asset. When someone else changed the attribute in the meantime, nothing is saved and Reload loads the current code.

Place one document several times with its own settings

Use this when the same visualization appears for several lines or units, each with its own title, limits or color. The document must declare these settings as parameters.

1. Select the symbol, right-click it and select Configure Custom Visualization+....
2. Expand Parameters. It shows one row per setting the document declares, with the labels the document gives them (1).
3. Enter a value and press Enter or leave the field (2). The symbol updates at once.
4. Pick a color (3). Theme (4) returns the color to the symbol's theme, and Reset returns any setting to the document's default.
5. Repeat for each placement, then save the display.

Three placements of one gauge document, each with its own title, limits, decimals and color:

Let a click change the time range and filter other symbols

Use this when a click on a day, an hour or a row should zoom the whole display to that period, or filter other symbols. The document decides what a click does; the pane decides whether it may.

1. Right-click the symbol and select Configure Custom Visualization+....
2. Under Code, turn Allow time range on (1).
3. Expand Filtering and select + Add Output. Enter a Channel name (2) and select the document's selection as Source (3).
4. In each symbol that should follow, add a Linked Input on the same channel, as described in "Configure a Linked receiver" in Filtering dashboards. Another Custom Visualization+ offers the filters its document declares.
5. Save the display.

In view mode, a click on the third day of Demo|Sinusoid 3 marks the source (1) and moves the display to that day. The document offers Clear selection (2), and the second visualization (3) shows only the selected source.

The time bar shows the selected day; operators go back with it.

Let operators write values

Use this for an operator panel that writes a set point, a mode or a note.

1. Right-click the symbol and select Configure Custom Visualization+....
2. Under Code, turn Allow writes on (1). Confirm every write (2) is on and asks the operator before each write.
3. To check values, expand Datasources and select a numeric data source. Turn Check limits on (1), choose Hard limit (2), choose Limits from Database or Custom (3), and enter a Message (4).
4. Close the pane and save the display.

When an operator selects a write button of the document, the Write values dialog lists each value and time. Confirm writes, Cancel writes nothing.

Use the symbol

What an operator sees and can do is defined by the document. The operator panel below writes a set point.

• Hover, click and keys do what the document provides, such as tooltips, a selection that filters other symbols, a zoom of the display time range or a write.
• Writes need the operator's PI or AF write permission and are confirmed in the Write values dialog unless the author turned that off.
• Asset switch: labels and values follow the display asset.
• Navigation link: with a navigation link (Add Navigation Link...), a click opens the link and the visualization takes no mouse input.
• Edit mode: clicks select the symbol; the visualization does not react to them.
• Errors of a document go to the PI Vision log, never into the display. Select Run in the code editor to see them under Output.

Security: the document runs in an isolated frame. It cannot reach the network, PI Web API or the PI Vision page, sees only the data of its own data sources and writes only to them.

Configure the symbol

Right-click the symbol and select Configure Custom Visualization+.... The pane has the groups Datasources, Code, Parameters, Filtering and Style, followed by the standard Web API, License Status, Help and About groups.

Data sources

Multi-state

Right-click the symbol and select Configure Multi-State... to give a data source PI Vision's own multi-state. The symbol evaluates the states; the document receives the color, blink and name of the current state and paints them.

Code

Code editor

Parameters

One row per setting the document declares: a text field, a number field, an on/off toggle, a list or a color picker, labeled by the document in the viewer's language when the document provides it. Reset returns a setting to the document's default; Theme returns a color to the theme. When the document declares no settings, the group says so. See Place one document several times with its own settings.

Filtering

Linked Outputs map each selection the document declares to a channel; Linked Inputs map each filter it declares to a channel other symbols publish. See Filtering dashboards.

Style

Theme, Surface and Container Style set the colors and font the document receives and the container drawn around it. Custom follows the display background. See Themes and container styles.

What you can ask for

Everything a request can ask for, and the setting it needs. Mention the capability in your request; the copied prompt tells the AI how to build it.

Document API

The functions and data a document can use, for authors who read or write the code. The Custom Visualization+ document reference holds the complete text with examples, exactly as Copy AI prompt gives it to the AI.

Troubleshooting and limitations

Limitation: A document loads nothing from the network, and reads and writes only the symbol's own data sources over the display time range. See Write a request that gets a good result.

Limitation: Software Athlete supports the symbol and its document functions, not the code of individual documents.