Transcription
PI WebservicesAll rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 1
1.1PI Webservices1.1.1DescriptionPI Web Services is a product that allows users to access PI System Data through SimpleObject Access Protocol (SOAP) compliant Web services. The PI Web Services consists of aWeb service that accesses PI System data in response to Web service queries. In this lab youwill create an InfoPath form that can read data from the PI server and on that can write data tothe PI server1.1.2 1.1.3ObjectivesCreate an InfoPath form that can read PI data via PI WebservicesCreate an InfoPath form that can write data to the PI server via PI WebservicesProblem DescriptionYou want to create a simple InfoPath form that operators can use to read data from the PIserver, and a different InfoPath form that operators can use to write data to the PI server.1.1.4Suggested ApproachOpen InfoPath and create a Web service form that can read data from the PI server and adifferent form that can write PI data to the server by using the following already installed 56/piwebservices/pitimeseries.svcTry to do this exercise on your own before proceeding to the Step‐by‐StepInstructions.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 2
1.1.5Step-by-Step InstructionsWriting to the PI server1.2.3.Open InfoPath (Start All Program Microsoft Office InfoPath)On the “Getting Started” dialog window select “Design a Form Template”.Select web service and click OK.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 3
4.Select Receive and submit data.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 4
5.Point the Data Connection Wizard to the WSDL for the installed web service, PIEnterpriseServices,is the default installation, in our case the url aServices/PITimeSeries.svc?wsdlAll rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 5
6.Select the web service operation GetPIArchiveData from the list provided. Accept the default namefor 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 retrievalsystem, 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 94577Page 6
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 retrievalsystem, 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 94577Page 7
8.9.Select the requests element as shown highlighted above.Click through the page asking for a name for the data connection for submitting a web servicerequest by clicking the finish button.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 8
10. At this point, it is possible to simply drag the requests element onto the form and select “repeatingsection with controls” to create the request portion of the form. InfoPath, however, does notnecessarily present the parameters in the order or format that we desire. The following steps areintended to create a more pleasing result.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 9
11. Drag the Path element onto the form. This creates a text field within a repeating section. Theremainder of our choices will go into this section so that we create a form with the ability to submitmultiple requests with each call to the web service.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 10
12. Drag TimeRange onto the repeating section under Path. You may wish to change the width of thetext fields. Leave the controls as text fields. If you change them to date picker controls, you willlose the ability to submit PI relative times.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 11
13. Drag PIArcManner onto the form. Place it within the repeating section created by dropping Pathonto the form, but outside the section that encloses TimeRange. Select “repeating section withcontrols”. You are now ready to layout a table to accept the data coming back from the web servicecall.14. Note: the screen shots that follow show the completed data submission area edited to clean up thelayout and esthetics. The controls and their bindings remain unchanged from the precedingdiscussion.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 12
15. The data returned by the web service is an array of TimeSeries objects. Each such object consists ofsome data pertaining to the time series as a whole, followed by an array of TimedValue objectsrepresenting 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 underthe Path control. Edit the labels as desired. The error field is a numeric error code returned if theretrieval as a whole failed. If it is non-zero, an error occurred and errDesc will contain a descriptivestring. The uom field contains the units of measure for the tag or performance equation, anddatatype is the XML Schema datatype equivalent to the type of the tag or PE. The form at this pointshould look like this:All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 13
17. Now we need to create form fields for the individual timed values returned. If you examine theTimedValues field in the tree on the right of the form, you will note that there is nothing listed forvalue. This is because the value itself is returned as the textual content of an XML element in theweb service reply. In order to pick this up, we will drag the entire TimedValue object onto therepeating section we created above, then edit the table based on what the web service actually returnsfor this method.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 14
18. Select the TimedValue field and drag it into the TimeSeries repeating section, placing it directlybeneath the Datatype field. Select repeating table from the options InfoPath offers. Note that eachrow is fairly crowded. We can edit this to make it more presentable. Much of the data fields definedfor the TimedValue object overlap the TimeSeries object, or are used in different web servicemethods. For example, since every TimedValue returned in this method will have the same path asthe parent TimeSeries, the web service does not repeat this information. This reduces the amount ofdata transmitted over the network for each call. The pctGood property, moreover, is used whenperforming 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 retrievalsystem, 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 94577Page 15
20. Repeat the process for Uom, Pct Good, and Datatype. Adjust the size of the fields as desired. Theresults should be similar to this:All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 16
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 selectChange 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 retrievalsystem, 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 94577Page 17
22. Click on the button labeled “Format ”. You can then select the data and time formatting yourdesire. 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 theweb service as possible. The actual format you select will apply only to the way the data isdisplayed 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 ascircled below:All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 18
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 valuesAll rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 19
over the period *-1H, * with inside boundaries. Click the Insert item control to add fields for asecond 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 thenumValues property minus one. We want 15 minute intervals over two hours. The parameters forthe two requests are summarized below:PathStartEndRetrievalTypeNum 2H*interpolated9interpolated26. 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 retrievalsystem, 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 94577Page 20
Note that all times returned by PI Enterprise Services are UTC.Inserting Data1.Create a new form template for a web service following steps 1 – 5 above, selecting the InsertPIDataweb 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 retrievalsystem, 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 94577Page 21
3.4.The method used to insert events takes an array of TimeSeries objects. Events can be inserted in oneof two ways. A caller can put all the events into a single TimeSeries object, being sure to specify thepath for each TimedValue. Alternately, one can put events into multiple time series in which eachtime series pertains to a single tag. In this case, the path property for the TimeSeries object can beset and the path properties for each TimedValue left blank. Note that if both properties are set, theTimedValue path overrides the setting for the TimeSeries path property.Start by laying out the controls for submitting the data. Drag the path field from TimeSeries onto theform. This creates a repeating section. Change the label to Time Series Path so that you will be ableto distinguish it from the path field from TimedValue.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 22
5.The error field of TimeSeries is not optional according to the web service WSDL, so InfoPath flagsthis as a required field. This is not used when inserting data, so we will add it to the form, give it adefault value, and hide the control. Drag error onto the form directly under Time Series Path andwithin 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 retrievalsystem, 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 94577Page 23
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 retrievalsystem, 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 94577Page 24
7.8.9.Click OK to close the box. Delete the label “Error:” from the form.Drag TimedValue into the repeating section and select “Repeating Section with Controls”. Becareful not to drag TimedValues (the parent of TimedValue). PI Enterprise Services will onlyrespond to the path, time, and TimedValue fields when inserting TimedValue objects.Drag the controls for Pct Good to the bottom of the section and change its size to 0. Give it a defaultvalue of 0.Note: if you do not specify a default value, InfoPath will not submit the request. Delete the Pct Goodlabel. 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 usePI relative times or PI absolute time strings (e.g., TODAY) to insert events, you will want to be ableAll rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 25
to insert times as well as dates. Changing the control to a text box allows users to insert ISO 8601date time strings. Change the format to None (Display XML value). This value is typed as adateTime in the WSDL, so InfoPath requires compatible date and time formatting. None of theoptions offered by InfoPath conform to ISO 8601, which is the time format standard used throughoutPI Enterprise Services. The ISO 8601 format takes the form YYYY-MM-DDTHH:MM:SS. Thestring must end in either Z (UTC time) or { -}HH:MM to denote a time offset from UTC. Thus1: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 retrievalsystem, 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 94577Page 26
12. If all the events submitted are successfully inserted, PI Enterprise Services will return an array ofTimeSeries objects. One TimeSeries will be returned, and it will have no TimedValues. If anyevents 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 retrievalsystem, 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 94577Page 27
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 nolonger appears. Change the Time field to a Text Box, and format it “2001-3-14” for the date portionand “09:46:55” for the time portion.All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 28
16. The results of a successful insertion are shown below:All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 29
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 retrievalsystem, 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 94577Page 30
All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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 94577Page 31
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
