Prerequisites
In order to understand the content of this lesson, make sure you watched the following lessons:
Introduction
Usually, Web applications are not standalone; they need to integrate with external systems and other applications in the company intranet. The best way to make different applications communicate with one another is to use 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 will focus on REST-based Web Services. Another lesson provides an overview of the Web Service and how you can invoke a SOAP Web Service.
Invoke REST Web Service
REST Web Service Provider
Let's suppose you want to invoke a Web Service that gives you the stock quote of a company, and you want to use it in your Web application. In order to be able to use REST Web Services you need to know which is the "Web Service Descriptor" file; in this case the WADL.
The WADL 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 you access to a set of Web Service operations through a WADL. 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 and then move to the Outline View. Right-click on the "Service/Data Providers" node and choose "Add" and then the "Web Service Provider" option. The "Web Service Provider" will be shown as a child of the "Service/Data Providers" inside the Outline View.
Move to the Properties View and set the "Resource Type" property to "WADL" value. Next, enter the WADL description of the "Web Service Operations". Now, set the "URI" property to "http://wrservices-webservicesdemo.eu.webratio.net/wadl.do", which is the remote description file for the Web Service.
The XSD Definition
Usually, the WADL Definition includes or references some XSD files that contain the definition of the structure that the messages exchanged with the Web Service must have. In WebRatio Platform, 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 both an "XSD Provider" and 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", let’s add an "XSD Provider" at the project level. Move to the Project View and right-click on the "Service/Data Providers" node. Choose "Add" and then "XSD Provider".
An "XSD Provider" is a container for many "XSD Resources". 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".
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, or "Embedded WADL Schema" if the XSD Definition is inside the WADL.
To understand which is the "Type" for the "XSD Resource", open the WADL 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 WADL Definition for the "StockQuote" web service contains the schema element corresponding to the XSD Definition. Therefore, you will want to choose the "Embedded WADL Schema" type for the "StockQuote XSD Resource". Next, add the reference to the XSD Definition. Since in this case the XSD is inside the WADL 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/wadl.do".
From XSD to Domain Model
WebRatio Platform 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.
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 created between two "Volatile Entities", starting from an XSD file, have a 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. 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 specify 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 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 REST Web Service - Model
To invoke and show the results of a Web Service invocation, it's necessary to create a piece of a model composed of two main parts:
- The IFML model that allows the user to send the desired information to the Web Service and that shows the Web Service Response.
- The "Action Definition" containing the operation chain that is required to make the Web Service call, send all the information retrieved from the user, and save the Web Service Response.
IFML Model
To create the "Basic IFML Model" we need to 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 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, and will also pass 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 saves it as "Input Parameter".
- Invoke the Web Service using the "Input Parameter".
- Store the Web Service Response in the set of the available Domain Model entities.
- Provide as "Output Parameter" the "Key" of the saved "Object".
To model the shown "Action Definition", it’s necessary to learn how to use two operations: the "Restful Request Response" operation and the "Create" operation.
How to Use a Restful Request Response Operation with Provider
The "Restful Request Response" operation invokes a specific "REST 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 "Restful Request Response" operation inside an "Action Definition" and how to configure it to call the "Stock Quote" web service. Select the "Restful Request Response" operation from the "Service Components" section of the toolbar and place it inside the work area. Move to the Properties View and press the "Select" button next to the "Web Service Provider" of your choice. Then press "OK" to confirm. Press the "Select Operation" button next to the "Web Service Operation" property and choose the "GET" operation. The settings for provider and operation are now also shown inside the operation in the model.
Once the "Restful Request Response" operation is added and configured, you can make the binding. To provide the "Company Symbol" input parameter to the "Restful Request Response" operation, add an "OK Flow" connecting the "Input Port" and the operation. Double-click on the "OK Flow" and uncheck the "Enable Default Biding" property. 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 the single data to each item. Then bind the "Company Symbol" as value for the "symbol" query string parameter. Finally, press the "OK" button to confirm.
Now let's store the result by using the "Create" operation. Add a "Create" operation based on the "GetQuoteResponse" entity.
To complete the model, proper bindings must be set. Add an "OK Flow" that connects the "Restful Request Response" operation and the "Create" operation. Double-click on it, uncheck the "Enable Default Biding" property and then bind the "GetQuoteResponse/GetQuoteResult" as input for the "GetQuoteResult" attribute. Press the "OK" button.
Add another "OK Flow" that connects the "Create" operation and the "Success" OK port. Double-click on it, uncheck the "Enable Default Biding" property and bind the "oid" Attribute with the "Response Key". Then press the"OK" button. This will return, after the Web Service invocation, the Primary Key of the returned value.
Let's consider the case where the call to the Web Service fails. Add a "KO Flow" that connects the "Restful Request Response" operation and the "Failure" KO Port. Double-click on it, uncheck the "Enable Default Biding" property and set the "Error Message" of the "Restful Request Response" as input for the "Error Message". Press the "OK" button to confirm.
How to Use a Restful Request Response Operation without Provider
Let's suppose you want to call the REST Web Service with the "Restful Request Response" operation without the Web Service Provider. Remember that, to create the request and the response, it is need to know the structure of the service to call.
Let's start to add the "Restful Request Response" operation. Click on the "Service Components" section and select the "Restful Request Response" operation. Place it inside the work area and give a meaningful name for the operation, such as "Get Stock Quote". First of all, remove the automatically association with the Web Service Provider (if any exists). Click on the "Clear" button next to the "Web Service Provider" property. To invoke the Web Service without the Web Service Provider, you need to set the "Endpoint URL". In the Properties View of the operation, set "http://wrservices-webservicesdemo.eu.webratio.net/RESTServices/CRMWebServices/GetQuote" string in the "Endpoint URL" property.
Let’s create the Request Message by adding only one "Query String Parameter" because in this case we have a unique parameter "symbol". In the Outline View, right-click on the "Restful Request Response" node, choose the "Add" and the "Query String Parameter" option and give a name to it, such as "symbol". To define the type, press the "Edit" button next to the "XSD Type" property, select the "string" option and then press the "OK" button to confirm. Let’' now create the structure of the Response.
The Web Service returns a string. We need to add a Body Parameter with a Simple Fragment. In the Outline View, right-click on the "Restful Request Response" node, choose the "Add" and then "Response Body Parameter" option. Type a name for it, such as "GetQuoteResponse". Now, right-click on the "Response Body Parameter" node to add the Simple Fragment, choose the "Add" and then "Simple Fragment Parameter" option. Type a name for it, such as "GetQuoteResult". Now, we configure the Simple Fragment. In its Properties View, press the "Edit" button next to the "XSD Simple Type" property, select the "string" option and press the "OK" button.
Once the "Restful Request Response" operation is added and configured, you can make the binding. To provide the "Company Symbol" input parameter to the "Restful Request Response" operation, add an "OK Flow" connecting the "Input Port" and the operation. To bind the information, double-click on the "OK Flow", uncheck the "Enable Default Binding" property and then bind the "Company Symbol" as value for the "symbol" query string parameter. Press the "OK" button.
Now let's store the result by using the "Create" operation. Add a "Create" operation based on the "GetQuoteResponse" entity. Place it inside the work area to add it and give a name to the operation, such as "Save Stock Quote". Place it inside the work area to add it and give a name to the operation, such as "Save Stock Quote".
To complete the model, proper bindings must be set. Add an "OK Flow" that connects the "Restful Request Response" operation and the "Create" operation. To bind the result, double-click on the "OK Flow", uncheck the "Enable Default Binding" property and bind the "GetQuoteResponse - GetQuoteResponse/GetQuoteResult" as input for the "GetQuoteResult" attribute. Press the "OK" button to confirm.
Add another "OK Flow" that connects the "Create" operation and the "Success" OK port. To bind the information, double-click on the "OK Flow", uncheck the "Enable Default Binding" property and then bind the "oid" Attribute with the "Response Key" output parameter. Press the "OK" button to confirm.
This will return, after the Web Service invocation, the primary key of the returned value. Let’s consider the case where the call to the Web Service fails. Add a "KO Flow" that connects the "Restful Request Response" operation and the "Failure" KO port. To bind the information, double-click on the "KO Flow" and uncheck the "Enable Default Binding" property. In this case, we can use the "Guess Binding" button to bind the Error Message available as output of the Restful Request Response Operation. Press the "OK" button to confirm.
Test a REST 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 stock symbol for "Google Inc.", as the value. Press the "Submit" button to execute the Web Service.
After few seconds you should get the response formatted as a long string containing all the properties of the "Stock Quote".