1. INT-5: Integrate over the Web with OpenEdge® Web Services
Matthew Harrison
Senior Software Engineer, Progress OpenEdge

2. Initial Audience Reaction
INT-5: Integrate over the Web with OpenEdge® Web Services

3. Session Focus Understanding Web Services
Implementing OpenEdge Web Services
Understanding Web Services
Identify when to use Web Services
Implementing an OpenEdge service consumer
Implementing an OpenEdge service provider
INT-5: Integrate over the Web with OpenEdge® Web Services

4. Agenda The Value of Web Services OpenEdge Web Service Provider
Integrate over the Web with OpenEdge Web Services
The Value of Web Services
OpenEdge Web Service Provider
ABL Client as a Consumer
INT-5: Integrate over the Web with OpenEdge® Web Services

5. What is Web Services? Web Services
Web Services is Defined by Standards
Web Services
A set of standards that comprise a platform for building distributed, interoperable applications
OpenEdge Web Services utilizes W3C standards
Simple Object Access Protocol (SOAP)
Web Service Definition Language (WSDL)
XML
WSDL 1.1 (W3C Note – de facto standard)
SOAP 1.1 HTTP Binding
2001 XML Schema
Web services connects applications together through agreed upon standards.
Information can be shared between applications without writing a customized interface.
It does not matter what language the application is written in or the type of system that it is running on, since the common standards that makeup Web services are used to pass information back an fourth.
W3C = World Wide Web Consortium,
INT-5: Integrate over the Web with OpenEdge® Web Services

6. Standards: SOAP Protocol for message exchange XML-based
Simple Object Access Protocol
Protocol for message exchange
XML-based
Independent of encoding, transport, language, and platform
SOAP is a communication protocol for sending messages between applications
SOAP is based on XML
SOAP is platform independent
SOAP is language independent
SOAP is simple and extensible
SOAP is an XML-based standard that defines the protocol to format messages between a Web Services Clients and a Web service providers. It is an open messaging protocol that supports the exchange of data using multiple SOAP message formats (combinations of SOAP communications style and SOAP representation, or use).
For more information see the WSI Basic Profile:
INT-5: Integrate over the Web with OpenEdge® Web Services

7. Contract between provider and consumer
Standards: WSDL
Web Services Description Language
Specifies the interface
Bindings for the operations
SOAP over HTTP
Business methods that can be invoked (“operations”)
Message structure for each method
Data fields, types
Identifies network address of Web service
WSDL is an XML-based description on how to communicate with the web services (Describes the SOAP messages that a Web service accepts and generates)
A WSDL document describes a web service using these major elements:
portType-The operations performed by the web service
Message-The messages used by the web service
Types-The data types used by the web service
Binding-The communication protocols used by the web service
The WSDL document contains all the information a Web services client needs to “consume” a Web Service
WSDL is also used to locate Web services
Any special datatypes used are embedded in the WSDL file in the form of XML Schema
Also, again for more information see the WSI Basic Profile:
Contract between provider and consumer
INT-5: Integrate over the Web with OpenEdge® Web Services

8. Consumers and Providers
Web Service Provider
Develops and deploys the Web service
Publishes the WSDL
Web Service Consumer
Writes code to access deployed services based on the WSDL contract
Web service
provider
consumer
Client
SOAP
over HTTP
INT-5: Integrate over the Web with OpenEdge® Web Services

9. The Value of Web Services
Why to use Web Services
Heterogeneous applications
Many valuable Services are available
Many consumers
Why not to use Web Services
Homogenous applications
May not be efficient enough
SOA: For existing applications, Web services provides an alternative method to access existing applications. For example, in allowing Web service clients to access the business logic of a client server application over the web.
Why use Progress for Web Services?
Progress makes it easy.
INT-5: Integrate over the Web with OpenEdge® Web Services

10. Web Services Heterogeneous Distributed Interoperable SOAP WSDL
Consumers
Providers
What are we really talking about?
INT-5: Integrate over the Web with OpenEdge® Web Services

11. Web Services Demonstration
INT-5: Integrate over the Web with OpenEdge® Web Services

12. Agenda The Value of Web Services ABL Client as a Consumer
Integrate over the Web with OpenEdge Web Services
The Value of Web Services
ABL Client as a Consumer
OpenEdge Web Service Provider
INT-5: Integrate over the Web with OpenEdge® Web Services

13. Web Services ABL Client Requirements
What do I need to know?
How to use the WSDL Analyzer
A little AppServer™ persistent procedure syntax
That’s all!
INT-5: Integrate over the Web with OpenEdge® Web Services

14. Web Services ABL Client Process
Obtain WSDL (or its location)
Run the WSDL Analyzer on the WSDL
Generates ABL code snippets in HTML form
Use WSDL Analyzer information to code calls to Web service
Call the Web service
INT-5: Integrate over the Web with OpenEdge® Web Services

15. OpenEdge Client calling a Web service
Web service consumer
Web service provider
HTTP Client 1
Request WSDL
SOAP Processor
WSDL 2 3
Call Service
Client ABL Application Code
Service Response 4
To execute internal procedures on an AppServer, a ABL application needs to perform four tasks.
The application will connect the client to the AppServer, invoke a persistent procedure on the AppServer, run internal procedures in the proxy handle and finally (hopefully) cleanup by deleting the persistent procedure object and disconnecting from the AppServer. These are essentially the same tasks that an OpenEdge application will perform in order to execute operations on a Web Service.
Note that Prot Types are modeled as persistent procedures. However, nothing actually runs persistent.
INT-5: Integrate over the Web with OpenEdge® Web Services

16. WSDL Analyzer (command bprowsdldoc)
Input WSDL (obtained from service provider)
Output HTML documentation
ABL code snippets and examples
SOAP/XML samples
Textual information about service
proenv>bprowsdldoc myOutput
Documentation written to
File:///C:\OpenEdge\WRK\myOutput\index.html
The first step in working with Web services for an OpenEdge client is to locate the WSDL and to then run the WSDL Analyzer over that WSDL. The WSDL Analyzer provides information showing how to connect to and make calls to a service based on the WSDL.
The command to run the WSDL Analyzer is bprowsdldoc.
The returned message shows the full path to the location of the output and the name of the file to call to view the output.
The name of the file is always index.html, so use separate directories to prevent overwriting previous runs of the WSDL Analyzer.
The output directory is optional. If not specified documents are written to the current working directory.
INT-5: Integrate over the Web with OpenEdge® Web Services

17. The WSDL Analyzer Connection information
Output includes:
Connection information
How to create a Port type (Persistent Procedure)
Lists all the Operations (Internal Procedures)
How to call each Operation
Procedure and Function syntax
Data type format
Service - Includes the contents of the WSDL documentation element within the wsdl:definitions elements.
Location – URL of WSDL document used to generate this documentation.
Target Namespace - List of PortTypes available within this WSDL. Only PortTypes that are used in SOAP bindings are included.
PortType – for each supported PortType operation display: Connection Information - CONNECT Method Parameters
Connection example – shows possible 4GL statements for creating the connection and preparing for a web service invocation.
Operation Summary – List all operations available within this PortType. Essentially a table of contents for the next section.
Operation Detail – Describe each operation in detail.
Documentation – as given in the WSDL.
Parameters – including name, mode (input, output, input-output), proposed 4GL data type, XML Schema data type and any documentation. If a parameter is of a complex type, the WSDL Analyzer includes a hypertext link into the data types page, or if the format matches then it describes a ProDataSet or a TEMP-TABLE.
Return – value including proposed 4GL data type, XML Schema data type and documentation. Included only if the operation is RPC style or wrapped document literal.
Faults – A fault is a SOAP error message. Each fault is described in terms of the contents of the fault detail element.
Request Headers – A header is used for tracking, context, information useful for processing the SOAP message.
Port type is modeled as a persistent procedure (although it is not persistent)
Operations are modeled as internal procedures
INT-5: Integrate over the Web with OpenEdge® Web Services

18. The WSDL Analyzer There is no guarantee (It is a guideline)
Output limitations:
There is no guarantee (It is a guideline)
No disconnect and cleanup information:
DELETE OBJECT hPortType.
hWebService:DISCONNECT().
DELETE OBJECT hWebService.
INT-5: Integrate over the Web with OpenEdge® Web Services

19. Demonstration: Calling a Web service
key="cFvuCm9QFHKrSl+LARUiI6Tr/2gOGVGh".
phrase = "Phonix, Arizona".
RUN doSpellingSuggestion IN hGoogleSearchPort(INPUT key, INPUT phrase, OUTPUT return1).
MESSAGE "The phrase is: " + phrase + “ The suggesion is: " + return1 SKIP VIEW-AS ALERT-BOX.
DELETE OBJECT hGoogleSearchPort NO-ERROR.
hWebService:DISCONNECT() NO-ERROR.
DELETE OBJECT hWebService NO-ERROR.
INT-5: Integrate over the Web with OpenEdge® Web Services

20. Agenda The Value of Web Services ABL Client as a Consumer
Integrate over the Web with OpenEdge Web Services
The Value of Web Services
ABL Client as a Consumer
OpenEdge Web Service Provider
INT-5: Integrate over the Web with OpenEdge® Web Services

21. OpenEdge Web Service Provider
Required Components
Your Application
Broken down into services
Application Server
Hosts application code exposed as services
Provides database access
ProxyGen
Generate intermediate file used for deployment (includes wsdl mapping information)
Progress Explorer or wsaman
Manage Web service (deployment)
INT-5: Integrate over the Web with OpenEdge® Web Services

22. OpenEdge Web Service Provider
Required Components
WSA Servlet
Interface between the Web Service Consumer and the OpenEdge AppServer™
3rd Party Products
Java Servlet Engine (JSE)
Provides environment to run WSA servlet
Web Server
Provides HTTP support
Hosts JSE
WSA = Web Services Adapter
INT-5: Integrate over the Web with OpenEdge® Web Services

23. Deploying a OpenEdge Web Service
OpenEdge AppServer 4
Web Server
OpenEdge Application
Business Logic 1
Java Servlet Engine
WSA Servlet
r-code
WSDL
WSAD
WSM
ProxyGen is a tool used to specify interface information between the AppServer and a non-OpenEdge client. The selected client option in this case is Web services. ProxyGen takes as input compiled ABL file (r-code). There are a number of options in ProxyGen that allow the interface to be customized.
The generation option of ProxyGen generates the Web service interface information into a Web Service Mapping File (WSM). The WSM is an intermediate file that is used when the Web service is deployed.
At this stage of the implementation it is important to understand and to choose the session model that will be used on the AppServer. The two models are Session Managed and Session Free. Session Free does not retain any resources on the AppServer and in the vast majority of cases this is the model that should be used to implement Web services. However, there could be some exceptions when Session Managed is used to retain information between successive calls to the Web service. The Web service provider and the Web service consumer must use the same session model.
The Web Services Adapter (WSA) is used to deploy a Web service. The WSA takes as input the WSM file.
Deploying the Web service using either of these tools generates the WSDL and the WSAD.
WSDL is a ‘contract’ that is made available to the client describing how to access the Web service.
WSAD is used is made available to the WSA Servlet and provides information to the Servlet on how to call the AppServer. 3 2
ProxyGen
WSM
Progress Explorer or
wsaman
Intermediate file used for Web service deployment
INT-5: Integrate over the Web with OpenEdge® Web Services

24. Accessing an OpenEdge Web Service
Web Server
Web service consumer 8 7
HTTP Listener/Sender 1 2
Java Servlet Engine
WSA Servlet
WSAD 3 6
SOAP Processor
Message flow:
The request is sent as an HTTP POST.
The Web Server is listening for HTTP messages and receives the message request from the Web service client.
The WSA Servlet that is running in the JSE, on the Web Server, processes the message
The SOAP message is taken out of the HTTP message and processed by the SOAP Processor.
The SOAP processor and the WSAD convert the message into the format for the AppServer
The WSA Servlet uses the SOAP Processor and WSAD to change the response back into a SOAP message.
The SOAP message is included in a HTTP message and is sent by the Web Server back to the Web service consumer.
The message is send back using a HTTP Response
OpenEdge AppServer 4 5
ABL Business Logic
INT-5: Integrate over the Web with OpenEdge® Web Services

25. Demonstration: Deploying a Web service
INT-5: Integrate over the Web with OpenEdge® Web Services

26. Web Services Troubleshooting
ABL SOAP Fault
Envelope
Body
Body Entry
fault code
fault string
fault actor
<fault detail>
Whenever a Web Service is unable to honor the invocation of an operation it will generate a SOAP fault message. Progress will convert the SOAP fault into a Progress error message. The following error message will be generated for all SOAP faults:
Web Service %s<operation> failed. SOAP faultstring is %s (nnnn)
If the RUN statement had the NO-ERROR phrase, then this error string will not be generated. It would be available via the ERROR-STATUS system handle.
You can handle the ERROR condition as for any ABL procedure or user-defined function call, by trapping it with the ON ERROR option or inspecting the ERROR-STATUS system handle directly after invoking the request with the NO-ERROR option.
Within a SOAP header callback procedure, the same holds, as though it were part of the procedure or user-defined function call that generated the request.
In any application an error can occur, invoking a Web Service from the ABL is no different, in the event of an error an ERROR condition is raised – with Web Service operation fails, the error is returned in a SOAP fault. This information is returned to the ABL as part of the existing ERROR-STATUS system handle. In order for the ABL application to recover this information, the invocation of the Web Service operation must contain the NO-ERROR phrase. Without this phrase, the error will be presented to the end user, the SOAP-FAULT-DETAIL is appended to the Progress Error Message.
INT-5: Integrate over the Web with OpenEdge® Web Services

27. SOAP Faults
RUN operationName IN hPortType (INPUT value1, OUTPUT value2) NO-ERROR.
IF ERROR-STATUS:ERROR THEN DO:
DO iCnt = 1 TO ERROR-STATUS:NUM-MESSAGES:
MESSAGE ERROR-STATUS:GET-MESSAGE(iCnt) VIEW-AS ALERT-BOX.
END.
IF VALID-HANDLE(ERROR-STATUS:ERROR-OBJECT-DETAIL) THEN DO:
MESSAGE
"Fault Code:" ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-CODE
SKIP
"Fault Actor: " ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-ACTOR SKIP
"Fault String:" ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-STRING SKIP
"Fault Detail:" ERROR-STATUS:ERROR-OBJECT-DETAIL:SOAP-FAULT-DETAIL
VIEW-AS ALERT-BOX.
As a best practice your application code should always check for and handle SOAP Faults, as opposed to letting default actions control handling errors.
To see/test the fault messages:
Use NO-ERROR on the call to the service operation.
Disable the web service at the service provider
INT-5: Integrate over the Web with OpenEdge® Web Services

28. SOAP Viewers (prosoapview)
C:\Progress\OpenEdge\bin\prowin32.exe
-proxyhost localhost -proxyport 4444
There are a number of SOAP viewers available that can be used to view the messages send back and forth between a web service consumer and a web service client. OpenEdge ships with two of these viewers, prosoapview and wsaviewer. The screen shots on this slide are for prosoapview.
To use prosoapview:
Add parameters to your development session startup
i.e. ‘C:\Progress\OpenEdge\bin\prowin32.exe -proxyhost localhost -proxyport 4444’
Start a proenv session and run prosoapview from the command line
Set the proxy port to match the address used to start the development session
Start ‘spying’
(See the OpenEdge Web Services Manual for more information on prosoapview.)
When the client calls the Web service the messages are intercepted and displayed in the viewer
For a better view of the XML based SOAP message cut and paste the message into a file with extension xml. Don’t include http header, so that it is a well formed XML message. View in a tool that displays formatted XML, such as a web browser or DataDirect’s Stylus Studio.
INT-5: Integrate over the Web with OpenEdge® Web Services

29. In Summary Understand Web Services Identify when to use Web Services
Implementing OpenEdge Web Services
Understand Web Services
Identify when to use Web Services
Progress makes it easy
Web service
provider
consumer
Client
SOAP
over HTTP
INT-5: Integrate over the Web with OpenEdge® Web Services

30. For More Progress Information, go to…
Progress eLearning Community:
WSDL for OpenEdge Developers
Consuming Web Services from OpenEdge
Opening 4GL Applications to Web Services Clients
Documentation:
10.1B Web Services manual
ProxyGen Changes for Web Services in OpenEdge 10.1A
INT-5: Integrate over the Web with OpenEdge® Web Services

31. For More Web Services Information, go to…
The World Wide Web Consortium (W3C)
Web Services Interoperability Organization
WS-I Basic Profile:
W3 Schools
INT-5: Integrate over the Web with OpenEdge® Web Services

32. Questions?
INT-5: Integrate over the Web with OpenEdge® Web Services

33. Thank you for your time
INT-5: Integrate over the Web with OpenEdge® Web Services

34. INT-5: Integrate over the Web with OpenEdge® Web Services