PI Vision Alarms Add-in User and Administration Guide

Introduction
Purpose
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.
Intended Audience
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.
Scope
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.
Definitions, Acronyms and Abbreviations
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
Installation
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.
Prerequisites
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" />
Security
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.
Installation directory
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
Installing ALARMS-ADDIN extension from MSI
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”.
Setup Splash Screen
When installer is initiated the following splash screen should appear. Click “Next >” to proceed to next screen.
License Agreement 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.
Installation Folder Screen
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”.
Successful Installation Screen
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.
How to Cancel Installation Process
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 installation check
After successful installation process the ALARMS-ADDIN extension icon should be available on “Assets” panel in PI Vision platform.
Configuration
Configuration Section
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.
Data limit
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.
Table properties
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.
PI String Delimiter
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: “;”, “:”, “,”, “|”.
Columns Definition
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.
Row colors
This section contains parameters required for row color definition and provide the following:
Even rows color
Odd rows color
Mouse-over row color
Overall settings
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
Operations and troubleshooting
This chapter will cover common issues, error messages, and steps for troubleshooting problems related to the PI Vision Alarms Add-in (ALARMS-ADDIN) extension.
Principles of Operation
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.
Adding extension to the PI Vision display
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.
Read and change configuration
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
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.
Columns definition
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.
Read Data from PI Point or AF Attribute
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.
Run Once or Real-Time
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.
Ordering and Filtering
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.
Data reporting
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.
Error Reporting
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.
PI Vision Alarms Symbol - Previous
PI Vision Alarms Add-in Changelog
Next - Batch & RtReports Synchronization Utility
Batch & RtReports synchronization Releases Changelog