PI Webservices - OSIsoftcdn.osisoft.com/learningcontent/pdfs/PI Webservices.pdf · 1.1 PI Webservices 1.1.1 Description PI Web Services is a product that allows users to access PI
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
PI Web Services is a product that allows users to access PI System Data through Simple Object Access Protocol (SOAP) compliant Web services. The PI Web Services consists of a Web service that accesses PI System data in response to Web service queries. In this lab you will create an InfoPath form that can read data from the PI server and on that can write data to the PI server
1.1.2 Objectives
• Create an InfoPath form that can read PI data via PI Webservices • Create an InfoPath form that can write data to the PI server via PI Webservices
1.1.3 Problem Description
You want to create a simple InfoPath form that operators can use to read data from the PI server, and a different InfoPath form that operators can use to write data to the PI server.
1.1.4 Suggested Approach
Open InfoPath and create a Web service form that can read data from the PI server and a different form that can write PI data to the server by using the following already installed web service:
1. Open InfoPath (Start > All Program > Microsoft Office > InfoPath) 2. On the “Getting Started” dialog window select “Design a Form Template”. 3. Select web service and click OK.
5. Point the Data Connection Wizard to the WSDL for the installed web service, PIEnterpriseServices, is the default installation, in our case the url is: http://osisoft-trng.virtuallabs.int:55556/PIDataServices/PITimeSeries.svc?wsdl
6. Select the web service operation GetPIArchiveData from the list provided. Accept the default name for the data connection on the next page. Click through the following page (asking for WSDL again, this time for the data submission. Select GetPIArchiveData again on the following page.
8. Select the requests element as shown highlighted above. 9. Click through the page asking for a name for the data connection for submitting a web service
10. At this point, it is possible to simply drag the requests element onto the form and select “repeating section with controls” to create the request portion of the form. InfoPath, however, does not necessarily present the parameters in the order or format that we desire. The following steps are intended to create a more pleasing result.
11. Drag the Path element onto the form. This creates a text field within a repeating section. The remainder of our choices will go into this section so that we create a form with the ability to submit multiple requests with each call to the web service.
12. Drag TimeRange onto the repeating section under Path. You may wish to change the width of the text fields. Leave the controls as text fields. If you change them to date picker controls, you will lose the ability to submit PI relative times.
13. Drag PIArcManner onto the form. Place it within the repeating section created by dropping Path onto the form, but outside the section that encloses TimeRange. Select “repeating section with controls”. You are now ready to layout a table to accept the data coming back from the web service call.
14. Note: the screen shots that follow show the completed data submission area edited to clean up the layout and esthetics. The controls and their bindings remain unchanged from the preceding discussion.
15. The data returned by the web service is an array of TimeSeries objects. Each such object consists of some data pertaining to the time series as a whole, followed by an array of TimedValue objects representing events returned by the PI server. We will layout the TimeSeries data first.
16. Drag path from TimeSeries onto the lower portion of the form. This creates a repeating section. Drag error, errDesc, uom, and datatype onto the form, in succession, in the repeating section under the Path control. Edit the labels as desired. The error field is a numeric error code returned if the retrieval as a whole failed. If it is non-zero, an error occurred and errDesc will contain a descriptive string. The uom field contains the units of measure for the tag or performance equation, and datatype is the XML Schema datatype equivalent to the type of the tag or PE. The form at this point should look like this:
17. Now we need to create form fields for the individual timed values returned. If you examine the TimedValues field in the tree on the right of the form, you will note that there is nothing listed for value. This is because the value itself is returned as the textual content of an XML element in the web service reply. In order to pick this up, we will drag the entire TimedValue object onto the repeating section we created above, then edit the table based on what the web service actually returns for this method.
18. Select the TimedValue field and drag it into the TimeSeries repeating section, placing it directly beneath the Datatype field. Select repeating table from the options InfoPath offers. Note that each row is fairly crowded. We can edit this to make it more presentable. Much of the data fields defined for the TimedValue object overlap the TimeSeries object, or are used in different web service methods. For example, since every TimedValue returned in this method will have the same path as the parent TimeSeries, the web service does not repeat this information. This reduces the amount of data transmitted over the network for each call. The pctGood property, moreover, is used when performing summary retrievals (GetPISummaryData method).
19. Select the column of the table that contains Path, as shown below, then right click and select Delete > Columns.
21. By default, InfoPath turns the time field (typed dateTime in the WSDL) as a Date Picker control. This will hide the time. You may find it advantageous to right click on the Date Picker, and select Change To > Text box. Double click on the text box to display the field properties:
22. Click on the button labeled “Format…”. You can then select the data and time formatting your desire. For the purposes of this lab, we selected the field “2001-03-14” for the date and “09:46:55” for the time. This yields a string format as similar to the ISO 8601 date and time format used by the web service as possible. The actual format you select will apply only to the way the data is displayed and will not affect data retrieval at all.
23. Now you are ready to test the form. Click the Preview button on the InfoPath control ribbon as circled below:
over the period *-1H, * with inside boundaries. Click the Insert item control to add fields for a second request. This time, we want interpolated values for the performance equation ‘CDT158’*3. The intervals for interpolation as calculated by dividing the time range duration by the value of the numValues property minus one. We want 15 minute intervals over two hours. The parameters for the two requests are summarized below:
Note that all times returned by PI Enterprise Services are UTC.
Inserting Data
1. Create a new form template for a web service following steps 1 – 5 above, selecting the InsertPIData web service operation instead of GetPIArchiveData.
2. When asked to bind a field to the parameters, select the event field as shown below:
3. The method used to insert events takes an array of TimeSeries objects. Events can be inserted in one of two ways. A caller can put all the events into a single TimeSeries object, being sure to specify the path for each TimedValue. Alternately, one can put events into multiple time series in which each time series pertains to a single tag. In this case, the path property for the TimeSeries object can be set and the path properties for each TimedValue left blank. Note that if both properties are set, the TimedValue path overrides the setting for the TimeSeries path property.
4. Start by laying out the controls for submitting the data. Drag the path field from TimeSeries onto the form. This creates a repeating section. Change the label to Time Series Path so that you will be able to distinguish it from the path field from TimedValue.
5. The error field of TimeSeries is not optional according to the web service WSDL, so InfoPath flags this as a required field. This is not used when inserting data, so we will add it to the form, give it a default value, and hide the control. Drag error onto the form directly under Time Series Path and within the repeating section. Double click on the field and specify 0 as the default value.
7. Click OK to close the box. Delete the label “Error:” from the form. 8. Drag TimedValue into the repeating section and select “Repeating Section with Controls”. Be
careful not to drag TimedValues (the parent of TimedValue). PI Enterprise Services will only respond to the path, time, and TimedValue fields when inserting TimedValue objects.
9. Drag the controls for Pct Good to the bottom of the section and change its size to 0. Give it a default value of 0.
Note: if you do not specify a default value, InfoPath will not submit the request. Delete the Pct Good label. Delete the controls and labels for datatype, flags, uom, and status.
10. Right click on the Time Date Picker control and select Change To > Text Box. While you cannot use
PI relative times or PI absolute time strings (e.g., TODAY) to insert events, you will want to be able
to insert times as well as dates. Changing the control to a text box allows users to insert ISO 8601 date time strings. Change the format to None (Display XML value). This value is typed as a dateTime in the WSDL, so InfoPath requires compatible date and time formatting. None of the options offered by InfoPath conform to ISO 8601, which is the time format standard used throughout PI Enterprise Services. The ISO 8601 format takes the form YYYY-MM-DDTHH:MM:SS. The string must end in either Z (UTC time) or {+|-}HH:MM to denote a time offset from UTC. Thus 1:00 PM in Pacific Daylight Time is denoted by -07:00, as PDT is seven hours earlier than UTC.
12. If all the events submitted are successfully inserted, PI Enterprise Services will return an array of TimeSeries objects. One TimeSeries will be returned, and it will have no TimedValues. If any events cannot be inserted, the TimedValue will be returned with a status field.
13. Layout the section for the results as follows: 14. Drag TimeSeries onto the bottom of the form. Delete the controls and labels for Err Desc, Path,
Datatype, and Uom. Change the size of the Error control to 0 and delete the label.
15. InfoPath incorrectly specifies a bulleted list for TimedValue. To correct this, delete the bulleted list, then drag TimedValue onto the form and select “Repeating Table”. Delete the columns for Flags, Uom, and Datatype. Delete the Pct Good label, then shrink the column for that field until it no longer appears. Change the Time field to a Text Box, and format it “2001-3-14” for the date portion and “09:46:55” for the time portion.