PI Vision Alarms Add-in User and Administration Guide
PI Vision Alarms Add-in User and Administration Guide
This document serves as the User and Administration Guide (UAG) for the PI Vision Alarms Add-in (ALARMS-ADDIN) which was designed and developed by © TQS Integration Ltd.
This manual is aimed at system engineers who will be performing installation and configuration of the PI Vision Alarms Add-in (ALARMS-ADDIN) used for displaying alarms states and data.
This manual describes the concepts of the PI Vision Alarms Add-in (ALARMS-ADDIN). The information within this manual should be enough to provide system engineer with the knowledge needed to successfully install, configure, and perform necessary actions. The following topics will be covered in the following sections:
- Installation: This chapter contains information about the default installation including default components and their configuration.
- Configuration: This chapter describes configuration options for ALARMS-ADDIN. This chapter will outline all possible use scenarios and all possible parameters user can specify.
- Operations and Troubleshooting: This chapter explains how add-in operates.
Central Processing Unit
Content Security Policy
Comma-separated values, a file format (usually with a .csv extension)
Portable Document Format
Representation of specific computer node either as machine name or IP address.
An Internet Protocol address
Abbreviation for Microsoft
PI Server and AF–SDK software vendor
The Portable Document Format
Synonym to PI Server. OSIsoft nomenclature for Data Archive system.
OSIsoft software development kit for communications with PI Server (COM based).
Data stream container, storing time-series data.
AF Data stream, alias to a PI System Tag
OSIsoft nomenclature for Data Archive system
Suite of OSIsoft products that are used for data collection.
OSIsoft visualization tool for all of your PI System data
The PI Vision Alarms Add-in (ALARMS-ADDIN) comes as a Windows Installer. The installer contains all components necessary to configure and run the ALARMS-ADDIN extension. This chapter will examine installation components, basic requirements and the folder/file structure created by the installer.
It is required that the following components must be installed before installing ALARMS-ADDIN extension:
- OSIsoft PI Vision version 220.127.116.11 or Higher.
NOTE: In PI Vision 2020, Content Security Policy (CSP) headers are used by PI Vision to enhance protections against cross site scripting and other attacks. These CSP protections might interfere with custom symbols or tool panes built using the PI Vision extensibility framework, because they block scripts and frames that are loaded from remote sources (outside the PI Vision website). OSIsoft recommends keeping these CSP protections enabled if possible and configuring them to add any additional trusted sources your custom symbols require. If absolutely required, the CSP protections can be disabled entirely.
To add additional trusted sources to the “script-src” or “frame-src” directives used by PI Vision, refer to the PI Vision Installation and Administration Guide section titled “Change Content Security policy” in OSISoft Live Library.
To support ALARMS-ADDIN with PI Vision 2020, user need to specify additional CSP directives for use with PI Vision:
- 1.Open the web.config file in the PI Vision root installation folder in any text editor.
- 2.To modify (a) the script-src directive, to add additional allowed sources for scripts, add the following settings in (a) to the <appSettings> section To disable (b) the script-src directive use the following setting in (b):
- 3.<add key="ScriptSrcPolicy" value="*.company.com trustedsite.com" />
- 4.<add key="ScriptSrcPolicy" value="Disable" />
- 5.To modify (a) the script-src directive, to add additional allowed sources for scripts, add the following settings in (a) to the <appSettings> section To disable (b) the script-src directive use the following setting in (b):
- 6.<add key="FrameSrcPolicy" value="*.company.com trustedsite.com" />
- 7.<add key="FrameSrcPolicy" value="Disable" />
The ALARMS-ADDIN extension requires security models for PI System (with PI Server), it should be provided via PI Vision platform.
PI System Access Configuration
The ALARMS-ADDIN extension uses Windows identity for secure connections to AF Server and PI Server (via PI Vision platform). Domain users running an extension must have permissions to read data on both PI System (AF server) and PI Server (data archive). In case of extension not being executed under domain account, then ALARMS-ADDIN extension must be executed under specific user which has identical accounts on interface node, PI System (AF Server) node and PI Server node.
The ALARMS-ADDIN extension will be installed to the following default directory defined by installer automatically via PI Vision installation directory or defined by the user at installation time manually in case when installer can’t determine correct path to PI Vision platform:
<Root drive>:\Program Files\PIPC\PIVision
Final path to the PI Vision Add-in:
<Root drive>:\Program Files\PIPC\PIVision\Scripts\app\editor\symbols\ext
The PI Vision Alarms Add-in (ALARMS-ADDIN) is packaged as MSI installer wrapped in executable (.exe). In Order to start installation – right click on provided alarms-add-in.exe file and select: “Run as administrator”.
When installer is initiated the following splash screen should appear. Click “Next >” to proceed to next screen.
Read the license agreement and if you accept the terms of the agreement, click on the checkbox: “I accept the terms of the License Agreement”. Click “Next >” to proceed to next screen.
Note: Installation will not proceed unless License Agreement is accepted.
Select the installation folder for the ALARMS-ADDIN extension if it wasn’t determined by installer automatically or select another folder and move files to PI Vision folder manually after installation process. By clicking on “Browse” button, the folder selection dialog will be opened.
Click “Install” to move to next screen.
Installation Folder dialog
Select or create a folder where the interface should be installed. To close the dialog, press “OK”.
On successful Install, an “Installation Complete” message is displayed. The user should be able to see the screen provided below. Click “Close ” to exit the installer.
On any screen, at any time – user has an option to initiate cancellation. Installation process can be terminated by clicking the “Cancel” button. The Cancellation confirmation dialog should appear as shown below.
By clicking button “Yes” – installation process will be terminated successfully.
After successful installation process the ALARMS-ADDIN extension icon should be available on “Assets” panel in PI Vision platform.
The ALARMS-ADDIN extension uses standard PI Vision configuration panel as a source for its configuration. Configuration consists of several sections which are described below.
Define the limit of data amount which alarms-addin extension can receive for given period.
Define the table layout and row count for one table page.
PI String Delimiter
Define the symbol which should use for string split.
Define the column visibility, names and indexes.
Define the appearance of rows in the table.
Define the appearance of the table.
This section contains the ALARMS-ADDIN extension processing parameters and define the maximum rows for given time period to process. The parameter may vary from 1000 to a 1000000 and affects the CPU usage.
This section contains ALARMS-ADDIN extension parameter for table layout. The parameter determines how columns width should be calculated depends on string data length. Also, this section contains the parameter for the amount of rows to display. The parameter determines how many rows will be displayed on one page of the table. Rows may vary from 10 to 100.
This section contains parameters required for string split. For each data received, the ALARMS-ADDIN extension tries to split alarm string to string array via delimiter symbol. Each column in the table should correspond to alarm string array via provided indexes. The parameter can be the following characters: “;”, “:”, “,”, “|”.
This section contains parameters required for columns definition and define the column visibility, width, position in the table and names for strings array after split. Each column in the table corresponds to alarm string array via provided string delimiter. By default, all columns are visible, width is auto calculated and have the names from 0 to the last array index: 0,1,2, … etc. First column always contains Date and Time for given alarm.
This section contains parameters required for row color definition and provide the following:
- Even rows color
- Odd rows color
- Mouse-over row color
This section contains parameters required for table appearance definition and provide the following:
- Background color
- Header text color
- Main table text color
- Font size
- Text alignment
This chapter will cover common issues, error messages, and steps for troubleshooting problems related to the PI Vision Alarms Add-in (ALARMS-ADDIN) extension.
- Parsing and displaying Alarms from a string based delimited tag or AF Attribute from OSI PI.
- Define a delimiter to parse out the string data from the PI Point or AF Attribute.
- Define the headers of the table via configuration.
- Filterable and sortable columns in the table views based on any data type.
- Data export to CSV and PDF formats.
- Read PI Point data from specified PI System Server or PI AF Attribute data from AF.
- Per each PI Point - read input PI Point or AF Attribute data from source and parse it to the table data.
- Per each component – read configuration data from component internal configuration such as string delimiter, column definition, component colors etc.
The ALARMS-ADDIN does not create destination PI Points or AF Attributes, all required PI Points or AF Attributes must be defined. The flow of data in the extension is unidirectional—that is, source data can only be read from the specified PI Point or AF Attributes and associated source PI Servers. By design, the extension does not edit or delete source PI data.
In order to support PI Vision custom symbols, the ALARMS-ADDIN extension provide an additional component on the "Assets" panel in PI Vision platform. To add ALARMS-ADDIN extension to the PI Vision display to enable search for useful PI Point or AF Attribute with alarms data, select the ALARMS-ADDIN icon and find a PI Point or AF Attribute, drag and drop it to the screen.
ALARMS-ADDIN extension should appear on the PI Vision display. To change current PI Point or AF Attribute, select another PI Point or AF Attribute from PI Vision search panel, drag and drop it to the ALARMS-ADDIN extension. Data should be reloaded, and new data set related to the PI Point or AF Attribute. Displayed Columns definitions will be restored from previous PI Point or AF Attribute, but the amount of columns in the table will correspond to the new PI Point data or AF Attribute.
In order to support interactive processing, the ALARMS-ADDIN extension provide an ability to change configuration on the fly via standard PI Vision interface. ALARMS-ADDIN configuration loaded when the extension is loaded the first time on the PI Vision display. To change extension configuration, right click mouse button on the ALARMS-ADDIN component and select “Format Symbol…” menu item.
Configuration panel is displayed on the right side of the PI Vision screen and configuration parameters for ALARMS-ADDIN will be provided via configuration panel.
Table layout parameter determine how column width should be defined. In case of “Auto” mode, columns width is calculated based on data size, in case of “Fixed” columns width can be defined by the user.
The user has an ability to change column visibility by the check/uncheck combo box opposite each column, change displayed name for each column name. In case of table layout is set to “Fixed” the user can change width for each column in terms of html. Columns width can be in pixels (500px), percentage (50%), centimeters, millimeters etc. (5cm, 5mm) or auto. The user can also change the display order of the columns by clicking
buttons. The selected column will be moved up or down from the current position.
As result of ALARMS-ADDIN operations per each time interval provided via PI Vision interface, the extension displays alarm objects to the table form. Alarms data received through PI Vision internal functions are processed according to the configuration and displayed in the form of a table on the screen. Time interval is defined by PI Vision user interface via start and end times. Each PI Point record comes with a timestamp. To display it, the PI Vision Add-in reformats the system timestamps as YYYY-MM-DD HH:mm:ss.SSS where YYYY - 4 digits year, MM – month number, DD – day of month, HH – 24 hours’ time, mm – minutes, ss – seconds, SSS – milliseconds.
The extension is designed to run either continuous or once (single time). At any given time, user can validate or re-process source PI data. When extension is set to run mode as “continuous” via PI Vision user interface (end time selected as "Now") – it reads in real-time updates from given PI Point or AF Attribute, process the data and update data in the table. The period for data updates can be reviewed and changed via PI Vision configuration.
The extension is designed to use ordering and filtering functionality. Ordering and filtering allow for the creations of searches of greater complexity and precision based on alarm properties stored in the table. This support gives flexibility to find alarms from large number of stored entries with database - like search criteria using UI components.
In addition to general processing, the ALARMS-ADDIN extension provides data reporting. As the name suggest, the section of reports provides an ability to generate reports for selected criteria (predefined) based on the selected filtering options.
The reports may be generated either in PDF or CSV formats by using the buttons underneath the name of the report item. The file will automatically be uploaded to the user’s computer via the built-in browser functionality.
If the ALARMS-ADDIN extension is configured to receive a certain amount of data, but for the provided period of time it received more data than specified in the configuration, an error occurs during processing and standard error message appear in the PI Vision interface.
It can be fixed via increase of Data limit parameter. The constraint is this parameter affects the CPU usage and may cause browser freezing.