1. SOA-12: Integrate over the Web with OpenEdge® Web Services
Web services are the solution for Web-based application integration. Existing business logic can be called by clients using Web services standards, allowing you to reach more customers by providing your application as a Web service. Your applications can also call Web services − leveraging more resources by seamlessly accessing Web services as a consumer from an OpenEdge client. In this session you'll learn about the standards that form Web services and how OpenEdge provides you with the tools that take complexity out of the implementation and allow you to easily and quickly create and call standards-based Web services. We'll describe the OpenEdge 10 features that enable you to take your existing OpenEdge application and deliver it as a Web service. We also explain some of the programming statements used to call Web services.
David Lund
Sr. Training Program Manager

2. Session Focus Understanding Web Services
Implementing OpenEdge Web Services
Understanding Web Services
Identify when to use Web Services
Implementing an OpenEdge service provider
Implementing an OpenEdge service consumer
SOA-12: Integrate over the Web with OpenEdge Web Services

3. 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
This presentation use the abbreviation ABL for OpenEdge Advanced Business Language (formerly known as OpenEdge 4GL)
SOA-12: Integrate over the Web with OpenEdge Web Services

4. The Value of Web Services
Why to use Web Services
Heterogeneous connectivity
In SOA makes distributed services possible
Lower common denominator than either EDI or CORBA
Many Services are available
Why not to use Web Services
May not be efficient enough
May not be available
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.
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.
Web services, as compared to EDI and CORBA, is the lowest common denominator because it uses XML, which is simply text, rather than encoded values.
SOA-12: Integrate over the Web with OpenEdge Web Services

5. Consumers and Providers
Web Service Provider Developer
Develops and deploys the Web service
Publishes the WSDL
Web Service Consumer Developer
Writes code to access deployed services based on the WSDL contract
Web service
provider
consumer
Client
Standards
OpenEdge generally “hides” the complexities of the technology allowing the ABL developer to focus on the business issues. The ABL developer will not need to “get into the weeds of WSDL” as the WSDL analyzer will take care of the complexities of WSDL, SOAP, and HTTP, generating documentation/prototypes for the developer - leaving them to concentrate on the application functionality.
SOA-12: Integrate over the Web with OpenEdge Web Services

6. Web Services is Defined by Standards
A set of standards that comprise a platform for building distributed, interoperable applications
OpenEdge Web Services utilizes W3C standards
WSDL 1.1 (W3C Note – de facto standard)
SOAP 1.1 HTTP Binding
2001 XML Schema
The SOAP binding describes how to use WSDL to describe SOAP messages. WSDL can also be used to describe mail messages, JMS messages and even HTTP messages (that is, HTTP without SOAP).
The actual implementation of Web services can vary depending on the standards that are used.
Progress 4GL Web Services implement the 'commonly accepted' standards, WSDL 1.1, SOAP 1.1 over HTTP, and 2001 XML Schema.
W3C stands for the World Wide Web Consortium. W3C develops interoperable technologies (specifications, guidelines, software, and tools). For more information go to
W3C = World Wide Web Consortium,
SOA-12: 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 – Web Services Description Language. XML-based document used to describe the SOAP messages that a Web service accepts and generates. The WSDL document contains all the information a Web services client needs to “consume” a Web Service: location, message format, input/output parameters. Even with this information it is recommended that supplemental documentation be supplied by the Web service provider to help developers that are writing clients to access the service.
WSDL is a standard XML format for describing XML Web services, proposed by a group of vendors including Ariba, Intel, IBM, and Microsoft. It defines the set of operations and messages that can be sent to and received from a given Web service in an abstract, language-neutral manner. WSDL is also protocol-neutral, but it does have built-in support for binding to SOAP.
Contract between provider and consumer
SOA-12: Integrate over the Web with OpenEdge Web Services

8. Standards: SOAP Protocol for message exchange
Lightweight & XML-based
Independent of encoding, transport, language, and platform
Extensible via SOAP headers
Supports message typing, strong typing, and structured data
SOAP is an XML-based standard that defines the protocol to format messages between a Web Services Clients and a Web service providers.
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). Depending on the format, SOAP messages pass data using XML schema on a combination of XML schema and custom encoding. SOAP also supports multiple bindings that use different communications protocols to transport these messages. However, because of the ubiquity of HTTP/S, SOAP over HTTP is the prevailing standard protocol binding.
SOAP standards allow any existing Web service client technology that can code and decode SOAP to use Web services with no additional support. However, the complexity of coding SOAP messages is such that most Web service client vendors provide run-time libraries and code generation tools to enhance their existing client platforms, making them Web service-ready.
Web Services Client platforms (Progress, Microsoft .NET, Apache AXIS, etc.) and Web service Providers typically support only a few of the possible SOAP message formats. However, in order for a given client to access a Web service supported by a given Web service provider the service must use a SOAP format that the client supports. Flexible Web service providers support Web services using the SOAP formats that are supported by most Web service clients.
SOA-12: Integrate over the Web with OpenEdge Web Services

9. Standards: XML Schema Comprise of a set of agreed upon rules
Structure, Content, and Semantics
A means for defining XML Documents
Used to define formats for SOAP and WSDL messages
Maps ABL data types
XML Schemas express shared vocabularies and allow machines to carry out rules made by people. They provide a means for defining the structure, content, and semantics of XML documents.
OpenEdge maps ABL data types to XML Schema data types.
More information can be found at:
SOA-12: Integrate over the Web with OpenEdge Web Services

10. 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
Web services built with OpenEdge permit language and platform-independent access to OpenEdge business logic from non-OpenEdge clients, with the passing of data between the client and Progress 4GL Web service application is largely transparent to the client language or platform.
SOA-12: Integrate over the Web with OpenEdge Web Services

11. 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 interface file used for deployment
Progress Explorer or wsaman
Manage Web service (deployment)
SOA-12: Integrate over the Web with OpenEdge Web Services

12. OpenEdge Web Service Provider
Required Components
3rd Party Products
Web Server
Provides HTTP support
Host JSE
Java Servlet Engine (JSE)
Provides environment to run WSA servlet
WSA Servlet
Interface between the Web Server and the OpenEdge AppServer
WSA = Web Services Adapter
WSA = Web Services Adapter
SOA-12: Integrate over the Web with OpenEdge Web Services

13. Deploying a OpenEdge Web Service
OpenEdge AppServer
OpenEdge Application
Business Logic 1
r-code
The next few slides walk through the process of configuring and deploying a web service.
The code must be running on a OpenEdge Application Server. The code processes the business logic and accesses the database.
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. 2
ProxyGen
WSM
Intermediate file used for Web service deployment
SOA-12: Integrate over the Web with OpenEdge Web Services

14. Deploying a OpenEdge Web Service
OpenEdge AppServer
OpenEdge Application
Business Logic 1
r-code
WSDL
WSAD
The Web Services Adapter (WSA) is used to deploy a Web service. The WSA takes as input the WSM file.
There are two options available for deployment:
Progress Explorer
WSAMAN
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
SOA-12: Integrate over the Web with OpenEdge Web Services

15. Deploying a OpenEdge Web Service
OpenEdge AppServer 4
Web Server
OpenEdge Application
Business Logic 1
Java Servlet Engine
WSA Servlet
r-code
WSDL
WSAD
The Web service is deployed to a Java Servlet that is running in a Java Servlet Engine (JSE). The JSE must be hosted by a Web Server.
The WSA Servlet is provided as part of the OpenEdge installation. It is available in the Servlet directory in the OpenEdge installation directory. The WSA Servlet must be installed in the JSE. 3 2
ProxyGen
WSM
Progress Explorer or
wsaman
SOA-12: Integrate over the Web with OpenEdge Web Services

16. Accessing an OpenEdge Web Service
Web Server
Web service consumer
HTTP Listener/Sender 1 2
Java Servlet Engine
WSA Servlet
WSDL
WSAD 3
SOAP Processor
The next few slides go over the steps for accessing a Progress 4GL Web Service.
Progress 4GL Web Services can be accessed by any Web Service consumer that follows the common standards including WSDL and SOAP. For this example the Web service consumer is treated as a ‘black box’.
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 converts the message into the format for the AppServer
Request
SOAP over HTTP
SOA-12: Integrate over the Web with OpenEdge Web Services

17. Accessing an OpenEdge Web Service
Web Server
Web service consumer
HTTP Listener/Sender 1 2
Java Servlet Engine
WSA Servlet
WSDL
WSAD 3
SOAP Processor
Message flow:
The message is sent from the Web Server to the AppServer. The WSAD is used to locate the AppServer
The AppServer receives the message and the ABL program is run based on what is specified in the message
OpenEdge AppServer 4
ABL Business Logic
SOA-12: Integrate over the Web with OpenEdge Web Services

18. Accessing an OpenEdge Web Service
Web Server
Web service consumer 8
HTTP Listener/Sender 1 2
Java Servlet Engine
WSA Servlet
WSDL
WSAD 3 6
SOAP Processor
Message flow:
After the processing is complete on the AppServer the message is send back along the same path. First to the WSA Servlet.
The WSA Servlet uses the SOAP Processor to change the response back into a SOAP message.
OpenEdge AppServer 4 5
ABL Business Logic
SOA-12: Integrate over the Web with OpenEdge Web Services

19. Accessing an OpenEdge Web Service
Web Server
Web service consumer 8 7
HTTP Listener/Sender 1 2
Java Servlet Engine
WSA Servlet
WSDL
WSAD 3 6
SOAP Processor
Request
SOAP over HTTP
Response
Message flow:
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
SOA-12: Integrate over the Web with OpenEdge Web Services

20. Time for a little Demonstration
Standardized
Interfaces!!
SOAP WSDL
SOA-12: Integrate over the Web with OpenEdge Web Services

21. Demonstration Developing a Web service
Running ProxyGen
Confirming the Web Server and JSE
Deploying a Web service
Progress Explorer
SOA-12: Integrate over the Web with OpenEdge Web Services

22. 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
Web Service Client - AppServer not needed
SOA-12: Integrate over the Web with OpenEdge Web Services

23. Web Services ABL Client Overview
Obtain contract from Web service provider
i.e. WSDL and any documentation
Run the WSDL Analyzer over WSDL
Generates HTML information including ABL code snippet examples
Use WSDL Analyzer information to code calls to Web service
Call the Web service
SOA-12: Integrate over the Web with OpenEdge Web Services

24. 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. In the screen shot a proenv session has been started and the bprowsdldoc command is being run with input of a WSDL file that is available to the public over the internet. A output directory, relative to the working directory is entered as the location for the generated output. The command is executed. 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.
SOA-12: Integrate over the Web with OpenEdge Web Services

25. WSDL Analyzer Generated Documents
HTML generated documentation
Data types
complex data
Operation Index
Port type
connect & call
Service
index
Web Service
ABL connect & call
Port type
Interface
Persistent procedure
Operations
ABL procedure and function calls
An index.html document is generated by the WSDL Analyzer and placed in your default working directory. Open the index.html document in a browser to see the documentation.
In the slide diagram the main hypertext link (solid line) goes from the service list to actual entry. The secondary hypertext link (dashed line) goes to the cross reference.
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
SOA-12: Integrate over the Web with OpenEdge Web Services

26. Data Type Mapping Simple Data Types Complex Data XML document
XML Schema Progress ABL Data Type
i.e string CHARACTER
Complex Data
XML document
LONGCHAR/CHARACTER of serialized XML document
ProDataSet or TEMP-TABLE when possible
For a complete list of simple data type mappings and more information on complex data types see the documentation.
CHARACTER and LONGCHAR can always be used to map variables.
Analyzer shows examples of data mapping for both simple and complex data.
Part of the process of calling a web service from the ABL and getting a response will be translating between ABL data types and XML Schema data types. Progress provides a range of suggested and acceptable mappings for all XML Schema types.
It is likely that you will need to work with an XML Schema value that does not map easily to a ABL data type, e.g. a 51-digit decimal value. To do this you can pass an XML string (serialized) version of the value into or out of the Web service invocation. Progress will pass a serialized value when you map either a CHAR or LONGCHAR to any XML Schema data type that has a suggested mapping other than CHARACTER or LONGCHAR.
When you pass the serialized value as an INPUT parameter, the Web service invocation incorporates it directly into the generated SOAP message. For an OUTPUT parameter, the invocation copies the serialized value directly from the SOAP message into the CHARACTER or LONGCHAR parameter. This allows you to perform your own serialization and de-serialization of the value.
To handle complex data structures you will need to use the new LONGCHAR data type, possibly along with the X-DOCUMENT object.
To pass a complex data type to the Web Service you will need to create an XML document, using the DOM API or construct a character variable of the serialized XML.
A complex structure, coming from the Web Service will be returned as LONGCHAR, load into an X-DOCUMENT, you will then be able use either the SAX or DOM API to extract the data into ABL data types for the application to handle.
SOA-12: Integrate over the Web with OpenEdge Web Services

27. Connecting to a Web Service
Initial connection is made
WSDL obtained
Client holds local port
Physical connection only when calling an operation
CREATE SERVER hWebService.
hWebService:CONNECT("-WSDL ' ").
Progress’ implementation for Web Service Clients has been designed with the ABL developer in mind -
Syntax is similar to an AppServer CONNECT, but for a CONNECT to a Web Service there are several Web Service specific connection-parameters. See the documentation for more information.
While a physical connection is not maintained, the CONNECT statement does cause the WSDL to be read, which is typically located at the Web service, so there is physical connection to read the WSDL which is dropped once the operation is complete.
There are many similarities between invoking a Web Service operation and invoking an internal procedure on an AppServer. In both of these programming paradigms client applications want to invoke a set of functionality that is remote to the client. With the implementation parallels, a ABL developer should be able to take a client program written for an AppServer call to invoking a Web Service operation.
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.
In order to invoke an operation available on a Web Service, the ABL client must know the location of the service and the specifics of how data is sent between the client and the service (data format, transport protocol, etc). This is the same kind of information that is needed in order to call an AppServer. In the AppServer programming environment, the ABL provides an object, the SERVER object that gives the application access to a set of operations (the Progress code available through the AppServer), identifies a specific location and implicitly specifies the way information is passed between the client and the server. A ABL Web Service client uses the SERVER object in a similar manner that a ABL AppServer client.
PortType
Encapsulates operations in a Web service - Mapped to portType element of WSDL
Used to invoke operations - RUN statement, FUNCTION call
A Web Service and/or AppServer applications can support many operations. For Web Services, the WSDL document organizes these operations by associating them with a specific WSDL PortType element. Similarly, a common approach used to organizing AppServer functionality is to put a set of internal procedures into a procedure file and run it persistently . Though a port type appears to be similar to a persistent procedure, it is not, in fact, persistent.
As mentioned earlier, that’s a fair amount of detail that you do not need to focus on – the WSDL Analyzer will generate documentation for the “ABL developer” to work with…
SOA-12: Integrate over the Web with OpenEdge Web Services

28. Calling a Web Service from the ABL
DEFINE VARIABLE hWebService AS HANDLE.
DEFINE VARIABLE hPortType AS HANDLE.
CREATE SERVER hWebService.
hWebService:CONNECT(wsdl url).
RUN portTypeName SET hPortType ON SERVER hWebService.
RUN operationName …
DELETE PROCEDURE hPortType.
hWebService:DISCONNECT().
DELETE OBJECT hWebService. 1 2 3 4
Creates a Web service handle.
‘Connects’ to the Web service. Retrieves the WSDL. Does not maintain a physical connection to the server, but keeps port available on the client.
Creates the port type for the Web service.
Web service operations that are available for the port type can be called.
After all calls to the Web service have been completed the resources on the client are released.
The userid, password, and appserver-info arguments will be ignored for Web Service calls. Note that there are other arguments, specific to Web services. See the OpenEdge documentation for more information.
Note that Prot Types are modeled as persistent procedures. However, nothing actually runs persistent. 5
SOA-12: Integrate over the Web with OpenEdge Web Services

29. Calling a Web Service from the ABL1
FUNCTION DynDeptEmp RETURNS CHARACTER
(INPUT pcDeptName AS CHARACTER,
OUTPUT TABLE-HANDLE hDeptEmp)
IN hPortType.
rresult = DynDeptEmp(pcDeptName, TABLE-HANDLE hDeptEmp).
RUN DynDeptEmp IN hPortType(INPUT pcDeptName, OUTPUT rresult, OUTPUT TABLE-HANDLE hDeptEmp). 2
This slide shows an examples for calling web service operations using both functions and procedures. Both the function and the procedure call the same web service operation using hPortType.
Function prototype
Function call (requires function prototype)
RUN statement calling the operation/procedure
Invoking a Web Service Operation
RUN
If an operation has a return value, it is document as both a procedure and a user defined function. In the procedure the last OUTPUT parameter is the return value in the function.
Synchronous or Asynchronous
FUNCTION
Operations are documented a functions as long as the ABL can return the value as a UDF return value. If the data type of the Web service return value is not a valid return value in OpenEdge, such as an extent, the operation will only be documented as a procedure.
Synchronous only
Some Web service operations have an output parameter identified as the ‘return’ parameter. Operations that contain a return parameter can be invoked as a user-defined function. These operation can also be called as procedures. These operations can only be invoked synchronously called as user defined functions. Web Service operations that do not have a ‘return’ parameter need to be invoked using the RUN statement. These operations can be invoked either synchronously or asynchronously. The WSDL utility retrieves this information from the WSDL document and identifies for the 4GL programmer the correct calling method and signature for each Web Service operation. 3
SOA-12: Integrate over the Web with OpenEdge Web Services

30. 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
SOA-12: Integrate over the Web with OpenEdge Web Services

31. Demonstration WSDL Analyzer Client coding Calling a Web service
Connection
Operations
Calling a Web service
SOA-12: Integrate over the Web with OpenEdge Web Services

32. … SOAP Message Envelope - Encloses message Header (optional)
SOAP Envelope
Header (optional)
SOAP Header
Header Entry …
Header entries may contain extensions
Header Entry
Body - Encloses body entries
SOAP Body
Structure of a SOAP message
Envelope
Header (optional) – with multiple header entries
Body – payload!
The Body entry contains application-specific data, serialized based on encoding style.
SOAP Headers can be used to pass optional/additional information to/from the Web Service, not directly related to the Web Service logic. It is likely that customers are likely to access some complex Web services that require additional information. The SOAP header is an optional part of a SOAP message and is suited for this kind of data. One common use is to take the session context in the response to a web service call from the SOAP HEADER and use it in each subsequent request to the web services.
Application specific information can be used to maintain context between calls, examples are listed on the next slide.
Message name and data
or SOAP Fault(s)
Body Entry
SOA-12: Integrate over the Web with OpenEdge Web Services

33. SOAP Header
Optional
Allows context information to be added to message independently of the payload
Authentication and authorization information
Transaction id
Object id
Intermediary specific information
Routing information – to, from, via, etc…
Security information
Auditing
The Web service you are accessing may expect you to use SOAP headers in one or both of the SOAP request and response messages of an operation. depending on the Web service and its application requirements, this could simple, or very complex. OpenEdge provides access to the content of the SOAP header of any SOAP message (request or response).
For a SOAP request message, you can access the SOAP header at a point just after invoking the Web service operation and just prior to when OpenEdge sends the message to the Web service.
For a SOAP response message, you can access the SOAP header after the message arrives at your Web service client and just prior to when OpenEdge returns the results of any operation output and return parameters to your ABL program.
ABL callbacks and callback procedures
For each type of message the ABL allows you to set a ABL callback for either or both of the SOAP request and response.
SOA-12: Integrate over the Web with OpenEdge Web Services

34. 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.
Example error – invalid data, i.e. WSDL defined an integer, you sent an integer, but it is out of range or inconsistent with the values the Web Service was expecting..
Generated when a Web Service operation fails
NO-ERROR returns error to ABL
OpenEdge creates a SOAP-FAULT object
Error returned to the ABL as part of the ERROR-STATUS system handle
If NO-ERROR is NOT SPECIFIED
Error is presented to the user
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.
SOA-12: Integrate over the Web with OpenEdge Web Services

35. 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
SOA-12: Integrate over the Web with OpenEdge Web Services

36. 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.
SOA-12: Integrate over the Web with OpenEdge Web Services

37. Improved Complex Data Support
NEW
Prior to 10.1A
Complex data represented as a character string containing an XML document (LONGCHAR)
10.1A for ProDataSet and Temp-Table
Serialized as an XML document
Deserialize XML document
Analyzer will indicate if the mapping is possible
Recommended for ease of use
Release 10.1A enhances the ability of the ABL client to support of complex data when calling a web service provider.
Most other products supporting web services represent complex data as data structures or classes. For ABL Web service clients complex data has been represented as a character string containing an XML document.
In OpenEdge Release 10.1A the ABL programmer can serialize a ProDataSet or Temp-Table as an XML document. Conversely a properly structured document can be parsed to define and/or load a ProDataSet or Temp-Table.
This functionality makes it easier to process complex data in a manner familiar to ABL developers. It is useful for dealing with a subset of complex structures that may appear in web service operations.
Web service client may pass the following as parameters to the Web service: ProDataSet, ProDataSet handle, Temp-Table, Temp-Table handle.
XML mapping of ProDataSet and Temp-Table is a feature for OpenEdge 10.1A and not specific to Web services.
The WSDL Analyzer identifies an area that can be mapped to a ProDataSet or a Temp-Table. For mapped parameters objects the ABL object is automatically loaded from XML. The ABL object, or handle can be serialized to XML and sent to the Web service provider. If the object is static then the Analyzer provides ABL statements to define the object. If the object is dynamic then the Analyzer generates a description that indicates it can be mapped to a dynamic object, and no ABL code is generated.
SOA-12: Integrate over the Web with OpenEdge Web Services

38. Universal Naming Convention (UNC)
NEW
OpenEdge 10.1A supports UNC pathnames
Using UNC naming
WSDL Analyzer and CONNECT() method
WSDLs defining SOAP addresses
Configuration files in OpenEdge install directory
/* Example SOAP address using UNC file schema */ hWebService:CONNECT(
“-WSDL file:///\\aSystem\aDirectory\test.wsdl”)
Starting with OpenEdge™ 10.1A UNC pathnames are supported when the file name is a Microsoft® UNC pathname. These cases include:
* The WSDL Analyzer and the CONNECT() method
When referring to WSDLs using UNC.
* WSDLs defining SOAP addresses using UNC pathnames.
* Configuration files located in the OpenEdge install directory tree using UNC pathnames.
(Note: A SOAP address using the FILE scheme can be useful when debugging web service invocations)
SOA-12: Integrate over the Web with OpenEdge Web Services

39. Wrapped Document Literal
NEW
Wrapped document literal
Microsoft developed convention
Document literal message in a specific format
Also known as “Wrapped Doc/Lit”
Document literal handled like remote procedure calls (RPC)
Message is broken down into multiple parameters
Most cases simple data types
Can also be complex types
Like a Temp-Table or XML document
One way to look at this is prior to 10.1A the only option was to break about complex data using XML, by writing code to parse it. Now instead of writing code to do the parsing it is parsed for you into RPC style parameters.
Microsoft calls this convention “wrapped document literal”. The process of breaking down the wrapped document literal message into separate parameters is called “unwrapping”.
This is also referred as “Wrapped Doc Lit” and written as “Wrapped Doc/Lit”.
Prior to 10.1A document literal messages, quite often, looked like complex data values. They were processed as XML documents. To improve ease of use of web services using the wrapped document literal convention, support has been added in 10.1A to allow the user to unwrap these messages.
The default has been changed to unwrap wrapped document literal. To use 10.0[AB] document literal processing use parameter -show100style when calling the WSDL Analyzer.
When working with previous releases 10.0A and 10.0B care must be used to not mismatch parameters. Mismatched parameters results in a runtime error.
From the ABL programmers’ point of view, a web service using wrapped document literal messages appears to have multiple parameters, rather than a single complex parameter. In most cases these multiple parameters will be simple data types, which are easier to manipulate than a complex value that is normally received when using document literal.
Note that the analyzer can detect if the document literal parameter is in a valid wrapped document literal format. If it is not in a wrapped document literal format then the parameter is processed as it was prior to 10.1A.
Advantage of using Simplified programming. Multiple simple parameters are easier to work with than one complex document. Improved interoperability with Progress 4GL Web Services. Progress 4GL Web Services (server side) supported this convention prior to 10.1A.
SOA-12: Integrate over the Web with OpenEdge Web Services

40. Unwrapping Wrapped Document Literal
Showing 10.0A default (-show100style)
This slide and the next slide show a portion of the output from the WSDL Analyzer for the same Service. The first slide shows the complex data-type parameters in the Wrapped Document Literal format as LONGCHAR. There are always two parameters in XML format. The ABL client developer must write XML code to build the INPUT parameter and to parse the OUTPUT parameter to access the data that is being passed.
This slide makes the following call to get the WSDL and includes the –show100style
bprowsdldoc WSDLanalyzer/DynTempTable100 -show100style
Always uses LONGCHAR
Requires code for XML parsing
SOA-12: Integrate over the Web with OpenEdge Web Services

41. Unwrapping Wrapped Document Literal
Showing 10.1A default with parameter mapping
This slide shows output from the WSDL Analyzer for 10.1A where the Wrapped Document Literal can be passed as parameters, instead of XML documents in LONGCHAR parameters.
This slide makes the following call to get the WSDL (does NOT include – show100style parameter)
bprowsdldoc WSDLanalyzer/DynTempTable
SOA-12: Integrate over the Web with OpenEdge Web Services

42. Improved - Asynchronous Networking Support
ABL Client Web Service Consumer
10.0B
Asynchronous Requests
Web Service
Queued
Requests
Note: In the lower example the returned requests going from the Web service to the client are queued internally by OpenEdge so that the responses are not lost as they are being processed.
ABL code does not need to be modified to take advantage of this feature, since this is the standard behavior.
ABL Web service client behavior is designed to work like the ABL Session-free AppServer as closely as possible. The goal is to have the ability to make concurrent asynchronous requests. For the ABL Web service client, asynchronous requests to the same Web service are transmitted in parallel. However, prior to 10.1A for the ABL Web service client asynchronous requests to the same destination service are transmitted sequentially, requiring that the previous asynchronous response be received before the next request is sent out.
10.1A fixes this issue. Now asynchronous ABL Web service client requests are transmitted in parallel and provides behavior identical to asynchronous ABL requests to Session-free AppServers.
This change provides the potential for performance improvements when executing multiple asynchronous ABL Web service client requests to the same destination service.
When sending multiple asynchronous requests using Web services the application needs to handle the random return of the requests from the Web service provider.
Connection parameters added to support functionality
-connectionLifetime <seconds>
Controls length of time a connection is valid before it is destroyed
Default is 300 seconds
-maxConnections <number>
Allows the user to set the maximum number of connections created
Default is 0, unconstrained
The move of ABL Web service client to more of a session free model includes the addition of two new connection parameters, -connectionLifetime and –maxConnections.
The user can control the length of time a connection is valid using –connectionLifetime, which represents the number of seconds a given connection can be used before it is destroyed.
Since the number of connections a given application can make is a finite resource, –maxConnections allows the user to establish the maximum number of connections that can be created.
One possible problem is sending parallel asynchronous requests could potentially overwhelm the web server hosting the destination service. . The ABL programmer can minimize this problem by adjusting the –maxConnection parameter accordingly.
10.1A
Asynchronous
Requests
Web Service
Parallel
Execution
SOA-12: Integrate over the Web with OpenEdge Web Services

43. Demonstration
SOA-12: Integrate over the Web with OpenEdge Web Services

44. Under Development D I S C L A I M E R
This talk includes information about potential future products and/or product enhancements.
What I am going to say reflects our current thinking, but the information contained herein is preliminary and subject to change. Any future products we ultimately deliver may be materially different from what is described here.
D I S C L A I M E R
SOA-12: Integrate over the Web with OpenEdge Web Services

45. Beyond 10.1A We are considering
Improving complex data support based on OO initiative
SOAP 1.2, WSDL 2.0 Support
Integration with OpenEdge Architect
Top down Web service design (WSDL First)
Improved validation
WS-Security
ProDataSet support in OpenEdge Web services
XPATH, XQUERY, XSLT
SOAP 1.2 and WSDL 2.0 will be supported as they gain momentum in the industry.
Top down Web service design is a method to create a 4GL web service to conform to a standard provided by a consumer.   Also known as WSDL First.
SOA-12: Integrate over the Web with OpenEdge Web Services

46. In Summary Understand Web Services Identify when to use Web Services
Implementing OpenEdge Web Services
Understand Web Services
Identify when to use Web Services
Implementing an OpenEdge service provider
Implementing an OpenEdge service consumer
Web service
provider
consumer
Client
Standards
SOA-12: Integrate over the Web with OpenEdge Web Services

47. Relevant Exchange Sessions
All of the sessions in the SOA track
SOA-1: Fundamentals of Service-Oriented Architecture
SOA-5: Accessing the Application Server from Anywhere and Everywhere
SOA-10: Application Servers, Web Services and Integration Info Exchange
SOA-1 Fundamentals of Service-Oriented Architecture
By all accounts, service-oriented architecture is becoming the predominant way of building applications. But what is SOA all about, why is it something you should be looking into, and how is Progress helping you to make the transition to SOA? During this session we'll discuss how taking an SOA approach to building your applications allows you to build more agile and flexible systems that are easier to adapt to changing business requirements. The fundamental concepts and principals surrounding SOA will be put into perspective. A SOA maturity model will be described along with the associated architectural patterns that show how as your SOA environment matures it provides increasingly greater business benefit. Technologies such as Web services, the Enterprise Service Bus and event-stream processing will be covered. Case studies will demonstrate how several OpenEdge customers transformed their applications and are moving down the path of SOA.
SOA-2 Accessing the Application Server from Anywhere and Everywhere
The AppServer is a fundamental component of service-oriented business applications (SOBA). OpenEdge offers many client options, running on many platforms to access an AppServer application. During this session we look at the available clients for an AppServer including OpenEdge Advanced Business Logic (formerly known as OpenEdge 4GL), Web service, Microsoft .NET, Java, WebSpeed, and WebClient. For each client we identify the appropriate use cases and deployment models. This shows you the many ways you can expose your business logic throughout your enterprise and beyond.
SOA-12 Application Servers, Web Services and Integration Info Exchange
This is an information exchange between Progress product managers, engineers and our customers. Features and improvements in OpenEdge 10 in our Application Servers, Web services and integration support is reviewed at a high level and discussed. Improvements underway in our next release as well as the shape of our future roadmap are also presented. Lastly, open discussion will be encouraged covering features that the audience would like to see in our roadmap.
SOA-12: Integrate over the Web with OpenEdge Web Services

48. Education / Documentation References
Courses
What’s new in 10.1A : SOA Support
Consuming Web Services from OpenEdge
Opening 4GL Applications to Web Services Clients
Distributed AppServer Application Development
Documentation
OpenEdge Development: Web Services
SOA-12: Integrate over the Web with OpenEdge Web Services

49. Questions?
SOA-12: Integrate over the Web with OpenEdge Web Services

50. Thank you for your time
SOA-12: Integrate over the Web with OpenEdge Web Services

51. SOA-12: Integrate over the Web with OpenEdge Web Services