In order to understand the content of this lesson, make sure you watched the following lessons:
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 define your Web Services using WebRatio Platform.
In a previous lesson you already gained the basic knowledge about how to publish a Web Service.
This lesson gives you the basic knowledge to help you publish a SOAP Web Service. A separate lesson explains how you can publish a REST Web Service. This lesson does NOT cover how to invoke Web services.
SOAP and WSDL Overview
According to the W3C definition, "SOAP" is an XML based protocol defining the messages format to be used for communication with Web Services, using HTTP as a means for transport.
A "SOAP" message is an XML Document that consists of:
- The "Envelope": that is the root element defining the XML document as a SOAP message. It is mandatory.
- The "Header": that is an optional element containing header information.
- The "Body": that is a mandatory element containing the actual set of data passed during the Remote Procedure Call (RPC).
A SOAP Web Service is defined through a WSDL file. WSDL "Web Services Description Language" is an XML based language used for describing Web Services interfaces. A WSDL file is an XML Document containing a set of definitions. While a SOAP message is used to transmit data to the Web Service, the WSDL file describes the its interface, that is how to connect and make requests to it.
SOAP Web Service - The Model
In a previous lesson you learnt how to model the skeleton of a Web Service. Once you have a "Service View" and at least a "Port", you can start modeling your first Web Service. Let’s suppose you want to expose a Web Service that contains a method letting the service requestor to search for employees. The method receives the values provided as search criteria and gives back the list of employees matching the criteria.
This is how the IFML model of our web service method looks like.
As you can see, there is an entry point, which is the "Solicit" operation, and two exit points, one for success and the other one for error. Since we are creating a SOAP Web Service, the "Solicit" component uses the "POST" request method as default (is the only option available in this case). The "Content Type" property is disabled, since we know that the only one available for SOAP Web Services is XML format.
For the "Response" component, instead, we need to specify that the "Content Type" property is set to XML value. Let’s see in details how you can create the SOAP message.
SOAP Message Overview
"Solicit", "Response" and "Error Response" operations share the way in which the message is modeled on the operation itself.
As shown in a previous lesson, a SOAP message can be composed by different elements:
- "Body Parameter"
- "Simple Fragment"
- "Complex Fragment"
They are the parameters exposed by the Web Service and contain the corresponding value passed to the Web Service at runtime. They can be used standalone to obtain a simple structure. Otherwise they can contain a set of "Simple Fragment" and/or "Complex Fragment" defining the structure of the passed data.
For each "Body Parameter" you can set the "XSD Provider" and the "XSD Type". Moreover, you can specify a minimum and maximum cardinality for each one.
In this example, "Body Parameter" node represent the only body parameter in the SOAP message and it contains a "Simple Fragment" and a "Complex Fragment" .
They can be appended to a "Body Parameter" in order to declare a two-level structure of the message.
In this example, the "Body Parameter" contains a simple fragments: "SimpleFragment1". Each "Simple Fragment" carries the value to the corresponding method of the Web Service.
They can be appended to a "Body Parameter", in addition or in alternative to "Simple Fragments", in order to declare a multi level structure for the message. You can add "Simple Fragments" or use an XSD Definition to define the fragment structure.
In this example the "Complex Fragment" contain a Simple Fragment "SimpleFragment2". This is an example of XSD Definition: as you can see this structure define a new data type that we can associate to the "Complex Fragment" in the "Body Parameter". The sequence element specifies that the child elements must appear in a sequence. Each child element can occur from 0 to many times. You can set this range using the "Min Card." and "Max Card." properties.
How to Create a SOAP Web Service
Let’s suppose for a "CRM" web application you want to model a structured search for employees Web Service using the "First Name", the "Last Name" and the "Email" as search criteria. We have already created the "EmployeesWebServices" service view and the "SearchForEmployees" port with a "Solicit" component. In this case the "Solicit" component is already added because when you add for the first time a new "Port" in automatically is added a "Solicit". We have also the Domain Model containing the "Employee" entity.
We start by configuring the "Solicit" Service Component. Double-click on the Component and type a meaningful name for the "Solicit", such as "StructuredSearch".
Let’s create the Request Message. Right click on the "StructuredSearch" solicit operation and choose the "Add" and then the "Body Parameter" option. Give a meaningful name to the "Body Parameter", such as "searchCriteria". Let's now add all the possible criteria. Right click on the "searchCriteria" body parameter from the Outline View, choose the "Add", then the "SimpleFragment" option and give it a name such as "firstname". Move to the Properties View; press the "Edit" button next the "XSD Simple Type" property and choose the "string" type. Then press the "OK" button.
This procedure must be repeated for the other two criteria that we want to add: "Last Name" and "Email".
To retrieve the employee matching the search criteria, let’s use a "Selector" component based on the "Employee" entity.
Let’s suppose that the employees matching the search are those that match the provided "First Name" or "Last Name" or "Email". To model this requirement, we need to add to the "Selector" component a "Conditional Expression" composed of three different "Attribute Conditions", one for each attribute we want to check. At last, set the "Required" property as "False", in this way when no value is found for the condition, the condition is simply ignored.
This procedure must be repeated for the other two attributes that we have chosen to filter: "Last Name" and "Email".
Since we want an employee to be contained in the results if the input values have references at least in one of the Attributes, we have to change the operator combining the conditions, which is the "AND" operator by default. Move to the Outline View and select the "Conditional Expression". Then move to the Properties View and change the "Boolean Operator" property to "Or".
In order to provide the search criteria to the "Selector" component let's use a "OK Flow" connecting the "Solicit" operation and the "Selector" component. Double-click to make the binding, then bind each "Simple Fragment" of "searchCriteria" body parameter with the "First Name", "Last Name" and "Email" attribute conditions to which they refer and press the "OK" button.
Once the results are retrieved, we need to configure the Response Message. The SOAP Web Service must send back an XML, so we need an "XML I/O" Component to create an XML Document containing all the returned results. The "XML I/O" Component works with entities mapped on XSD, so we need to associate the "Employee" Entity in the Domain Model of the project with the XSD.
To see how to add an "XSD Provider" you can refer to the "Invoking SOAP Web Service" online lesson.
To associate the XSD to the entity, move to the Domain Model tab. Select the "Employee" entity in the work area and move to the Properties View. Let's now associate with the "XSD Provider", select the "XSD" tab and press the "Select" button next to the "XSD Provider" property and select the "XSD Provider" of your choice. Then press "OK" to confirm. Now, associate the "XSD Type" of the "XSD Provider" as soon as chosen. Press the "Edit" button next the "XSD Type" and choose the "employee" type. Then press the "OK" button to confirm your choice. In this way, the "Employee" Entity is associated to the structure of the XSD.
Now, you can connect the attributes to the XSD, select the "oid" attribute in the "Employee" entity and move to his Properties View. In the "XSD" tab, for the "XSD Element" property choose the corresponding XSD element to the Attribute, in this case "employeeId". This procedure must be repeated for the other Attributes of the Entity.
Now, go back to "EmployeesWebServices" service view. Select the "XML I/O" service component from the toolbar section related to "Service Components" place it in the "SearchForEmployees" Port and give a name to it, such as "Export Results". Let's now define the "Data Binding" connection. Select the "XML I/O" service component and move to the "Properties View". Set the "Mode" property to "Export"; in this way the operation creates an XML Document using the retrieved information. Press the "Select" button next to the "Entity" property and in the opening dialog select the "Employee" entity. Press on the "OK" button to confirm your choice. As you can see, when you add the "XML I/O" component is automatically added a "Key Condition".
Let's now add the "Parameter Binding" to pass the Employee Primary Key to the "Condition". Let's now add an "OK Flow" connecting the "Selector" Component and the "XML I/O" Component. Double-click on the "OK Flow". As you can see, when you add the "XML I/O" Component is automatically added a "Key Condition" and, since the two components are based on the same Entity, WebRatio Platform automatically infers this "Binding".
Let's now create the Web Service Response. Select the "Response" item from the "Service Components" section of the toolbar and click inside the "Port". Type a name for it, for example "StructuredSearchResponse" (with no spaces in it).
Let's now configure the Response Message. Right click on the "StructuredSearchResponse" response and select the "Add" and then the "Body Parameter" option. Give a meaningful name to the "Body Parameter", such as "employeesList". Since we are going to pass to the "Response" operation an entire XML Document, let's add to the "Body Parameter" a "Complex Fragment" element. Right click on the "employeesList" body parameter from the Outline View, choose the "Add", then the "ComplexFragment" option and type a name for it, such as "employee". Move to the Properties View; press the "Select" button next the "XSD Provider" property and choose your "XSD Provider" that you have in the project. Now choose the "XSD Type" to which it refers the "Complex Fragment". Press the "Edit" button next the "XSD Type/Element" property and choose the "employee" type. Finally, let's change the cardinality of the result. Set the "Min Card." as "0" because you might not get results, then set the "Max Card." as "-1" because you may have more than one result. Indeed if you set the value “-1” for this property, this fragment will have unbounded max cardinality.
In order to provide to the "Response" operation the XML Document created by the "XML I/O" operation let's use a "OK Flow" connecting the "XML I/O" component and the "Response" component. Double-click on the "OK Flow" and bind the "Employee XML Documents(s)" with the "employeesList/employee[array]".
Now let's consider the case in which the Web Service call fails for some reason. Select the "Error Response" item from the "Service Components" section of the toolbar and click inside the Port. Type a name for it, such as "StructuredSearch Error Response".
Before adding the "KO Flow" to handle the failure case, let’s enclose all the operation chain in an "Operation Group". Now, add a "KO Flow" that connects the "Operation Group" and the "Error Response". Double-click on it to open the "Parameters Binding" dialog. Write an error message as input for the "Fault Message" and press the "OK" button to confirm.
Testing SOAP Web Service
How to Test the Web Service
Now, we need a way to be able to test if the Web Service is working or not. WebRatio Platform considers Web Services as Web applications. It’s enough to generate the Web Project in order to publish the Web Services. For SOAP Web Services, you have to access the WSDL Definition automatically created by WebRatio to check whether the web service is running.
Now let's publish the Web Service clicking on the "Generate and Run" button.
As soon as the browser opens, write in the address the URL to the Port of the Web Service we just created, and to see the WSDL generated. In this case this is the "http://localhost:8080/CRM/EmployeesWebServices/SearchForEmployees/wsdl.do". Now you can see the WSDL of the "SearchForEmployees" Web Service. In this case, in the project there is only one Web Service Method in the "SearchForEmployees" Port.
How to Use SOAP UI
In order to test if the Web Service works properly or not, you can use an additional software. For our example we are going to use "SOAP UI". Launch "SOAP UI", and create a new project that points to the WSDL of our Web Service.
Right click on the "Projects" node in the left menu and choose the"New SOAP Project" option. In the open dialog, give a meaningful name for the "Project Name", such as "CRM". In the "Initial WSDL" field insert the URL of the Port of the Web Service "http://localhost:8080/CRM/EmployeesWebServices/SearchForEmployees/wsdl.do". Then press the "OK" button to confirm.
When the WSDL is downloaded, let's test the Web Service. Expand the "StructuredSearch" node in the left menu and double click on the "Request 1" node.
Now the request dialog to the Web Service is opened. This dialog is divided in two part. On the left part there is the structure of request where you insert can insert the value you prefer and in the right part you can see the web service response.
Insert a value for the one optional parameter, for example "John" in the "firstname" parameter. Remember that if you insert a value for only one parameter the other must be deleted in the request. Now, run the request to the Web Service with use the "Submit request to specific endpoint URL" green arrow, to return the result search.