Docstoc

B2B Web Service Guidelines V1

Document Sample
B2B Web Service Guidelines V1 Powered By Docstoc
					    B2B Web Service Guidelines V1
    RSVZ Enterprise Architecture




Owner                              Dirk Vaneynde / Gert Driesen
Version                            6
Last changed on                    12/11/2011 01:00

Niets uit deze uitgave mag worden verveelvoudigd, openbaar gemaakt, overgeschreven, opgeslagen in een automatisch gegevensbestand, of vertaald
in enige menselijke of computertaal, in enige vorm of op enige wijze, hetzij elektronisch, mechanisch, magnetisch, optisch, chemisch, met de hand of
op enige andere wijze, zonder uitdrukkelijke schriftelijke toestemming van Cegeka N.V.
Cegeka N.V. behoudt zich het recht voor om de informatie in dit document te wijzigen of te herzien zonder voorafgaande kennisgeving.
                                                  Cegeka N.V. 2007-2011
B2B Web Service Guidelines V1                                             RSVZ Enterprise Architecture



History
Date          Description                                              Author
22/3/2007     Translation to English                                   Dirk Vaneynde
8/6/2007      Changes after TW2                                        Dirk Vaneynde
12/6/2007     Http as only transport, pseudo one-way, error            Dirk Vaneynde
              handling.
21/9/2007     Major version now in filename. New directorystructure.   Dirk Vaneynde
              Described soapaction.
              Details on ApplHeader
23/10/2007    Changed error handling.                                  Dirk Vaneynde
              Included Configuration Mgmt in this document.
9/11/2007     Changed schema name and structure.                       Dirk Vaneynde
              Added Helper_V1.wsdl
22/11/2007     Operation naming convention (4.3.1)                    Dirk Vaneynde
               ApplHeader: Codes for Origin and Destination,
                   TimestampSent field, FluxID
               Rationale on ApplHeader in Body was not clearly
                   explained
               TransferOk has timestamp
               Error handling – rewritten for clarity (4.3.5)
               Path structure of wsdl‟s and schemas has slightly
                   changed (4.4.3)
               Multiple Releases – rewritten for clarity (4.4.5)
               Message Security (4.4.8)
               Audit Logging (4.4.9).
11/2/2008      Soap faultstring & faultactor specified                Dirk Vaneynde
               Removed FluxID copying in 4.3.3 (bug)
               Removed §5.2 (WSDL for Bulk Operations)
12/02/2008    Updated guideline wrt SOAPAction.                        Gert Driesen
4/6/2008      Update of ApplHeader and Baselines.                      Dirk Vaneynde
              Fix {Meta}Error.DetailX001




Cegeka N.V.                                                                              page 2 of 60
B2B Web Service Guidelines V1                                                                                  RSVZ Enterprise Architecture



Table of Contents
1.         INTRODUCTION ............................................................................................................... 4
2.         CONTEXT .......................................................................................................................... 5
3.         GLOSSARY ........................................................................................................................ 7
4.         GUIDELINES ..................................................................................................................... 9
     4.1      GENERAL ................................................................................................................................ 9
       4.1.1        Standards ...................................................................................................................... 9
     4.2      SCHEMA NAMESPACES .............................................................................................................. 10
       4.2.1        Always use a Target Namespace in schemas .................................................................. 10
       4.2.2        elementFormDefault & attributeFormDefault .................................................................. 11
       4.2.3        Default namespace and qualifiers .................................................................................. 12
       4.2.4        Prefixes ....................................................................................................................... 13
       4.2.5        Reuse & Encapsulation: Local vs. Global Elements, Elements vs. Types ........................... 14
       4.2.6        Schema element & type name conventions .................................................................... 16
       4.2.7        Substitution groups ...................................................................................................... 17
       4.2.8        Use of <xs:redefine> ................................................................................................... 18
       4.2.9        Documentation & Comments ......................................................................................... 19
     4.3      WEB SERVICES ...................................................................................................................... 20
       4.3.1        Operation Names ......................................................................................................... 20
       4.3.2        Web Service versus Document approach ........................................................................ 22
       4.3.3        ApplHeader for Generic Message Information ................................................................. 24
       4.3.4        Pseudo One-Way over HTTP - Idempotent Operations .................................................... 28
       4.3.5        Error Handling and the {MetaInfo} Error element ........................................................... 31
       4.3.6        Error Handling of System Errors .................................................................................... 34
       4.3.7        SOAPAction .................................................................................................................. 37
     4.4      CONFIGURATON MANAGEMENT & RELEASE MANAGEMENT.................................................................. 38
       4.4.1        Namespaces & schema file. ........................................................................................... 38
       4.4.2        Versions....................................................................................................................... 39
       4.4.3        Schema and WSDL file names and path structure ........................................................... 41
       4.4.4        Releases & Impact Analysis ........................................................................................... 43
       4.4.5        Serve Multiple Releases of a Web Service in Parallel ....................................................... 46
       4.4.6        Pre-Production & Production Environment ...................................................................... 48
       4.4.7        About Downloading Schema & WSDL Files ..................................................................... 49
       4.4.8        Message Security ......................................................................................................... 50
       4.4.9        Audit Logging ............................................................................................................... 51
5.         WSDL TEMPLATES .......................................................................................................... 53
     5.1      WSDL FOR NON-BULK OPERATIONS ........................................................................................... 53
       5.1.1        Introduction ................................................................................................................. 53
       5.1.2        WSDL Template - SERVICE.wsdl.................................................................................... 53
       5.1.3        Nisse WSDL template – NisseSERVICE.wsdl ................................................................... 54
       5.1.4        Sif WSDL Template – SifSERVICE.wsdl........................................................................... 55
       5.1.5        Helper WSDL ............................................................................................................... 56
       5.1.6        MetaInfo.xsd ................................................................................................................ 56
     5.2      WSDL FOR BULK OPERATIONS – MAILBOX ................................................................................... 57
6.         REFERENCES .................................................................................................................. 58
7.         APPENDIX 1 – CONFIGURATION MGMT CONCEPTS ...................................................... 59
     7.1      WEB SERVICES AS INTERFACES .................................................................................................. 59
     7.2      CONFIGURATION ITEMS & VERSIONS ........................................................................................... 59
     7.3      FROM CHANGE REQUESTS (CR) TO RELEASES ................................................................................ 60




Cegeka N.V.                                                                                                                           page 3 of 60
B2B Web Service Guidelines V1                                               RSVZ Enterprise Architecture



1. Introduction
RSVZ-INASTI strives for standardising automated message exchange, especially towards Social Insurance
Funds (SIF), using standard Web Services. Also KSZ, KBO (primary network) and FedICT evolve towards
and support these standards.

This document describes general guidelines on Web Service and the use of XML Schema therein. We
intend to maximally re-use the existing XML message schemas in the future web services. Therefore
guidelines on XML and XML schema are also described herein.

The next chapter gives context information on the guidelines. Specifically the role of XML Schema and
WSDL – Web Service Description Language – is explained.

Chapter 3 describes the terminologie used in this document.

In chapter 4 the guidelines are listed one by one, including explanation and example.

Chapter 5 lists the base templates for the WSDL‟s, and hence the Web Services.

Finally chapter 6 contains references to other useful documents.


An additional Appendix chapter gives background information on general configuration management
concepts, used here for version control and release management.




Cegeka N.V.                                                                                 page 4 of 60
B2B Web Service Guidelines V1                                                                RSVZ Enterprise Architecture



2. Context
Web Services is a standardized exchange of XML messages between two parties, for example between
RSVZ-INASTI and a SIF. This standard has two parts, one being the XML message structure 1 and the
other being the transport protocol such as HTTP, SMTP etc. A Web Service thus imposes rules on the
message itself and how it is transported.

The rules on a specific Web Servic are described in a separate WSDL file, which is also an XML file
describing the message structure and transfer protocol. A WSDL file has two functions:
     A “contract” between RSVZ-INAST and the SIF‟s on what functionality must be available on each
        side, and how it can be invoked using an XML message exchange. Consequently, if a SIF
        provides software based on this contract it is guaranteed to use the functionalities described in
        the contract.
     A WSDL can (and should) be used by today‟s standard tools for code generation. All code to
        create or interpret the XML messages and code to set up the communication can be generated
        this way. This greatly improves development productivity and maximally avoids errors.

Today when one speaks of „standard Web Services‟ the use of this WSDL and code generation is typically
implied. The figure below shows a typical scenario, starting by a new or changed web service „contract‟
up to putting the new or changed web service into production.



                                                 1. Download WSDL




    3. If needed,
    write/adjust
    application code
                                     2. Generate code
                                     voor web service
                                     exchange                                RSVZ-INASTI

                                      SIF

                                                                       5... Web service
                                                                       exchange conforming to
                                                                       WSDL
         4. Install code on server



       1. A WSDL file is published on a RSVZ-INASTI web site and is downloaded by a SIF and imported in
          a standard software tool (Visual Studio .NET, Java Eclipse…). Functional personnel can see what
          functionality is available, and technical personnnel can see how to use and integrate this
          functionality in their application programs.
       2. The software tool generates all code that transforms XML web service messages to program data
          and vice versa, including code to set up a connection with RSVZ-INASTI.
          Specifically, for each Web Service functionality („operation‟) a corresponding programming
          language operation (or method) is generated. Then, for each data exchanged in the form of an
          XML message for that web service functionality, a corresponding programming language data
          structure is defined, and used as input or output parameter of the generated code operation.




1
 The message structure of Web Services is defined by the SOAP protocol. The term Web Service is really an umbrella term,
covering lots of standards, of which SOAP is the base standard.

Cegeka N.V.                                                                                                     page 5 of 60
B2B Web Service Guidelines V1                                                  RSVZ Enterprise Architecture


    3. A technical person then integrates the generated code with the SIF‟s own application code. Two
       possibilities:
            a. If RSVZ-INASTI offers (and implements) the functionality (service) then the SIF just has
                to generate so-called „stub-code‟ used for calling the RSVZ-INASTI server implementing
                the functionality.
                For example, for asking RSVZ-INASTI to register a new self-employed worker.
            b. If the SIF has to implement the service it has to generate a so-called „server-skeleton‟
                and install it on its own server, so it can be called by RSVZ-INAST.
                For example, RSVZ-INASTI informing the SIF that registration has succeeded.
    4. The generated code, together with the SIF‟s application code, is installed on the SIF‟s server
       infrastructure.
    5. The SIF and RSVZ-INAST exchange web services conforming to the WSDL standard.

Without WSDL or soap web services, as is the case for the current electronic exchanges (fazes 1a, 1b and
2a), codegeneration is possible from the schemas, but with some important restrictions:
    - Schema is intended for describing possible documents; it is not centered around functionality or
        operations as WSDL is. With WSDL functionality comes first, with Schema alone you need to add
        additional written documentation on what to do with the documents transferred.
    - Code can be generated from Schema files, but the code to set up a communication over HTTP,
        JMS or other protocols, must be written by hand, as well as dispatching to the proper functional
        implementation. With WSDL all of the code is generated.

Web Services still are in constant evolution, in that new or improved features are added. Since all major
vendors provide these added features through their development tools and infrastructure software it is
very easy to adapt these new features once needed and mature.

For example, extensions such as „reliable transport‟, security, transactions, load-balancing, processes etc.
are already available, or are in the proces of being standardized. Existing WSDL‟s and Web Services can
be extended with these features almost transparantly to the application code; often it is just a matter of
configuration.

As noted before, WSDL documents describe possible soap (or web service) message exchanges, just like
XML Schema describes possible XML documents. In a way it is fair to say that WSDL builds further upon
XML Schema, adding notions as operations, operation parameters, interfaces grouping operations, and
URL‟s where these interface operations can be invoked.
                                             WSDL


                                                 (Wsdl) Schema




                                                       import




                                             (Document) Schema




So when a Fund imports and uses a WSDL, it also has to import the related Schemas. In our approach
we try to re-use maximally the existing XML Schema‟s. In the end XML Schema will describe 80% of the
message exchanges, leaving 20% for the WSDL‟s.




Cegeka N.V.                                                                                    page 6 of 60
B2B Web Service Guidelines V1                                               RSVZ Enterprise Architecture



3. Glossary

Document Literal       Convention on web services.
Wrapped                See http://www-128.ibm.com/developerworks/webservices/library/ws-
DLW                    whichwsdl/.
Message Type           Classification of a pre-webservice XML message. Technically a Message Type
MT                     corresponds to an XSD schema file.
                       Examples: B003, A020 described by B003LegalInfo.xsd and
                       A020Disablement.xsd respectively.

Soap                   Base protocol of web services. Soap defines the structure of the XML messages
                       and how they are exchanged.
                       See http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/#session.

Web Service            Interaction and data exchange between two parties, based on soap and
                       optionally other protocols such as WSDL, WS-Security and the like.
                       Often narrowed down to soap over http.
                       See also http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/#webservice.

WSDL                   WSDL = Web Service Description Language
WSDL file              XML file dat describes actual Web Service operations and message exchanges,
                       as well as the protocols used and the actuall addres of the service or
                       „endpoint‟.
                       See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#WSDL;

XML meta-data          XML data that describes the actual message data.
XML meta-informatie    The ApplHeader element can be seen as such meta-data.

Request-Response       The caller waits until it receives a response – it does not do anything else
Operation              meanwhile. This is very similar to a function call in most programming
                       languages.
                                            1 request

                           caller                               callee

                                          2 response

                                                             Web Service
                                                               Server




One-Way Operation      A caller sends a message to a callee, and does not wait for an answer.

                                            message

                           caller                               callee




                                                             Web Service
                                                               Server




                       The example below shows a typical case, where two one-way operations are
                       used, one to ask for the latest inocme data, and the other in the reverse




Cegeka N.V.                                                                                  page 7 of 60
B2B Web Service Guidelines V1                                              RSVZ Enterprise Architecture


                                                               1.sendIncomeUpdate()

                                                   caller                                   callee

                                                  callee                                    caller

                                                               2.processIncomeUpdate
                       direction for the result.
                       Both sendIncomeUpdate() and processIncomeUpdate() are two separate one-
                       way operations. Once the calling party has called sendIncomeUpdate() it can
                       continue doing other stuff – it does not wait for some reply.
                       Later –seconds, hours or weeks – roles reverse and the original callee now
                       calls processIncomeUpdate() on the original caller.
Pseudo One-Way         See Pseudo One-Way over HTTP - Idempotent Operations on page 28.
Operation
Business Errors        A Business Error is an error interpreted by the user (human or machine). The
System Errors          user may have the ablity to resolve this, e.g. by changing input data.

                       A System Error is interpreted by system operators and/or developers, and they
                       take action to resolve it. A user is typically also informed in a general way,
                       saying that „a general system error occurred – please contact your system
                       administrator at phone...”.

Flux                   A Message Flux is a set of messages that is used together, in the sense that
Message Flux           they are related to the same function.
                       Where each message is identified individually by a unique number (in
                       ApplHader.MessageID) a message may also belong to a flux instance. In the
                       latter case each message of the flux has an additional unique id identifying
                       that flux.




Cegeka N.V.                                                                               page 8 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture



4. Guidelines
Note: the terms MUST, SHOULD, MAY when they appear in all-capitals must be understood as in
http://www.faqs.org/rfcs/rfc2119.html.


4.1 General


4.1.1 Standards
Guideline
Following standards MUST be used:
     1. XML 1.0 - http://www.w3.org/TR/2000/REC-xml-20001006
     2. UTF-8 encoding
     3. Namespaces in XML 1.0 - http://www.w3.org/TR/2006/REC-xml-names-20060816/
     4. XML Schema 1.0 - http://www.w3.org/2001/XMLSchema
     5. SOAP 1.1 - http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
     6. WSDL 1.1 - http://www.w3.org/TR/wsdl

In addition to this, the following conventions must be used:
    1. WS-I on platform interoperability
         http://www.ws-i.org/deliverables/workinggroup.aspx?wg=basicprofile
    2. Document Literal Wrapped (DLW) convention
Explanation
These are the standards and conventions that are mature today, and supported by all common
commercial tools today.

UTF-8 is „backward compatible‟ with ASCII, using one byte for western character sets. Therefore it is
most suited for our applications.

Both WS-I and DLW help us to achieve maximum platform interoperability, that is interoperability
between BEA, IBM, Oracle, Sun, open source and Microsoft implementations.
Example
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" ...>




Cegeka N.V.                                                                                  page 9 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture




4.2 Schema Namespaces
Here we describe guidelines specific to the schema‟s, this is the .XSD files as well as the schema
definition part in the .WSDL files.


4.2.1 Always use a Target Namespace in schemas
Guideline
All schemas MUST define a targetnamespace.

This namespace must start with http://www.rsvz-inasti.fgov.be/schemas/WS for WSDL schemas,
and with http://www.rsvz-inasti.fgov.be/schemas/WS/schema for ordinary schemas (XSD files).
Explanation
Namespaces define a scope for the name of elements, types and attributes, such that two elements can
have the same name as long as they belong to different namesapces. This is so because the real name of
an element, type or attribute is the name of the element, type or attribute prefixed with the namespace
name.

By having http://www.rsvz-inasti.fgov.be/schemas/WS as the first part of the namespace name we
ensure that our namespace names will be unique worldwide.
Example
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
  targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/LegalInfo/V1"




Cegeka N.V.                                                                                  page 10 of 60
B2B Web Service Guidelines V1                                                  RSVZ Enterprise Architecture




4.2.2 elementFormDefault & attributeFormDefault
Guideline
When defining a schema you MUST specify the following in the <schema> element:
   - elementFormDefault=”qualified”
   - attributeFormDefault=”unqualified”.
Explanation
elementFormDefault=”qualified” ensures that local (or anonymous) element definitions must be
namespace-prefixed in instance documents. This improves human readability, as well as performance of
xml parsers.

An schema fragment:
  <xsd:element name="Couple">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Husband" type="Husband"/>
        <xsd:element name="Wife" type="Wife"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

If we specified elementFormDefault=”unqualified” an instance document would look like this:
<?xml version="1.0" encoding="utf-8"?>
<ex:Couple xmlns:ex=" http://www.darin.com/example/v1">
  <Husband>Darin</Husband>
  <Wife>Darby</Wife>
</ex:Couple>

Applying our guideline the same instance document is as follows:
<?xml version="1.0" encoding="utf-8"?>
<ex:Couple xmlns:ex=" http://www.darin.com/example/v1">
  <ex:Husband>Darin</ex:Husband>
  <ex:Wife>Darby</ex:Wife>
</ex:Couple>

Readability is even more important when multiple namespaces are involved, as will be the case for
reasons of version management.

For attributes the opposite approach is taken, since intuitively attributes belong to their element and thus
implicitely have the same namespace. A prefix is thus unnecessary.
Example
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/LegalInfo/V1"
   elementFormDefault="qualified" attributeFormDefault="unqualified"
   xmlns="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/LegalInfo/V1">




Cegeka N.V.                                                                                   page 11 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.2.3 Default namespace and qualifiers
Guideline
If in a schema definition a default namespace is used it MUST be that of the target namespace.
Explanation
This guideline is for human readability. Element or type definitions (via name attribute) have no prefixes
– they are defined in the namespace mentioned as target namespace. If these elements or types are
referred to elsewhere in the same schema definition (via type or ref attribute) then it makes sense not to
use a prefix either. To achieve this the default namespace must be the same as the target namespace.
Example
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/Affiliation/V1"
   elementFormDefault="qualified" attributeFormDefault="unqualified"
   xmlns="http://www.rsvz-inasti.fgov.be/schemas/WS/Affiliation/V1">
   <xs:simpleType name="BirthDateType">
   ...
   </xs:simpleType>
   ...
   <xs:element name="BirthDate" type="BirthDateType">




Cegeka N.V.                                                                                 page 12 of 60
B2B Web Service Guidelines V1                                               RSVZ Enterprise Architecture




4.2.4 Prefixes
Guideline
You SHOULD use these prefixes for the listed namespaces:
xs     W3C schema namespace
soap   SOAP namespace
wsdl   WSDL namespace
tns    target namespace
Explanation
Standardising prefixes improves human readiblity, and developer productivity.




Cegeka N.V.                                                                               page 13 of 60
B2B Web Service Guidelines V1                                                    RSVZ Enterprise Architecture




4.2.5 Reuse & Encapsulation: Local vs. Global Elements, Elements vs. Types
Guideline
Local elements SHOULD be preferred over global elements.

For reuse, types SHOULD be preferred over global elements.
Explanation
Re-use via types is more flexible than re-use via global elements. One advantage of types is that you can
have multiple elements re-using the same type but with a different name. Extension of types is also an
advantage.

Some techniques are not possible with types, only with global elements. Still, you can define a type, have
a global element of this type, and have all possibilities. Further, some of these techniques are forbidden
elsewhere in this document, e.g. substitution groups.

Encapsulation is about hiding complexity. Someone that takes a look to a schema for the first time only
considers the global elements at first: they are the ones that can be used to start some XML documents.
Local elements are only considered next, in the scope of a global element. If many global elements exist
then lots of elements must be studied; if only a few, a minimum, exists it is much easier to see which
ones to use.
The separation global/local can be seen as a sort of drill-down: first select the interesting one, then drill
down to its internals.
Example
Below we first have a type definition, RelationshipType. This is then used to define a local element
Relation in AcceptAffiliationType. Finally a global element AcceptAffiliation is created of that latter type.

   <xs:complexType name="RelationshipType">
      <xs:sequence>
         <xs:element name="Century" type="CenturyType" minOccurs="0">
            …
   </xs:complexType>

Then RelationshipType is reused to define an element named Relationship, in yet another type

   <xs:complexType name="AcceptAffiliationType">
      <xs:complexContent>...
         <xs:element name="Relationship" type="tns:RelationshipType" minOccurs="0" />
      </xs:complexContent>
   </xs:complexType>

   <xs:element name="AcceptAffiliation" type="tns:AcceptAffiliationType" />




Another example on the schema extension mechanism:

   <xs:complexType name="AbstractResultType" abstract="true" />

   <xs:complexType name="NoMatchType">
      <xs:complexContent>
         <xs:extension base="AbstractResultType">
            <xs:sequence>
               <xs:element name="Code">
   ...
   </xs:complexType>

   <xs:complexType name="MatchesType">
      <xs:complexContent>
         <xs:extension base="AbstractResultType">

Cegeka N.V.                                                                                      page 14 of 60
B2B Web Service Guidelines V1                                            RSVZ Enterprise Architecture


   ...
   </xs:complexType>




Het element Result is dan een AbstractResultType:
   <xs:element name="Result" type="AbstractResultType"/>

Een XML document moet het xsi:type attribuut gebruiken om het echte type aan te duiden:
<p:Result xsi:type="p:NoMatchType"
   xmlns:p="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/LegalInfo/V4"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<p:Code>250250</p:Code>
</p:Result>




Cegeka N.V.                                                                               page 15 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.2.6 Schema element & type name conventions
Guideline

Names SHOULD follow UpperCamelCase convention.
Names of types SHOULD end with suffix “Type”.

A schema definition that semantically indicates some type, like type of address (official or work), SHOULD
have another suffix than “Type”. A suitable alternative may be “Kind”.


Explanation
UpperCamelCase means that identifiers start with a capital, and each following noun also starts with a
capital – other letters are lower case.
Abbreviations can be all uppercase. The noun following the abbreviation then should start with a lower
case, not upper case.

The suffixes make it immediately clear what kind of construct is used: is it an element, complex type or
simple type.

Be aware that in XML Schema an element definition „Attestation‟ can co-exist with a type definition
equally named „Attestation‟. Internally, schema makes a kind of sub-namespace division between
elements and types. This may lead to hard to find validation error.


Example

UpperCamelCase Example:
   - LastPaymentDate
   - SIFcode




Cegeka N.V.                                                                                 page 16 of 60
B2B Web Service Guidelines V1                                                   RSVZ Enterprise Architecture




4.2.7 Substitution groups
Guideline
Substitution groups MUST NOT be used.
Explanation
Substition group elements must be definied as global elements. This is inconsistent with the guideline on
re-use and encapsulation.

Codegenerators have difficulties processing substitution group elements.

A better alternative to substitution groups is “schema restriction”, as explained in
http://www.w3.org/TR/xmlschema-0/#UseDerivInInstDocs.




Cegeka N.V.                                                                                   page 17 of 60
B2B Web Service Guidelines V1                                            RSVZ Enterprise Architecture




4.2.8 Use of <xs:redefine>
Guideline
The technique <xs:redefine> SHOULD NOT be used.
Explanation
Using this technique may have far-stretching consequences in schema documents that import other
schemas containing this construct. These side-effects are difficult to detect and predict.




Cegeka N.V.                                                                            page 18 of 60
B2B Web Service Guidelines V1                                             RSVZ Enterprise Architecture




4.2.9 Documentation & Comments
Guideline
For documentation or comments the annotation and documentation elements MUST be used.

XML comments (<!-- xml comment -->) MUST NOTbe used for documentation purposes.
Explanation
When using parsers or other XML tools, e.g. XSLT, Xquery, an XML comment is often lost.

With annotation and documentation elements it is possible to generate user documentation.
Example
Do not use:
   <!-- Comment -->
Instead, use:
      <xs:annotation>
         <xs:documentation xml:lang="nl">Datatype voor geboortedatum</xs:documentation>
         <xs:documentation xml:lang="fr">Format date de naissance</xs:documentation>
      </xs:annotation>




Cegeka N.V.                                                                                 page 19 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture




4.3 Web Services


4.3.1 Operation Names
Guideline
Operation names MUST start with a verb, followed by zero or more nouns and/or verbs.

The names MUST indicate the functionality from the viewpoint of the caller, i.e. what the caller expects to
be done by the callee.

Operation Names and all other Identifiers MUST use UpperCamelCase.
Explanation
This guideline is common today in all modern programming environments and software platforms (J2EE,
.NET). Since WSDL operations have the same intent, which is exemplified by the fact that code
generation turns WSDL operations into programming language operations, it makes sense to adopt the
same convention.

Some examples:
   - GetIncome(inss): give me (“get me”) the Income data for the person with the given inss
   - UpdateIncome(inss, changes): update your records of person “inss” with these “changes”
   - SendIncomeUpdate(inss): send me, at some later time, the income update data on person “inss”
   - ProcessIncomeUpdate(inss, data): here are some income update “data” for person “inss”, please
       process them

There is a subtle different between the two first examples, and the latter two.

GetIncome() is an example of a request-response exchange. The caller wait until it receives a response
– it does not do anything else meanwhile. This is very similar to programming languages.
                    1 request

    caller                               callee

                  2 response

                                     Web Service
                                       Server


The operation ProcessIncomeUpdate() is an example of a one-way operation. Once the calling party has
called processIncomeUpdate () it can continue doing other stuff – it does not wait for some reply.
               processIncomeUpdate

    caller                               callee
    (fund)                            (rsvz-inasti)



Request-reply and one-way operations are the building blocks for more complicated exchanges, what we
call „fluxes‟. In a flux one operation starts it and then, depending on back-end processing results, one or
more other operations can follow in different orders.

For example, both SendIncomeUpdate() and ProcessIncomeUpdate() are two separate one-way
operations. Once the calling party has called SendIncomeUpdate() it can continue doing other stuff – it
does not wait for some reply.
Later –seconds, hours or weeks – roles reverse and the original callee now calls ProcessIncomeUpdate()
on the original caller.



Cegeka N.V.                                                                                  page 20 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture


                 1.sendIncomeUpdate()

    caller                                    callee

    callee                                     caller

                 2.processIncomeUpdate


Note: the concept of fluxes is out of scope for this guideline. We only define guidelines on the building
blocks, request-reply and one-way.
Example
A request-reply operation.
<wsdl:portType name="LegalInfo">
   <wsdl:operation name="GetLegalInfoViaInss">
      <wsdl:input message="tns:GetLegalInfoViaInss" />
      <wsdl:output message="tns:LegalInfo" />
   </wsdl:operation>
</wsdl:portType>

Two related one-way operations. ProcessIncomeUpdate may occur out-of-bound.
<wsdl:portType name="Income">
   <wsdl:operation name="SendIncomeUpdate">
      <wsdl:documentation>
         Ask service provider, which is a SIF, to send Income Update to INSS
         on some Person.
      </wsdl:documentation>
      <wsdl:input message="tns:SendIncomeUpdate" />
   </wsdl:operation>
   <wsdl:operation name="ProcessIncomeUpdate">
      <wsdl:documentation>
         Ask service provider, which is INSS, to update some person's
         Income information.
         This operation can be the result of some earlier SendIncomeUpdate, or is sent
         out-of-bound by SIF.
      </wsdl:documentation>
      <wsdl:input message="tns:ProcessIncomeUpdate" />
   </wsdl:operation>
</wsdl:portType>




Cegeka N.V.                                                                                  page 21 of 60
B2B Web Service Guidelines V1                                                                 RSVZ Enterprise Architecture




4.3.2 Web Service versus Document approach
Guideline
Element or type definitions which are intended for web services only, SHOULD be defined in the WSDL‟s
schema.

Document Literal Wrapped elements (DLW) MUST be defined in the WSDL‟s schema.

XSD schema files MAY define a document root element representing a document, for use in a document-
oriented (i.e. non-web service) approach.


Explanation
WSDL and XML Schema have two very different underlying philosofies:
   - XML Schema describes document structure, or possible XML documents
   - WSDL describes operations that can be called, with input data and optional output data

WSDL also uses XML schema, but merely as a tool for defining input and output data, not documents 2.

Code generation imposes additional restrictions on WSDL schemas. A parameter element containing a
<xs:choice> will block code generation for this web service. This restriction does not exist for schema
documents3.

In a DLW convention a wrapper element must be defined with the same name as the operation. This is a
pure WSDL convention, hence this wrapper element is best defined in the WSDL‟s schema.
This wrapper element is not a good candidate for a document approach. A wrapper element is named
like the operation, thus “GetLegalInfo”. In a document approach we would name an element
“RequestForLegalInfo”, mimicing a paper form send to some other departement.
Example
The figure below describes a B003 LegalInfo request, a request for information on a person. This request
can functionally have two inputs, either an INSS number, or if this is not known other information such as
name, year of birth etc.




2
  In WSDL there is another means to describe input and output data that is not related to XML Schema, called RPC Encoding. This
shows that schema is merely one option and just a subordinate tool.
3
  Tested with JAX-WS / JAX-B 2.0 and .NET 2.0.

Cegeka N.V.                                                                                                     page 22 of 60
B2B Web Service Guidelines V1                                                  RSVZ Enterprise Architecture



                GetLegalInfoVia Inss(...)


                                                    GetLegalInfoWithoutInss(...)




     WSDL             GetLegalInfoViaInss
                                                       GetLegalInfoWithoutInss




     Document

                                                                               RequestForLegalInfo

                                                                     choice




                                                     NoINSS
                                            INSS




The document approach has one document root for a request, “RequestForLegalInfo”. Depending on
what is known of the person an INSS element is used, or other information in a NoINSS structure. Note
however that we forbid the use of such document root element in web services – this is used in non-web
service exchanges.

For the same functionality we need two separate web service operations because of the code generation
problems with xsd:choice. In addition, because of DLW two wrapper elements are defined with the same
name as the operations, GetLegalInfoInss and GetLegalInfoWithoutInss, that must be defined in the
WSDL‟s schema.

Note that the INSS and NoINSS structures are re-used in both the Web Service structures and document
structures.

Note: The existing fase 1A and 1B exchanges are inherently Document approaches.




Cegeka N.V.                                                                                  page 23 of 60
B2B Web Service Guidelines V1                                                   RSVZ Enterprise Architecture




4.3.3   ApplHeader for Generic Message Information
Guideline
A separate XML element <ApplHeader> MUST be present as the first child of the DLW soap:body
wrapper element (i.e. the <input> message).

The following fields MUST be filled in: TimestampSent, Origin, Destination, MessageID.

The combination (Origin, MessageID) of a message MUST be unique for each message exchanged.

If an operation (i.e. message) is part of a defined flux, the FluxDescriptor MUST be provided by the
sending party that starts the flux, and it must be preserved in all further operations that are part of that
flux.

Note for existing backend applications (ARZA/ARV):
    - The (Origin, MessageID) MAY not be unique. Today‟s situation (Flat File, Mailbox) continues here.
    - RequestInitiatorID MUST be filled in when calling NISSE.
    - FluxDescriptor is not used.


Explanation
The ApplHeader collects information about the message that is independent of the message type and
must always be present. Because it is information about information we use the term „Meta information‟ –
though most of it can be regarded as routing information at a high level.




All fields are filled in by the soap message sender (i.e. webservice caller).
      - TimestampSent: Timestamp when sent by sender.
              o Note: best approach is to determine this timestamp as late as possible, i.e. just before
                    sending it. For retries we leave it up to you whether you change the timestamp at each
                    retry, or leave it the same.
      - Origin: Sending or calling organization and application. See below.
          Destination: Receiving or called organization and application. See below.
      - MessageID: message id, unique per Origin.

Both Origin and Destination are structured as follows:




The codes for   Organization:
Organization    Name
000             NISSE
001             "GROEP S" Sociale verzekeringskas voor zelfstandigen
002             Xerius Sociaal Verzekeringsfonds


Cegeka N.V.                                                                                    page 24 of 60
B2B Web Service Guidelines V1                                                       RSVZ Enterprise Architecture


003              Nationale sociale verzekeringskas voor middenstand en beroepen in afkorting
007              "PARTENA" Sociale verzekeringen voor zelfstandigen
010              "ACERTA" Sociaal verzekeringsfonds
011              "ARENBERG" Sociaal Verzekeringsfonds voor zelfstandigen V.Z.W.
012              "SECUREX-INTEGRITY" Vrije sociale verzekeringskas voor zelfstandigen
013              ATTENTIA sociaal verzekeringsfonds
014              "INTERSOCIALE" Sociale verzekeringskas voor zelfstandige beroepen
015              "MULTIPEN" Sociaal-verzekeringsfonds voor Landbouw, Middenstand en Vrije
016              "HDP" Sociaal verzekeringsfonds voor zelfstandigen
017              "STEUNT ELKANDER" Vrij sociaal verzekeringsfonds voor zelfstandigen
019              Caisse wallonne d'assurances sociales des classes moyennes, in afkorting :
900              Nationale hulpkas voor de sociale verzekeringen der zelfstandigen

The codes for Application are defined by each Organization.

Organization     Application   Description
000              120           RSVZ-Inasti,   PEN applications
000              200           RSVZ-Inasti,   ARZA system
000              300           RSVZ-Inasti,   VOB applications
000              400           RSVZ-Inasti,   Inspection applications
000              601           RSVZ-Inasti,   ARV system

When a Flux is involved, a FluxDescriptor element must be present. It must be defined and provided by
the sending party that initiates the Flux, and must be copied in each subsequent message that is part of
that flux.

Fluxes are really explicit B2B processes, where it is clearly defined which messages (operations) may
follow one another, or in parallel, to achieve a certain goal. All these messages (operations) have their
own unique message id but have the same FluxDescriptor.

The FluxDescriptor is as follows:




      -   Initiator: Organization and Application that start the flux.
          This is equal to Origin if the message is the first one in a Flux.
      -   FluxID: unique id, identifying the Flux Instance.
      -   FluxDefinition: defines the Flux, e.g. NewAffiliation, and its version.


Note that there is some redundancy:
    - An Origin or Destination Application can be deduced from the operation name and/or
        fluxdefinition




Cegeka N.V.                                                                                       page 25 of 60
B2B Web Service Guidelines V1                                                         RSVZ Enterprise Architecture


We do not want to use the SOAP header as an alternative for the ApplHeader, since this is the area for
vendor tools implementing WS-* standards such as WS-Addressing, WS-Security etc. The ApplHeader
contains information other than this standardized WS-* functionality.


The figure below shows where the ApplHeader is located in a web service operation. ApplHeader is the
first child of the operation‟s wrapper element GetLegalInfoWithoutInss, element NoINSS being the
second.

                         GetLegalInfoWithoutInss(ApplHeader p1, NoINSS p2)




               SOAP
                                         GetLegalInfoWithoutInss




              Document

                                                                              RequestForLegalInfo



                                                                             choice




                   ApplHeader                          NoINSS
                                                                                INSS



Modern code generation tools will detect that the DLW convention is used in the WSDL and will not
generate code for the wrapper element. Instead, the wrapper elements children will be the input types
for the operation: ApplHeader p1 and NoINSS p2.

For completeness the figure also contains a document root element, RequestForLegalInfo. This element
too must have as its first child the meta information.

Waarom zijn we tot deze keuze gekomen? Om dergelijke meta-informatie te transporteren in soap zijn
er drie mogelijkheden:
    1. expliciet als extra input part van de <wsdl:operatie>, naast de input body part
    2. expliciet als extra input part van de <wsdl:operatie>, naast de input body part, waarbij
         aangegeven wordt dat de extra part in de soap header dient vervoerd te worden
    3. ApplHeader is onderdeel van de soap body (voorgestelde oplossing)

Oplossingen 1 & 2 zijn niet mogelijk, omdat een DLW conventie voor een soap operatie slechts één part
toelaat in de input parameter, onafhankelijk van het feit of die part via de soap header of soap body
vervoerd wordt.
Daarnaast wordt bij optie 2 de soap input part voor de ApplHeader ook niet opgenomen in de
gegenereerde Java of .NET operatie – waardoor het voor de programmeur niet duidelijk is dat deze
ingevuld moet worden.

Oplossing 3 heeft deze nadelen niet. Misschien kan het als nadeel aanzien worden dat de meta-
informatie mee in de informatie zelf vervoerd wordt. Hiervoor echter een aparte structuur opzetten
introduceert een niet te verantwoorden extra complexiteit. Ook is het verschil tussen informatie en
meta-informatie vaak flou.


See the MetaInfo schema for more information.



Cegeka N.V.                                                                                         page 26 of 60
B2B Web Service Guidelines V1                                RSVZ Enterprise Architecture


Example
See template in “WSDL for Non-Bulk Operations” at page 50.




Cegeka N.V.                                                                page 27 of 60
B2B Web Service Guidelines V1                                                                          RSVZ Enterprise Architecture




4.3.4 Pseudo One-Way over HTTP - Idempotent Operations
Guideline
The only transport protocol used SHOULD be HTTP(s).

Both request-reply (RR) and one-way (O-W) operations over HTTP are supported functionally, but
technically all these operations are RR in that they MUST define a <wsdl:output> element.
     A functionally Request-Reply operation MUST define a <wsdl:output> message that has business
        value.
     A functionally One-Way operation using HTTP transport MUST define a <wsdl:output> message
        containing only the <meta:TransferResult> element shown below, which serves as a „ack of
        delivery‟. A One-Way response MUST NOT contain business related information.
   <xs:element name="TransferResult">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="TransferOk">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="Timestamp" type="xs:dateTime">
                        <xs:annotation>
                           <xs:documentation>
Timestamp when the service provider (the callee) has received the one-way message.
                           </xs:documentation>
                        </xs:annotation>
                     </xs:element>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

Operations MUST be idempotent.


Explanation
The only transport protocols officially supported in SOAP/WSDL are HTTP and SMTP. SMTP is not very
useful – it is not reliable and not suited for large messages4. FTP is not supported as a transport protocol
by most code generation tools or ESB‟s. JMS has more support by ESB tools, but not in the .NET world.

FTP and JMS have a big advantage for one-way messages: transport and processing are decoupled. This
means that a sender can continue working while the message is being processed by the server. Put
another way, once the sender has delivered the message through FTP or JMS, it is the responsibility of
the receiver to make sure that the message is processed. This is a big advantage of one-way message
exchanges, sometimes also called „fire-and-forget‟ for this reason.

Since HTTP is well supported in web services, could we have the advantages of FTP or JMS while still
using HTTP? Yes, by decoupling http transport and message processing, as described below. We call this
pseudo one-way.




4
    Attachments are also not a solution for this: standards are still moving, as is vendor adoption.

Cegeka N.V.                                                                                                          page 28 of 60
B2B Web Service Guidelines V1                                                  RSVZ Enterprise Architecture



                                       1. SOAP/HTTP request
                                         functional message



                                                                                 Soap
                      Soap                                Soap
     Sender                                                                     Service        Receiver
                     Service                             Service
    Application                                                                 Endpoi        Application
                      Client                             Server
                                                                                  nt

                                                                        persistent
                           3. SOAP/HTTP                                   store
                              response
                          is delivery ack,
                            optional fault
                                                                    2. Validation, followed
                                                                        immediately by
                                                                    put in persistent queue


Figuur 1 - Pseudo One-Way

The SOAP/HTTP message is technically request-reply, but functionally one-way. It delivers the message
at the Soap Service Server, which only does schema validation, immediately followed by writing it to a
persistent store. The Service Server then sends a fixed TransferResult element to the Soap Service Client,
indicating that the message is successfully received and will be processed later on.
Somewhat later the receiver application will read the message from the persistent store and process it.

If the Soap Service Server detects a validation error, or it cannot write the message to the persistent
store, then it returns a fault to the Soap Service Client.

If the Service Server or the network fails while the Service Client is waiting for an (empty) answer, then
the Service Client will get some fault or exception error (e.g. „connection lost‟). The Service Client then
must assume the message is lost and re-send the message later on.
This requires that operations are idempotent, meaning that whether they are processed 1, 2 or more
times by the receiver application the net effect is the same.

Both request-reply and one-way message exchanges are supported by HTTP(s). Using HTTP for one-way
– which is done by not specifying an <output> in the WSDL – effectively means that the client will not
receive a soap response. Also note that in WSDL 1.x an operation <fault> can only be specified if there is
also an <output> parameter – thus a fault is only supported for request-reply exchanges5.
Therefore we use HTTP in request-reply for delivering the message, so that we can still send a fault if the
message cannot be safeguarded by the receiving application.

HTTP(s) is not the only transport protocol that can be used in this way. One could use JMS to directly
connect to the queue. FTP is also feasible, if some mechanism is foreseen to pick-up the soap message
from the FTP directory and put it in the queue. This might be useful for very large messages that cannot
be transferred by HTTP.

The pseudo one-way with HTTP is still not as reliable as JMS, which can be configured to be really
transactional end-to-end. To achieve the same reliability as JMS this mechanism should be augmented by
WS-Reliable Messaging. But if programmed correctly the solution described here is at least as good as
FTP.
Error situations and error handling is described in the next section.




5
 The next WSDL standard, version 2.0, solves this problem, but this standard is not yet implemented by
software vendors. Moreover there seems to be a lot of scepticism about this standard.

Cegeka N.V.                                                                                    page 29 of 60
B2B Web Service Guidelines V1   RSVZ Enterprise Architecture


Example
See templates at page 50.




Cegeka N.V.                                   page 30 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture




4.3.5 Error Handling and the {MetaInfo} Error element
Guideline
1. For new errors a distinction MUST be made between System Errors and Business Errors.

2. The {MetaInfo}Error element MUST be used for System Errors, with subtype „SystemError‟.

3. Business Errors SHOULD be reported in one of the following ways
           a. as an XML construct in a reply (Request Reply)
           b. as a separate operation (One Way),
           c. or as a {MetaInfo}Error with subtype „BusinessError‟ in
                     i. a Reply of the operation
                    ii. or a Generic.HandleError() operation

4. A SystemError MUST be transmitted as follows, in the following order:
       a. By default: as a custom web service fault SystemError
       b. Otherwise, only if the http connection is not available anymore, a separate
          Generic.HandleError() operation.

5. Errors in backend applications MAY be wrapped in the {MetaInfo}Error element. In this case the
   application MAY specify that it is unknown whether it is a System or Business error (type „Unknown‟).


Explanation
A Business Error is an error interpreted by the user (human or machine). The user may have the ablity to
resolve this, e.g. by changing input data.

A System Error is interpreted by system operators and/or developers, and they take action to resolve it. A
user is typically also informed in a general way, saying that „a general system error occurred – please
contact your system administrator at phone...”.

Below is pictured that an Error is either a Business Error or System Error.




Cegeka N.V.                                                                                 page 31 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture



                                                                                                     Either:
                                                                                                    - X001
                                                                                                   - Other
                                                                                      wrapped
                                                                   {MetaInfo}Error                 - No ne




                                                                     Specific Elements

                                           Business Error




            Error                                                 {MetaInfo}Error
                                                                                                  Either:
                                                                                    wrapped
                                                                                                 - X001
                                            System Error                                        - Other
                                                                                                - None




A System Error is always indicated by a {MetaInfo} Error element. This error then indicates:
    - Type is „SystemError‟
    - Standardized application id of application that raised the error.
       Each SIF has its own applications. So does INSS, e.g. ARZA and PEN applications. The same
       approach is used at KSZ through the „codelist‟.
    - Standardized errorcode ID within that application.
       Each application defines its own error codes. Some error codes are general for all applications.
    - Optionally, a wrapped error giving more detail.

Each partner in a web service conversation that adheres to this specificaton must use the System Error
defined here. But often the error occurs in a back-end application, for example an X001 error reported by
KSZ. Then an Error element is created with error code “General System Error in backend KSZ” and the
original X001 error may be wrapped in the Error element.

A Business Error can be treated in several ways. If you prefer to use standardized error codes instead of
specific xml constructs then you should use the {MetaInof}Error element, with subtype „Business Error‟.
Here too another (business) error, raised in a back-end system, can be wrapped.

Since a KSZ X001 error message does not make a difference between business errors or system errors an
application may create an Error element with type „Unspecified‟, so it is up to the receiving application to
make the distinction.

Note: Business Errors as soap faults is a problem on .NET platforms. Business Errors should be checked
exceptions, meaning that a developer is forced to handle it in any way. In .NET however exceptions are
always unchecked. For this reason we advise to not use soap faults for Business Errors – but no definitive
decision has been made, hence the SHOULD in the guideline.

The {MetaInfo} Error element is as follows:




Cegeka N.V.                                                                                      page 32 of 60
B2B Web Service Guidelines V1                                          RSVZ Enterprise Architecture




A SystemError fault is defined as follows:
<wsdl:message name="SystemError">
   <wsdl:part element="meta:Error" name="systemError"></wsdl:part>
</wsdl:message>
...
<wsdl:operation name="GetLegalInfoByInss">
...
   <wsdl:fault name="SystemError" message="tns:SystemError" />
</wsdl:operation>


If possible with your infrastructure, fill in the soap fields as follows:
    - {soap}faultstring = {MetaInfo}Error.Code + “: “ + {MetaInfo}Error.CodeDesc
    - {soap}faultactor = {MetaInfo}Error.Application


Example
See higher in this guideline, SystemError.




Cegeka N.V.                                                                          page 33 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.3.6 Error Handling of System Errors
Guideline
Senders MUST NOT assume that, on detection of a System Error, the operation has or has not been
processed.

Therefore operations MUST be made idempotent, and senders must be able to handle this appropriate.

System   Errors include the following:
    -    TCP/IP errors
    -    HTTP errors
    -    Soap Faults
    -    A TransferOK element not received.


Explanation
This guideline is only for System Errors. Business Errors imply that the operation has been processed.

System Errors are not merely Error operations or faults of type „System Error‟, but also HTTP or TCP/IP
errors and crashes.

We assume a HTTP transport, with request-reply operations or pseudo one-way operations as described
elsewhere in this guideline.

The figure below shows a sender and receiving application, soap service endpoints and a HTTP transport.
The arrows show the message exchange. Note that for pseudo one-way the reply message contains a
fixed „delivery ack‟ message or a fault. For request-reply the reply message contains a business result or
a fault.

Component            Contains...                                        Error examples
Send – Service       - Generated code from WSDL or Service Bus          - Invalid message or operation
Endpoint             - HTTP client software                                 detected
                     - TCP/IP client software                           - Problem with http or tcp/ip
                                                                            client infrastructure

HTTP Transport       tcp/ip network, routers, gateways, firewalls...    Any failure in any network
                                                                        component
Recv – Service       - Generated code from WSDL or Service Bus          - Crash
Endpoint             - HTTP server software                             - Validation error
                     - TCP/IP server software
Receiver             Business logic interpreting request.                -   Crash
Application          For request-reply only generates a response         -   System error
                     (no response for pseudo one-way).                   -   Business error




Cegeka N.V.                                                                                   page 34 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




                           Service                                Service
          Sender           Endpoint                               Endpoint          Receiver
                                           HTTP Transport
         Application          -                                      -             Application
                            Send                                   Recv




                                  1                  2                   3
                                                                                           4a
      Request-Reply               7                  6                   5




                                  1                  2                   3

                                                                                 4b
     Pseudo One-Way               7                  6                   5




The arrows show a Request Reply operation and a Pseudo One Way operation.
Assuming the errors occur where red crosses appear, the next scenarios are possible:

Error      Processed by          Comment
in...      Receiver App?
Request-Reply
1          No                    The sender application immediately detects an error, typically as a soap
                                 fault or another means determined by the tools used.
                                 Typically the sender side must correct the problem and redo the
                                 operation.
2          No                    The sender application immediately detects an error, a TCP/IP error like
                                 „connection lost‟.
                                  After the network problem is solved the operation must be redone.
3          No                    The sender application immediately detects an error:
                                      - Crash, System malfunction: TCP/IP error
                                      - General system or software error:: HTTP error, Soap fault
                                      - Validation Error: soap fault of type SystemError.
                                 Typically the sender side must redo the operation.
4a         Unsure                The sender application immediately detects an error.
                                  - Crash, System malfunction: TCP/IP error System error
                                  - General system or software error: HTTP error or Soap fault

                                 Typically the sender side must redo the operation.

                                 ! Since it is unsure whether the operation already executed the
                                 operation must be idempotent. Either side must implement this, for
                                 example by using a unique MessageID or indirectly by using WS-
                                 Reliability.

5          Yes (but not always   The sender application immediately detects an error:
           known to sender)         - Crash, System malfunction: TCP/IP error
                                         redo operation, since Sender does not know if already
                                        processed
                                    - General system or software error:: HTTP error, Soap fault
                                         redo operation, since Sender does not know if already

Cegeka N.V.                                                                                page 35 of 60
B2B Web Service Guidelines V1                                                   RSVZ Enterprise Architecture


                                           processed
                                       -   Validation Error: soap fault of type SystemError
                                           This error occurred on the reply message, and will be noted
                                           by a dedicated SystemError indication validation error on the
                                           reply.
                                           In this case the operation must also be re-done, but only after
                                           the receiver has fixed the problem!

6          Yes, but not known      Idem to 2.
           to Sender
7          Yes                     The sender application immediately detects an error, typically as a soap
                                   fault or another means determined by the tools used.
                                   Typically the sender side must correct the problem and redo the
                                   operation.
Pseudo One-Way
Note that the reply message is either a „delivery ack‟ or soap fault.
Also, there is no processing in the Receiver Application for what error handling is concerned.
1          No                      Idem request-reply.
2          No                      Idem request-reply.
3          No                      Idem request-reply.
4b         Unsure                  Problems at this stage are where the Receiver Application cannot be
                                   reached. In this case a soap fault with a specific SystemError is
                                   returned.
                                    The sender can retry the operation.
5          No                      Idem request-reply, except that Validation Error cannot occur. Only
                                   crashes or system malfunction can occur.
6          Yes, but not known      Idem request-reply.
           to Sender
7          Yes                     Idem request-reply.


It shows that multiple types of errors can be detected: tcp/ip errors, http errors, soap faults.
Soap faults can be the standardized soap fault, or the custom SystemError fault.


Example
Below is an example of a Soap Fault using SystemError and Error.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soap:Fault xmlns:hlp="http://www.rsvz-inasti.fgov.be/schemas/WS/Service/V1"
                    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
         <faultcode>hlp:SystemError</faultcode>
         <faultstring>Something terrybly went wrong…</faultstring>
         <faultactor>ALSB</faultactor>
         <detail>
            <meta:Error
            xmlns:meta="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V4">
               <meta:Type>System</meta:Type>
               <meta:Application>ALSB</meta:Application>
               <meta:Code>1234</meta:Code>
               <meta:MessageIDcausingError>123456789012345</meta:MessageIDcausingError>
            </meta:Error>
         </detail>
      </soap:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Note: instead of hlp:SystemError a soap:Client or soap:Server can be received when the error is
generated by soap infrastructure (e.g. ESB products) and not handled by custom code.



Cegeka N.V.                                                                                    page 36 of 60
B2B Web Service Guidelines V1                                             RSVZ Enterprise Architecture




4.3.7   SOAPAction
Guideline
In the WSDL SOAP binding, we use the following pattern to construct the soapAction attribute:

        [WSDL targetNamespace][deilimiter][port type name][delimiter][operation name]


Explanation

While WS-I Basic Profile does not require a soapAction in the SOAP binding, our tests have shown that
defining a soapAction provides a better experience across vendors.

When a given SOAP implementation defaults to using the SOAPAction HTTP header for selecting the
operation to invoke, then each operation must define a unique soapAction attribute in the SOAP
binding.


Example

<wsdl:definitions targetNamespace=”.../schemas/WS/LegalInfo/V3”>
   <wsdl:portType name="LegalInfo">
      <wsdl:operation name="GetLegalInfoByInss">
        ...
      </wsdl:operation>
   </wsdl:portType>
   <wsdl:binding name="LegalInfoSOAPbinding" type="tns:LegalInfo">
      <wsdl:operation name="GetLegalInfoByInss">
         <soap:operation soapAction=".../schemas/WS/LegalInfo/V3/LegalInfo/GetLegalInfoByInss"/>
         ...
      </wsdl:operation>
   </wsdl:binding>
</wsdl:definitions>


Note:

The targetNamespace has been abbreviated for clarity.
              …




Cegeka N.V.                                                                              page 37 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.4   Configuraton Management & Release Management



As an introduction it may be helpful to first read “Appendix 1 – Configuration Mgmt Concepts” at page
59.



4.4.1 Namespaces & schema file.
Guideline
There MUST be one and only one xsd schema file per targetnamespace and vice versa, not taking into
account versions.
Explanation
Multiple XSD schema documents that use the same target namespace but that describe different
functionality (through element and type definitions) can lead to problems.

It is not easy to see if some element or type is redefined in some other schema file. With this guideline
all element and type definitions in the scope of one namespace live together in the same XSD file – with
proper tools then it is easy to detect that there is a name clash.

Some tools, e.g. BizTalk, can validate instance documents on the basis of the namespace of the
document and a repository containing schema definitions. However, this does not work well if one
namespace is used as target namespace in multiple XSD files, especially if elements or types have
multiple – inconsistent – definitions.
Example




Cegeka N.V.                                                                                 page 38 of 60
B2B Web Service Guidelines V1                                               RSVZ Enterprise Architecture




4.4.2 Versions
Guideline
Each XSD schema document MUST be versioned individually.
Each Web Service, including containing schema, MUST be versioned individually.

A schema or web service MUST consist of a major version number M 1 and a minor version number m
0.
A version is reverred to as VM.m.
     A minor version increment is a transparant change; such a version may be ignored by
        communicating partners. Such increments are „backward compatible‟.
     A major version increment has changes that lead to funcional changes and code updates for
        communicating partners.

A target namespace MUST contain the major version, but MUST NOT contain the minor version.

The <xs:schema> element MUST contain the version attribute: version=”M.m”, thus including the major
and minor number.

The following table MUST be adhered to:

 Configuratie      Namespace & Version Attribuut
 Element
 Web Service       Namespace:
                   http://www.rsvz-inasti.fgov.be/schemas/WS/aaaa/Vmajor
                   Version attribute of included <schema> element:
                           <xs:schema version=“major.minor“… >

                   A Web Service is typically split up in 3 WSDL‟s: SERVICE.wsdl, NisseSERVICE.wsdl
                   and SifSERVICE.wsdl. Each of these files has the same version indication.

 XML Schema        Namespace:
                   http://www.rsvz-inasti.fgov.be/schemas/WS/schema/aaaa/Vmajor

                   Version attribute of <schema> element:
                           .<xs:schema version=“major.minor“… >


 Legend:
              o   major: major version, sequence number  1.
              o   minor: minor version, sequence number 0.
              o   aaaa: identifying name, e.g. LegalInfo.




Explanation
This type of major-minor versioning is well known today for software or software components that have
frequent release updates that may impact multiple customers. Schemas and WSDLs will change because
of legal changes or other changes, and impact more than 10 social insurance funds and other partners.
Hence it is logical to adapt the same well-established convention.

We did not choose for an explicit SchemaVersion attribute defined in the schema and (implicitly)
accessible to XML parsers. Major versions are already visible through the namespace. Minor versions are
backward compatible; it suffices to always use the highest minor version schema (within one major
version) to be able to parse a (possibly old) XML document.



Cegeka N.V.                                                                               page 39 of 60
B2B Web Service Guidelines V1   RSVZ Enterprise Architecture


Example
-




Cegeka N.V.                                   page 40 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.4.3 Schema and WSDL file names and path structure
Guideline
Schema .XSD and Web Service .WSDL filenames MUST only contain the major version indication, as
follows, wehere M is the major number:

        SomeName_VM.wsdl
        SomeName_VM.xsd

The following path structure MUST be followed:

./schema/Name/Name_VM.xsd                 Schema files, where Name is an identifying name and M the
                                          major number.
./service/Name/Name_VM.wsdl               Service file, up to and including the PortType definitions.
./service/Name/NisseName_VM.wsdl          Service file importing Name_VM.wsdl, defining the soap binding
                                          and service definition of the operations provided by Nisse.
./service/Name/SifName_VM.wsdl            Service file importing Name_VM.wsdl, defining the soap binding
                                          and service definition of the operations provided by a Sif.


Explanation

Why did we not include the minor version indication in the filename?
The <xsd:import> statement contains a „schemaLocation‟ attribute, whose value is a (relative) path to an
imported schema file. If the minor version number would be incorporated in the filename then any minor
upgrade of the imported file would also change its filename, and thus the importing schema file must
change its „schemaLocation‟ attribute value.
Thus a minor change in the imported file leads to a minor change in the importing file. To avoid this
„ripple effect‟ we forbid a version indication in the filename.

The major version is included in the filename because the reasoning for the minor is not applicable here:
an importing schema must declare the namespace of the imported schema, which contains the major
version. Also it makes it much more easy to have two major versions of the same service or schema
running in parallel.

The path structure was introduced to ease readability: this way all files do not appear in the same
directory.
Example
The figure below shows a configuration of two Services, consisting of WSDLs and XML Schemas.

Each file has its own target namespace containing the major version number ( not the minor version
number). The full version number is in the „version‟ attribute of the <xsd:schema> element. The
filenames indicate the major version of the schema. The arrows indicate that a schema is imported in
another schema, or that a wsdl is imported into another wsdl.




Cegeka N.V.                                                                                 page 41 of 60
B2B Web Service Guidelines V1                                                                RSVZ Enterprise Architecture



                                                        NisseAffiliation_V1.wsdl          SifAffiliation_V1.wsdl
                                                              version=”1.1"                    version=”1.1"
                                                          .../WS/Affiliation/V1            .../WS/Affiliation/V1


                          LegalInfo_V2.wsdl
                             version=”2.0"
                         .../WS/LegalInfo/V2
                                                                           Affiliation_V1.wsdl
                                                                              version=”1.1"
                                                                          .../WS/Affiliation/V1




                          Legal_V2.xsd                  Legal_V3.xsd                       Affiliation_V1.xsd
                           version=”2.2"                 version=”3.0"                       version=”1.3"
                     .../WS/schema/Legal/V2        .../WS/schema/Legal/V3             .../WS/schema/Affiliation/V1




              imported
                 in


                                    MetaInfo_V1.xsd                         Base_V2.xsd
                                     version=”1.0"                          version=”2.3"
                                .../WS/schema/Base/V1                  .../WS/schema/Base/V2


                                      Figure 1 - Example Configuration

Some notes on the example configuration:
   - Of Legal there are two major versions used at the same time, V2 and V3. V2 is used by LegalInfo
       web service, V3 is used by Affiliation web service.
   - The full version of a Service.wsdl, NisseService.wsdl and SifService.wsdl, as exemplified by
       Affiation.wsdl, must be exactly the same for all three files.

The path structure of the wsld and schema files also follows a fixed pattern, as shown below.
.
|-- Affiliation
     |-- Affiliation_V1.wsdl
     |-- NisseAffiliation_V1.wsdl
     |-- SifAffiliation_V1.wsdl
|-- LegalInfo
     |-- LegalInfo_V2.wsdl
     |-- NisseLegalInfo_V2.wsdl
     |-- SifLegalInfo_V2.wsdl
|-- schema
     |-- Affiliation
        |-- Affiliation_V1.xsd
     |-- Legal
        |-- Legal_V2.xsd
        |-- Legal_V3.xsd
     |-- Base
        |-- Base_V2.xsd
     |-- MetaInfo
        |-- MetaInfo_V1.xsd




Cegeka N.V.                                                                                                        page 42 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture




4.4.4 Releases & Impact Analysis
Guideline
A release MUST follow the following naming conventions:

Release             RCM.m_s         M: major
Candidate                           m: minor
                                    s: sequence starting at 0
Release             R M. m          M: major
                                    m: minor

A proper impact analysis MUST be conducted before creating a new Release. See below for details.

NISSE MUST always have the latest Release in production.

A SIF SHOULD use the latest Release, unless it is absolutely certain that the changes in the newer
Release are transparant and functionally not needed.


Explanation



As an introduction it may be helpful to first read “Appendix 1 – Configuration Mgmt Concepts” at page
59.


Impact Analysis of Configuration Items
Once known whether a configuration item (i.e. schema or web service) update is a minor or major
update we can determine the impact on other configuration items.

To determine if a configuration item undergoes a Major, Minor or no change, it suffices to follow the
import-relation between configuration items (see “Figure 1 - Example Configuration” on page 42 for an
example) and apply the following algorithm recursively:
    1. A Minor change in an imported configuration item (CI) occurs:
             a. A changed element or type is used or referred to in the importing CI.
                 The minor version of the importing CI augments.
             b. No change otherwise.
    2. A Major change in an imported configuration item (CI) occurs:
             a. If this change is not needed in the importing configuration item, 2 options are possible:
                      i. The importing CI may stick to the older major version.
                         The version of the importing CI stays the same.
                     ii. The importing CI may upgrade to the new major version, typically to limit the
                         number of parallel versions of the same CI that need to be supported.
                         The effect is the same as described in 2.b.
             b. If this change is needed in the importing configuration item, 2 options are possible:
                      i. The import does only lead to transparant changes in the importing CI.
                         A minor upgrade of the importing CI is sufficient.
                     ii. The import does lead to at least one non-transparant change in the importing CI.
                         A major upgrade of the importing CI is needed.


Releases
A Release is a consistent set of schemas and web services that is put as a whole in production. An
example of a release might be all the schemas and web services depicted in “Figure 1 - Example
Configuration” on page 42.



Cegeka N.V.                                                                                page 43 of 60
B2B Web Service Guidelines V1                                                               RSVZ Enterprise Architecture


As seen in this example a release, identified as say R2.1, consists of multiple specific versions of a
schema or web service. Even more, the same schema may be included under multiple versions, as is the
case for Legal schema.

Before a Release is put into production it has been the result of earlier tests, like System testing and
Acceptation. In these fazes we do not yet speak of Release, but of Baselines and Release Candidates.
The next schema defines these terms.
 class Guidelines


         XsdOrWsdlFile                          Base line

     +    major: int                        +   label: string
     +    minor: int      1. .*      0..*
     +    namespac e: uri




                                  ReleaseCandidate                       Rele ase

                                                                 +   inProducti on: date
                                                     1. .*       +   outProduct ion: date
                                                     {ordered}



Figuur 2 – Baseline, Release and File

A Baseline is a consistent set of schema and web service files, each of a specific version. Baselines have a
label, e.g. “BUILD20080515_256” – and is typically used internally and for System Testing.

Once development is ready, a special kind of Baseline is created, the “Release Candidate”. This is a
package that will be distributed to all parties for acceptance testing. The label name follows a specific
convention described below.
Note that during acceptance testing multiple new Release Candidates may be distributed and installed,
typically to fix a bug.

Once acceptance testing has finished successfully, the Release Candidate used at that time becomes a
Release. A Release has 3 fazes: ready to be put into production, in production, retired from production.
Releases are also special in that they have to be stored „for eternity‟, and that they are published on the
web site of RSVZ-INASTI.

The label convention is as follows:
 Development/Test Internal
                           NISSE
 Release                   RCM.m_s           M: major
 Candidate                                   m: minor
                                             s: sequence starting at 0
 Release                   RM.m              M: major
                                             m: minor

Whether a new Release is a minor or major upgrade is determined as follows:

 minor             all configuration items (schema or wsdl) are either minor version increases, or no increase
 release           at all, relative to the previous release
 major             at least one configuration item has a major version increase
 release




Cegeka N.V.                                                                                               page 44 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture


A Fund may skip one or more minor releases, on the condition that the corresponding changed or added
functionality is never used.
On the contrary, RSVZ-INASTI always has the latest minor Release in production.

Impact on Back-End Applications
The next table summarizes the impact on Applications of the communicating partners, such as the SIFs
and NISSE, when a configuration item‟s version increases.

Tabel 1 - Application Impact
 Configuration      Minor                                    Major
 Item Change
 Partner Glue       Two options:                             Re-generate code for changed
                    1. (recommended) import and/or           xsd‟s or wsdl‟s.
                       re-generate code for xsd‟s and
                       wsdl‟s. (1)
                    2. do nothing, on condition that
                       changed functionality is not
                       used

 Partner              No change, unless changed              Functional & technical changes
 Applications         functionality is used.                 where necessary.


Legend
    Partner: Funds and other parties in the secondary network
    Glue: generated web service communication code
    Applications: the applications of the partners involved in B2B and that integrate the glue code

    (1) Even if the changed functionality is not used it is still recommended to re-generate the glue code.
        For example, if the minor change is a new optional element, another party might fill in this
        element. If the glue code has not been re-generated at the receiver side then an error may still
        occur.




Cegeka N.V.                                                                                   page 45 of 60
B2B Web Service Guidelines V1                                                   RSVZ Enterprise Architecture




4.4.5 Serve Multiple Releases of a Web Service in Parallel
Guideline
A Release MAY contain multiple major versions of the same Configuration Item (schema or web service)
for two reasons:
      Phasing out a service without disrupting production traffic.
      Support unfinished business of the past that does not comply and is incompatible with newer
        legislation.

A Release MUST always contain the latest minor version within a major version of the same Configuration
Item, as available at that time. A service consumer or provider MAY choose an earlier minor version,
under well studied conditions.

NISSE and the SIFs MUST
   - be able to offer multiple major versions of a service as a service provider.
   - only use one major version of a service at a given time as a service consumer (i.e. caller)


Explanation

Minor Release
Transparantie van een minor change is er enkel op schema niveau, niet op berichtniveau. Dwz dat als
een zender de nieuwe versie gebruikt en de ontvanger niet, dit tot een validatiefout kan leiden.
 Mogelijke oplossingen:
       1. validatie hiervoor afzetten
       2. minor release toch importeren in de soap infrastructuur, maar de applicaties niet aanpassen en
       de verandering dus negeren.

De 2e optie is te verkiezen, omdat de 1e optie later in de applicatie tot fouten kan leiden.

Er moeten echter duidelijke afspraken gemaakt worden. Als de zender een informatie opstuurt die de
ontvanger niet verwerkt, dan mag dit geen invloed hebben op de correcte functionele werking.

Major Release
Two major versions of the same web service can be serviced in parallel by having different namespaces
and different service URLs.

To have NISSE and SIFs transition from one major to a newer major requires the protocol described in
the following table:


Sequence      Send Side                                            Receive Side
1             Sends V1                                             Receives V1
2             Sends V1                                             Receives both V1 & V2, and processes
                                                                   both V1 & V2.
                                                                   The sender (INSS) or senders (SIFs) are
                                                                   notified of this change by e-mail.
3             Sender side(s) switch to new major release, after
              development and testing have finished.

              Sends new operations as V2.
              Queued but yet unsent V1 operations are sent,
              and can still be processed by receiver.

              When switched to V2 and all V1 messages are
              sent too, Receiver is notified by e-mail.
4                                                                  All Senders have confirmed they all use

Cegeka N.V.                                                                                    page 46 of 60
B2B Web Service Guidelines V1              RSVZ Enterprise Architecture


                                V2 now.
                                Disable V1.
                                Receive and process V2 only.




Cegeka N.V.                                              page 47 of 60
B2B Web Service Guidelines V1                                                    RSVZ Enterprise Architecture




4.4.6 Pre-Production & Production Environment
This chapter details how a Baseline evolves into a Release.

In a first phaze, internal development and test, the CR‟s of the release are implemented. External parties
cannot test yet, except perhaps informally.

       RSVZ-INASTI



                                Interface Type Rx.y

              Internal Development
              & Test


                                     Interface Rx.y




                                                                    Fund


                                                         consult/
                                Interface Type Rx.y     download
                                                                             Development
                                                                                                  Pre-production
              Pre-production


                                                                           Interface   Programmatie
                                     Interface Rx.y   communicate
                                                                           Rx.y           & Test




                                Interface Type Rx.y


              Production
                                                                                                       Production
                                                                            Interface Productie
                                     Interface Rx.y   communicate
                                                                            Rx.y      programma




As soon as the interface is fixed and an implementation of it is ready a Release Candidate is put into pre-
production. This pre-production environment is accessible to external parties, e.g. Funds, so they can:
    - Consult and import the interface description (WSDL‟s, Schemas, other documentation).
    - Generate glue code and server code, and integrate it into their applications in their own test
        environment.
        In some cases the external parties have to provide RSVZ-INASTI with information:
            o If the external party has to provide the server side interface then that endpoint‟s
                information hast to be communicated.
    - Test their updated application with the pre-production environment of RSVZ-INASTI.

Cegeka N.V.                                                                                           page 48 of 60
B2B Web Service Guidelines V1                                               RSVZ Enterprise Architecture



Finally the running Release is removed from production and the new Release goes into production.


4.4.7 About Downloading Schema & WSDL Files
Guideline
Communicating partners MUST store a copy of the Schema and WSDL files locally.

The element <xsd:schemaLocation> MUST use relative path references, never absolute paths or url‟s.
Explanation
For optimal performance these files must be kept locally.

Also for robustness reasons these files are best kept locally. The RSVZ-INASTI website containing the
official schema and wsdl files may be down or unreachable for other reasons.

In xsd:schemaLocation relative references are preferred because they are more platform independent
(e.g. c: drive on Windows does not exist on Unix), can be moved throughout a directory structure, and
may even be independent of protocol (http, ftp, file…).
Also distribution using a .zip, .jar or .cab is easy this way.
Example

      <xsd:import
            namespace="http://www.rsvz-
inasti.fgov.be/schemas/WS/schema/LegalInfo/V1"
            schemaLocation="./schema/LegalInfo.xsd">
      </xsd:import>




Cegeka N.V.                                                                                page 49 of 60
B2B Web Service Guidelines V1                                              RSVZ Enterprise Architecture




4.4.8   Message Security
Guideline
Privacy and integrity of the message contents MUST be ensured.

Communicating partners (NISSE and SIFs) MUST authenticate each other.

Explanation

All of the requirements are fulfilled by using 2-way SSL.

Authentication of individual users requires more complex technologies, such as WS-Encryption (signature)
and e-ID.
Non-repudation also requires these technologies, by using a digital signature generated either by the
SIF‟s key or the individual user‟s key.




Cegeka N.V.                                                                               page 50 of 60
B2B Web Service Guidelines V1                                                                                    RSVZ Enterprise Architecture




4.4.9 Audit Logging
Guideline

All incoming and outgoing messages MUST be logged in an audit log.

The ApplHeader.Origin field MUST correspond with6 the sender‟s certificate‟s (2-way SSL) CN (Common
Name) to certify the Origin value.

The information listed in the table below MUST be logged:

    Security Policy                       Web Services SVF --> RSVZ                                       Web Services RSVZ --> SVF
                            Log SVF as Sender          Log RSVZ as Receiver                 Log RSVZ as Sender         Log SVF as Receiver
    Algemeen
    Timestamp               sent time                       received time                   sent time                       received time
    Communicatie type       POW or RR                       POW or RR                       POW or RR                       POW or RR
    Transport type          HTTP                            HTTP                            HTTP                            HTTP

    Bestemmeling
    ServerOrg Id            ApplHeader.Destination          ApplHeader.Destination          ApplHeader.Destination          ApplHeader.Destination
    ServerOrg MatrixId      ApplHeader.Destination          ApplHeader.Destination          ApplHeader.Destination          ApplHeader.Destination
    ServerOrg MatrixSubId   N/A                             N/A                             N/A                             N/A
    ServerOrgUserId         N/A                             N/A                             N/A                             N/A
    ServerOrgPgmId          ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID
    Verzender
    ClientOrg Id            ApplHeader.Origin               ApplHeader.Origin               ApplHeader.Origin               ApplHeader.Origin
    ClientOrg MatrixId      ApplHeader.Origin               ApplHeader.Origin               ApplHeader.Origin               ApplHeader.Origin
    ClientOrg MatrixSubId   N/A                             N/A                             N/A                             N/A
    ClientOrgUserId         ApplHeader.UserID               ApplHeader.UserID               N/A                             N/A
    ClientOrgPgmId          ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID   ApplHeader.RequestInitiatorID
    Bericht informatie
    MessageID               ApplHeader.MessageID            ApplHeader.MessageID           ApplHeader.MessageID             ApplHeader.MessageID
    MessageEnveloppe        SOAP-WS-2B                      SOAP-WS-2B                     SOAP-WS-2B                       SOAP-WS-2B
    MessageTimeRequest      ApplHeader.TimestampSent        ApplHeader.TimestampSent       ApplHeader.TimestampSent         ApplHeader.TimestampSent
    MessageServiceId                                         namespace naam + '/' + porttype-name + ':' + operation-name
    MessageVersion                                           namespace naam + '/' + porttype-name + ':' + operation-name
    CorrelationId           ApplHeader.FluxID               ApplHeader.FluxID              ApplHeader.FluxID                ApplHeader.FluxID
    Message                 {soap}Envelope                  {soap}Envelope                 {soap}Envelope                   {soap}Envelope

Explanation
This guideline is based on the RSVZ B2B Security Policy.doc.

In a 2-way SSL setup the client (or service consumer) sends its certificate to the server (or service
provider) amongst other things. If the SSL connection is successfully established this implies that the
certificate is correct, and that the client really is whom he claims to be (unless private key would have
been stolen).
Inside the certificate is the distinguished name proper to the client and known to the server. This way the
server can certify that the ApplHeader.Origin field is correct.

The first column is based on guidelines from the KSZ, and is described in RSVZ B2B Security Policy.doc.
All of these fields need to be logged, except those marked „N/A‟.

The second and third column described what needs to be logged, depending whether the SIF is the
initiating partner or NISSE.
     - SIF  NISSE: a SIF starts a Request-Reply, or a SIF sends a One Way to NISSE
     - NISSE  SIF: NISSE starts a Request-Reply, or NISSE sends a One Way to SIF

Remarks on the table:
   - N/A means „not applicable‟, meaning that this information is not logged.




6
 “Correspond” is not the same as “Equal” – which is in this case impossible anyway since the CN will be different from the Origin.
But there is a one to one relationship between the CN and the Origin which must be checked here.

Cegeka N.V.                                                                                                                           page 51 of 60
B2B Web Service Guidelines V1                                           RSVZ Enterprise Architecture


    -   General, Timestamp:
           o a timestamp generated together with the logging of an incoming message;
           o optionally the Applheader.TransferOk.Timestamp field for Pseudo One Way;
           o note: the timestamp that the message is sent is in MessageTimeRequest further down in
                the table
    -   Communication type:
           o POW = Pseudo One Way
           o RR = Request Reply
    -   MessageServiceId: This is a combination of:
           o the Web Service name as found in the <wsdl:definitions> name attribute, e.g.
                "Affiliation_V3" for version 3.x of Affiliation
           o a „-„
           o the operation named as found under the name attribute of the <wsdl:operation>
                element, e.g. “InvestigateNew” in Affiliation.
           o Example: “Affiliation_V3-InvestigateNew”


Example
-




Cegeka N.V.                                                                           page 52 of 60
B2B Web Service Guidelines V1                                                 RSVZ Enterprise Architecture



5. WSDL Templates
There are two different types of Web Services:
   - Web Services
   - Bulk Web Services, used for invoking bulk operations (including transferring bulk data).


Note: the Bulk Web Services are included here for possible future use. The guidelines earlier in this
document do not (yet) describe bulk web services.



5.1 WSDL for Non-Bulk Operations


5.1.1 Introduction
A Web Service has two parts: the operations offered by the INSS (Rsvz-Inasti) and the operations offered
by the Social Insurance Fund (SIF). Therefore we define two PortTypes per web service, one containing
the operations implemented by the INSS and one containing the operations implemented by a SIF. These
are contained in a WSDL file SERVICE.wsdl, where SERVICE stands for the service name.

A separate NisseSERVICE.wsdl file imports the SERVICE.wsdl definitions, and it defines the soap binding
and wsdl service definition for the Nisse‟s portType.

Similarly, SifSERVICE.wsdl file imports the SERVICE.wsdl definitions, and it defines the soap binding and
wsdl service definition for the Sif‟s portType.
Note that each SIF has a different service URL, and that the SifSERVICE.wsdl should contain this URL.
This is only an issue for INSS – the Sif‟s just communicate the URL for each service.

The templates contain placeholders in all capitals that have to be replaced by a suitable name.
Also we give an example of a Request Reply operation and a One Way operation; one is assigned to the
Sif PortType the other to the Nisse PortType – but both Nisse and Sif may define any number and type of
operations.

Placeholder       Meaning                                        Example
SERVICE           Name identifying the service                   LegalInfo
SERVICE_V1        Service name with major version indication.    LegalInfo_V2
OPERNAME-OW       Name of a One Way operation.                   InvestigateNewAffiliation
OPERNAME-RR       Name of a Request Reply operation.             GetLegalInfoByInss



5.1.2 WSDL Template - SERVICE.wsdl
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SERVICE_V1"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:tns="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:hlp="http://www.rsvz-inasti.fgov.be/schemas/WS/Helper/V1"
   xmlns:meta="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V1"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">

   <wsdl:import location="../Helper_V1.wsdl"
      namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/Helper/V1" />

   <wsdl:types>
      <xs:schema elementFormDefault="qualified"
         attributeFormDefault="unqualified"
         targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"


Cegeka N.V.                                                                                  page 53 of 60
B2B Web Service Guidelines V1                                      RSVZ Enterprise Architecture


        version="1.0">
        <xs:import
           namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V1"
           schemaLocation="../schema/MetaInfo/MetaInfo_V1.xsd" />

        <xs:element name="OPERNAME-OW">
           <xs:complexType>
              <xs:sequence>
                 <xs:element ref="meta:ApplHeader"   />
                 <!-- Here your operation specific   request -->
              </xs:sequence>
           </xs:complexType>
        </xs:element>
        <xs:element name="OPERNAME-RR">
           <xs:complexType>
              <xs:sequence>
                 <xs:element ref="meta:ApplHeader"   />
                 <!-- Here your operation specific   request -->
              </xs:sequence>
           </xs:complexType>
        </xs:element>
        <xs:element name="OPERNAME-RROut">
           <xs:complexType>
              <xs:sequence>
                 <!-- Here your operation specific   reply -->
              </xs:sequence>
           </xs:complexType>
        </xs:element>
     </xs:schema>
  </wsdl:types>

  <wsdl:message name="OPERNAME-OWMsg">
     <wsdl:part element="tns:OPERNAME-OW" name="in" />
  </wsdl:message>
  <wsdl:message name="OPERNAME-RRMsg">
     <wsdl:part element="tns:OPERNAME-RR" name="in" />
  </wsdl:message>
  <wsdl:message name="OPERNAME-RROutMsg">
     <wsdl:part element="tns:OPERNAME-RROut" name="out" />
  </wsdl:message>

  <wsdl:portType name="SifSERVICE">
     <wsdl:operation name="OPERNAME-OW">
        <wsdl:input message="tns:OPERNAME-OWMsg" />
        <wsdl:output message="hlp:TransferResultMsg" />
        <wsdl:fault name="SystemError" message="hlp:SystemErrorMsg" />
     </wsdl:operation>
  </wsdl:portType>

  <wsdl:portType name="NisseSERVICE">
     <wsdl:operation name="OPERNAME-RR">
        <wsdl:input message="tns:OPERNAME-RRMsg" />
        <wsdl:output message="tns:OPERNAME-RROutMsg" />
        <wsdl:fault name="SystemError" message="hlp:SystemErrorMsg" />
     </wsdl:operation>
  </wsdl:portType>

</wsdl:definitions>




5.1.3 Nisse WSDL template – NisseSERVICE.wsdl
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SERVICE_V1"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:tns="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">


Cegeka N.V.                                                                      page 54 of 60
B2B Web Service Guidelines V1                                     RSVZ Enterprise Architecture



  <wsdl:import
     namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
     location="SERVICE.wsdl" />

  <wsdl:binding name="NisseSERVICESoapBinding"
     type="tns:NisseSERVICE">
     <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http" />
     <wsdl:operation name="OPERNAME-RR">
        <soap:operation soapAction="" />
        <wsdl:input>
           <soap:body use="literal" />
        </wsdl:input>
        <wsdl:output>
           <soap:body use="literal" />
        </wsdl:output>
        <wsdl:fault name="SystemError">
           <soap:fault name="SystemError" use="literal" />
        </wsdl:fault>
     </wsdl:operation>
  </wsdl:binding>

   <wsdl:service name="SERVICEService">
      <wsdl:port binding="tns:NisseSERVICESoapBinding"
         name="SERVICEPort">
         <soap:address
            location="http://your.domain:80/NisseSERVICE_V1" />
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>


5.1.4 Sif WSDL Template – SifSERVICE.wsdl
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SERVICE_V1"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:tns="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

  <wsdl:import
     namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/SERVICE/V1"
     location="SERVICE.wsdl" />

  <wsdl:binding name="SifSERVICESoapBinding" type="tns:SifSERVICE">
     <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http" />
     <wsdl:operation name="OPERNAME-OW">
        <soap:operation soapAction="" />
        <wsdl:input>
           <soap:body use="literal" />
        </wsdl:input>
        <wsdl:output>
           <soap:body use="literal" />
        </wsdl:output>
        <wsdl:fault name="SystemError">
           <soap:fault name="SystemError" use="literal" />
        </wsdl:fault>
     </wsdl:operation>
  </wsdl:binding>

   <wsdl:service name="SERVICEService">
      <wsdl:port binding="tns:SifSERVICESoapBinding"
         name="SERVICEPort">
         <soap:address location="http://domainname/SifSERVICE_V1" />
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

Cegeka N.V.                                                                     page 55 of 60
B2B Web Service Guidelines V1                                              RSVZ Enterprise Architecture


5.1.5 Helper WSDL
The wsdl messages SystemErrorMsg and TransferResultMsg are defined once in a helper WSDL with its
own namespace and imported in all other WSDL‟s.

This technique ensures that SystemError and TransferResult are only defined once. For example, n the
WSDL generated code there will be only one SystemError or TransferResult class.

Helper_V1.wsdl:
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="Helper_V1"
   targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/Helper/V1"
   xmlns:tns="http://www.rsvz-inasti.fgov.be/schemas/WS/Helper/V1"
   xmlns:meta="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V4"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">

   <wsdl:documentation>
      Baseline: @BASELINE@
   </wsdl:documentation>

   <wsdl:types>
      <xs:schema elementFormDefault="qualified"
         attributeFormDefault="unqualified"
         targetNamespace="http://www.rsvz-inasti.fgov.be/schemas/WS/Helper/V1"
         version="1.0">
         <xs:import
            namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V4"
            schemaLocation="./schema/MetaInfo/MetaInfo_V4.xsd" />
      </xs:schema>
   </wsdl:types>

   <wsdl:message name="TransferResultMsg">
      <wsdl:part element="meta:TransferResult" name="result" />
   </wsdl:message>
   <wsdl:message name="SystemErrorMsg">
      <wsdl:part element="meta:Error" name="systemError"></wsdl:part>
   </wsdl:message>
</wsdl:definitions>




5.1.6 MetaInfo.xsd
See schema.




Cegeka N.V.                                                                              page 56 of 60
B2B Web Service Guidelines V1            RSVZ Enterprise Architecture


5.2 WSDL for Bulk Operations – Mailbox


Removed.




Cegeka N.V.                                            page 57 of 60
B2B Web Service Guidelines V1                                         RSVZ Enterprise Architecture



6. References
FedICT Guidelines
FedICT RSVZ Service Interface Guidelines.pdf


xFront Guidelines
Element Versus Type
Global Versus Local Elements
Hide Versus Expose
Schema Versioning
Zero, One, Or Many Namespaces


Other documents
Document Literal Wrapped: http://www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/
Security Policy: RSVZ B2B Security Policy.doc




Cegeka N.V.                                                                         page 58 of 60
B2B Web Service Guidelines V1                                                                  RSVZ Enterprise Architecture



7. Appendix 1 – Configuration Mgmt Concepts
7.1 Web Services as Interfaces
Web Services are essentially interfaces, things through which functionality is achieved or executed.
Interfaces must have a description describing the structure of this interface and how to use it. WSDL‟s
are the most important part of this interface description, with the added advantage that all
communication code can be generated from it.

RSVZ-INASTI will issue the interface descriptions, which the external parties (funds…) must adhere
to7. These descriptions are:
     - WSDL (.wsdl) document, containing:
            o PortTypes: a set of operations; PortType is also called „abstract interface‟.
            o Operations, including input and optionally output parameters, as well as faults
            o Structure of the parameters en fault, defined with XML Schema
            o A binding of the PortType to the soap protocol and, more importantly, a URL where the
                service is offerred and can be called
     - Accompagning documentation:
            o For other transport protocols than http: transport type, ip adresses etc.
                      For http these data are included in the WSDL.
            o Functional information on the operations.
            o Other information, such as authentication and authorisation information, maximum sizes,
                etc.
     - Schemas imported by the WSDL, and used indirectly for input and output parameters.

An implementation of a web service then is an interface. Often the term interface is used for the
implementation or its description – the context makes clear what is meant.
The one providing the interface implementation is the „server‟, the one using the interface is the „client‟.

Depending on the functionality or operation either RSVZ-INASTI is the server or a Fund is the server. For
B003, Request Legal Info, for example, RSVZ-INASTI is the server side and a Fund is the client side. For
A020, Disablement, a Fund is the server side and RSVZ-INASTI is the client side.

7.2 Configuration Items & Versions
All files, including WSDL files, Schema files or even accompagning documentation, are configuration
items.

A configuration is a set of configuration items that are used together. For example, a WSDL file imports
one or more Schema files that it needs and is accompanied by a Word document describing its operations
more functionally; all these files together form a configuration.

Each configuration item has a version. The rules for version numbers are defined elsewhere in this
document.

Taking into account versions of configuration items, a configuration is a set of configuration items
whereby each configuration item has a specific version. In this respect we also speak of a baseline. In
practice some text label indicating the baseline, e.g. “build_of_2007-04-01” is attached to each included
configuration item version – this label then is the baseline label.

In the example below the “build_of_2007-04-01” baseline consists of Affiliation.wsdl version 1.1 and
Base.xsd version 1.2.




7
    We do not and cannot include interfaces that RSVZ-INASTI does not control, such as web services defined by KSZ.

Cegeka N.V.                                                                                                      page 59 of 60
B2B Web Service Guidelines V1                                                RSVZ Enterprise Architecture


Affiliation.wsdl   V1.0
Affiliation.wsdl   V1.1   build_of_2007-04-01
Base.xsd           V1.0
Base.xsd           V1.1
Base.xsd           V1.2   build_of_2007-04-01

A release is a baseline that has been tested and approved for production. While a baseline is not yet a
release, while it is in teste, we speak of a release candidate –when tests are successful it becomes a
release, if not successful it remains a –failed– release candidate.
Release labels have a specific form and meaning, defined later in this document.

7.3 From Change Requests (CR) to Releases
Change Requests (CR) are described in a separate document; here we only describe the relationship to
configuration management and releases.

Once a CR has been approved it is assigned to a future release of some WSDL(s) and other configuration
items. It is possible that this will be the next release on which work is already under way, or in a later
release scheduled for perhaps 6 months later. This is a decision of the Change Control Board (CCB).

A Release is in fact a collection of implemented Change Requests, assigned to that Release. It is not
feasible to have one Release per CR – this would cause very frequent new releases and associated work
from all parties involved.
Interfaces are used by many parties ( 10 funds), so any change in an interface impacts all of these
parties.

Therefore each change and release must be carefully coordinated, and with tens op participating parties
this is not an easy task. This coordination is, again, the responsibility of the Change Control Board.




Cegeka N.V.                                                                                 page 60 of 60

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:2
posted:11/12/2011
language:English
pages:60