1. The Design and Generation of WSDL in EA Sparx
(Composer: Frank Ning, Jan.13, 2016)
1.Introduction
2. Description of the sample requirement
3. Creating/Defining the Logical Domain Model
4. Define the Service Model - Logical Interface
5. Create Physical Domain Model
6. Define WSDL Message Structure
7. Create the Physical WSDL Interfaces/Definitions
7.1 Delete the <<XSDschema>>“Types” package and clean up the other sections.
7.3 Update the “PortTypes” package
7.4 Set up the Binding
7.5 Create the WSDL service
7.6 Enable the Usage of the WSDL Service in the <<WSDL>> document
7.7 Generate Related Physical XML Schema and WSDL Files
7.8 Update and Validate the Generated WSDL File
1.Introduction
This document describes, at very high level, an approach to design and generate WSDL in
Sparx for a new SOA project.
As shown in the figure below, the logical “Domain Model” and “Service Model” can be first
defined. The “Domain Model” defines the logical data structure of the related business
entities and the “Service Model” simply defines the logical interfaces with input and output
parameters. The physical domain model (called “StockTradeBusinessEntities” in this
document in the following diagram) and service model (called “WSDL Physical Interface” in
the following figure) are then built based on the logical models. WSDL definition sections
include one section defining data types/schemas, which is moved out of the Sparx generated
“WSDL Physical Interface” package to the “WSDL Message Structure” package shown in the
figure below.

2. 2. Description of the sample requirement
The requirements of the sample stock trade web services are to define the following two
service operations:
1) setLastTradePrice(lastTradePrice,tickerSymbol, administrator)
2) getPrice(tickerSymbol):price
The setLastTradeProce() takes three input parameters and has no output parameter.
lastTradePrice:string[1..1]
tickerSymbol:string[1..1]
administrator:Administrator[0..1]
The Administrator is a new data type containing firstName:string[1..1], lastName:string[1..1]
and middleName:string[0..1]
The getPrice() takes one input parameter tickerSymbol:string[1..1] and returns price:float.
Both operations in this example will be SOAP operations over http. Thus fault details are
required to be covered in the WSDL definitions.
3. Creating/Defining the Logical Domain Model
If no existing logical domain model can be used, a new one needs to be created based on
the analysis of the requirements.
Based on the requirements, the data architect defined the logical Domain Model “StockTrade
Business Entities” with two data types “Administrator” and “FaultDetail”, as shown in the
figure below. The “FaultDetail” can be at enterprise level but for this sample scenario, it is
defined for this specific stock trade requirement.
The domain model does not define those parameters which simply use the XSD string type.
The figure below shows the structure layout in Sparx’s project browser.

3. 4. Define the Service Model - Logical Interface
Based on the requirements and the logical domain model, the logical service model package
with the “StockTrade” interface is created as shown below.
The following diagram shows the logical interface with the two operations and the traces to
the data types defined in logical domain model used by the parameters of the operations.

4. In theory, Sparx provides an option to convert the logical interface to physical WSDL
package in Sparx. However, it has certain issues preventing us from using this feature and
thus manually creation of the physical WSDL packages are needed (see later sections)
5. Create Physical Domain Model
A package with the stereotype of “XSDschema” needs to be created, which is the physical
domain model corresponding to the logical domain model. XSDcomplexType are created
within the package corresponding to those logical data types defined in the logical domain
model packages. Sometimes enumeration data types need to be defined, which is omitted in
this document. In Sparx, there is no major difference between logical and physical
enumerations. The data architects are responsible to create/update both logical and physical
enumerations.

5. As shown in the diagram, “XSDelement” stereotype of elements are defined within the
related XSDcomplexType, which can be traced back to attributes inside logical data types.
The target namespace, its prefix, and the schema file path need to be defined properly as
shown in the figure below.
6. Define WSDL Message Structure
Based on the JSR-224 specification for Java implementation of web services defined in
WSDL, the WSDL model uses document style and literal encoding. There should be only
one message part for request message and one message part for response message. The
request message part name and its type should be the same as the operation’s name. The
response message part name should be “<OperationName>Response”.

6. In this example, the <<XSDschema>>“WSDL Message Structure” package is created as
shown below.
The following diagram shows the details of the WSDL message structure model which will
be used to define WSDL messages inside WSDL definitions.
Since a physical schema file will be created from the package, proper target namespace and
referred XML namespace(s) need to be properly defined, as shown in the following figure.

7. 7. Create the Physical WSDL Interfaces/Definitions
Up to this point, the physical domain and WSDL message structure models are created in
Sparx. It is the time to create the physical WSDL definitions.
A regular package needs to be created with a default class diagram like the “WSDL Physical
Interface” package shown below. A “WSDL namespace” type of element needs to be directly
created (by dragging it from toolbar) on the default diagram (“WSDL Physical Interface”
diagram in this example). This will automatically create the sample WSDLnamespace
package.

8. The default “Overview” diagram in the generated <<WSDLnamespace>> package (WSDL
definitions) clearly shows the sections inside the WSDL definitions and the “TODO” notes.
The generated WSDL definition package needs to be updated to the need of the
requirements.
7.1 Delete the <<XSDschema>>“Types” package and clean up
the other sections.
● Since the special WSDL message structure model will be used for the types needed
in WSDL definitions, the <<XSDschema>>“Types” package is deleted here.
● The generated sample elements inside individual WSDL section packages are
cleaned up. The default diagrams in each section package are kept, which will be
used to create new elements.
● The diagram name inside the “Services” package is renamed to a proper name.
● The <<WSDL>> document component is renamed to a proper name (in this
example, “StockTrade”.
The figure below shows the updated WSDLnamespace package “StockTrade”

9. 7.2 Update the WSDL Message Section (Package)
Using the “Messages” diagram and “WSDL” toolbar, WSDL messages can be defined for the
operations to be defined. The figure below shows the updated “Message” package for the
two operations needed in the StockTrade WSDL definition and for the fault message to be
used in those operations.
The “Message” diagram is shown below with details. The data types used by the message
parts are the complex types defined in the WSDL message structure schema package.

10. 7.3 Update the “PortTypes” package
The “PortTypes” package needs to be updated to have the required operations defined.
The figure below shows the generated “StockTrade” <<WSDLportType” with the aid of the
“PortType”diagram and the “WSDL” tools on the toolbar.
The figure below uses the getPrice() operation as an example to show how the portType
operation is defined with proper names and message types. Notice that the fault is also
defined for the operation.

11. 7.4 Set up the Binding
Dragging the “Binding” WSDL element to the “Binding” diagram inside the “Binding” package
creates the binding.

12. In this example, we use the “soap” protocol, http transport and the document style to define
the “StockTrade” binding.
The SOAP action needs to be defined for each operation binding as shown below. The
action is normally in the format of <taregetNamespace_of_WSDL>/<operationName>.

13. 7.5 Create the WSDL service
Using the “StockTradeService” diagram inside the “Services” package and the WSDL
toolbar, the WSDL service can be created by dragging the “Service” element in the WSDL
toolbar into the diagram and defining proper properties as shown in the figure below.
7.6 Enable the Usage of the WSDL Service in the <<WSDL>>
document
Before generating the physical WSDL file, the <<WSDL>> document has to be updated to
use the WSDL service. If the WSDL service is not seen under the <<WSDL>> document,
double click the WSDL document on the project browser and check the WSDL service on its
properties dialog as shown below.

14. The following diagram shows the update “Overview” diagram right under the
<<WSDLnamespace>> package.It shows the sections inside the WSDL definition package
and the tracing to the WSDL message structure and physical domain models.
7.7 Generate Related Physical XML Schema and WSDL Files

15. Refer to the WSDL release document about how to create physical XML schema and WSDL
files from Sparx. Details about them are omitted in this document
7.8 Update and Validate the Generated WSDL File
The generated WSDL file includes <wsdl:import> elements for the dependent XML schemas
and the blank <wsdl:type/> element. These need to be updated. On the other hand, the
<wsdl:part> uses the “type” attribute name which needs to be changed to “element”.
The following figure shows the updated WSDL contents with the changed parts marked in
“red” bars. Refer to the document “ “Release Management of the eHealth Canonical WSDL
and Related XSD” for the details about how to make the changes.
The above changes are needed to meet the WSDL profile compliance which can be
validated via Apache CXF.
The following figure visually shows the physical WSDL definition file by using the XML Spy.

16. The generated XML schema and WSDL files need to be validated by using Saxon, Apache
CXF and XML Spy before they can be released.