PI Webservices. Page 1

Transcription

1 PI Webservices Page 1

2 1.1 PI Webservices Description 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 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 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 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: Try to do this exercise on your own before proceeding to the Step by Step Instructions. Page 2

3 1.1.5 Step-by-Step Instructions Writing to the PI server 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. Page 3

4 4. Select Receive and submit data. Page 4

5 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: Page 5

6 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. Page 6

7 7. When asked which fields provide the parameters for the web service request, click on the plus icon (middle of dialog above, on the right) to select a field or group. Page 7

8 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 request by clicking the finish button. Page 8

9 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. Page 9

10 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. Page 10

11 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. Page 11

12 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. Page 12

13 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: Page 13

14 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. Page 14

15 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. Page 15

16 20. Repeat the process for Uom, Pct Good, and Datatype. Adjust the size of the fields as desired. The results should be similar to this: Page 16

17 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: Page 17

18 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 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: Page 18

19 24. A runtime version of the form appears. Enter data as shown below. 25. These selections will give us the compressed events for sinusoid up to a maximum of 400 values Page 19

20 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: Path Start End Retrieval Type Num Values Boundaries pi:\\osisoft-trng\sinusoid *-1H * compressed 400 inside pe:\\osisoft-trng\ CDT158 *2 *-2H * interpolated 9 interpolated 26. Click the Run Query button, then OK for the security notice. The results are shown below: Page 20

21 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: Page 21

22 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. Page 22

23 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. Page 23

24 6. Before you close this dialog, go to the size tab. Change the Width value to 0. Page 24

25 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 Page 25

26 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. 11. The result after reformatting is shown below: Page 26

27 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. Page 27

28 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 for the date portion and 09:46:55 for the time portion. Page 28

29 16. The results of a successful insertion are shown below: Page 29

30 17. Now submit several events for tags that do not exist. The results of failed insertions are shown here: Page 30

31 Page 31