Appendix 1 - Writing your own WSDL

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

<?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 web 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.

Our WSDL 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 types section describes the data model used by the web service. This data model description is used by Blueriq to generate the domain model.

We will describe the datamodel using a separate XSD, therefore our WSDL will only contain a reference to this XSD file.

<wsdl:types> <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.blueriq.com/baas/NameOfMyService/"> <include schemaLocation="NameOfYourXSDschemaFile.xsd"/> </schema> </wsdl:types>

The targetNamespace is the namespace used to refer to elements in your XSD. It's a unique prefix for the elements in your datamodel and is usually a web address, this is not required though. The namespace must be a unique string. 
The schemaLocation is the name of your XSD file. We will place the WSDL and XSD files in a single ZIP file, both in the root directory. The schemaLocation is used by Encore to locate the XSD schema during import. The runtime wil generate it's own schema location when the Blueriq as a Service application is activated.

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.

<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 Encore, 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.

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.

<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 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.

<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>

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

<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/

For Blueriq as a Service we first develop our WSDL and XSD file and generate the domain model based on the XSD file rather than creating the model in Encore. If the domain model is generated properly we know that the XSD file is valid.

In this section we will describe the various Blueriq domain model structures and how to model them in the XSD file.

Elements that can be generated using the XSD file are:

• Entity
• Relation
• Attribute
• Inheritance relation

When we want the WSDL/XSD import to create an entity in our domain model, we have to define an element of a complex type in our XSD file, as shown in the example code below.

<xsd:complexType name="Teacher"/>

This will create the entity Teacher in our domain model. All entities will be non-singleton entities after import. The reason for this is that based on the XSD file, there is no way of knowing if an entity can have only one or multiple instances. Therefore all entities are generated as non-singleton entities. If you want to you can change entities into singleton entities.

Usually we will have multiple related entities in our domain model. To add a relation to our domain model we need to add a second complex type and a reference from one entity to the other entity. Don't worry about reverse relations, they are generated automatically during the import.

<xsd:complexType name="Teacher">
   <xsd:sequence>
      <xsd:element name="TeachesStudents" type="MyTypeDef:Student" minOccurs="1" maxOccurs="unbounded"/>
   </xsd:sequence>
</xsd:complexType>
 
<xsd:complexType name="Student"/>

In the example a second entity Student is added and a multivalue relation named TeachesStudents between Teacher and Student is created.

Relations are placed in a special sequence section in the complexType which defines the entity. A relation is created for each element in the sequence that refers to another entity.

Options minOccurs and maxOccurs can be specified with these type of relation definitions, making the relation single or multivalued. For single value relations the minOccurs and maxOccurs options can be omitted because the default is minOccurs=1 and maxOccurs=1.

Now that we specified two related entities we are going to add some attributes to the entities. Suppose we want to add attributes to the Teacher entity. We can do that by simply adding attributes to the complex type definition. Each attribute has a name and type. The primitive types like string, integer, date etc. are specified in the W3C XML schema and therefore get the xsd namespace as a prefix.

<xsd:complexType name="Teacher">
   <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:complexType>

These type of attribute definitions will result in single value attributes in the domain model. We specified a use option with the value required. Adding this option has no impact on the generated model, but a business engineer can now see that these attributes are required and he should add validation rules to the operation's input message. This way the service will send an error message when the attributes are omitted from the request.

If we would want to add multivalue attributes we would specify them as an element in the sequence part of the complexType definition. We use elements for multivalue attributes because an element has the minOccurs and maxOccurs options.