Page History

Table of Contents

There are various ways to write and structure WSDLs and XSDs. This page describes one way that works for Blueriq as a Service. Not all possible constructions will be covered in this section, but the ones described work best and will suffice for most projects using Blueriq as a Service.

WSDL

Each WSDL file starts with a header which that contains a set of definitions. Our header look like this:

Code Block

language	html/xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions 
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
  xmlns:tns="http://blueriq.com/schema/test/1.0/" 
  targetNamespace="http://blueriq.com/schema/test/1.0/" 
  xmlns:MyTypeDef="http://www.blueriq.com/baas/NameOfMyService/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">

The prefix tns is used as a prefix for our WSDL namespace, this namespace is the same as the namespace defined as targetNamespace. Your WSDL namespace should be a unique string, usually a webadressweb adress, but you are free to choose any unique string as a namespace.

The prefix MyTypeDef refers to the namespace used in your XSD file. Similar to the WSDL namespace this is usually a web address, this is not required though. Make sure this namespace matches the namespace in your XSD file.
The WSDL, SOAP and XSD namespaces should not be altered.

WSDL sections

Our WSDL (Web service description language) consists of five major sections:

Types - A container for data type definitions used by the web service
Message - A typed definition of the data being communicated
Porttype - A set of operations supported by one or more endpoints
Binding - A protocol and data format specification for a particular port type
Service - The service definition

...

The message section describes the input and output data for each service operation. Each message contains one or more parts. A part can be compared to the parameters of a function call in a traditional programming language. An example of an input and output message with one message part is given below.

Code Block

language	html/xml

<wsdl:message name="Input">
   <wsdl:part name="InputData" element="MyTypeDef:TeacherInfo"/>
</wsdl:message>
 
<wsdl:message name="Output">
  <wsdl:part name="OutputData" element="MyTypeDef:StudentInfo"/>
</wsdl:message>

All input and output messages that are used by your service operations are specified in a message section. Input and output messages can be used by multiple operations.

During import of the WSDL file in the Studio, singlevalued Request and Response entities are created. The name of the message part is used as name for the relation between these generated entities and the type specified in the message.
The element refers to an element in the XSD file. The input and output message part can refer to the same or two different elements. Because of WSI-BP 1.2 compliancy the messages must refer to an element in the XSD and not directly to a simple or complex type.

Info
The prefix MyTypeDef refers to the XSD namespace in this example.

Porttype

The portType element is the most important WSDL element. It describes a web service, the operations that can be performed, and the messages that are involved.

The portType element can be compared to a function library (or a module, or a class) in a traditional programming language.

Code Block

language	html/xml

<wsdl:portType name="PortType">
   <wsdl:operation name="DoSomething">
      <wsdl:input message="tns:Input" name="Input"/>      
      <wsdl:output message="tns:Output" name="Output"/>      
   </wsdl:operation>
</wsdl:portType>

The name of the portType is not really important for the Studio model. The name of the operation is used as prefix for the name of the generated request and response entities. In the example this would result in the entities DoSomethingRequest and DoSomethingResponse

The input and output messages refer to the messages defined in the 'message' section of the WSDL definition. Each operation can refer to exactly one input and one output message.

...

The binding element defines the data format and protocol for each port type. Since Blueriq only supports one binding with the binding style document and the use literal for each message the binding can be used in the WSDL as is. The operation part should be copied for each operation in the service and the operation name must be replaced. Each operation must have a unique soapAction. Best practise is to keep the soapAction and operation name identical.

Code Block

<wsdl:binding name="ServiceBinding" type="tns:PortType">
   <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
   <wsdl:operation name="DoSomething">
      <soap:operation soapAction="DoSomething"/>
      <wsdl:input name="Input"> <soap:body use="literal"/> </wsdl:input>
      <wsdl:output name="Output"> <soap:body use="literal"/> </wsdl:output>
   </wsdl:operation>
</wsdl:binding>

Service

Finally we define the service. The service name should match the web service object that you defined in the project's configuration module.

Code Block

<wsdl:service name="ServiceName">
   <wsdl:port binding="tns:ServiceBinding">
      <soap:address location="http://localhost:8080/Runtime/webservices/baas/studio-RepositoryName-BaasProjectName/BranchName/ServiceName/"/>
   </wsdl:port>
</wsdl:service>

The address location is generated for Blueriq as a Service. It consists of:

the runtime server address - http://localhost:8080/Runtime/
the default location for baas webservices - webservices/baas/
a name composed of the repository and project name. This name is proceeded by export or studio depending on whether the runtime uses an export or the studio database to run the service - studio-RepositoryName-BaasProjectName/
The branch name (only if the service is in the studio database) - BranchName/
and finally the service name as defined in the project's configuration module - ServiceName/

...

Code Block

language	html/xml

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions 
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
   xmlns:tns="http://blueriq.com/schema/test/1.0/" 
   targetNamespace="http://blueriq.com/schema/test/1.0/" 
   xmlns:MyTypeDef="http://blueriq.com/schema/test/types/1.0/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
   <wsdl:types>
      <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://blueriq.com/schema/test/types/1.0/">
         <include schemaLocation="XSDTemplate.xsd"/>
      </schema>
   </wsdl:types>
 
   <wsdl:message name="StudentInfoIn">
      <wsdl:part element="MyTypeDef:TeacherInfo" name="InputData"/>
   </wsdl:message>
 
   <wsdl:message name="StudentInfoOut">
      <wsdl:part element="MyTypeDef:StudentInfo" name="OutputData"/>
   </wsdl:message>
 
   <wsdl:portType name="StudentInfoPortType">
      <wsdl:operation name="GetStudentInfo">
         <wsdl:input message="tns:StudentInfoIn" name="StudentInfoIn"/>      
         <wsdl:output message="tns:StudentInfoOut" name="StudentInfoOut"/>      
      </wsdl:operation>
   </wsdl:portType>
 
   <wsdl:binding name="StudentInfoBinding" type="tns:StudentInfoPortType">
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"/>
      <wsdl:operation name="GetStudentInfo">
	<soap:operation soapAction="GetStudentInfoAction" style="document"/>
         <wsdl:input name="StudentInfoIn">
            <soap:body use="literal"/>
         </wsdl:input>
         <wsdl:output name="StudentInfoOut">
            <soap:body use="literal"/>
         </wsdl:output>
      </wsdl:operation>
   </wsdl:binding>
 
   <wsdl:service name="StudentInformation">
      <wsdl:port binding="tns:StudentInfoBinding">
         <soap:address location="http://localhost:8080/Runtime/webservices/baas/studio-WSDLscenarios-WSDLExample/Trunk/Service/"/>
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

XSD

Code Block

language	html/xml

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   elementFormDefault="qualified" 
   xmlns:MyTypeDef="http://blueriq.com/schema/test/types/1.0/" 
   targetNamespace="http://blueriq.com/schema/test/types/1.0/">
 
   <xsd:element name="TeacherInfo" type="MyTypeDef:Teacher"/>
   <xsd:element name="StudentInfo" type="MyTypeDef:Student"/>
 
   <xsd:complexType name="Person" abstract="true">
      <xsd:sequence>  
         <xsd:element name="Class" minOccurs="1" maxOccurs="unbounded" type= "MyTypeDef:TypeOfClass"/>  
      </xsd:sequence>
      <xsd:attribute name="Initials" type="xsd:string"/>
      <xsd:attribute name="Name" type="xsd:string"/>
      <xsd:attribute name="DateOfBirth" type="xsd:date"/>
   </xsd:complexType>
 
   <xsd:simpleType name="TypeOfClass">
      <xsd:restriction base="xsd:string"> 
         <xsd:enumeration value="Physics"/>
         <xsd:enumeration value="Mathmatics"/>
         <xsd:enumeration value="English"/>
      </xsd:restriction>
   </xsd:simpleType>
 
   <xsd:complexType name="Student">
      <xsd:complexContent>
         <xsd:extension base="MyTypeDef:Person">
            <xsd:sequence>
               <xsd:element ref="MyTypeDef:HasClassMates" minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
            <xsd:attribute name="StudentNumber" type="xsd:integer" use="required"/>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>
 
   <xsd:element name="HasClassMates" type="MyTypeDef:Student"/>
 
   <xsd:complexType name="Teacher">
      <xsd:complexContent>
         <xsd:extension base="MyTypeDef:Person">
            <xsd:sequence>
               <xsd:element name="TeachesStudents" type="MyTypeDef:Student" minOccurs="1" maxOccurs="unbounded"/>
            </xsd:sequence>
            <xsd:attribute name="SocialSecurityNumber" type="xsd:string" use="required"/>
            <xsd:attribute name="EmployeeNumber" type="xsd:integer" use="required"/>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>
</xsd:schema>

...

Previous Chapter: Chapter 7 - Modules and Data Mapping

...

Versions Compared

Old Version 7

New Version 8

Key

WSDL

WSDL sections

Porttype

Service

XSD