PI for StreamInsight User Guide. Version 1.0

Transcription

1 PI for StreamInsight User Guide Version 1.0

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: OSIsoft Australia Perth, Australia OSIsoft Europe GmbH Frankfurt, Germany OSIsoft Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal & Calgary, Canada OSIsoft, LLC Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil OSIsoft France EURL Paris, France PI for StreamInsight User Guide Copyright: OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Version: Published: 14 June 11

3 Table of Contents Chapter 1 Introduction... 1 PI for StreamInsight Adapter Overview... 2 Supported Features... 2 About this Guide... 3 Prerequisite Knowledge... 4 How to Use PI for StreamInsight with Microsoft StreamInsight... 4 Microsoft StreamInsight Concepts... 4 Microsoft StreamInsight Architecture... 8 PI for StreamInsight Deployment Models... 9 PI for StreamInsight Scenarios... 9 Chapter 2 Install PI for StreamInsight Minimum Hardware Requirements Supported Operating Systems Installation Prerequisites To Install PI for StreamInsight Adapters To Remove PI for StreamInsight Chapter 3 Verify PI for StreamInsight Installation Run the Installation Test Program Chapter 4 PI for StreamInsight Samples Before You Use the Samples Build and Run the Samples Chapter 5 Create a StreamInsight Application Set up the Visual Studio Project Add Using Directives Configure PI Points Set up Constants Instantiate a server instance and application Configure PI for StreamInsight Create an Input Stream Define the Query Create an Output Adapter Start the Query Run the Sample Extending the Application PI for StreamInsight User Guide iii

4 Table of Contents Chapter 6 Using PI for StreamInsight Adapters Creating Different Types of Adapters Configure the Input Adapter Configure the Output Adapter Using Typed and Untyped Adapters Additional Features of Event Payloads PI for StreamInsight Support for Microsoft StreamInsight Event Shapes Chapter 7 Developing Applications with.net Chapter 8 Diagnostics Appendix A Technical Support and Resources iv

5 Chapter 1 Introduction PI for StreamInsight integrates the PI System with Microsoft StreamInsight, a platform for developing Complex Event Processing (CEP) applications, and allows users to write analytical queries against PI System data. When used together, these products enable you to build applications and queries that monitor, analyze, report, record and filter PI System events. Data from PI or non-pi systems can be streamed (page 5) into StreamInsight as events using input adapters. Events generated by StreamInsight can be streamed out of StreamInsight using output adapters. PI for StreamInsight includes the input and output adapters required for the PI System. The PI for StreamInsight input adapter streams events from a PI Server into StreamInsight, while the PI for StreamInsight output adapter writes events to a PI Server. Developers can create Language Integrated Queries (LINQ) with Microsoft StreamInsight, using the PI for StreamInsight adapters to access the PI System. These adapters are provided as assemblies that developers can reference and use in their queries. PI for StreamInsight User Guide 1

6 Introduction PI for StreamInsight Adapter Overview PI for StreamInsight includes adapters to read and write data between the PI System and Microsoft StreamInsight. The PI input adapter receives PI snapshot events from the PI Update Manager and converts those events into a form that can be read and queued into the StreamInsight server. Queries defined by the user are applied to the input events. The PI output adapter receives events from StreamInsight server and sends the data to the PI archive. These adapters are focused on streaming PI Time Series data types. Both typed (page 6) and untyped (page 6) input adapters are supported. The typed adapter has better performance and is best suited for streaming PI event data. The untyped adapter is best suited for streaming configuration or reference data from the PI point database. The PI for StreamInsight output adapter is untyped. For more information, see Using Typed and Untyped Adapters (page 46). The.NET code that implements the adapters and interfaces to PI is provided in three assemblies: OSIsoft.ComplexEventProcessing.Adapters.dll OSIsoft.ComplexEventProcessing.PINet.dll OSIsoft.ComplexEventProcessing.Archive.dll These assemblies are installed in: [pipc]\pi for StreamInsight\Bin Supported Features This version of the PI for StreamInsight adapters supports: Reading events from the PI Server Snapshot Subsystem for selected PI points. Snapshot events are new events that arrive at the PI Server. Writing events to the PI archive of the PI Server. 2

7 About this Guide The following features are not supported in this version of PI for StreamInsight: PI collective connections Each PI adapter can be configured to connect to a specific PI Server. If the PI Server you specify is a member of a PI collective, there is no support for failover to another collective member if the connected PI collective member fails. Buffering of data to PI Server(s). PI trusts cannot be used to authenticate to PI Servers. PI for StreamInsight supports only Windows Integrated Security (WIS) for authentication to PI Servers. About this Guide This guide describes how the PI for StreamInsight adapters work and provides instructions and code samples that explain how to configure the adapters, build queries and stream events to and from PI points. Also included is a hands-on tutorial (page 29) to help you learn these concepts quickly. Both Microsoft StreamInsight and components of PI for StreamInsight are developed with.net, and expose a set of.net APIs, making Microsoft Visual Studio a natural development environment for implementing CEP applications. This guide provides an example of such a program that captures events generated by the Random Simulator Interface to the PI Server. For additional information about PI for StreamInsight, see the OSIsoft vcampus Web site ( the developer community for OSIsoft users. Information about Microsoft StreamInsight, such as discussions, documentation and support, can be found on the Microsoft Developers Network Web site For additional information about Microsoft StreamInsight, see: Microsoft StreamInsight Web site ( complex-event.aspx) Microsoft StreamInsight blog ( An introduction to Microsoft StreamInsight concepts ( The PI for StreamInsight Reference Help provides class library documentation for all public classes supplied with PI for StreamInsight. These classes are organized into two namespaces: The OSIsoft.ComplexEventProcessing.Adapters namespace contains the classes required for creating and configuring adapters The OSIsoft.ComplexEventProcessing.DataTypes namespace contains some example event payload types that may be used as they are, or used to produce custom payload types either by extending or imitating them. The documentation of individual classes and methods can also be obtained within Visual Studio in the form of IntelliSense contextual help. PI for StreamInsight User Guide 3

8 Introduction Prerequisite Knowledge This guide is intended for use by.net programmers who are currently familiar with the use of Microsoft StreamInsight, Language Integrated Query (LINQ) expressions, or for those interested in learning about these tools. How to Use PI for StreamInsight with Microsoft StreamInsight An example of the steps required to implement a StreamInsight query using PI for StreamInsight are: Install Microsoft StreamInsight Install PI for StreamInsight Determine the input and output points to be used by the StreamInsight query Configure PI Security to allow the PI for StreamInsight adapters to access the PI System Create a new project in Visual Studio Reference Microsoft StreamInsight and the PI for StreamInsight adapters Configure the PI for StreamInsight adapters in the application code Build StreamInsight queries and required application code Test and debug queries Implement the Microsoft StreamInsight application or queries Microsoft StreamInsight Concepts StreamInsight Server The StreamInsight server is the processing engine that runs user-defined queries across event streams. The StreamInsight server can run as an in-process embedded service in a user application or run by a Windows Service as a stand-alone server deployment. As an embedded service, the queries are included in the application. When the StreamInsight server is run as a Windows service, queries are sent to the StreamInsight server to run. Events StreamInsight processes events that have two distinct parts, the payload and the temporal properties. The temporal properties define the shape of the event. The payload is made up of user accessible fields. These properties are defined by a schema based on a.net class. 4

9 Microsoft StreamInsight Concepts The temporal (time) properties consist of one timestamp that indicates the start time of the event and, for interval and edge event shapes only, a second timestamp that indicates the end time of the event. The temporal properties of events in a stream may be modified using standard StreamInsight operators that change the shape of events. A set of ready-to-use payload classes which will be suitable for most StreamInsight applications using PI event data are provided. These can be found in the namespace OSIsoft.ComplexEventprocessing.DataTypes. See the PI for StreamInsight Reference for more details. Developers using PI for StreamInsight input adapters can also define their own classes to use the payload. Event Shape The shape of an event describes the period of time during which its payload is valid. Three shapes are supported: Point represents an event at a single point in time. Point events have a single timestamp representing the start time of the event but no timestamp for the end time of the event. This is similar to a PI event from the PI archive. Interval represents events that span a time period. These events have a start and an end time that represent a time span during which the event payload is considered to be valid. Edge an alternative to interval events for use if the end time of the event is not known at the time the event is started. Initially, the end time is set to a value in the far distant future, and this is modified to the actual end time when it becomes known. Event Type Event type is the data type of the event, for example string, float or digital state. Payload Payload is the information supplied with each event. An example payload is PIEventBasic which includes the following fields: Point Id, Point name and Point status and the Point value. Streams A stream is a sequence of events that are the same event shape and type, and have the same payload. Streams are first produced by the input adapters and flow into the standing queries. Streams flow from the queries to other queries and/or output adapters. An example stream from the PI Server could be the PI events for one or more PI points of the same data type. PI for StreamInsight User Guide 5

10 Introduction Queries Queries are defined using Language Integrated Queries (LINQ) and operate as standing queries on event streams. A standing query operates on the values arriving in one or more streams by filtering them, adjusting their shape, performing joins over events that are valid at the same time, and projecting new payloads from the query into a result stream. Note: StreamInsight queries are often referred to as standing queries to distinguish their behavior from typical SQL queries. SQL queries are applied against existing, static data within a database. StreamInsight queries are static and data flows through the query. Adapters Adapters that provide events in streams to StreamInsight are known as input adapters. Adapters that consume events from StreamInsight are called output adapters. PI for StreamInsight includes both input and output adapters. For information on the use and configuration of the adapters, see Using PI for StreamInsight Adapters (page 37). Typed Adapters Typed adapters are those for which payload type is determined when the adapter code is compiled. This generally means that the number of fields, their names and their types are fixed. This knowledge allows the adapters to build and populate StreamInsight events more efficiently so the throughput of a typed adapter is usually better than that of an untyped adapter using the same payload. Untyped Adapters Untyped adapters support payload types that are not known at the time the adapters are compiled, so an application developer using an untyped adapter has more freedom to design a payload type. StreamInsight must do extra work to analyze the payload structure and work out how to populate the individual fields in the payload so there is a performance penalty every time a new event created and submitted to the StreamInsight engine. 6

11 Microsoft StreamInsight Concepts Note: PI for StreamInsight input adapters are available in typed and untyped form. Both typed and untyped input adapters will work with the full set of predefined payload types. Typed adapters are preferred for performance reasons, however untyped adapters give the required flexibility to contain PI point attribute values in the payload. PI for StreamInsight output adapters are available as untyped adapters only. For more information about the use of typed and untyped adapters in PI for StreamInsight, see Using Typed and Untyped Adapters (page 46). Current Time Increment (CTI) The notion that time passes, from earlier times that steadily progress toward later times without ever going backwards, is crucial for executing queries on event streams. Queries cannot yield results in a timely manner unless the query engine can assume that all events up to a certain time have been received by the engine. StreamInsight establishes the concept of current time as being a time value such that no events with a timestamp earlier than this time value will be received. The current time value does not increase smoothly like the time on a clock; instead an input adapter (or the StreamInsight engine) increases the value in a stepwise manner as events are processed. The action of increasing the current time value is known as a Current Time Increment (CTI) event. Not all events entering the input stream cause the current time to change different rules can be used to influence this. The AdvanceTimeSettings provided by StreamInsight provide the mechanism to configure advancement of time. PI for StreamInsight User Guide 7

12 Introduction Microsoft StreamInsight Architecture Microsoft StreamInsight can be run as an embedded in-process server or as a Windows service. See Microsoft StreamInsight Help for scenarios on how to deploy StreamInsight. PI for StreamInsight supports embedded or Windows Service implementations (page 9). Here is a diagram of an embedded StreamInsight application that runs configured queries: This diagram shows a StreamInsight Server configured as a Windows Service that runs provided queries: 8

13 PI for StreamInsight Deployment Models PI for StreamInsight Deployment Models To implement queries using StreamInsight, you can: Embed the StreamInsight server in an application. The sample PI for StreamInsight application (page 29) uses this method. Submit a query to a StreamInsight server running as a Windows service. PI for StreamInsight Scenarios PI for StreamInsight can meet customer needs for a number of scenarios, such as the requirement to evaluate and validate data quality. For example, consider how PI for StreamInsight might be used if a customer wants to monitor the status of power meters. The customer's goal is to detect outages for a set of power meters, each of which has a digital signal that reports the meter status (ON, OFF) and report in real time the total number of meters that are out of service. Meters are known to incorrectly report an outage, so to compensate for this, only outages of at least 5 minutes should be reported. It is possible to build a custom application or use PI ACE to perform this requirement where the calculation is required to: Perform a query for each meter individually to check for those that have a time validated outage status Sum up these events To accomplish this with a streaming engine such as Microsoft StreamInsight, the application needs only: Create an event stream for the required input tags Query the event stream for events that last for 5 minutes or longer and are in the state of OFF Output the total of meters PI for StreamInsight User Guide 9

14

15 Chapter 2 Install PI for StreamInsight Before you run the PI for StreamInsight installation program, verify that the target server and client computers: Meet the minimum hardware requirements (page 11) Use a supported operating system Note: Prior to installation, the PI for StreamInsight installation program will verify that your server fulfills the system requirements. The installer will exit if any components are missing. Include the installation prerequisites (page 12) Can access the PI Server and are configured with the required authentication setup. For details, see Configuring PI Server Security, available at the OSIsoft Technical Support Web site ( Include an enabled.net Framework (page 13) Have the security permissions required to install software Include Microsoft Visual Studio if the system is to be used to build StreamInsight queries Minimum Hardware Requirements PI for StreamInsight has these hardware requirements: Recommended: 2.2 GHz or faster CPU, 1024 MB or more of RAM Minimum: 1.6 GHz CPU, 384 MB of RAM Supported Operating Systems PI for StreamInsight supports both the 32- and 64-bit version of these Windows servers: All editions of Windows Server 2003 and 2003 R2 SP2 and later All editions, except for Core Edition, of Windows Server 2008 SP2 and later All editions of Windows Server 2008 R2 and later PI for StreamInsight User Guide 11

16 Install PI for StreamInsight For development and testing environments only, these 32- and 64-bit version client operating systems are supported: Windows XP, SP2 and later Windows Vista, SP2 and later Windows 7 and later Installation Prerequisites The following software should be installed on the computer that you plan to use to run a Microsoft StreamInsight application that uses PI for StreamInsight to access a PI System: Microsoft StreamInsight 1.1 ( Note: Microsoft StreamInsight is included with SQL Server 2008 R2. However, SQL Server does not need to be installed to use Microsoft StreamInsight..NET Framework 3.5. Note: If you are using MS Windows 2003, XP, Vista, or Windows 7, you can use the OSIsoft Prerequisite Kit to install the required.net Framework. To download the prerequisites installation program, see the OSIsoft Technical Support Web site ( The required.net Framework is included with Windows 2008 R2 or later, but must be enabled. (page 13) Note: You can use.net 4.0 (page 57) to build and deploy applications for PI for StreamInsight. PI SDK or later; PI SDK is installed by the PI for StreamInsight installation program Note: The PI for StreamInsight adapters do not require PI SDK libraries but use PI Network Manager and PI Message Subsystem services installed with the PI SDK. You can also use the About PI-SDK utility to verify PI Server connectivity. You must also have: Access to PI Server 2010 or later Note: Microsoft StreamInsight does not have to be installed on the PI Server. 12

17 To Install PI for StreamInsight Adapters To develop StreamInsight applications that use PI for StreamInsight the following software should also be installed: Visual Studio 2008 or Visual Studio 2010 is preferred as there are additional StreamInsight tools available Enable.NET Framework on Windows 2008 R2 If you are using Windows 2008 R2, verify that the computer has.net Framework Features enabled: 1. Choose Start >Administrative Tools > Server Manager. 2. Select Features. 3. Review the Features Summary and verify that.net Framework Features is present. To install the.net Framework, click Add Features, select.net Framework Features and follow the prompts in the Add Feature Wizard. To Install PI for StreamInsight Adapters Run the PI for StreamInsight installation program. Note: By default, PI for StreamInsight is installed in the directory to which you typically install PI System applications. For example, C:\Program Files\PIPC. You may change this directory during the installation. To Remove PI for StreamInsight To remove PI for StreamInsight from Windows 2000, XP, and 2003 operating systems, use Add or Remove Programs in Windows Control Panel. For Windows 2008, Windows Vista and Windows 7 operating systems, use Programs and Features. PI for StreamInsight User Guide 13

18

19 Chapter 3 Verify PI for StreamInsight Installation To verify the installed files, refer to the PI for StreamInsight Release Notes for a complete list. To verify your installation, run the installation test program (page 15) included with PI for StreamInsight. This program is located in the bin folder where PI for StreamInsight is installed. It contains a simple StreamInsight query that verifies that: The PI for StreamInsight input adapter detects events as they are written to a tag These events are passed through the StreamInsight query and into the PI for StreamInsight output adapter Output is logged at the verbose level Note: The output adapter does not write the events to a PI point in this test program. Run the Installation Test Program 1. Open a Command Prompt window and change directories to the bin folder where PI for StreamInsight is installed. For example, C:\Program Files\PIPC\PI for StreamInsight\bin. 2. Enter this command to run the installation test program: InstallationTest [siinstancename] [piservername] [tagname] To use the parameters: siinstancename Enter the name of a Microsoft StreamInsight instance installed on the local machine. piservername Enter the name of the PI Server. If omitted, the default value is localhost. tagname enter the name of the input PI point. If omitted, the default value is sinusoid. Note: OSIsoft recommends that you specify a PI point that updates frequently, such as cdt158, so that you can determine quickly if your installation was successful. For example: InstallationTest.exe siinstance PISRV1 cdt158 PI for StreamInsight User Guide 15

20 Verify PI for StreamInsight Installation Note: The program will continue to run until you press Enter to stop the query. 3. To verify whether events are received by the adapters, review the # of Insert Events in the output that is logged to the console: a. For example, this sample output indicates that one event was streamed from the PI Server through the PI for StreamInsight input adapter and Microsoft StreamInsight, and then to the PI for StreamInsight output adapter: OSIsoft.ComplexEventProcessing Verbose: 0 : Counter Report for SnapshotPointOutput_0: # of Insert Events: 1 (0.03/sec) b. This sample output shows the results of a successful test. The output adapter reports each insert event as it is processed: Starting the query. Press any key to stop. OSIsoft.ComplexEventProcessing Verbose: 0 : TypedSnapshotInputFactory.cTor enters OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotOutputFactory created OSIsoft.ComplexEventProcessing Verbose: 0 : TypedSnapshotInputFactory.cTor enters OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput adapter SnapshotPointOutput_0 created OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput_0(Running): starting... OSIsoft.ComplexEventProcessing Verbose: 0 : TypedSnapshotPointInput adapter TypedSnapshotPointInput`1_0 created OSIsoft.ComplexEventProcessing Verbose: 0 : TypedSnapshotPointInput`1_0(Running): starting... OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput_0(Running): server session started. OSIsoft.ComplexEventProcessing Verbose: 0 : TypedSnapshotPointInput`1_0(Running): server session started. OSIsoft.ComplexEventProcessing Information: 0 : SnapshotPointOutput_0 initialized OSIsoft.ComplexEventProcessing Verbose: 0 : Counter Report for SnapshotPointOutput_0: # of Insert Events: 0 (0.00/sec) # of discarded events: 0 # of Cti Events: 0 # of Cycles: 1 Time in Cycles: 00:00: OSIsoft.ComplexEventProcessing Information: 0 : TypedSnapshotPointInput`1_0 initialized with pathcount 1 OSIsoft.ComplexEventProcessing Verbose: 0 : Counter Report for TypedSnapshotPointInput`1_0: # of Insert Events: 0 (0.00/sec) # of discarded events: 0 # of Cti Events: 0 # of Cycles: 1 16

21 Run the Installation Test Program Time in Cycles: 00:00: OSIsoft.ComplexEventProcessing Verbose: 0 : Counter Report for TypedSnapshotPointInput`1_0: # of Insert Events: 1 (0.03/sec) # of discarded events: 0 # of Cti Events: 0 # of Cycles: 367 Time in Cycles: 00:00: OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput_0(Running): resuming... OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput_0 dequeued Cti Event at 9/3/ :02: OSIsoft.ComplexEventProcessing Verbose: 0 : SnapshotPointOutput_0 dequeued 1 Events OSIsoft.ComplexEventProcessing Verbose: 0 : Counter Report for SnapshotPointOutput_0: # of Insert Events: 1 (0.03/sec) # of discarded events: 0 # of Cti Events: 1 # of Cycles: 2 Time in Cycles: 00:00: Press Enter to stop the query. PI for StreamInsight User Guide 17

22

23 Chapter 4 PI for StreamInsight Samples PI for StreamInsight includes three samples distributed as complete Visual Studio projects under the directory: [PIPC]\PI for StreamInsight\Samples The location of this directory depends on where the software was installed. For example, the PIPC folder might be in C:\Program Files\PI. This topic describes the samples and includes procedures on how to use them. Before You Use the Samples Review these Help topics before you use the samples to determine if they apply. Copy Sample Folders The samples can be found in the following folders: [PIPC]\PI for StreamInsight\Samples\Passthrough [PIPC]\PI for StreamInsight\Samples\AlarmWithFixedLimit [PIPC]\PI for StreamInsight\Samples\AlarmWithLimitTag On Windows 2008 Server, Windows Vista or later, these directories may be write-protected by default. We recommend that you copy the sample folders into a working directory. Reserve URL for User Account The code samples demonstrate the use of the StreamInsight Management Service Web service endpoint. In order to run the samples on Microsoft Windows Vista, Windows 2008, and Windows 7 operating systems, you might need to ensure that the configured URL is reserved for the user account that executes the samples. The following command can be run in an elevated command shell, if required: netsh http add urlacl url= user=<domain\userid> PI for StreamInsight User Guide 19

24 PI for StreamInsight Samples For example: netsh http add urlacl url= user=domain\siuser See the Microsoft StreamInsight documentation on Publishing and Connecting to the StreamInsight Server for more information. Generate PI Data Values The PI Random interface is used to provide data values for input points for the AlarmWithFixedLimit Example (page 27) and AlarmWithLimitTag (page 28) samples. This interface must be configured and running and is often set up when PI Server is installed. For complete information, see the manual Random Simulator Interface to the PI System. Review PI Point Tag Attributes Verify that the PI point names for the samples do not conflict with point names already in use on the PI Server. The output points use the point source CEP. Verify that point source CEP is not already in use on the PI Server. If it is, change the point source before you set up the required PI points (page 21). The input PI points used by the samples are: AlarmTest.Input.Float32.1 AlarmTest.Input.Float32.2 AlarmTest.Input.Float32.3 AlarmTest.Input.Float32.4 AlarmTest.Input.Float32.5 AlarmTest.Input.Float32.6 AlarmTest.Input.Float32.7 AlarmTest.Input.Float32.8 AlarmTest.Input.Float32.9 AlarmTest.Input.Float32.10 The output PI points are: AlarmTest.Output.Float32.1 AlarmTest.Output.Float32.2 AlarmTest.Output.Float32.3 AlarmTest.Output.Float32.4 AlarmTest.Output.Float32.5 AlarmTest.Output.Float

25 Before You Use the Samples AlarmTest.Output.Float32.7 AlarmTest.Output.Float32.8 AlarmTest.Output.Float32.9 AlarmTest.Output.Float32.10 The name of the PI point that indicates the limit is: AlarmTest.Input.Float32.Limit Set up Required PI Points Note: Check that the user who is going to create the PI points is authenticating with the PI Server with an account that has the ability to create points. The Passthrough (page 26), AlarmWithFixedLimit (page 27) and AlarmWithLimitTag (page 28) samples require PI points to run. Select one of these PI Server utilities to create these PI points: PI System Management Tools (PI SMT). It is recommended that you create the sample PI points with the PI Tag Configurator plug-in and the AlarmTestTags.csv file. piconfig This command-line utility is installed by the PI Server or PI SDK may be preferred by advanced users. Use AlarmTestTags.dat to create PI points with piconfig. Use PI Tag Configurator 1. Open the AlarmTestTags.csv file with Microsoft Excel. 2. Select the PI-SMT menu if available. If not and you have an add-ins menu, check under that menu item for PI-SMT. If the PI-SMT menu option is not listed, see Add PI Tag Configurator Plug-in (page 22). 3. Select Export and verify the settings for these options: Export to: PI Server PI Server: <the name of your PI Server> Point Class: Classic Mode: Create 4. Select OK to create the points. 5. Review the output to verify that that 21 PI points (page 20) were created. Note: You can find more information about PI Tag Configurator in [PIPC]\help\PITagCnf.chm on a machine with PI System Management Tools (PI SMT) software installed. PI for StreamInsight User Guide 21

26 PI for StreamInsight Samples Add PI Tag Configurator Plug-in PI Tag Configurator is a PI System Management Tools (PI SMT) add-in for Microsoft Excel. You must add the PI Tag Configurator utility to the Excel Add-Ins menu before you can use it. Complete the following steps: 1. Open Excel. 2. Open the Add-Ins menu: In Excel 2003 and earlier: Select Tools > Add-Ins In Excel 2007 and Excel 2010: From the Office button click Excel Options, choose Add-Ins, then click the Go button 3. Click Browse to open the Browse explorer window. 4. Browse to the \PIPC\SMT folder. 5. Select PITagCnf.xla. 6. Click OK to return to the Add-Ins window. 7. Select PI-TagConfigurator 32 bit. 8. Click OK to exit the Add-Ins window. This adds the PI-SMT menu to Excel. Use the PI SMT Help file for instructions about how to use the PI-SMT menu. Use piconfig To create the points with piconfig: 1. Open a Command Prompt and change directories to the samples\setup folder where PI for StreamInsight is installed. For example, if PI for StreamInsight is installed on the C: drive, the directory would be: C:\Program Files\PIPC\PI for StreamInsight\samples\setup Note: The location of piconfig depends on whether you run the utility on the local PI Server or remotely. On the local PI Server, see the [PI]\adm directory. On the remote PI Server, see the [PIPC]\adm directory. For example, C:\Program Files\PI\adm\piconfig. a. From the local PI Server enter: [PI]\adm\piconfig < AlarmTestTags.dat b. If the PI Server is not installed locally, enter: [PIPC]\adm\piconfig -remote < AlarmTestTags.dat 22

27 Before You Use the Samples For the remote option only, follow the piconfig prompts to enter the following information about the PI Server on which you will create the points: node name port number (default is 5450) user name password 2. Verify that 21 PI points are successfully created - 10 input point and 10 output points and one limit point. The highlighted lines at the end of the following output indicate successful creation of the points: *> AlarmTest.Input.Float32.1,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.10,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.2,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.3,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.4,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.5,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.6,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.7,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.8,1,4,2,28800,0,1,1,Floating Point CEP Test Input PI for StreamInsight User Guide 23

28 PI for StreamInsight Samples Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.9,1,4,2,28800,0,1,1,Floating Point CEP Test Input Tag,2,2,1,600,0,0,0,30,0,1,1,R,float32,1,1,,200,0,0,0,0,140, 0,0,0,0,50 *> AlarmTest.Input.Float32.Limit,1,0,0,28800,0,1,1,Floating Point CEP Test Limit Tag,2,0,0,600,0,0,0,30,0,2,1,R,float32,1,1,,20,0,0,0,0,180,0,0,0,0,170 *> AlarmTest.Output.Float32.1,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.10,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.2,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.3,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.4,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.5,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.6,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.7,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.8,1,4,2,28800,0,1,1,Floating Point CEP Test Output 24

29 Build and Run the Samples Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 *> AlarmTest.Output.Float32.9,1,4,2,28800,0,1,1,Floating Point CEP Test Output Tag,2,2,1,600,0,0,0,0,0,0,0,CEP,float32,1,1,,200,0,0,0,0,140,0,0,0,0,50 PIconfig 21 Data lines 8 Command line 0 Records in error Records Created To Reconfigure Input PI Points The input points are created with the point source set to R, so they will be served values by the PI Server Random interface. The 10 primary input points are configured to scan class 1 and the limit point is configured to scan class 2. The assumption is that scan class 2 will generate new events less frequently than scan class 1 so that the value of the limit will change slowly compared to the values of the primary inputs. This default scan class configuration may be too slow for your experimentation with the samples. If desired, reconfigure a separate instance of the Random Simulator Interface to the PI Server that uses more aggressive scan class settings, and reconfigure the 11 input points to use this instance. Build and Run the Samples Each sample folder (page 19) contains one Visual Studio 2008 project file for the corresponding sample, along with the necessary source files. Each sample is a console application and may be run or debugged either directly from Visual Studio or from the command line. To build and run each sample: 1. Double-click the project file to launch Visual Studio and automatically create a solution file. Note: If you are using Visual Studio 2010, the project will be converted to the newer format when you launch it. This conversion may result in a change to the project properties so that it will use.net 4.0 instead of.net 3.5. Although the samples were developed against.net 3.5, they work with the newer version. To use the newer.net version to develop applications, you must manually update the file app.config. See Developing Applications with.net 4.0 (page 57) for details. 2. Check the References for the project. If both StreamInsight and PI for StreamInsight were installed into their default locations then all.dlls referenced by the sample should be resolved, otherwise these will need to be repaired manually. PI for StreamInsight User Guide 25

30 PI for StreamInsight Samples 3. For the Passthrough sample, update the four constants (page 26) that define the input and output PI Server and PI points. 4. Build and run the sample. 5. Review the console output for trace messages that describe the progress of the application. 6. Use PI System Management Tools (PI SMT) or another utility to view current data values and observe changes in the values of the output PI points. Passthrough Sample The Passthrough sample uses the PI for StreamInsight input and output adapters to receive PI events for a configured PI point and then propagates the events through a simple query to another configured PI point. It demonstrates a how a query is used to read and write PI events to and from a PI System. The PI server and PI points are configured as constants in the program that the user updates prior to running the sample. Note: Create a StreamInsight Application to use PI for StreamInsight Adapters (page 29) includes procedures that you can use to develop a simple StreamInsight application that is based on the Passthrough sample. Run the Passthrough Sample 1. Review and complete the applicable steps in Before You Use the Samples (page 19). 2. Review and complete the steps Build and Run the Samples (page 25). 3. Open the [PIPC]\PI for StreamInsight\samples\Passthrough\passthrough.csproj file with Visual Studio. 4. In Visual Studio, open the passthrough.cs file 5. Update the constants in the Passthrough program. Scroll down to the start of the Passthrough class and update name of the StreamInsight instance and the four constants that identify the input and output PI Server and PI points: Constant instancename InputPIServer inputtag outputpiserver Description Name of the Microsoft StreamInsight instance installed on the machine Name of the PI Server A PI point that is receiving new events Name of the PI Server, can be the same as the input PI Server outputtag PI point created as part of Before You Use the Samples (page 19). For example: "AlarmTest.Output.Float32.1" 26

31 Build and Run the Samples 6. Run the application: Select Debug > Start Debugging. 7. Review the console output to verify events are processed and check the status of the output point to verify the operation. For example, to use the PI System Management Tools (PI SMT) Current Values plug-in: a. Search for the input and output tags b. Check for updating values. If there are no new values for the input tag, there will be no updates for the output tag. AlarmWithFixedLimit Sample This sample application detects events that contain floating-point values that arrive at 10 PI points through the input adapter. As the values are propagated through a StreamInsight query, they are compared against a fixed alarm limit. The point AlarmTestInputLimit includes a hard-coded value on the limit point. The output adapter writes values to 10 output points, each of which corresponds to an input point. A value of 1 for an output point indicates that a value greater than the alarm limit arrived at the input point. An output value of -1 indicates that the input point value was below the configured alarm limit. Run AlarmWithFixedLimit Sample 1. Open the project file in Microsoft Visual Studio Solution Explorer. 2. Verify the references. 3. Review the limit variable. 4. Build the application: Go to Visual Studio > Build > Build Solution. 5. Run the query: a. Right click on the project name in Microsoft Visual Studio Solution Explorer and select Properties. b. Select Debug in the left-hand pane. c. Enter the command line parameters: <instancename> <piserver> 6. Run the application: Select Debug > Start Debugging. PI for StreamInsight User Guide 27

32 PI for StreamInsight Samples 7. Check the status of the output points to verify the operation: To use PI System Management Tools (PI SMT) Current Values plug-in: a. Search for alarm*output* b. Review changes in PI point values. A value of 1 for an output point indicates that a value greater than the alarm limit arrived at the input point. An output value of -1 indicates that the input point value was below the configured alarm limit. AlarmWithLimitTag Sample This sample uses two input adapters: One adapter detects events that contain floating-point values and arrive at 10 PI points simultaneously. A second input adapter creates a stream with events from a single PI point that records an alarm limit that changes slowly. The alarm limit value is derived from the Random Simulator Interface to the PI Server. The StreamInsight query performs a temporal join across these two streams, allowing each value from the 10 input points to be compared with the current value of the alarm limit point. The output adapter writes values to 10 output points, each of which corresponds to an input points. A value of 1 for an output point indicates that a value greater than the current alarm limit arrived at the input point. An output value of -1 indicates that the input point value was below the current alarm limit. Run AlarmWithFixedLimit Sample 1. Run the query: a. Right click on the project name in Microsoft Visual Studio Solution Explorer and select Properties. b. Select Debug in the left-hand pane. c. Enter the command line parameters: <instancename> <piserver> 2. Run the application: Select Debug > Start Debugging. 3. Check the status of the output points to verify the operation: To use PI System Management Tools (PI SMT) Current Values plug-in: a. Search for alarm*output* b. Review changes in point values. A value of 1 for an output point indicates that a value greater than the alarm limit arrived at the input point. An output value of -1 indicates that the input point value was below the configured alarm limit. 28

33 Chapter 5 Create a StreamInsight Application This section demonstrates how you can build a simple StreamInsight application that uses PI for StreamInsight. You can use the application to analyze your PI data through a query that streams data from one PI point to another. Note: The completed application is also available as a sample (page 26) in the form of a Visual Studio solution and is located in the directory: [PIPC]\PI for StreamInsight\Samples\Passthrough. Set up the Visual Studio Project 1. Open Microsoft Visual Studio and create a new C# console application named HelloPI. Use.NET Framework 3.5 as the application s target framework. To verify this, go to Project > HelloPI Properties: 2. Add the StreamInsight references to the project. Typically they are available in the folder \Program Files\Microsoft StreamInsight 1.1\Bin: Microsoft.ComplexEventProcessing.dll Microsoft.ComplexEventProcessing.Adapters.dll Microsoft.ComplexEventProcessing.ManagementService.dll 3. Add references for PI for StreamInsight adapters that are available in [PIPC]\PI for StreamInsight: OSIsoft.ComplexEventProcessing.Adapters.dll OSIsoft.ComplexEventProcessing.Archive.dll OSIsoft.ComplexEventProcessing.PINet.dll Add Using Directives using Microsoft.ComplexEventProcessing; using OSIsoft.ComplexEventProcessing.Adapters; using Microsoft.ComplexEventProcessing.Linq; using OSIsoft.ComplexEventProcessing.DataTypes; PI for StreamInsight User Guide 29

34 Create a StreamInsight Application Configure PI Points This sample uses two PI points defined as variables inputtag and outputtag in Set up Constants (page 30). The inputtag should be should be configured with a PI point that is receiving new events; the example is currently configured to use cdt158. The outputtag should be configured with a PI point that can be written to by the PI for StreamInsight output adapter and have a point type of Float32. Set up Constants To keep configuration of this example simple, replace the parameters within the class that contains the Main method: // The name of the StreamInsight instance, determined when // StreamInsight was installed const string instancename = "MyStreamInsightInstance"; // The name of the PI Server to use for input. // A null value will use the local PI Server const string inputpiserver = null; // The name of the tag to read input values from const string inputtag = "cdt158"; // The name of the PI Server to use for output. // A null value will use the local PI Server const string outputpiserver = null; // The name of the tag to write values to const string outputtag = ""; Where: MyStreamInsightInstance is the name of the StreamInsight instance null should be replaced with the name of the PI Servers used: inputpiserver is the server from which the input points values are derived outputpiserver is the server to which output points values are written cdt158 is the name of the input PI point Note: The outputtag constant is an empty string in this example. With this configuration, events are handled by the output adapter but not written to a PI Server. If you want output values to be written to a PI Server, provide the name of a valid PI point that can accept FLOAT point values in this constant. Most of the remaining code that you add for this example is placed within the Main method. 30

35 Instantiate a server instance and application Instantiate a server instance and application Create a StreamInsight server instance using the instance name that was registered on the machine when StreamInsight was installed. By default the instance is named default. This example uses an instance called MyStreamInsightInstance, obtained from the first of the previously defined constants (page 30). static void Main(string[] args) { using (Server cepserver = Server.Create(instanceName)) { Application cepapplication = cepserver.createapplication("hellopi"); // : // Other code // : } } Note that this example takes advantage of the fact that the Server instance implements the IDisposable interface by making it the target of a using statement. OSIsoft recommends this as a best practice since it helps ensure that all resources used by the server are released efficiently after PI for StreamInsight finishes using them. The example uses a StreamInsight server instance created in the application. An alternative deployment scenario is to use a StreamInsight service on the local or remote server. The remaining application code appears where the Other code comment is shown. Configure PI for StreamInsight PI for StreamInsight adapters retrieve data from PI Server into the StreamInsight Server engine and from the StreamInsight Server engine into PI Server(s). When creating an application, you must configure the adapter properties to provide the name of the PI server and the PI points for which PI data is read and written. PI for StreamInsight input and output adapters are configured independently. As shown in this example, the input and output adapters can be configured to use separate PI Servers: The input adapter indicates the PI points to be streamed. To configure the input adapter, enter the name of the PI points or provide search criteria: SnapshotInputConfig inputconfig = new SnapshotInputConfig(); inputconfig.server = inputpiserver; inputconfig.pointsquery = new string[] { inputtag }; The configuration of the output adapter is very similar; however, in this example the PI points that PI for StreamInsight will write to are not indicated in the output adapter; they are instead added later to the query definition (page 32): SnapshotOutputConfig outputconfig = new SnapshotOutputConfig(); outputconfig.server = outputpiserver; PI for StreamInsight User Guide 31

36 Create a StreamInsight Application Create an Input Stream The input stream ensures that the StreamInsight engine examines all the events. Note that this example passes the configuration structure (page 31) for the input adapter (stored in inputconfig). var input = CepStream<PIEvent<Double>>.Create( "PI Input Stream", typeof(snapshotinputfactory), inputconfig, EventShape.Point, AdvanceTimeSettings.StrictlyIncreasingStartTime); Note: This input stream indicates that StreamInsight should expect events of the class PIEvent<Double> type. A developer can use custom classes as needed for untyped adapters. For typed adapters, there are limitations on the custom classes that can be used in the payload. See Using Typed and Untyped Adapters (page 46) for more details. In StreamInsight, the shape (page 5) of the event defines the temporal properties of the event (page 4); it can be of Point, Interval or Edge. In a Point event, any result event lifetime is reduced to a Point event. In an Interval event, any result event is only output if its full lifetime is committed by a Current Time Increment (CTI) (page 7) event. In an Edge event, only the start time is known upon arrival to the StreamInsight server; the end time is known later and updated. Define the Query The input stream is used as the basis for the query definition. The query will run continuously processing events received from the input stream is bound to and will send processed events to the output adapter to which is bound. var query = from e in input select new PIDataSingle() { Path = outputtag, Status = 0, Value = e.value }; 32

37 Create an Output Adapter This example assumes that, for all processed events, the output is going to be of a class named PIDataSingle that has three properties: Path (output tag name), Status and Value. public class PIDataSingle { public String Path { get; set; } public Double Value { get; set; } public Int32 Status { get; set; } } Create an Output Adapter To bind the query to an output adapter, this example passes the configuration structure that was written when the output adapter was configured (page 31): var outputtopi = query.toquery(cepapplication, "simpleoutput", "A simple Output", typeof(snapshotoutputfactory), outputconfig, EventShape.Point, StreamEventOrder.FullyOrdered); The StreamEventOrder.FullyOrdered parameter tells the application the interval events should be output in the order of their start times. Start the Query The last step is to start the query. In this example, the query is stopped by a user-provided keystroke. outputtopi.start(); Console.ReadLine(); outputtopi.stop(); Run the Sample Compile and run the example. Use a utility such as PI Server Manager Tools (PI SMT) to track the values of the input and output points and verify that the values written to each input point is passed through the PI for StreamInsight adapters to its corresponding output point. If you used the pre-coded example instead of writing your own example as described above, you will also notice the stream of output that appears in the console window. Most of this is provided as configurable trace output from the PI for StreamInsight adapters. The quantity and features of this output is configured using the app.config file in the project. The tracing capabilities in the PI for StreamInsight adapters are based on the techniques available through the System.Diagnostics namespace in Microsoft s.net framework and are comprehensively documented in the MSDN documentation. See Diagnostics for an explanation of the features specific to the PI for StreamInsight adapters. PI for StreamInsight User Guide 33

38 Create a StreamInsight Application Extending the Application Much of the power of StreamInsight for complex event processing lies in the flexibility of LINQ to query the data. The HelloPI application uses a simple pass-through query. This section examines other more advanced queries that you can use. The skeleton of the application does not change, only the query definition. Note: The StreamInsight server in itself has no notion of wall clock (time passing). StreamInsight server uses events received from input adapters to determine if processing of the currently received events should occur. Calculating Averages One example is to calculate the average of the values for a selection of PI points for specified time intervals. This requirement implies that the application must collect data for the time specified before it generates output. In StreamInsight, these subsets of events are defined through windows. StreamInsight supports different types of windows, such as tumbling windows. Tumbling windows are used to process sequential windows of data; data is output only when interval for the window ends. For example, this query computes the average every 5 seconds, then generates output: var query = from e in input group e by e.path into targettags from t in targettags.tumblingwindow(timespan.fromseconds(5), HoppingWindowOutputPolicy.ClipToWindowEnd) select new PIDataSingle() { Path = "MovingTarget", Status = 0, Value = t.avg(e => e.value) }; There are situations in which you may not want to wait until a fixed time interval ends before producing an output. For example, you might want to calculate the average of a PI event data stream for the last 10 seconds but report the data every 3 seconds. For this type of StreamInsight query, you can use hopping windows: var query = from e in input group e by e.path into TargetTags from t in TargetTags.HoppingWindow(TimeSpan.FromSeconds(10),TimeSpan.Fro mseconds(3), HoppingWindowOutputPolicy.ClipToWindowEnd)select new PIDataSingle() 34

39 Extending the Application { Path = "MovingTarget", Status = 0, Value = t.avg(e => e.value) }; Filtering Data It is possible to filter data in the query directly, for instance we can query data greater than a set limit, in this case 20. var query = from e in input where e.value > 20 select new PIDataSingle() { Path = "MovingTarget", Status = 0, Value = e.value }; PI for StreamInsight User Guide 35

40

41 Chapter 6 Using PI for StreamInsight Adapters The PI for StreamInsight input adapter provides the functionality to stream events from the PI Server Snapshot Subsystem into the Microsoft StreamInsight server, where these inbound events can be further processed and ultimately passed onto a PI for StreamInsight output adapter and then streamed into the PI archive. The topics described in this section provide details on the required and optional configuration for the PI for StreamInsight adapters. The expressions used to create input streams and consume output streams using these adapters feature all the different options for configuring the adapters for different applications. Here are the code fragments shown previously for creating input and output adapters: and var input = CepStream<PIEvent<Double>>.Create( "PI Input Stream", typeof(snapshotinputfactory), inputconfig, EventShape.Point, AdvanceTimeSettings.StrictlyIncreasingStartTime); var outputtopi = query.toquery(cepapplication, "simpleoutput", "A simple Output", typeof(snapshotoutputfactory), outputconfig, EventShape.Point, StreamEventOrder.FullyOrdered); The fragments relevant to PI for StreamInsight are: The factories, used to create the adapters that will be used with this stream, in this case SnapshotInputFactory and SnapshotOutputFactory. There are additional factories that may be used on the input side. For further details about factories and adapters, see Creating Different Types of Adapters (page 38). The event payload type. In the creation of this input adapter, the payload type is PIEvent<Double>. In the output, the adapter must handle the payload that the query projects, which is one reason OSIsoft uses untyped adapters on the output side. Payload types and the techniques for customizing them are discussed in detail in Using Typed and Untyped Adapters (page 46). Additional Features of Event Payloads (page 53) is also useful, as it discusses how to make a payload that will be understood by an output adapter. PI for StreamInsight User Guide 37

42 Using PI for StreamInsight Adapters The configuration objects, inputconfig and outputconfig. These provide the information needed to configure the input and output adapters once they have been created by their respective factories. For details about how to populate these objects, see Configure the Input Adapter (page 38) and Configure the OutputAdapter (page 43). The event shape, EventShape.Point. Each adapter comes in different varieties to handle the different event shapes, Point, Interval or Edge. This value helps the factory to choose the correct variety of adapter. The effect of choosing the different event shapes in either input or output adapters are described in PI for StreamInsight Support for Microsoft StreamInsight Event Shapes (page 55). For information about the application developer s experience when building applications with PI for StreamInsight, see: Developing Applications with.net 4.0 (page 57) discusses minor configuration changes you may need to make if you choose to use this version of.net. Diagnostics illustrates the approach to logging and tracing (based on the capabilities of the System.Diagnostics namespace in.net) with typical content of an app.config file. Creating Different Types of Adapters Adapters are created by factory classes. The type of the factory class is provided to the expressions that create input streams or that bind to the results of a query. PI for StreamInsight provides four different factory classes in the namespace OSIsoft.ComplexEventProcessing.Adapters: SnapshotInputFactory this creates a typed input adapter that subscribes to new PI event data through the Snapshot subsystem. UntypedSnapshotInputFactory this creates an untyped input adapter that subscribes to new PI event data via the Snapshot subsystem. UntypedSnapshotInputFactory<T> this is the superclass of UntypedSnapshotInputFactory. The type parameter T represents the type of the configuration object that will be passed into the adapter that has been created by the factory. Normally this will be SnapshotInputConfig, however there is also a subclass of SnapshotInputConfig that can be used. This is the PointAttributeInputConfig type, which modifies the behavior of the adapter so that it generates one event per selected PI point for which the payload contains point attribute values instead of PI event data. This technique is used with the Edge event shape. SnapshotOutputFactory this creates an untyped output adapter that writes StreamInsight events to the PI archive. Configure the Input Adapter The input configuration object is an instance of SnapshotInputConfig (or as required PointAttributeInputConfig) which has a number of public properties that can be set. Most of these will have useful default values so they can often be ignored. 38

43 Configure the Input Adapter As with other.net objects, property values can be set individually, as in the following example: SnapshotInputConfig config = new SnapshotInputConfig(); config.server = "PIServer"; config.port = 8888; or using the object initializer syntax to set them all together, like this: SnapshotInputConfig config = new SnapshotInputConfig() { Server = "PIServer", Port = 8888 }; Both styles are used in the examples in this user guide and in sample code. Input Adapter Property Summary To configure the PI for StreamInsight input adapter, you must use a property to: Enter a query in the PointsQuery (page 41) property to search the PI point database for the tags to be streamed into the adapter. Optionally, you can also specify one or more of the following properties: Server (page 40) Identifies the PI server. If omitted, the server defaults to the local computer. Port (page 40) Specifies the PI Server port. If omitted, the port number defaults to TimestampOption (page 41) Specifies how the timestamp of StreamInsight events is determined. StopOnCommunicationFailure (page 40) Determines whether the adapter should cause the StreamInsight query to stop on loss of communication with the PI Server or allow the query to continue and continually attempt to reestablish communication with the PI Server. If omitted the default is not to stop. Remember that it may be necessary to set up security authentication and authorization to the PI Server(s) used in input adapters. To do this: Determine which Windows user will execute the query. Configure Windows Integrated Security (WIS) on the PI Server(s). PI Server Connection Properties This section defines the PI for StreamInsight input adapter properties to connect to a PI Server. Note: PI for StreamInsight only supports Windows Integrated Security (WIS) and requires use of PI mappings. PI trusts are not supported. PI for StreamInsight User Guide 39

44 Using PI for StreamInsight Adapters Server Determines the name of a PI Server to which the configured input adapter will attempt to connect. This field is Null by default. A Null value will cause the adapter to attempt to connect to a local PI Server, using localhost. The following examples demonstrate how to assign a connection to a PI Server named PIServer: or SnapshotInputConfig config = new SnapshotInputConfig() { Server = "PIServer" }; SnapshotInputConfig config = new SnapshotInputConfig(); config.server = "PIServer"; Port Specifies the network port number that will be used for the PI Server. Default value is For example, to specify 8888 as the port: or SnapshotInputConfig config = new SnapshotInputConfig() { Port = 8888 }; SnapshotInputConfig config = new SnapshotInputConfig(); config.port = "8888"; StopOnCommunicationFailure Boolean field that determines the behavior of an adapter when it detects that communication with the PI System has been lost. If set to TRUE, this flag notifies the adapters that StreamInsight and all associated queries are to stop when loss of connectivity with the PI Server occurs. Default is FALSE. When false the adapter will not attempt to process any PI events until communication is restored; at the time that communication resumes, the adapter will continue to process events. Note: This property applies only after an initial connection has been successfully made to the PI Server. If the adapter cannot connect successfully to the PI Server, the adapter will not start. For example, to set this flag: SnapshotInputConfig config = new SnapshotInputConfig(); config.stoponcommunicationfailure = true; 40

45 Configure the Input Adapter TimestampOption This field determines how the timestamps (StartTime and EndTime) of StreamInsight events gets created from PI events arriving in the adapter. Three options are possible: PIEventTimestamp This option is the default. It uses the timestamp of the PI event to provide the timestamp of the StreamInsight event. EventArrivalTime This option notes the time a collection of PI events arrives in the adapter, and uses that time to provide timestamps for all StreamInsight events created from the collection. EventArrivalTimeStrictlyAscending This operates the same way as the EventArrivalTime option, except that each successive event in the collection generates a timestamp one tick (100 nanoseconds) later than its predecessor, guaranteeing a strictly ascending sequence of timestamps. PointsQuery PointsQuery defines one or more PI point queries that search the PI point database for matching PI points. Once initialized, the input adapter will stream new events for each of the PI points to the StreamInsight server. PI StreamInsight adapters use a query mechanism that allows a set of PI points to be selected from a PI Server. The following example shows a query for point sinusoid and for all points with the prefix Test. or, SnapshotInputConfig config = new SnapshotInputConfig(); config.pointsquery = PISearch.TAG.eq("sinusoid") + PISearch.TAG.eq("Test.*"); SnapshotInputConfig config = new SnapshotInputConfig(); inputconfig.pointsquery = new String[1] { "sinusoid" }; inputconfig.pointsquery += PISearch.TAG.eq("Test.*"); Note that the class PISearch contains constants for all of the PI point attributes declared against the different point classes. Also note that the value provided as a parameter to the eq() methods on these constants is typed according to the type of these attributes. In this example, the PISearch.TAG constant expects a string value, however PISearch.USERINT1 would expect an integer value. The topics in this section give a more complete illustration of the search capabilities. PI for StreamInsight User Guide 41

46 Using PI for StreamInsight Adapters Simple Filter The most basic building-block of these queries is a filter. The purpose of a filter is to only allow those PI Points that match some criterion based on a point attribute value. This example shows the construction of a query that looks for a PI point with the given name: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.TAG.eq("AlarmTest.Input.Float32.1"); Note that the eq() methods are strongly typed. The methods expect a value that matches the type of the point attribute, so a query for all PI Points where the userint1 attribute equals 42 looks like this: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.USERINT1.eq(42); A query using the pointtype attribute can make use of a set of constants defined to simplify the expression. In the following example all points with a pointtype of Float32 are selected: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.POINTTYPE.eq(PointType.Float32); The asterisk character can be used as a wild card in string searches. The following example matches all tags that start with "AlarmTest.Input.": PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.TAG.eq("AlarmTest.Input.*"); Combination of Filters The bitwise AND operator, or & has been overridden to allow a simple syntax for combining two or more filters to make a more restrictive filter. This can be thought of as a compound filter that returns a result set of those PI points that match the first filter AND match the second filter AND match any more filters in the expression. The following query will find all classic PI points that also have pointtype of Float32: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.POINTTYPE.eq(PointType.Float32) & PISearch.PTCLASSNAME.eq("classic"); Combining Result Sets Result sets from more than one filter (simple or compound) can be combined using the union operator. The addition operator + has been overridden to provide a programmatic style complementary to the & operator (page 42). This operator merges the results of one filter with those of another, eliminating duplications if necessary. This example combines the results of two wildcard text searches using the tagname attribute: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = PISearch.TAG.eq("AlarmTest.Input.*"); 42

47 Configure the Output Adapter Here is another example that shows the use of the & and + operators together to obtain a list of tags that are Float32 and have a point class name of either classic or base: PIInputAdapterConfig config = new PIInputAdapterConfig(); config.pointsquery = (PISearch.POINTTYPE.eq(PointType.Float32) & PISearch.PTCLASSNAME.eq("classic")) + (PISearch.POINTTYPE.eq(PointType.Float32) & PISearch.PTCLASSNAME.eq("base")); Building the query using the union operator and + operator with a very large number of filter elements may cause a stack overflow, however the optimizations associated with using an array of tag names avoid this limitation and this is described in Building a Query from an Array of Tags (page 43). Building a Query from an Array of Tag Names As mentioned before, there is a mechanism for automatically creating a query from an array of tag names. This is illustrated below: PIInputAdapterConfig config = new PIInputAdapterConfig(); String[] paths = new String[10]; for (int i = 0; i < 10; i++) { paths[i] = "AlarmTest.Input.Float32." + (i + 1); } config.pointsquery = paths; The above technique using arrays of tag names contains optimizations for handling very large arrays of names and is preferred over the union operator for very large number of PI points. Configure the Output Adapter Output streams are configured using an instance of SnapshotOutputConfig in the namespace OSIsoft.ComplexEventProcessing.Adapters. Output Adapter Property Summary To configure the PI for StreamInsight output adapter, the following properties can be set. All properties have defaults and are optional. Server (page 44) Identify the PI server. If omitted, the server defaults to the local computer name localhost. Port (page 44) Specify the PI Server port. If omitted, the port number defaults to PI for StreamInsight User Guide 43

48 Using PI for StreamInsight Adapters StopOnCommunicationFailure (page 44) Determines whether the adapter should cause the StreamInsight query to stop on loss of communication with the PI Server or allow the query to continue and continually attempt to reestablish communication with the PI Server. If omitted, the default is not to stop. UseDeliveryTimestamp (page 45) Specify which timestamp is used for the event. Coincident Event Handling (page 45) Define how to handle duplicate events. Remember that it may be necessary to set up security authentication and authorization to the PI Server(s) used in output adapters. To do this: Determine the Windows user that will be executing the query Configure Windows Integrated Security (WIS) on the PI Server(s) PI Server Connections This section defines the PI for StreamInsight output adapter properties to connect to a PI Server. This section corresponds to the fields of the same names in Configure the Input Adapter (page 43). Note: PI for StreamInsight only supports Windows Integrated Security (WIS) and requires use of PI mappings. PI trusts are not supported. Server The name of a PI Server with which the output adapter will attempt to connect. This field is Null by default. A Null value will cause the adapter to attempt to connect to a local PI Server, using the name localhost. The following example demonstrates how to assign a connection to a PI Server named PIServer: SnapshotOutputConfig outputconfig = new SnapshotOutputConfig(); outputconfig.server = PIServer; Port The network port number that will be used for the PI Server. Default value is For example, to specify 8888 as the port: SnapshotInputConfig config = new SnapshotOutputConfig() { Port = 8888 }; 44

49 Configure the Output Adapter StopOnCommunicationFailure Boolean field that determines the behavior of an adapter when it detects that communication with the PI System has been lost. If set to TRUE, this flag notifies the adapters that StreamInsight and all associated queries are to stop when loss of connectivity with the PI Server occurs. If not set, the adapter will not attempt to process any PI events until communication is restored; at the time that communication resumes, the adapter will recover and continue to process events. Note: This property applies only after an initial connection has been successfully made to the PI Server. If the adapter cannot connect successfully to the PI Server, the adapter will not start. For example, to set this flag: SnapshotOutputConfig config = new SnapshotOutputConfig(); config.stoponcommunicationfailure = true; UseDeliveryTimestamp If set to TRUE, the adapter uses a timestamp from the event payload rather than the standard StreamInsight event timestamp as the timestamp recorded by the PI System for the event. If set to FALSE, or if there is no Timestamp field in the payload, the timestamp of the StreamInsight event is used. CoincidentEventHandling Use CoincidentEventHandling to specify the methodology used when encountering events for a particular point with coincident or identical time stamps. The output adapter supports four PI archive methods for data handling: ReplaceDuplicates Adds events to the archive and when an event with a matching timestamp is encountered, the new event overwrites the existing value. This is the default option for the property. InsertDuplicates Adds events to the archive and when an event with a matching timestamp is encountered, appends the new event after the event with the matching timestamp. ErrorDuplicates Adds events to the archive and returns an error if an event with a matching timestamp is encountered; the new event is discarded. The error does not cause the adapter to stop. ReplaceOnlyDuplicates Adds values to the archive only when events with identical values exist. The existing events are replaced. If no events with a matching timestamp exist, the event is discarded and an error is returned. The error does not cause the adapter to stop. PI for StreamInsight User Guide 45

50 Using PI for StreamInsight Adapters Using Typed and Untyped Adapters This section describes the use of typed and untyped adapters available with PI for StreamInsight. The architecture of StreamInsight allows two distinct approaches so that the type of payload can be either: Strongly constrained at compile time allowing for maximum throughput of events, or Flexible or determined from configuration with lower performance. PI for StreamInsight supports both typed and untyped input adapters. The typed adapters have been designed to accommodate generic payloads that can be populated through an interface, yielding the expected boost in performance but retaining some of the payload flexibility available in the untyped adapters. One significant feature of the untyped adapters is their ability to support extensions to the event payload to handle arbitrary application-specific content. The most common application of this feature is to allow metadata associated with each PI point to be included in the event payload. It is also possible to use untyped adapters to create streams that contain only PI point metadata in their payload. These streams can be joined with the regular streams of PI event data from typed adapters within a StreamInsight query to yield event payloads indistinguishable from those that can be produced by the untyped adapters, but with higher throughput since the rapidly changing PI event stream is handled through a typed adapter. See Standard Payload Classes (page 47) for descriptions of the standard payload types provided with PI for StreamInsight adapters and the tasks required to: Set up input adapters using typed adapters for the production of streams of PI event data Use untyped adapters to set up streams of PI point metadata For insight into the design of non-standard event payloads that meet the needs of more demanding applications, see Custom Payloads (page 51), which describes how event payloads are populated in typed and untyped adapters. 46

51 Using Typed and Untyped Adapters Standard Payload Classes There are four classes included with PI for StreamInsight assemblies that you can use as event payload definitions for PI event data. You may find these optional classes useful, since they are designed to meet requirements for a wide range of applications. The two variants at the top of the diagram carry less information than those at the bottom and will be processed more efficiently, therefore use PIEventBasic<T> or PIDigitalStateEventBasic if only basic information from each event is needed; use PIEvent<T> or PIDigitalStateEvent if complete information is needed. The classes at the right are dedicated to digital state tags, those on the left for all other types of tags. The generic parameter T represents a suitable.net type to receive values from the tags configured for the particular value and is the type of the Value property. This imposes the constraint that each tag handled by a particular adapter instance must have a point type compatible with T. Note that the classes dedicated to digital state tags set the type of the generic parameter to int. This is because the numerical value of the digital state will be written to the Value property, and the string representation of that value into the DigitalStateName property. PI for StreamInsight User Guide 47

52 Using PI for StreamInsight Adapters The following table gives a more complete summary of the properties of these types: Event Type Field Type Comments PIEventBasic Id Int32 Identifies the PI point referenced by the Path PIEventBasic Path String PI point name PIEventBasic Value String Double Int32 Any supported PI point data type may be used PIEventBasic Status Int32 Status code for the event PIEvent ArrivalTime DateTime UTC timestamp of the moment the PI event arrived in the input adapter PIEvent Timestamp DateTime UTC timestamp of the PI event PIEvent StatusText String Status of the event as text PIEvent IsAnnotated Boolean Indicates that the Value has been annotated PIEvent IsQuestionable Boolean Indicates that the Value is questionable PIEvent IsEdited Boolean Indicates that the original Value has been substituted PIEvent Annotation String The text of the annotation. Not supported in this release but reserved for future use PIDigitalStateEventBasic and PIDigitalStateEvent DigitalStateName String The digital state name Creating a Stream of PI Event Data Using a Typed Adapter The following code fragment shows the creation of a typical stream of PI event data it includes search criteria in the configuration object that will find all digital state tags and yield a point event whenever the digital state value of any events change. Note that SnapshotInputFactory is used as the adapter factory that will create the appropriate adapter instance. This is the factory that produces typed adapters. Untyped adapters are created using the UntypedSnapshotInputFactory. // Input Stream Configuration SnapshotInputConfig config = new SnapshotInputConfig(); Config.PointsQuery = PISearch.POINTTYPE.eq(PointType.Digital) // Input Stream var inputstream1 = CepStream<PIDigitalStateEventBasic>.Create( "PI Event Data Stream", typeof(snapshotinputfactory), config, EventShape.Point, 48

53 Using Typed and Untyped Adapters new AdvanceTimeSettings( new AdvanceTimeGenerationSettings( 1, TimeSpan.FromTicks(1), true), null, AdvanceTimePolicy.Adjust) ); // Expression var outputstream = from e in inputstream1 select new { DigitalStateName = e.digitalstatename, Path = e.path, StatusText = e.status.tostring() }; Creating a Stream of PI Point Metadata Using an Untyped Adapter Streams of PI point metadata are created using an untyped adapter which creates a single event for each retrieved PI point using a PI point search. The duration of the event is indeterminate the usual technique is to create an adapter that uses Edge events such that the leading Edge of each event is created when the adapter starts, and the trailing Edge is never created. The payload of the events in the metadata stream is a set of one or more fields that contain PI point attributes read from the PI point database. These event payloads are available in a query that joins this stream with a stream of events with PI event data payloads, but to ensure timely delivery of the metadata events it is important that the PI point metadata stream imports CTI events from the PI event data stream. Note that it is important that the set of PI points represented in the metadata stream is correlated with the set of PI points represented in the PI event data stream. To ensure this, we compose the search criteria first, and then parameterize the configuration objects of both streams with the search criteria, as shown in this example. The following code fragment is an adaptation of the example in the previous section which illustrates the techniques used to build an additional metadata stream and combine them in a single query expression: // Search Criteria PointSet searchcriteria = PISearch.POINTTYPE.eq(PointType.Digital); // Input Stream Configurations SnapshotInputConfig pieventconfig = new SnapshotInputConfig() { PointsQuery = searchcriteria }; PointAttributeInputConfig pimetadataconfig = PI for StreamInsight User Guide 49

54 Using PI for StreamInsight Adapters new PointAttributeInputConfig() { PointsQuery = searchcriteria }; // Input Streams var eventstream = CepStream<PIDigitalStateEventBasic>.Create( "Event Data", typeof(snapshotinputfactory), pieventconfig, EventShape.Point, new AdvanceTimeSettings( new AdvanceTimeGenerationSettings( 1, TimeSpan.FromTicks(1), true), null, AdvanceTimePolicy.Adjust) ); var reffactorytype = typeof(untypedsnapshotinputfactory<pointattributeinputconfig>); var metadatastream = CepStream<DSPointMetadata>.Create( "Metadata", reffactorytype, pimetadataconfig, EventShape.Edge, new AdvanceTimeSettings( null, new AdvanceTimeImportSettings("Event Data"), AdvanceTimePolicy.Adjust) ); // Expression var outputstream = from e in eventstream join m in metadatastream on e.id equals m.id select new { Path = e.path, PointClass = m.ptclassname, DigitalSet = m.digitalset, DigitalStateName = e.digitalstatename, StatusText = e.status.tostring() }; The metadata stream uses a custom class called DSPointMetadata as its payload type, as shown here: public class DSPointMetadata { public int Id; public string PtClassName; public string DigitalSet; } 50

55 Using Typed and Untyped Adapters Custom Payloads The use of the PI for StreamInsight adapters along with the standard payload types (page 47) removes a large amount of complexity from the implementation of a StreamInsight application that works with PI event data. A consequence of this simplification is that there is extra work to do in order to use payload types other than the standard ones. It is necessary to first understand how values are mapped from PI into the properties of the event payloads, and this is different for untyped and typed adapters. Property Mapping in Untyped Adapters Mapping of data into the payload is done based on the names of each property of the payload in untyped adapters. The PI for StreamInsight adapters recognize two sets of names: Properties found in the standard payload types described above. These names correspond to individual data elements found in PI event data. This guarantees that the standard payload types work in the untyped adapters. Properties that correspond to attributes of points in the PI point database. Names in this set are compared to these attribute names (using a case-blind comparison) and if a match is found, then the value of that attribute is mapped into the payload property. All other property names cannot be matched to PI System data, so will be ignored. Property Mapping in Typed Adapters Typed adapters are more efficient because the adapter already knows how exactly to populate the payload. In the PI for StreamInsight adapters, this is achieved using a.net interface called OSIsoft.ComplexEventProcessing.Adapters.IPIInputEvent. This specifies a set of methods allowing elements of PI event data to be assigned into the payload, as follows: public interface IPIInputEvent { void AssignAnnotation(string annotation); void AssignId(int id); void AssignIsAnnotated(bool isannotated); void AssignIsEdited(bool isedited); void AssignIsQuestionable(bool isquestionable); void AssignPath(string path); void AssignStatus(int status, string statustext); void AssignArrivalTime(DateTime time); void AssignTimestamp(DateTime timestamp); void AssignValue(object value, string valuetext); } Note that the signatures for the AssignValue and AssignStatus methods are slightly different. The extra string parameter holds the string representation of digital set values. Status is always a digital set value, so the statustext parameter will always contain a nonnull string. For the Value field, this will be null if the value is NULL (usually when the status is bad) or if the value is not a digital set value. PI for StreamInsight User Guide 51

56 Using PI for StreamInsight Adapters An abstract superclass of the standard payload types implements this interface to facilitate the mapping of the PI event data elements onto the corresponding payload properties, guaranteeing that these types will work in the typed adapters. This class is illustrated here: Each method in the IPIInputEvent interface delegates onto one of the protected virtual methods in PIEventStandard. The parameters and return types of these methods are the same as in the interface. Each method is a stub, that is, they exist only to be overridden. The intent is that any subclass of PIEventStandard can override as many of the AcceptXXXX methods as necessary to meet the needs of the desired payload. PIEventStandard is therefore a convenient base class for any payload in a typed PI for StreamInsight adapter. There is no support for attributes of PI points into the payload for typed adapters. Instead, create a stream of metadata events that can be joined with the stream of event data. Extending the Standard Payload Classes This section describes techniques for extending PIEventStandard or any of the four concrete subclasses supplied with PI for StreamInsight adapters to design a payload that: Contains exactly the fields needed, rather than compromising with one of the supplied payloads. There is a small processing overhead for each unnecessary field in the payload, so event throughput can be optimized by fine-tuning the payload design. Combines event and metadata fields for use in an untyped adapter. Although this approach is not recommended there may be a few scenarios where this is appropriate. For example, if there is a need to constrain the total number of concurrent events in the StreamInsght engine or if the time needed to shut down and restart a query must be minimized. To illustrate fine-tuning of payload fields, consider a class TimestampedPIEvent<T> that extends PIEventBasic<T> by adding a property to contain the timestamp of the PI event. 52