Prerequisites
In order to understand the content of this lesson, make sure you watched the following lessons:
Introduction
Usually Web applications do not exist standalone but need to integrate with external systems and applications already existing in the company intranet. The best way to make different applications communicate with one another is using a Web Service infrastructure. That's why it is important to know how you can easily integrate your WebRatio Platform designed application with existing Web Services.
This lesson gives you the basic knowledge to help you invoke a Web Service. This lesson does NOT cover how to create Web Services but provides references to deepen your knowledge about the world of Web Services. This lesson will focus on SOAP-based Web Services.
Web Service Overview
The "W3C" defines a Web Service as a software system designed to support interoperable machine-to-machine interaction over a network.
A Web Service has an interface described in a machine-processable format (specifically WSDL).
Other systems interact with the Web Service in a manner prescribed by its description using "SOAP" messages, typically conveyed using "HTTP" with an "XML" serialization in conjunction with other Web-related standards.
Web Service Structure
Web Services are Application Components that communicate using open protocols; they are self-contained, self-describing, and they can be used by other Applications. Web Services have a service descriptor file that distinguishes the Web Services Methods from the structure of the messages exchanged with the Web Services.
The service requestor can use this information to interact with a specific Web Service Provider. You can think of an individual Web Service as a piece of software that performs a specific task (also known as a function), and makes that task available by exposing a set of operations that can be performed (known as methods or "Web Methods") with the task.
Additionally, each of the methods exposes a set of variables that can accept data passed into the method. These variables are known as parameters or properties. Together, the properties and methods refer to a Web Service's interface.
Web Service Structure Example
For example, "Company A" creates a Web Service that provides currency rate functionality, which may expose a method called "GetRate". "Company B" is then able to pass a parameter, called "CountryCode", into the "GetRate" method. The "GetRate" method takes the "CountryCode" parameter, looks up the appropriate currency rate in a database, and returns the rate back to the program that requested it.
In this example, which database did "Company A" use to access the currency rate information? What was the name of the database server? What communication mechanisms and security mechanisms were used to access the database server? The answer to all of these questions is, "It doesn't matter".
The beauty of a Web Service is the concept of encapsulation. Encapsulation allows the complexity of retrieving the actual currency rate to be completely self-contained within the company that created the Web Service, "Company A". The only thing that "Company B" knows is that they called a Web Service to get a currency rate and it was given to them.
Web Services are made possible by placing the programs, or Applications, on a "Web Server". Since the Application resides on a "Web Server", it can be called, or invoked, from any other computer on the network by using "HTTP". The Web Service provides seamless distributed computing across the entire network, as long as both sides know how to use a Web Service.
Expose a Web Service
A Web Service must be "exposed" in order to comply with the "W3C" specification. Exposing a Web Service means that a programmer creates the "interface" for it.
There are mainly two ways to expose a web service: "SOAP" and "REST".
- "SOAP" is a communication protocol defining format of the messages to be used for communication with Web Services. "SOAP" is based on "XML" and is a "W3C" standard.
- "RESTful" is an architectural style that specifies constraints that if applied to a Web Service include desirable properties such as performance, scalability, and modifiability, that enable services to work best on the Web. The "REST" architecture works with a client/server architecture and is designed to use a stateless communication protocol, typically "HTTP".
This lesson focuses on the invocation of SOAP Web Services.
Invoke a Web Service
Web Service Provider
Let’s suppose you want to invoke a Web Service that gives you back the stock quote of a company and you want to use it in your Web application. In order to be able to use SOAP Web Services you need to know which is the "Web Service Descriptor" file; in this case the "WSDL".
The "WSDL Definition" is referenced in a WebRatio Platform Web Project through a "Web Service Provider". A Web Service Provider is a reference to a remote system that gives access to a set of Web Service operations through a WSDL. You can have several "Web Service Providers" in your Web Project.
How to Add a Web Service Provider
Let’s see how you can add a "Web Service Provider" to your project. This example uses the "Stock Quote" web service, but can be used as reference for other Web Services.
Since the "Web Service Provider" may be used by "Site Views" and "Service Views", it has to be defined at the Project level. Select the "Project" tab in the main work area and then move to the Outline View; right-click on the "Service/Data Providers" node and choose "Add" and then "Web Service Provider" option.
The "Web Service Provider" will be shown as a child of the "Service/Data Providers" inside the Outline View. Enter the name for the "Service Provider", which may be something like "StockQuote".
Next, enter the "WSDL" description of the "Web Service Operations". The tool shows two different options: "File" and "URI". The "File" property is used to refer to the workspace file of the "WSDL", while the "URI" property is the endpoint "URI" of the "WSDL". From the Properties View, set the "URI" property to "http://wrservices-webservicesdemo.eu.webratio.net/wsdl.do", which is the remote description file for the Web Service.
XSD Definition
Usually the "WSDL" definition includes or references some "XSD" files which contain the definition of the structure that the messages exchanged with the Web Service must have. In WebRatio you also need to add references to the "XSD" files in the Web Project. This will help you create the Domain Model used to communicate with the Web Service.
The "XSD" references are added to the Web Project by means of an "XSD Provider" and of several "XSD Resources".
The XSD Service Provider is a container of XSD Service Resource. The aim of the XSD Service Provider is to enable the creation of model objects, starting from an XML Schema Definition file.
The XSD Service Resource is a reference to XML Schema Definition resources.
How to Add an XSD Provider
As for a "Web Service Provider", an "XSD Provider" can be referred by "Site Views" and "Service Views" so it will be added at the Project level. Move to the Project View and right-click on the "Service/Data Providers" node and choose "Add" and then "XSD Provider".
The only property that you can configure for it is the name. Type for example "StockQuote XSD Provider". An "XSD Provider" is a container for many "XSD Resources".
To add an "XSD Resource", right-click on the "XSD Provider" node, and choose "Add" and then "XSD Resource". This resource is added inside the Outline View as a child of the "Provider". Enter the name: a meaningful one can be "StockQuote XSD Resource". An "XSD Resource" has to be configured by choosing the "Type" which can be "XML Schema" if it’s defined in a separate file, or "Embedded WSDL Schema" if the "XSD Definition" is inside the "WSDL".
To understand which is the "Type" for the "XSD Resource", open the "WSDL Definition" of the Web Service by clicking on the "Show" button in the "URI" field in the Properties View for the "StockQuote" web service provider. As you can see, the "WSDL Definition" for the "StockQuote" web service contains the schema element corresponding to the "XSD Definition". Therefore, choose the "Embedded WSDL Schema" type for the "StockQuote XSD Resource". Next, add the reference to the "XSD Definition", which can be done by filling in the "File" and "URI" properties. The "File" property is used when you want to load a file inside your workspace, while the "URI" property identifies a remote resource. Since in this case the "XSD" is inside the" WSDL Definition", use the same setting for the "URI" property as for the "Web Service Provider". Set the value for the "URI" property as "http://wrservices-webservicesdemo.eu.webratio.net/wsdl.do".
From XSD to Domain Model
WebRatio uses the "XSD Definitions" to help you create a piece of a Domain Model. This is done with the "Synchronization" process. This process reads through the "XSD Definition" and proposes a set of "Entities" and "Relationships" to be imported. The proposed schema is translated into the shown Domain Model reported.
The translation rules used during the "Synchronization" process are:
- A Complex Type becomes a "Volatile Entity". For example, the "Get Quote" complex type corresponds to the "Get Quote" entity.
- A Simple Type becomes an attribute of the "Volatile Entity", whose type is inferred from the "type" property of the "XSD" specification. For example, the "GetQuoteResult" becomes an attribute of the type string.
By default, all relationships between two "Volatile Entities" created, starting from an "XSD" file, have the 1:1 cardinality. The cardinality changes when a "max-Occurs" attribute with value "unbounded" is present on the "XSD" element that will be translated into the entity that can have one or more instances. This is translated into a 1:N cardinality.
The connection to the XSD Provider can return an error if the Internet connection does not reach the defined address.
How to Synchronize an XSD Provider
To launch the synchronization of "XSD Resources" into the "Domain Model" of the Web Project, move to the "Project" tab and from the Outline View select the "XSD Provider" to synchronize. Right-click on it and select the command "Synchronize XSD…".
This will open the "XSD Synchronizer" dialog that shows you a preview of the Domain Model elements that the procedure will create. From the bottom of this dialog you can set the "Entity Duration" property that will decide the "Duration" property of the new entities. For the purposes of this example, this property can be left to the default: "Session Volatile Database".
Press on the "Import All Objects" button on the upper left and then press the "Finish" button to confirm. As you can see now in the Domain Model, you have all the entities necessary in order to invoke the Web Service and to store the obtained response.
Invoking a Web Service - Model
In order to invoke and show the results of a Web Service invocation it’s necessary to create a piece of model composed of two main parts:
- The "IFML" model allows the user to send the desired information to the Web Service and show the "Web Service Response".
- The "Action Definition" containing the operation chain is required to make the Web Service call, sending all the information retrieved from the user, and to save the "Web Service Response".
IFML Model
To create the "Basic IFML Model" requires that we have a "Page" with a "Form" in which the user can enter the information needed to make a valid request to the Web Service. In the example of the "Stock Quote" web service, only the "symbol" of the company for which you want to know the "Stock Quote" is required. The "Form" has a single "Field" in which the user can type the "symbol".
To make the Web Service call, there will be a "Navigation Flow" connecting the "Form" component to the "Action". This will be the button used to invoke the Web Service, passing also the "symbol" for the company to the "Action".
Presuming that the user wants to see the result in the same page, you can place a "Details" component based on the "GetQuoteResponse" entity next to the "Form" component, if the call to the service is successful; otherwise an error is displayed with "Message" component next to the "Form" component.
Action Definition Workflow
The "Action" included in the previous IFML model refers to an "Action Definition" that contains the operation chain handling the Web Service call. The workflow diagram refers to the generic structure of the "Action Definition".
The "Action Definition" must accomplish the following tasks:
- Retrieve the information provided by the user, which comes from the "Form" component and save it as "Input Parameter".
- Invoke the Web Service using the "Input Parameter".
- Store the "Web Service Response" in the set of available Domain Model entities.
- Provide as "Output Parameter" the "Key" of the saved "Object".
This is the resulting model of the "Action Definition". As you can see, there’s an "Input Parameter" that is the "symbol" of the company for which you want to know the "Stock Quote" and two "Output Parameters"; one for each "Output Port". Depending on the Web Service call result, only one of the "Output Ports" is executed. If the call is successful, then the "Action Definition" provides the "key" of the save "Object"; otherwise, it gives an error message. To model the shown "Action Definition", it’s necessary to learn how to use two operations: the "Request Response" Operation and the "XML I/O" operation.
How to Use a Request Response Operation
The "Request Response" operation invokes a specific "SOAP Web Service" using the provided information for building the request message. It can be configured in order to decide which is the Web Service to call. Let's see how to use a "Request Response" operation inside an "Action Definition" and how to configure it to call the "Stock Quote" web service.
The "Request Response" operation is inside the "Service Components" section of the toolbar, available from within the "Action Definition". Select it and place it inside the work area. After placing it in the work area you can type directly a name for it. Use a meaningful name such as "Get Stock Quote".
Move to the Properties View to configure the other properties. Press the "Select" button next to the "Web Service Provider" property and select the "Web Service Provider" of your choice. Then press "OK" to confirm. Notice that if you have just one "Web Service Provider" in your Web Project, WebRatio Platform automatically chooses it as the "Web Service Provider" for the operation. Press the "Select Operation" button next to the "Web Service Operation" property and choose the "GetQuote" Operation. Press "OK" to confirm your choice. The settings for provider and operation are now also shown inside the operation in the model.
Once the "Request Response" operation is added and configured, you can make the binding. To provide the "Company Symbol" input parameter to the "Request Response" operation, add an "OK Flow" connecting the "Input Port" and the operation. Select the "OK Flow" from the "Flow" section of the toolbar and click first on the "Input Port", and then on the "Request Response" operation. Double-click on the "OK Flow" to open the "Parameters Binding" dialog. The "Input Parameters" of the "Request Response" depend on the "Web Service Method" to call and, based on the "Web Service Method" that you have to invoke, you can choose to pass an entire "XML Document" or the single data to each item. To bind the "Company Symbol", uncheck the "Enable Default Binding" checkbox and bind the "Company Symbol" as value for the "symbol" input parameter. Press the "OK" button to confirm your choice.
How to Set and User an XML I/O Operation
To manage the response, another operation must be introduced. The best choice is the "XML I/O" operation which is able to work with the "XSD Definition".
The "XML I/O" operation is an operation that imports or exports information through an XML Document that is compliant with a specific XSD Definition. The Operation is able to store all the information provided in an "XML Document", respecting a specific "XSD Schema" starting from the root Entity, and navigating all the outgoing relationships as long as there is data to be saved.
Let's see how to set and use this operation in the "Get Stock Quote Response" action definition. Select the "XML I/O" operation from the "Service Components" section of the toolbar available from within the "Action Definition" and place it in the work area. Type "Save Stock Quote" as the name.
From the Properties View, use the dropdown selection to set the "Mode" property to "Import", since here you are importing information from the "Response" of the Web Service Invocation to the Domain Model. Next, set the "Entity" to store the information by pressing the "Select" button next to the "Entity" property and then selecting the "GetQuoteResponse" Entity. Press "OK" to confirm.
To complete the model, proper bindings must be set. Add an "OK Flow" that connects the "Request Response" operation and the "XML I/O" operation. Double-click on it to open the "Parameters Binding" dialog. Remove the "Enable Default Binding" check and set the "GetQuoteResponse" of the "Request Response" as input for the "GetQuoteResponse XML Document". Click the "OK" button.
Add another "OK Flow" that connects the "XML I/O" operation and the "Success" OK Port. Double-click on it to open the "Parameters Binding" dialog. Remove the "Enable Default Binding" checkbox and set the "oid" Attribute as "Output Value" for the "Port", binding it with the "Response Key". Press "OK" to confirm. This will return, after the "Web Service Invocation", the Primary Key of the returned value.
We consider the case that the call to the Web Service fails. Add a "KO Flow" that connects the "Request Response" operation and the "Failure" KO Port. Double-click on it to open the "Parameters Binding" dialog. Remove the "Enable Default Binding" check and set the "Error Message" of the "Request Response" as input for the "Error Message". Click the "OK" button.
Test a Web Service
"Generate and Run" the current status of the Web application to test it.
As soon as the browser opens, go to the page with the form to insert the stock quote symbol. Use "GOOG", which is the symbol for "Google Inc.", as the value. Press the "Submit" button to execute the "Web Service".
After few seconds you should get the response in the format of a long string containing all the properties of the "Stock Quote".