Web Services

Bells & WSDL's: Consuming Web Services From Enterprise Portal : 

Bells & WSDL's: Consuming Web Services From Enterprise Portal Session #20427 March 14, 2006 Alliance 2006 Conference Nashville, Tennessee

Your Presenter : 

2 Your Presenter Robert Jones 20 years experience in application development Approximately 20 years to go Playing with half-a-deck 3 long years in PeopleSoft

University of North Texas : 

3 University of North Texas Public university est. 1890 32,000 + enrollment Purchased every PeopleSoft product known to man Where my parents met

Overview : 

4 Overview Web Services: What are they and what are they good for? What can you do with them as an Oracle/PeopleSoft developer? What can’t you do with them? What have we done with them?

What Is a Web Service? : 

5 What Is a Web Service? A Web Service: Is any service available over the internet that is based on XML messaging and is independent of an Operating System Should be Self-Describing Should be Discoverable

Two Main Flavors : 

6 Two Main Flavors XML-RPC (xml based Remote Procedure Call) SOAP (Simple Object Access Protocol)

A Basic Web Service : 

7 A Basic Web Service WS Consumer WS Provider XML Request XML Response What is this person’s employment history? Start Date, End Date, Title, Last Salary, etc. Employment Verification Service

Not the Whole Picture for SOAP : 

8 How do you know what services are available? Where do you send the request? How do you format the message? How do you send the message? Not the Whole Picture for SOAP

The WSDL Answers All : 

9 The WSDL Answers All Web Services Descriptive Language contains 5 basic parts of speech. How do you format the message?

WSDL Parts – Conversions Service (service) : 

10 WSDL Parts – Conversions Service (service) <definitions name="Conversions" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.dataaccess.com/webservicesserver/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://www.dataaccess.com/webservicesserver/"> . . . <service name="Conversions"> <documentation>The Conversions Web Service, (…), provides functions that convert numbers into words or dollar amounts, and texts into Title Cased Texts.</documentation> <port name="ConversionsSoap" binding="tns:ConversionsSoapBinding"> <soap:address location="http://www.dataaccess.com/webservicesserver/conversions.wso"/> </port> </service> </definitions>.

WSDL Parts – Conversions Service (binding ) : 

11 WSDL Parts – Conversions Service (binding ) <definitions name="Conversions" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.dataaccess.com/webservicesserver/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://www.dataaccess.com/webservicesserver/"> . . . <binding name="ConversionsSoapBinding" type="tns:ConversionsSoapType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="NumberToWords"> <soap:operation style="document" soapAction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> <operation name="NumberToDollars">. . . </definitions>

WSDL Parts – Conversions Service (portType) : 

12 WSDL Parts – Conversions Service (portType) <definitions name="Conversions" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.dataaccess.com/webservicesserver/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://www.dataaccess.com/webservicesserver/"> . . . <portType name="ConversionsSoapType"> <operation name="NumberToWords"> <documentation>Returns the word corresponding to the positive number passed as parameter. Limited to quadrillions.</documentation> <input message="tns:NumberToWordsSoapRequest"/> <output message="tns:NumberToWordsSoapResponse"/> </operation> <operation name="NumberToDollars">. . . </definitions>

WSDL Parts – Conversions Service (message) : 

13 WSDL Parts – Conversions Service (message) <definitions name="Conversions" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.dataaccess.com/webservicesserver/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://www.dataaccess.com/webservicesserver/"> . . . <message name="NumberToWordsSoapRequest"> <part name="parameters" element="tns:NumberToWords"/> </message> <message name="NumberToWordsSoapResponse"> <part name="parameters" element="tns:NumberToWordsResponse"/> </message> . . . </definitions>

WSDL Parts – Conversions Service (types) : 

14 WSDL Parts – Conversions Service (types) <definitions name="Conversions" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.dataaccess.com/webservicesserver/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://www.dataaccess.com/webservicesserver/"> <types> <xs:schema targetNamespace="http://www.dataaccess.com/webservicesserver/" elementFormDefault="qualified"> <xs:element name="NumberToWords"> <xs:complexType> <xs:sequence> <xs:element name="ubiNum" type="xs:unsignedLong"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="NumberToWordsResponse"> <xs:complexType> <xs:sequence> <xs:element name="NumberToWordsResult" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> …</types> . . .

A Working Example… : 

15 A Working Example… …from xMethods and Mindreef

What Are They Good for? : 

16 What Are They Good for? Integration, Integration, Integration! Abstracting the form from the function Driving me nuts!

What Can You Do With Them? : 

17 What Can You Do With Them? The Oracle/PeopleSoft Web Service (Consumer) Implementation…as I understand it.

Process Overview : 

18 Process Overview Configure Integration Broker (see PeopleSoft Enterprise Portal Solutions 8.9 PeopleBook: Enterprise Portal Application Technology > Using External Web Services) Import WSDL Create/Assign Messages to Operations Configure Node (Will use HTTP Target connector) Code! Test

Walk-through of the Process : 

19 Walk-through of the Process From Our Development Portal

Coding Tips : 

20 Coding Tips Get to know these classes SOAPDoc, XMLDoc, XMLNode All about setting up the request and parsing the response And this function SyncRequestXmlDoc(&XmlDoc, message.MessageName [, node.NodeName] Note from PeopleBooks. Because SyncRequestXmlDoc is an XmlDoc built-in function, you must convert the SoapDoc request message to an XmlDoc object before sending it. Likewise, the response message is an XmlDoc object, so you must convert it to a SoapDoc object to process it with SOAP methods. Can be any non-rowset based message. Check connector information.

Coding Tips – continued : 

21 Coding Tips – continued When writing a large or complete interface to a service, encapsulate the interface in Application Packages Use ValidateSoapDoc(1) for response objects to avoid namespace prefix error <SOAP-ENV:Envelope> vs. <soap:Envelope) Use GetElementsByTagNameNS(NamespaceURI, TagName) to process response to deal with namespace prefix Use Try-Catch logic to handle SOAP faults & other errors

Coding Tips - Continued : 

22 Coding Tips - Continued Very helpful (and in some cases expensive tools) Altova XML spy (enterprise edition) -$$$ SOAtest (by ParaSoft) - $$$ MindReef SoapScope - $ http://www.xmethods.net (TryIt) Oracle/PeopleSoft Sendmaster All ways of troubleshooting your web services code independent of the code itself!

Coding Trips : 

23 Coding Trips SOAP specification compliance:Soap faults Dealing with namespaces & namespace prefixes in the SOAP Response

Two HTTP Conversation Scenarios : 

24 HTTP 200 OK Web Page Two HTTP Conversation Scenarios HTTP 500 Internal Server Error

W3C SOAP 1.2 Specification : 

25 W3C SOAP 1.2 Specification 6.2 SOAP HTTP Response SOAP HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc. In case of a SOAP error while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP Fault element (see section 4.4) indicating the SOAP processing error

Where’s the Compliance?* : 

26 Where’s the Compliance?* HTTP 200 OK SOAP Response WSVC HTTP 200 OK SOAP Response AppSvr Integration Gateway HTTP 500 SOAP Fault WSVC PeopleCode Error Message AppSvr Integration Gateway * Available in PeopleTools 8.48

So How Do You Look at the Fault? : 

27 So How Do You Look at the Fault? Check the errorLog.html file on the Integration Gateway. In our environment… /opt/weblogic/padv89/webserv/peoplesoft/applications/peoplesoft/PSIGW/errorLog.html DataBase/ Environment Name Webserver Home

How to handle it? : 

28 How to handle it? /* Send the Request */ try &xmlResponse = SyncRequestXmlDoc(&xmlRequest, Message.GBGB_GENERIC_SOAP_DI, Node.GBDW_WSHUB_DI); catch Exception &cl &fLogFile = GetFile(&sFileName, "W", %FilePath_Absolute); &fLogFile.WriteLine("There was an problem retrieving the requested log file during the fetch. Either the log file expired or a system error occurred"); &fLogFile.Close(); Return False; end-try; /* Get the SOAP response from the XmlDoc response */ &soapRes = CreateSOAPDoc(); &soapRes.XmlDoc = &xmlResponse; . . .

Namespaces and Namespace Prefixes : 

29 Namespaces and Namespace Prefixes SOAP Response Documents often use names spaces around the result tags. <SOAP-ENV:Body> <tns:NumberToWords xmlns:tns="http://www.dataaccess.com/webservicesserver/"> <tns:ubiNum>123</tns:ubiNum> </tns:NumberToWords> </SOAP-ENV:Body> &xmlNode.GetElementsByTagName(“ubiNum”) – Fails! Because the tag name is actually tns:ubiNum &xmlNode.GetElementsByTagNameNS(“http://www.dataaccess.com/webservicesserver”,”ubiNum”) - Succeeds! The example in real-time….

How It All Started : 

30 How It All Started A quick tour of what we've done with the Informatica WorkFlow Monitor via Informatica’s Web Services Hub which is what started me on this exploration

Informatica Integration Architecture : 

31 Informatica Integration Architecture Repository Portal Integration Broker Application Server Integration Gateway HTTP Connector App Messaging Informatica Web Services Hub DataIntegration Web Services MetaData Web Services Power Center Server Repository Server SOAP/XML

Demo of Informatica Interface : 

32 Demo of Informatica Interface Back to Our Development Portal

Helpful Web Services Resources : 

33 Helpful Web Services Resources Ethan Cerami. Web Services Essentials: O’Reilly 2002 – Good overview of architecture & programming examples (Java) Eric Newcomer. Understanding Web Services XML, WSDL, SOAP, and UDDI: Addison-Wesley 2002 - Another good overview in somewhat less technical terms

Helpful Web Services Resources – WSDL’s : 

34 Helpful Web Services Resources – WSDL’s Web Services Description Language (WSDL) Explained (MSDN) What's new in WSDL 2.0 W3C Web Services Description Language (WSDL) Version 2.0 Specification Understanding Complex Types

Questions? : 

35 Questions?

Contacts : 

36 Contacts Robert Jones Manager, Tools and User Services Computing and Information Technology Center University of North Texas E-mail: rjfones@unt.edu

Slide 37: 

This presentation and all Alliance 2006 presentations are available for download from the Conference Site Presentations from previous meetings are also available