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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 1

 

   

PI Webservices

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 2

 

1.1 PI Webservices

1.1.1 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

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:

http://osisoft-trng.virtuallabs.int:55556/piwebservices/pitimeseries.svc

 

 

Try to do this exercise on your own before proceeding to the Step‐by‐Step Instructions. 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 4

 

4. Select Receive and submit data.

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 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: http://osisoft-trng.virtuallabs.int:55556/PIDataServices/PITimeSeries.svc?wsdl

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 24

 

 

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

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

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 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 “2001-3-14” for the date portion and “09:46:55” for the time portion.

 

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 29

 

 

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 30

 

 

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

 

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. © Copyright 1995-2009 OSIsoft, LLC, 777 Davis St., Suite 250, San Leandro, CA 94577

Page 31