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.
Term | Definition/Description |
CPU | Central Processing Unit |
CSP | Content Security Policy |
CSV | Comma-separated values, a file format (usually with a .csv extension) |
PDF | Portable Document Format |
Host | Representation of specific computer node either as machine name or IP address. |
IP Address | An Internet Protocol address |
MS | Abbreviation for Microsoft |
MSI | Microsoft Installer |
OSIsoft | PI Server and AFâSDK software vendor |
PDF | The Portable Document Format |
PI | Synonym to PI Server. OSIsoft nomenclature for Data Archive system. |
PI-SDK | OSIsoft software development kit for communications with PI Server (COM based). |
PI Point | Data stream container, storing time-series data. |
AF Attribute | AF Data stream, alias to a PI System Tag |
PI Server | OSIsoft nomenclature for Data Archive system |
PI System | Suite of OSIsoft products that are used for data collection. |
PI Vision | 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 3.3.0.9 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.
Name | Description |
Data limits | Define the limit of data amount which alarms-addin extension can receive for given period. |
Table properties | Define the table layout and row count for one table page. |
PI String Delimiter | Define the symbol which should use for string split. |
Columns Definition | Define the column visibility, names and indexes. |
Row colors | Define the appearance of rows in the table. |
Overall Settings | 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.
The purpose of this section is to provide the high-level description of internal procedures ALARMS-ADDIN extension performs while processing data. The extension is provided in a form of standard application installer. The ALARMS-ADDIN extension is a JavaScript application and is dedicated interface for:
- 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.
The input data required for alarms detection and parsing - is retrieved from the PI Server through the use of OSIsoft PI Vision. ALARMS-ADDIN is a JavaScript extension for OSIsoft PI Vision platform which performs the following steps per each data retrieval:
- 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.