B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
Owner
Version
Last changed on
Dirk Vaneynde / Gert Driesen
23
31/07/2017 16:50
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-2017
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
History
Date
22/3/2007
22/11/2007
11/2/2008
12/2/2008
3/12/2008
27/1/2009
29/1/2009
5/3/2009
Description
Translation to English
 Operation naming convention (4.3.1)
 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 XML 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).
 SOAP faultstring & faultactor specified
 Removed FluxID copying in 4.3.3 (bug)
 WSDL for Bulk Operations - Removed (5.2)
Updated guideline wrt SOAPAction.
Major rework: fluxes, faults, configuration
management, new operation types.
 Enumerations – rewritten for clarity (5.2.10)
 Code and Description (5.2.11)
 URI References (5.2.12)
 WSDL Style and Use (5.2.13)
 Bulk Operations (5.3.3) – order is not guaranteed
 Error handling (5.3.7) – removed BusinesViolation
and BcssError
 Handling of System Errors / Idempotence –
rewritten for clarity (5.3.8)
 Interface Documentation (5.4)
 Unique Identifiers (5.2.14)
 About Downloading Schema & WSDL Files –
rewritten for clarity (5.5.8)
 Pseudo One-Way (5.3.2) – removed TransferResult
requirement
 Bulk Operations (5.3.3) – describe updated struct
 ApplHeader (5.3.6) – describe updated struct


21/4/2009
27/7/2009


21/01/2010

26/04/2010


Cegeka N.V.
Error Handling (5.3.7) – added AuthenticationFault
and AuthorizationFault
Support for Fluxes (5.3.9) – describe updated
struct
Removed references to WS-RM
WSDL Style and Use (5.2.13) – added information
on XmlSerializer for WCF
Bulk Operations (5.3.3) – describe need for unique
MessageID for individual chunks.
Certificate Request (6.1) – added
Certificate Renewal (6.2) – added
Author
Dirk Vaneynde
Dirk Vaneynde
Dirk Vaneynde
Gert Driesen
Dirk Vaneynde
Gert Driesen
Gert Driesen
Gert Driesen
Gert Driesen
Gert Driesen
Gert Driesen
Gert Driesen
page 2 of 70
B2B Web Service Guidelines V2
18/06/2010







03/12/2010


Cegeka N.V.
Pseudo One-Way (5.3.2) – removed information
on how to construct the ApplHeader for a POW
reply as this information is specific to the version
of the MetaInfo XSD
Bulk Operations (5.3.3) – removed specifics on the
BlockStruct as this information is now part of the
interface documentation for the MetaInfo XSD
ApplHeader (5.3.6) – moved information that is
specific to a given version of the MetaInfo XSD to
the interface documentation of that XSD
Service Definition Anatomy (5.5.2) – remove
references to WS-ReliableMessaging
Versions (5.5.3) – remove distinction between
major and minor version
WSDL Templates – removed
Binary content (5.3.10) – added guideline on
transferring data
Message Security (5.6.1) – added link to RSVZ
certificates URL
Certificate Renewal (6.2.2) – added link to RSVZ
certificates URL
RSVZ Enterprise Architecture
Gert Driesen
page 3 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
Table of Contents
1.
INTRODUCTION ............................................................................................................... 6
2.
REFERENCES .................................................................................................................... 7
3.
CONTEXT .......................................................................................................................... 8
4.
GLOSSARY ...................................................................................................................... 10
5.
GUIDELINES ................................................................................................................... 12
5.1
GENERAL .............................................................................................................................. 12
5.2
SCHEMA NAMESPACES .............................................................................................................. 13
5.3
WEB SERVICES ...................................................................................................................... 30
5.4
INTERFACE DOCUMENTATION ..................................................................................................... 47
5.5
CONFIGURATON MANAGEMENT & RELEASE MANAGEMENT.................................................................. 48
5.6
SECURITY ............................................................................................................................. 63
5.1.1
Standards .................................................................................................................... 12
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
5.2.6
5.2.7
5.2.8
5.2.9
5.2.10
5.2.11
5.2.12
5.2.13
5.2.14
Always use a Target Namespace in schemas .................................................................. 13
elementFormDefault & attributeFormDefault .................................................................. 14
Default namespace and qualifiers .................................................................................. 15
Prefixes ....................................................................................................................... 16
Reuse & Encapsulation: Local vs. Global Elements, Elements vs. Types ........................... 17
Schema element & type name conventions .................................................................... 19
Substitution groups ...................................................................................................... 20
Use of <xs:redefine> ................................................................................................... 21
Documentation & Comments ......................................................................................... 22
Enumerations ............................................................................................................... 23
Code and Description.................................................................................................... 25
URI References ............................................................................................................ 26
WSDL Style and Use ..................................................................................................... 27
Unique Identifiers ......................................................................................................... 29
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.3.8
5.3.9
5.3.10
Taxonomy of Operations ............................................................................................... 30
Pseudo One-Way .......................................................................................................... 32
Bulk Operations ............................................................................................................ 34
Operation Names ......................................................................................................... 35
SOAPAction .................................................................................................................. 36
ApplHeader .................................................................................................................. 37
Error Handling .............................................................................................................. 38
Handling of System Errors - Idempotence ...................................................................... 40
Support for Fluxes ........................................................................................................ 44
Binary content .............................................................................................................. 45
5.4.1
5.4.2
5.4.3
Identification ................................................................................................................ 47
Operations ................................................................................................................... 47
Samples ....................................................................................................................... 47
5.5.1
5.5.2
5.5.3
5.5.4
5.5.5
5.5.6
5.5.7
5.5.8
Introduction of Concepts............................................................................................... 48
Service Definition Anatomy ........................................................................................... 50
Versions....................................................................................................................... 52
Modifications and Version Impact Analysis ..................................................................... 55
Releases ...................................................................................................................... 56
Service Implementation Aspects & Versioning ................................................................ 58
Life Cycle of Releases ................................................................................................... 60
About Downloading Schema & WSDL Files ..................................................................... 62
5.6.1
5.6.2
Message Security ......................................................................................................... 63
Audit Logging ............................................................................................................... 63
6.
APPENDIX ...................................................................................................................... 65
6.1
CERTIFICATE REQUEST............................................................................................................. 65
6.1.1
6.1.2
Cegeka N.V.
Server certificate .......................................................................................................... 65
Client certificate ........................................................................................................... 67
page 4 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
6.1.3
6.1.4
Key Length .................................................................................................................. 68
Procedure .................................................................................................................... 68
6.2.1
6.2.2
Social Insurance Fund .................................................................................................. 69
RSVZ ........................................................................................................................... 70
6.2
CERTIFICATE RENEWAL ............................................................................................................ 69
Cegeka N.V.
page 5 of 70
B2B Web Service Guidelines V2
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 all guidelines on the design and use of Web Services between RSVZ-INASTI and
the Social Insurance Funds.
Chapter 3 gives context information on the guidelines. Specifically the role of XML Schema and WSDL –
Web Service Description Language – is explained.
Chapter 4 describes the terminology used in this document.
In chapter 5 the guidelines are listed one by one, including explanation and an example.
Finally chapter 6 describes the procedure for the initial certificate request, and the renewal of certificates.
Cegeka N.V.
page 6 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
2. References
2.1.1.1 FedICT Guidelines
FedICT RSVZ Service Interface Guidelines.pdf
2.1.1.2 xFront Guidelines
Element Versus Type
Global Versus Local Elements
Hide Versus Expose
Schema Versioning
Zero, One, Or Many Namespaces
2.1.1.3 Other documents
Document Literal Wrapped:
http://www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/
Cegeka N.V.
page 7 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
3. 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 Service 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-INASTI 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 personnel 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.
3. A technical person then integrates the generated code with the SIF’s own application code. Two
possibilities:
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 8 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
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 (phases 1a, 1b
and 2a), codegeneration is possible from the schemas, but with some important restrictions:
- Schema is intended to describe possible documents; it is not centered on functionality or
operations as WSDL is. In WSDL functionality comes first, with Schema alone you need to add
additional written documentation on what to do with the transferred documents.
- 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 which 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 process of being standardized. Existing WSDL’s and Web Services can
be extended with these features almost transparently 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 9 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
4. Glossary
Bulk Operation
One-Way Operations that have the additional aspect of sending large datasets,
as a sequence of chunks, where each transfer of a chunk corresponds to one
operation execution.
See also “Taxonomy of Operations” at page 30.
Business Errors
System Errors
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...”.
Document Literal
Wrapped
DLW
Convention on web services.
See http://www-128.ibm.com/developerworks/webservices/library/wswhichwsdl/.
Flux
Message Flux
A Message Flux is a set of messages that is used together, in the sense that
they are related to the same function.
Where each message is identified individually by a unique number (in
ApplHeader.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.
A caller sends a message to a callee, and does not wait for an answer.
One-Way Operation
See also “Taxonomy of Operations” at page 30.
Pseudo One-Way
Operation
Request-Response
Operation
See Pseudo One-Way over HTTP - Idempotent Operations on page 32.
The caller waits until it receives a response – it does not do anything else
meanwhile. This is very similar to a function call in most programming
languages.
See also “Taxonomy of Operations” at page 30.
Service Consumer
Software making use of a service, by sending a message to it and possibly
waiting for an answer.
Possible aliases:
 ‘caller’, i.e. ‘caller of a service’.
 ‘client’ as the client-side of a client-server relationship.
 ‘sender’ or ‘initiator’, as they send a message and/or initiate sending a
request message and wait for the reply.
Service Provider
Software providing and implementing a service.
Possible aliases:
 ‘callee’, the opposite of ‘caller’.
 ‘server’ as the server-side of a client-server relationship.
 ‘receiver’ as they listen for incoming messages, doing some business
functionality (and optionally send back another message)
Cegeka N.V.
page 10 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
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/.
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 file
WSDL = Web Service Description Language
XML file that describes actual Web Service operations and message exchanges,
as well as the protocols used and the actual address of the service or
‘endpoint’.
See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/
Cegeka N.V.
page 11 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5. Guidelines
Note: the terms “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, “MAY”, “REQUIRED”, “OPTIONAL” when they appear in all-capitals - must be understood as in http://www.faqs.org/rfcs/rfc2119.html.
5.1 General
5.1.1 Standards
5.1.1.1 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, conformance with WS-I Basic Profile is the overall goal for the B2B guidelines and the
implementation.
5.1.1.2 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.
WS-I help us to achieve maximum platform interoperability, which is interoperability between BEA, IBM,
Oracle, Sun, open source and Microsoft implementations.
5.1.1.3 Example
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" ...>
Cegeka N.V.
page 12 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2 Schema Namespaces
Here we describe guidelines specific to the schemas, this is the .XSD files as well as the schema definition
part in the .WSDL files.
5.2.1 Always use a Target Namespace in schemas
5.2.1.1 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).
5.2.1.2 Explanation
Namespaces define a scope for the name of elements, types and attributes, so that two elements can
have the same name as long as they belong to different namespaces. 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.
5.2.1.3 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 13 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.2 elementFormDefault & attributeFormDefault
5.2.2.1 Guideline
When defining a schema you MUST specify the following in the <schema> element:
- elementFormDefault=”qualified”
- attributeFormDefault=”unqualified”.
5.2.2.2 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.
In the case of attributes the opposite approach is taken, since intuitively attributes belong to their
element and thus implicitly have the same namespace. A prefix is thus unnecessary.
5.2.2.3 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 14 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.3 Default namespace and qualifiers
5.2.3.1 Guideline
If a default namespace is used in a schema definition, then it MUST be that of the target namespace.
5.2.3.2 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.
5.2.3.3 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 15 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.4 Prefixes
5.2.4.1 Guideline
You SHOULD use these prefixes for the listed namespaces:




xs
soap
wsdl
tns
W3C Schema namespace
SOAP namespace
WSDL namespace
target namespace
5.2.4.2 Explanation
Standardising prefixes improves human readability, and developer productivity.
Cegeka N.V.
page 16 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.5 Reuse & Encapsulation: Local vs. Global Elements, Elements vs. Types
5.2.5.1 Guideline
Local elements SHOULD be preferred over global elements.
For reuse, types SHOULD be preferred over global elements.
5.2.5.2 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 who takes a look at 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, exist 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, and then
drill down to its internals.
5.2.5.3 Example
Below we first have a type definition, RelationshipStruct. This is then used to define a local element
Relationship in AcceptAffiliationType. Finally, a global element AcceptAffiliation is created of that latter
type.
<xs:complexType name="RelationshipStruct">
<xs:sequence>
<xs:element name="Century" type="CenturyType" minOccurs="0">
…
</xs:complexType>
Then RelationshipStruct is re-used to define an element named Relationship, in yet another type
<xs:complexType name="AcceptAffiliationStruct">
<xs:complexContent>...
<xs:element name="Relationship" type="tns:RelationshipStruct" minOccurs="0" />
</xs:complexContent>
</xs:complexType>
<xs:element name="AcceptAffiliation" type="tns:AcceptAffiliationStruct" />
Another example on the schema extension mechanism:
<xs:complexType name="AbstractResultStruct" abstract="true" />
<xs:complexType name="NoMatchStruct">
<xs:complexContent>
<xs:extension base="AbstractResultStruct">
<xs:sequence>
<xs:element name="Code">
...
</xs:complexType>
<xs:complexType name="MatchesStruct">
<xs:complexContent>
<xs:extension base="AbstractResultStruct">
Cegeka N.V.
page 17 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
...
</xs:complexType>
The element Result is then defined with type AbstractResultType:
<xs:element name="Result" type="AbstractResultStruct"/>
An XML instance must use the xsi:type attribute to signal the actual type:
<p:Result xsi:type="p:NoMatchStruct"
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 18 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.6 Schema element & type name conventions
5.2.6.1 Guideline
Names SHOULD follow UpperCamelCase convention.
Names of simple types SHOULD end with suffix “Type”.
Names of complex types SHOULD end with suffix “Struct”.
5.2.6.2 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 again start with an
upper case letter.
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.
5.2.6.3 Example
<xs:simpleType name="CompanyIDType">
<xs:restriction base="xs:string">
<xs:maxLength value="10" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="CompanyStruct">
<xs:sequence>
<xs:element name="Name" type="xs:string" />
<xs:element name="CompanyID" type="CompanyIDType" />
</xs:sequence>
<xs:attribute name="IsActive" type="xs:boolean" />
</xs:complexType>
Cegeka N.V.
page 19 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.7 Substitution groups
5.2.7.1 Guideline
Substitution groups MUST NOT be used.
5.2.7.2 Explanation
Substitution group elements must be defined as global elements. This is inconsistent with the guideline
on re-use and encapsulation.
Code generators 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 20 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.8 Use of <xs:redefine>
5.2.8.1 Guideline
The technique <xs:redefine> SHOULD NOT be used.
5.2.8.2 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 21 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.9 Documentation & Comments
5.2.9.1 Guideline
For documentation or comments the annotation and documentation elements MUST be used.
XML comments (<!-- xml comment -->) MUST NOT be used for documentation purposes.
5.2.9.2 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.
5.2.9.3 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 22 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.10 Enumerations
5.2.10.1 Guideline
1.
2.
3.
4.
5.
XSD
XSD
XSD
XSD
XSD
enumerations
enumerations
enumerations
enumerations
enumerations
MUST only be used for value-sets that are relatively stable and limited in size.
of type xs:string MUST be composed of letters, numbers or an underscore.
of type xs:string MUST NOT start with a number.
of type xs:string MUST NOT only differ in case.
of type xs:string SHOULD be preferred over other types.
5.2.10.2 Explanation
Using enumerations has the advantage that only prescribed values can be used, since the possible values
are validated against a set prescribed in the schema.
The downside is: any addition or removal of a value requires a minor or major upgrade of the defining
schema. This implies that all parties involved must integrate the new schema. Therefore one must be
sure that the set of values in the enumeration will not change, at least for the normal life of a schema
version.
Some examples:
 NACE codes must not be enumerations. The messages that somewhere use a NACE code will
change less frequently than the set of NACE codes, overall.
 Error codes must never be part of enumerations. A backend-system might add an error code at
any time, rather independently. It is better to describe these errorcodes in a separate humanreadable document.
 Male/Female is a good candidate for an enumeration. Adding a third option, like ‘Unspecified’,
would mean that there are a lot of other accompanying business changes, so the schema change
would be necessary anyway and would be part of a much bigger rework of different systems and
databases.
 Other legally prescribed values are also a good candidate for an enumeration, as far as they do
not change too much and that they are closely related to the business processes involved.
Enumations of type xs:string are preferred since they are better suited to be transformed into
language constructs.
Web Service frameworks that generate code for these enumerations, are limited by the language and
development platform that they are targeting.
Not all frameworks support generating enums for types other than xs:string, mostly because
identifiers are required to start with a letter.
5.2.10.3 Example
Good example:
<xs:simpleType name="GenderType">
<xs:restriction base="xs:string">
<xs:enumeration value="male" />
<xs:enumeration value="female" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Person">
<xs:sequence>
<xs:element name="Name" type="xs:string" />
<xs:element name="Gender" type="tns:GenderType" />
</xs:sequence>
</xs:complexType>
Cegeka N.V.
page 23 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
Java code:
public enum GenderType {
MALE("male"),
FEMALE("female");
}
public class Person {
protected String name;
protected GenderType gender;
public String getName() {
return name;
}
public void SetName(String value) {
this.name = value;
}
public GenderType getGender() {
return gender;
}
public void SetGender(GenderType value) {
this.gender = value;
}
}
C# code:
public enum GenderType : int {
male = 0,
female = 1
}
public partial class Person {
private string NameField;
private GenderType GenderField;
public string Name {
get { return this.NameField; }
set { this.NameField = value; }
}
public GenderType Gender {
get { return this.GenderField; }
set { this.GenderField = value; }
}
}
Cegeka N.V.
page 24 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.11 Code and Description
5.2.11.1 Guideline
1. A code element SHOULD NOT be accompagnied by a textual description of the code when the
value-set is stable or common knowledge.
2. For codes that are not accompanied by a textual description, the XSD or the interface
documentation SHOULD include a textual description of each item in the value-set or a reference
to it.
5.2.11.2 Explanation
A textual description of a code is only useful for presentation purposes, and would affect the size of all
exchanged messages – even if the description would hardly ever change.
Localization of messages, and presenting codes in a human-readable form SHOULD be a feature of
consuming applications, and is usually implemented using resource bundles or code tables.
Below is an example of a NisseProfession element, which describes the profession of a person.
Good example:
<xs:element name="NisseProfession">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="6" />
</xs:restriction>
</xs:simpleType>
</xs:element>
Bad example:
<xs:element name="NisseProfession">
<xs:complexType>
<xs:sequence>
<xs:element name="Code">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="6" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="Description" type="xs:string" minOccurs="0" />
</xs:sequence>
</xs:complexType
</xs:element>
Cegeka N.V.
page 25 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.12 URI References
5.2.12.1 Guideline
1. The case of a URI MUST exactly match the actual location and filename of a referenced
document.
2. To refer to other documents in the same tree, you MUST use relative path references.
3. The slash "/" character MUST be used to separate hierarchical components.
5.2.12.2 Explanation
If the case of a URI does not match the actual location and filename of a referenced file, then that file
cannot be found when the scheme is case-sensitive.
URI references that refer to the same document but differ in case are not considered equivalent. In the
context of WSDL/XSD imports and includes, this can cause definitions from the same document to be
imported more than once.
imported schema’s
VierdeWeg_V1.xsd
NisseVierdeWeg_V1.wsdl
vierdeweg_V1.xsd
schemaLocation=”vierdeweg_v1.xsd”
NisseVierdeWeg_V1.xsd
VierdeWeg_V1.xsd
schemaLocation=”VierdeWeg_V1.xsd”
Relative addressing of URI allows document trees to be partially independent of their location and access
scheme. For instance, it is possible for a single set of documents to be simultaneously accessible and
traversable via multiple schemes if the documents refer to each other using relative URI. Such document
trees can be moved, as a whole, without changing any of the relative references.
According to RFC 2396, URI references that do make use of the slash "/" character for separating
hierarchical components are considered opaque by the generic URI parser. Although some URI parsers
do support other separator characters for hierarchical components, using them disables interoperability.
Good example:
<xs:import namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/VierdeWeg/V1"
schemaLocation="schema/VierdeWeg/VierdeWeg_V1.xsd" />
Bad example:
<xs:import namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/VierdeWeg/V1"
schemaLocation="schema\VierdeWeg/VierdeWeg_V1.xsd" />
Cegeka N.V.
page 26 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.13 WSDL Style and Use
5.2.13.1 Guideline
A WSDL document MUST use the document/literal wrapped style, meaning:
1.
2.
3.
4.
5.
6.
Each part definition MUST reference a global element declaration defined, imported, or included
in the types section of the WSDL document.
In the binding definition, the soap:binding MUST specify style="document" (this is the default
value), and the soap:body definitions MUST specify use="literal".
Input and output messages (if present) MUST contain exactly one part.
The element definitions are "wrapper" elements; the input and output parameters are defined as
element structures within these wrapper elements.
A wrapper element MUST be defined as a complex type that is a sequence of elements (with no
attributes).
The name of the input wrapper element MUST be the same as the operation name.
The Web Services stack in Windows Communication Foundation (WCF) imposes the following additional
requirements:
1.
2.
3.
4.
5.
Message part for input or output parameters MUST always be named "parameters".
For headers, the message part MUST have “header” as name.
For faults, the message part MUST be named “detail”.
The name of the response wrapper element MUST be the same as the operation name with suffix
“Response”.
The elements representing input or output parameters which are mapped to “object types” must
be nillable.
The JAX-WS 2.0 specification (JSR-000224) adds the following criteria:
1.
2.
The wrapper elements MUST NOT contain other structures such as wildcards (element or
attribute), xsd:choice, substitution groups (element references are not permitted) or attributes;
furthermore, they MUST NOT be nillable.
Wrapper child elements with the same local name MUST also have the same type.
The JAX-WS 2.0 specification and WCF specify difference criteria with regards to the nillability of
parameters. Therefore, the only valid approach here is to compare the results on both.
Microsoft recommends using the XmlSerializer (instead of the DataContractSerializer) when dealing
with contract-first design. This can be accomplished by passing the following options to svcutil.exe:
Option
/useSerializerForFaults
/serializer:XmlSerializer
Description
This option specifies whether the serializer specified in the 'serializer' switch
is used for fault contract types.
DataContractSerializer is used for faults if this switch is not specified.
Generate data types that use the XmlSerializer for serialization and
deserialization.
More information is available here.
Cegeka N.V.
page 27 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.13.2 Explanation
WSDL distinguishes two different binding styles for SOAP:

Document style
Indicates that the SOAP body simply contains an XML document. The sender and receiver
must agree on the format of the document ahead of time.

RPC style
Specifies that the SOAP body contains an element with the name of the Web method being
invoked. This element in turn contains an entry for each parameter and the return value of
this method.
The strength of the “document” style (compared to RPC) is that the soap:body is completely defined by
XML Schema, allowing the message to be validated before invoking an operation on the service producer.
The “Use” attribute specifies the encoding rules of the SOAP message. This concerns how types are
represented in XML. The two offered choices are:

Encoding
Each message part references an abstract type using the type attribute.

Literal
If the use is Literal, each part references a concrete schema definition using either the
element or type attribute; in other words, data is serialized according to a given schema. In
practice, this schema is usually expressed using W3C XML Schema.
Neither document/encoded nor RPC/encoded are WS-I compliant, so that leaves us with the
document/literal binding model.
Apart from the mentioned styles and uses, there’s another very commonly used style called
document/literal wrapped. Its advantage over the document/literal (non-wrapped) style is that the
operation name is in the SOAP message, so the receiver can dispatch the message easiliy.
Although there’s no formal specification that defines the style, document/literal wrapped has become the
de facto standard for defining interoperable Web Services.
Cegeka N.V.
page 28 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.2.14 Unique Identifiers
5.2.14.1 Guideline
When a given element is intended as a unique identifier:
1.
2.
The application that creates the identifier MUST ensure the value is unique within its application.
A unique identifier MUST be combined with the identity of the originator to obtain an identifier
that is unique across all partners.
5.2.14.2 Explanation
While mechanisms exist to generate a Universally Unique Identifier, these implementations may not be
available on all hardware or development platforms.
Depending on the actual implementation, the identifier may also reveal private information such as the
identity of the computer that created the UUID.
Combining the unique identifier with the identity of the organization that created it, results in a more
controlled approach while still guaranteeing uniqueness across all parties involved.
For example:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<v3:GetLegalInfoByInss xmlns:v3="http://www.rsvz-inasti.fgov.be/.../V3">
<meta:ApplHeader xmlns:meta="http://www.rsvz-inasti.fgov.be/.../V4">
<meta:TimestampSent>2008-09-29T03:49:45</v4:TimestampSent>
<meta:Origin>
<meta:Organization>003</meta:Organization>
<meta:Application>SOCIAS</meta:Application>
</meta:Origin>
<meta:Destination>
<meta:Organization>000</meta:Organization>
<meta:Application>200</meta:Application>
</meta:Destination>
<meta:MessageID>004</meta:MessageID>
</meta:ApplHeader>
<v3:Inss>73081328744</v3:Inss>
</v3:GetLegalInfoByInss>
</soap:Body>
</soap:Envelope>
In this example, the MessageID is intended as the identification of the message exchange. A receiving
application combines the value of the MessageID element (i.e. 004) with the identity of the sender to
obtain an identifier that is unique across all partners.
Cegeka N.V.
page 29 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3 Web Services
5.3.1 Taxonomy of Operations
5.3.1.1 Guideline
A B2B Web Service operation MUST be one of the following Concrete Operation Types:
1. RR – Request Reply over SOAP/HTTP
2. POW – Pseudo One Way over SOAP/HTTP
3. B-POW – Bulk POW over SOAP/HTTP
NISSE MUST support all of these Operation Types.
5.3.1.2 Explanation
Conceptually, a B2B Web Service is either a Request-Reply (RR) operation, or a One-Way (OW)
operation2. The table below defines these terms.
Note the following aliases:
 Caller = Service Consumer = Client
 Callee = Service Producer = Server
Request-Response
Operation
The caller waits until he receives a response. The caller does not do any other
work until a response is received.
1 request
caller
callee
2 response
Web Service
Server
5.3.1.2.1
This is very similar to a function call in most programming languages.
Typically, the caller will only wait for a limited time (timeout), to avoid being
blocked forever when no answer returns, e.g. when the callee crashes in
between.
One-Way Operation
A caller sends a message to a callee, and does not wait for an answer but
immediately continues working.
message
caller
callee
Web Service
Server
2
The SOAP specification mentions Request-Response and One-Way, and is similar to our concepts. The WSDL specification has 4
message exchange patterns, including Request-Reply and One-Way, but is very abstract, binding dependent, and unclear. In
practice the solutions we propose here work very well in soap and wsdl.
Cegeka N.V.
page 30 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
The example below shows a typical case, where two one-way operations are
used, one to ask for the latest income data, and the other in the opposite
direction for the result.
1.sendIncomeUpdate()
caller
callee
callee
caller
2.processIncomeUpdate
Both sendIncomeUpdate() and processIncomeUpdate() are two separate oneway operations. Once the calling party has called sendIncomeUpdate() he can
continue doing other stuff – he does not wait for any reply.
Later – seconds, hours or weeks – the roles reverse and the original callee now
calls processIncomeUpdate() on the original caller.
In practice the above conceptual operation types are dependent on real-world protocols, like HTTP,
SOAP, WSDL. The figure and table below summarize these concrete operation types.
In short – and explained in length further on – the similarities and differences are:
Request-Reply
One-Way
Bulk-One-Way
ApplHeader as 1st parameter of DLW
yes
yes
yes
Block as 2nd parameter of DLW
no
no
yes
Business reply possible in same exchange yes
no
no
In the table below the conceptual operation types (2nd and 3rd column) are mapped to the concrete
operation types (rows). The protocol and policy bindings used are indicated, or ‘n/a’ if a combination is
not possible.
RR
POW
B-POW
Request-Reply
One-Way
SOAP, HTTP
n/a
n/a
n/a
SOAP, HTTP
Cegeka N.V.
Bulk-One-Way
SOAP, HTTP
page 31 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.2 Pseudo One-Way
5.3.2.1 Guideline
1. Pseudo One Way (POW) is one concrete realization of the conceptual One-Way operation.
Functionally it behaves as a One Way operation to the application layer.
2. Technically POW is a SOAP Request-Reply over HTTP, but with a <wsdl:output> reply element
indicating successful delivery of the message at the server side. This DLW wrapper for the
response MUST only contain a {MetaInfo}ApplHeader element.
<xs:element name="ReceiveDebtSearchResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="ApplHeader" type="meta:ApplHeaderStruct" />
</xs:sequence>
</xs:complexType>
</xs:element>
5.3.2.2 Explanation
The only transport protocols officially supported in SOAP/WSDL are HTTP and SMTP. HTTP is great for
RR, since HTTP itself is request-reply. SMTP would be a solution for OW, but is not useable – it is not
reliable and not suited for large messages3. Better candidates for OW are FTP and JMS, but FTP is not
supported as a transport protocol by web service code generation tools or ESB’s and JMS is only
supported in the Java world. Hence, for One Way there is not a good underlying transport solution.
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 business processing, as described below. We call this
pseudo one-way.
1. SOAP/HTTP request
functional message
Sender
Application
Soap
Service
Client
3. SOAP/HTTP
response
is delivery ack,
optional fault
Soap
Service
Server
Soap
Service
Endpoi
nt
Receiver
Application
persistent
store
2. Validation, followed
immediately by
put in persistent queue
Figure 1 - Pseudo One-Way
In Pseudo One-Way, the SOAP/HTTP message is technically request-reply, but functionally one-way. A
Sender Application delivers the message through a SOAP Service Client at the SOAP Service Server. The
latter only does schema validation, immediately followed by writing the message to a persistent store.
The SOAP Service Server then sends a response element back to the SOAP Service Client, indicating that
the message is successfully received and will be processed later on.
Somewhat later, probably after the SOAP Service Client has received the response, the Receiver
Application will read the message from the persistent store and process it.
3
WS-Attachments are also not a solution for this: standards are still a moving target, as is vendor adoption.
Cegeka N.V.
page 32 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
When the SOAP Service Server detects a validation error, or when it cannot write the message to the
persistent store, it returns a fault to the SOAP Service Client. Errors are described later in this document.
‘Practical Problems’ with current Web Service standards.
The SOAP specification both supports request-reply and one-way using HTTP as the underlying protocol.
Using HTTP for one-way just involves not specifying an <output> element in the WSDL. In practice,
SOAP servers still transmit a HTTP response (because HTTP requires this) but the client will not receive
a SOAP response, even if it contained an error indication!
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 exchanges4.
Therefore, in pseudo one-way, we use HTTP in request-reply for delivering the message by specifying a
standardized <output> and a <fault>; if there is a delivery error we can still send a fault if the message
cannot be safeguarded by the receiving application.
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.
4
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 33 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.3 Bulk Operations
5.3.3.1 Guideline
1. A Bulk Operation MUST always be a Pseudo One-Way operation.
2. For a Bulk Operation, the second – or third if the operation is performed in a flux - parameter of
a DLW request MUST be a Block element of type {MetaInfo}BlockStruct (>= V5).
3. The receiving application MUST NOT rely on the order in which chunks are received.
4. A unique {MetaInfo}MessageID must be assigned to each chunk.
5.3.3.2 Explanation
A Bulk Transfer happens when a lot of data is transferred in separate chunks, where each chunk is
transferred in its own SOAP message. This SOAP message must comply with one definition, the Bulk
Operation definition in a WSDL. Thus: bulk data is transferred with one and the same operation for some
given bulk data.
To allow load balancing for both the sender and the receiver, the receiving application is responsible for
processing chunks in the right order.
The Block element is primarily used to determine whether all data chunks are transferred. It can also be
used to ask for resends in case of lost messages, if supported by the service in question.
5.3.3.3 Example
Below is an UploadCareer bulk operation that has three child elements of its “UploadCareer” DLW
element: the mandatory ApplHeader, the Block element and finally the payload which is here a “Career”
element.
Cegeka N.V.
page 34 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.4 Operation Names
5.3.4.1 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.
5.3.4.2 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:
- ReturnIncome(inss): callee, please give me (the caller) the Income data for the person with the
given inss
- UpdateIncome(inss, changes): callee, I ask you to 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
5.3.4.3 Example
A request-reply operation:
<wsdl:portType name="LegalInfo">
<wsdl:operation name="SearchLegalInfoViaInss">
<wsdl:input message="tns:SearchLegalInfoViaInss" />
<wsdl:output message="tns:SearchLegalInfoViaInssResponse" />
</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 35 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.5 SOAPAction
5.3.5.1 Guideline
In the WSDL SOAP binding, one MUST use the following pattern to construct the soapAction attribute:
[WSDL targetNamespace]/[port type]/[operation name]
5.3.5.2 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.
5.3.5.3 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.
Cegeka N.V.
page 36 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.6 ApplHeader
5.3.6.1 Guideline
A separate XML element <ApplHeader> MUST be present as the first child of the DLW wrapper element.
5.3.6.2 Explanation
The ApplHeader collects information about the message that is independent of the message type and
must always be present. It must be an {XML Schema}element with name ApplHeader and type
{MetaInfo}ApplHeaderStruct (>= V5) or reference {MetaInfo}ApplHeader (V4). It must be, in DLW
parlance, the first parameter of the operation.
See MetaInfo_Vx.xsd for the definition of ApplHeader. Additional information can be found in the
interface documentation that accompanies this XML Schema.
5.3.6.3 Example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<Suspend xmlns="http://www.rsvz-inasti.fgov.be/schemas/WS/Affiliation/V3"
xmlns:aff="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/Affiliation/V3">
<meta:ApplHeader xmlns:meta="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/MetaInfo/V4">
<meta:TimestampSent>2007-11-29T17:16:16.245+01:00</meta:TimestampSent>
<meta:Origin>
<meta:Organization>000</meta:Organization>
<meta:Application>200</meta:Application>
</meta:Origin>
<meta:Destination>
<meta:Organization>003</meta:Organization>
<meta:Application>SOCIAS</meta:Application>
</meta:Destination>
<meta:MessageID>000000000009902</meta:MessageID>
</meta:ApplHeader>
<aff:INSS>83022134803</aff:INSS>
<aff:AffiliationNbr>A073331716004</aff:AffiliationNbr>
</Suspend>
</soap:Body>
</soap:Envelope>
Cegeka N.V.
page 37 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.7 Error Handling
5.3.7.1 Guideline
1. In general, a distinction MUST be made between the following conceptual Error Types:
a. Business Errors indicate violation of some business rule
b. System Errors are infrastructure related errors
Business errors are identified as part of a business process. The guidelines do not define how these
errors are reported to a consumer.
2. When applicable, the SOAP faults that are defined in Helper_Vx.wsdl MUST be used to report System
Errors:





AuthenticationFault
AuthorizationFault
SystemFault
ValidationFault
FluxSyncFault
3. Depending on the operation type, whether or not a specific fault may appear, MUST adhere to the
rules summarized in the table below. ‘Yes’ means the given fault may appear in the result, ‘No’
means the given fault must never appear in the result, ‘n/a’ indicates that there is no reply possible.
SOAP Fault
AuthenticationFault
AuthorizationFault
SystemFault
ValidationFault
FluxSyncFault
SOAP infrastructure generated fault5
RR Reply
Yes
Yes
Yes
Yes
Yes
Yes
POW Reply
Yes
Yes
Yes
Yes
No
Yes
In POW, FluxSyncFaults MUST be reported by invoking a HandleFluxSyncFault operation on the
service interface provided by the consumer.
4. SOAP faults defined by the Guidelines have further restrictions:
a. {soap}faultcode: element MUST contain either {soap}Client or {soap}Server.
b. {soap}Client: this value MUST only be used for AuthenticationFault, AuthorizationFault,
ValidationFault and FluxSyncFault, with the interpretation given by the SOAP 1.1
specification.
c. {soap}faultstring SHOULD contain a (high-level) human readable description of the fault.
d. {soap}faultactor SHOULD contain “{MetaInfo}ErrorBaseStruct.Origin.Organization + ‘.’ +
{MetaInfo}ErrorBaseStruct.Origin.Application
5.3.7.2 Explanation
First, System Error and Business Error are concepts that are independent of web services, .NET, JAVA or
mainframe development to name a few. All errors can be categorized as such:


5
A Business Error is a violation of some business rule.
It may be interpreted by the (human or machine) user, and resolved, e.g. by changing input
data.
A System Error is purely software-technical, often infrastructure related.
A user is typically informed in a general way, saying that ‘a general system error occurred –
please contact your system administrator at phone...”. Users will merely report it to the helpdesk,
and technical personnel (system operators, developers…) take action to resolve it.
Strictly speaking this is outside the scope of the guideline since this is not under our control, but added for completeness.
Cegeka N.V.
page 38 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
The table below shows how concrete errors map to these conceptual errors:
Conceptual
Error Type
System Error
Concrete Error Type
AuthenticationFault
AuthorizationFault
SystemFault
ValidationFault
FluxSyncFault
SOAP infrastructure generated fault, not under our control
Other infrastructure generated errors: HTTP errors, TCP/IP errors, system crash.
Business Error
SOAP fault defined in service interface definition
An ordinary SOAP message (i.e. SOAP response, or separate WSDL operation)
communicating a business outcome dat happens to be a business rule violation.
Business Errors may be reported as a specific fault – defined in a service interface definition - but they
can also be an ordinary one-way message or an ordinary reply in a request-reply message. However,
System Errors should never be communicated as an ordinary xml element in a reply or message.
Communicating System Errors in a Request, both in RR or POW, does not make sense. A System Error is
always the consequence of sending a message. So it is logical that it only appears in a reply. For a POW
however the set of System Errors is very limited, as it can only be a validation error or some error related
to the Persistent Store6. And of course, SOAP faults can only be communicated in a reply, as defined in
the SOAP and WSDL specifications.
Business Errors are the result of processing a request by business logic, so only in a RR it may appear in
the reply. In a POW it cannot appear in a Reply: the reply of a POW is a technical/delivery ack, no
business processing has taken place yet.
However, a Business Error can appear in the Request of a POW, typically when an earlier POW was
received and processed which resulted in a business rule violation, of which the sender is notified. The
figure below illustrates this.
There is one other possible set of SOAP faults, those that are generated by the SOAP infrastructure itself
which is out of control of the application developer. Typically they are generated by ESB products, code
generated from WSDL’s, or SOAP intermediaries if they exist. These can only exist as a reply, never as a
request.
Note that besides SOAP faults there are other System Errors, like HTTP or TCP/IP related errors. These
are described in the next guideline.
6
Persistent Store is explained in the previous guideline on Pseudo One Way.
Cegeka N.V.
page 39 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.8 Handling of System Errors - Idempotence
5.3.8.1 Guideline
1.
-
System Errors include the following:
TCP/IP errors
HTTP errors
SOAP faults generated by SOAP infrastructure
AuthenticationFault, AuthorizationFault, SystemFault, ValidationFault and FluxSyncFault faults
2. Senders that detect a System Error, and that want to resend the same message, MUST use the
same {MetaInfo}ApplHeader.MessageID, {MetaInfo}ApplHeader.Origin (MetaInfo < V6) and –
when applicable - {MetaInfo}ApplHeader.FluxDescriptor.
3. Receivers MUST implement idempotence via the combination of Origin and MessageID:
If an incoming message has the same MessageID and sender - identified by
{MetaInfo}OriginOrganization (MetaInfo < V6) or client certificate (MetaInfo >= V6)- as a
previous message, and that message was already processed by business logic, then:
a. This message MUST NOT be processed again by the business logic.
b. The original response SHOULD be returned, or a new one MAY be generated giving the
same result.
TODO: what happens if a duplicate message is received before the business logic has processed
the original request.
TODO: explicictly state how long the receiver MUST be able to return the original response. We
do not want to retain all messages indefinitely.
5.3.8.2 Explanation
This guideline is only for System Errors, and specifically how operations may be re-executed after
detection of a System Error. Business Errors imply that the operation has been functionally processed,
implying that the system level has functioned correctly.
We limit ourselves to HTTP transport, with request-reply operations or pseudo one-way operations as
described earlier in this guideline.
System Errors are not merely SystemFault SOAP faults, but also HTTP or TCP/IP errors and crashes. This
is described in detail in the box “System Error Analysis” below. That analysis shows that a sender that
receives a System Error is unsure whether the message has actually been functionally processed by the
receiver or not.
Therefore the sender must be able to resend the message, and the receiver must be able to handle the
same message being received twice or more, so that no inconsistencies are created. This implies a well
known property of idempotency: doing the operation or redoing the operation multiple times has the
same overall effect7.
Idempotence is not a problem for queries: the state at the receiver is not changed in that case.
For updates, deletes or creations, if the sender receives a System Error he re-sends exactly the same
message, including the same MessageID and ApplHeader.Origin (MetaInfo < V6). The receiver uses the
MessageID and identity of the sender of the operation to detect and prevent re-execution. Receivers
must be able to give the same answer in case of a re-execution.
7
Note that the sender may also choose to stop sending messages in case of a System Error.
Cegeka N.V.
page 40 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
The figure below illustrates one of the possible error cases, and how it should be handled.
Note that we do not make any assumption on where (in an ESB, or directly in the application) or how you
implement this solution.
5.3.8.3 Example
None.
Cegeka N.V.
page 41 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.8.4 System Error Analysis
The figure below shows a sender and receiving application, SOAP service endpoints and a HTTP transport. The arrows show the
message exchange. The red crosses show possible locations of infrastructure-related errors.
Sender
Application
Service
Endpoint
Send
HTTP Transport
Service
Endpoint
Recv
1
2
3
7
6
5
1
2
3
7
6
5
Receiver
Application
4a
Request-Reply
Pseudo One-Way
4b
Component
Send – Service
Endpoint
Contains...
Generated code from WSDL or Service Bus
HTTP client software
TCP/IP client software
Error examples
Invalid message or operation
detected
Problem with http or tcp/ip client
infrastructure
HTTP Transport
Recv – Service
Endpoint
tcp/ip network, routers, gateways, firewalls...
Generated code from WSDL or Service Bus
HTTP server software
TCP/IP server software
Business logic interpreting request.
For request-reply only generates a response (no response
for pseudo one-way).
Any failure in any network component
Crash
Validation error
Receiver Application
-
Crash
System error
Business error
Remember that for pseudo one-way the reply message contains a fixed ‘delivery ack’ message or a fault. Also for request-reply the
reply message contains a business result or a fault.
Assuming the errors occur where red crosses appear, the following table describes in detail what the error is, and what the
possible consequences are. They are grouped by Request-Reply and Pseudo One Way.
Error
in...
Processed by
Receiver
App?
Comment
Request-Reply
1
No
2
No
3
No
Cegeka N.V.
The sender application immediately detects an error, typically as a SOAP fault or another
means determined by the tools used.
 The sender MUST redo the operation.
The sender application immediately detects an error, a TCP/IP error like ‘connection lost’.
 The sender MUST redo the operation.
The sender application immediately detects an error:
Crash, System malfunction: TCP/IP error
page 42 of 70
B2B Web Service Guidelines V2
4a
Unsure
RSVZ Enterprise Architecture
General system or software error:: HTTP error, SOAP fault
Validation Error: SOAP fault of type SystemError.
 The sender MUST redo the operation.
The sender application immediately detects an error.
Crash, System malfunction: TCP/IP error or SOAP fault
General system or software error: HTTP error or SOAP fault
 The sender MUST redo the operation.
If the transport between the endpoint at the receiver and the receiver itself is not reliable,
and the recSince it is unsure whether the operation has already been processed by business
logic, the operation must be resent, using the same MessageID/Origin. The receiver must
reject an already processed message, based on this MessageID/Origin.
Note: alternatively the operation itself can be idempotent, by including the old and new
values. This is out of scope of this specification, since it involves the applications
themselves.
5
Yes (but not always
known to sender)
6
Yes, but not known
to Sender
Yes
7
The sender application immediately detects an error:
Crash, System malfunction: TCP/IP error
 The sender MUST redo the operation, since request may not be processed.
General system or software error:: HTTP error, SOAP fault
 The sender MUST redo the operation, since request may not be processed.
Validation Error in reply: SOAP fault of type SystemError
 The sender MUST redo the operation after receiver has fixed the problem.
Idem to 2.
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 by the Receiver
Service Endpoint. In this case a SOAP fault with a specific SystemError is returned.
 The sender MUST retry the operation.
5
Unsure
The Sender Application immediately detects an error:
Crash, System malfunction: TCP/IP error
 The sender MUST retry the operation, since request may not be processed
General system or software error: HTTP error, SOAP fault
 The sender MUST retry the operation, since request may not be processed
6
Yes, but not known
Idem request-reply.
to Sender
7
Yes
Idem request-reply.
This shows that multiple types of errors can be detected: TCP/IP errors, HTTP errors, SOAP faults. It also shows that in general a
sender cannot know whether a message has been functionally processed or not when receiving a system error.
If the transport between the Receiver Service Endpoint and the Receiver Application is not reliable, then the Receiver Application
MUST ensure the operation is idempotent.
Idempotency Choices
For idempotency there are two options:
1. The operation is made idempotent, e.g. by adding the old and new state in the message.
2. The receiver uses the MessageID/Origin of the operation to detect and prevent re-execution.
The first solution is visible at the functional application level, so functional analysis is necessary. Also the
size of messages is doubled. Therefore the second solution is the one chosen.
Cegeka N.V.
page 43 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.9 Support for Fluxes
5.3.9.1 Guideline
1. When a Flux is used it MUST be documented in an Interface document using a Flux Chart.
2. If an operation (i.e. message) is part of a Flux, a FluxDescriptor element of type
FluxDescriptorStruct MUST be provided as first parameter after the ApplHeader by the sending
party that starts the flux, and it must be preserved in all further operations that are part of that
flux.
[Applies only to web services that use MetaInfo >= V6]
3. NISSE MUST check that all operations that participate in a Flux are consistent with that Flux.
4. SIFs MAY check that all operations that participate in a Flux are consistent with that Flux.
5.3.9.2 Explanation
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 request that is part of
that flux.
Fluxes are really explicit protocol descriptions, 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.
See MetaInfo_Vx.xsd for the definition of FluxDescriptorType (< V6) and FluxDescriptorStruct (>= V6).
Additional information can be found in the interface documentation that accompanies this XML Schema.
Cegeka N.V.
page 44 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.3.10 Binary content
5.3.10.1 Guideline
1. Binary data MUST be defined as an element of type xs:base64Binary in XML Schemas.
2. A web service MUST use MTOM for transferring binary content.
3. Policy assertions MUST NOT be used to indicate the use of MTOM.
5.3.10.2 Explanation
Various specifications exist for attaching binary content to SOAP requests, such as SOAP Messages with
Attachments, DIME and MTOM.
MTOM is a W3C Recommendation and an interoperable standard supported by all major web service
frameworks (JAX-WS, WCF, Axis). Although the SOAP 1.1 Binding for MTOM 1.0 is only a W3C Member
Submission, it is equally well supported by vendors.
An advantage of using MTOM – when compared with Base64 - is that binary data can be sent and
received without incurring the cost of data encoding. This is accomplished by externalizing data elements
that are contained in a message using XOP and carrying them with the message as binary data.
MTOM messages are packaged as multipart/related MIME sequences with the root part being the actual
SOAP message. Due to the MIME format, MTOM-encoded messages that are less than 1 KB might still be
larger than message that use the Base64 encoding for binary data.
To reduce the overhead encurred by MTOM for small binary data, most web service frameworks allow
binary content to be sent inline when the size of a message is below a threshold.
When compared to DIME, a major benefit of MTOM is that the binary data can be protected using WSSecurity. Currently, very little vendors actually support this, but at least the MTOM specification allows
this.
Web services that need to transfer binary content MUST NOT use policy assertions. There are multiple
specifications that define policy assertions for MTOM, and there’s no broad vendor support for either of
them. As a result, MTOM must be explicitly enabled in both client –and server implementations when
applicable.
5.3.10.3 Example
The extract below shows an MTOM-encoded HTTP response where the binary content has been XOP
optimized in a separate MIME part.
HTTP/1.1 200 OK
Date: Wed, 02 Jun 2010 08:33:16 GMT
Transfer-Encoding: chunked
Content-Type: multipart/related;start="<rootpart*[email protected]>";type="application/xop+xml";boundary="uui
d:6a38ae26-b022-40d6-944c-f79d4c7a7df3";start-info="text/xml"
--uuid:6a38ae26-b022-40d6-944c-f79d4c7a7df3
Content-Id: <rootpart*[email protected]>
Content-Type: application/xop+xml;charset=utf-8;type="text/xml"
Content-Transfer-Encoding: binary
<?xml version='1.0' encoding='UTF-8'?><S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><CreatePartnerRes
ponse xmlns="http://www.rsvzinasti.fgov.be/PrivateWS/GWYSecurity/V1"><Result>5</Result><Signature>
Cegeka N.V.
page 45 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
<Include xmlns="http://www.w3.org/2004/08/xop/include" href="cid:[email protected]"/></Signature></CreatePartnerResponse></S:
Body></S:Envelope>
--uuid:6a38ae26-b022-40d6-944c-f79d4c7a7df3
Content-Id: <[email protected]>
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
<binary data>
--uuid:6a38ae26-b022-40d6-944c-f79d4c7a7df3—
Cegeka N.V.
page 46 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.4 Interface Documentation
Each version of a service MUST be accompanied by a document providing at least the following
information:



Identification
Operations
Samples
The filename of the document should match the following pattern:

<service name>_V<version>.*
Example: Affiliation_V3.docx
5.4.1 Identification
The interface documentation MUST clearly state the name, version and namespace of the service, and
the version of the B2B Web Service Guidelines that applies to it.
For services provided by NISSE, the location of the WSDL MUST also be included.
5.4.2 Operations
The following information MUST be provided for each operation:




Goal
Operation type
List of error codes
Pre –and postconditions
Any deviations from the B2B Web Service Guidelines that apply to the service MUST also be clearly
documented.
5.4.3 Samples
An example of the message(s) exchanged for each operation SHOULD be included for reference.
Note:
Technical ACKs sent as part of a POW operation SHOULD NOT be included.
Cegeka N.V.
page 47 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5 Configuraton Management & Release Management
5.5.1 Introduction of Concepts
5.5.1.1 Web Service Definitions
Web Services are essentially service interfaces, things through which an interface user communicates
with the interface implementor in a well-defined way and with the expectation that the interface
implementor will do as asked – i.e. execute that functionality. Interfaces are not new – (Web) Services is
just another technology implementing the same idea but with other – more open – technologies.
Service Definitions define what functionality is offered by an interface and how it should be called
upon. WSDL’s are the first and most important part of this interface description, these are automatable
definitions in the sense that all communication code can be generated from it, either by codegeneration
tools or Enterprise Service Buses (ESB). WSDL’s import schema XSD files, which typically define the
functional parts of the input and output of the service operations. Finally, a Service Definition also needs
a textual description, on how to use the interface – not everything can be described using WSDL or
XSD’s.
RSVZ-INASTI will be the ‘owner’ of these Service Definitions, although they are defined together with all
parties involved. All parties, NISSE and the SIFs, must adhere to it8. These definitions include:
- WSDL’s (.wsdl files) 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 and faults, 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
- XSD Schemas (.xsd files) imported by the WSDL, and used indirectly for input and output
parameters.
- 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.
An implementation of a web service then is a Service. The term Service often is used for both the
implementation and its definition – the context makes clear what is meant.
A Service Definition contains a number of Operations. The communicating party implementing the
operation acts as a Service Provider for this operation, the one using the operation is the Service
Consumer. Sometimes Server is used as an alias for Service Provider, and Client or Caller are used as
an alias for Service Consumer.
A communicating party typically acts at the same time as Service Provider and Consumer for the same
Service, for some operations it is the consumer whereas for others it is the provider.
5.5.1.2 Configuration Items & Versions
All files, including WSDL files, Schema files and accompanying Documentation, are configuration
items.
8
We do not and cannot include services that RSVZ-INASTI does not control, such as web services defined by KSZ.
Cegeka N.V.
page 48 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
A configuration is a set of configuration items that are or should be 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; all these files together form a configuration.
Each configuration item has a version. In essence this is just a name or number, used as a label
attached to a specific version of a configuration item.
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.
Note that tag and label are aliases; both are names or numbers attached to something else.
In the example below the configuration baseline labeled “build_of_2007-04-01” consists of configuration
item Affiliation.wsdl version 1 and configuration item Base.xsd version 2.
Affiliation.wsdl
Affiliation.wsdl
Base.xsd
Base.xsd
Base.xsd
V1
V2
V1
V2
V3
build_of_2007-04-01
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 test, we speak of a release candidate. When tests are successful it becomes a
release, if not successful it remains a –failed– release candidate.
5.5.1.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. It is possible that this will be the next
release, on which work is already being done, or in a later release scheduled for perhaps 6 months later.
This is a decision of the Change Control Board (CCB).
In fact, a Release is 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. Services are used by many parties ( 10 funds), so any change in a service
impacts all of these parties. Therefore each change and release must be carefully coordinated, and with
dozens of participating parties this is not an easy task. This coordination is, again, the responsibility of
the Change Control Board.
Cegeka N.V.
page 49 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.2 Service Definition Anatomy
5.5.2.1 Guideline
1. A Service Definition MUST be described using WSDL, SHOULD import XML Schemas for messages
(i.e. input and output parameters of operations) and MUST have a textual description of nonautomatable aspects.
1. A Service Definition MUST be identified by a Name and a Version.
1. A Service Definition MUST consist of:
a. one or more Endpoints
b. an Endpoint is of one of the following possible types:
i. NISSE – contains all operations of which NISSE is the service provider
ii. SIF – like NISSE, but for operations of which a SIF is the service provider
c. only one Endpoint Type can appear in a Service Definition
5.5.2.2 Explanation
This guideline describes the base service structure which we use. The next guidelines build further upon
this guideline; Versions are described in a later guideline.
We intentionally limit the flexibility WSDL and SOAP offer, to make it easier to understand and use.
The figure below summarizes the structure and rules of a Service Definition.
Note that other guidelines also apply. For example, the allowed types of operations and faults were
described earlier.
Cegeka N.V.
page 50 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
A Service Definition is an umbrella concept, defining a service. As we’ll see later it corresponds to exactly
one namespace, and 2 or 3 WSDL files.
An Endpoint has a very concrete aspect, at runtime it is a URL at which you can call operations. This
corresponds to exactly one <endpoint> element in a WSDL. At the same time however it also represents
a WSDL <binding> and a WSDL <porttype>. In our Service Definitions there is a one-to-one relationship
between PortType, Binding and EndPoint elements in WSDL.
The Endpoint types are defined by the communicating partner, NISSE or SIF. Discriminating between
“provider” allows us to easily split Operations between provider and consumer, which is handy for
generation tools – see also the guideline on files.
5.5.2.3 Example
TODO.
Cegeka N.V.
page 51 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.3 Versions
5.5.3.1 Guideline
1. An XML Schema or Web Service WSDL MUST be identified by a tuple (Name, [Provider,] Version)
where Name and Provider are a string, and Version a number V 1.
The Name MUST indicate the use of the Service or Schema and the Version augments when
there are evolutionary changes. The Provider element only applies to services in which multiple
providers play a role.
2. A target namespace MUST be as follows:
 WSDL:
http://www.rsvz-inasti.fgov.be/schemas/WS/name[/provider]/Vversion
 XML Schema:
http://www.rsvz-inasti.fgov.be/schemas/WS/schema/name/Vversion
where:
name
the service or schema name.
version
the version.
provider
(optional) an identifier representing the provider that offers the service.
3. There MUST be one and only one XML Schema file per targetNamespace and vice versa.
It MUST be named name_Vversion.xsd.
4. A Web Service, named service, MUST be described using one or more of the following files:



service_Vversion.wsdl – (optional) containing WSDL type, message and porttype elements
Nisseservice_Vversion.wsdl – (optional) containing WSDL binding and service elements
where NISSE is the service provider and interface definition specific to the operations
provided by the service provider
Sifservice_Vversion.wsdl – (optional) containing WSDL binding and service elements where a
SIF is the service provider, and interface definition specific to the operations provided by the
service provider
where version MAY differ between the indivual WSDL files.
If a service has only one service provider (NISSE or SIF), then service_Vversion.wsdl MUST also
contain the WSDL binding and service elements.
When there are multiple service providers, the targetnamespace of the WSDL for a given
provider SHOULD contain an identifier representing that provider. The binding and service
elements MUST NOT be prefixed with this identifier.
In that case service_Vversion.wsdl SHOULD only contain the WSDL types, messages and port
types that are shared between two or more providers.
5. The following path structure MUST be followed:
./name/name_Vversion.wsdl
./name/Nissename_Vversion.wsdl
./name/Sifname_Vversion.wsdl
./schema/name/name_Vversion.xsd
Cegeka N.V.
Service file, up to and including the PortType
definitions.
Service file defining the SOAP binding and service
definition of the operations provided by NISSE.
Service file defining the SOAP binding and service
definition of the operations provided by a SIF.
Schema files, where name is an identifying name and
version is the version number.
page 52 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.3.2 Explanation
All types and elements of one namespace are defined in exactly one XSD Schema file. It is possible to
have multiple XSD Schema files that use the same target namespace, but this may lead to problems. For
example, it is not easy to see if an element or type is redefined in some other schema file, which is
obviously a problem. Such redefinition is easy to detect with tools if co-located in the same file.
For WSDL’s it is a bit more complex. For one Service Definition there can be more than one WSDL file,
but all with the same name, and with a target namespace that MAY only differ in the provider component
and version. The individual WSDL files MAY differ in version to cope with changes that only affect a single
service provider.
The reason to split WSDL files this way is to make it much easier to import them in code generation tools
or ESB products. For example, given a service Affiliation_V3, a SIF will import SifAffiliation_V3.wsdl and
Affiliation_V3.wsdl as a Service Provider and NisseAffiliation_V3.wsdl and Affiliation_V3.wsdl as a Service
Consumer.
Note that the combination (name, [provider,] version) has the same identifying value as a
targetnamespace, since a targetnamespace consists of some static text, the service name and the
version. This is true for both XSD Schemas and WSDL files.
Specifically for WSDL files, the targetnamespace MAY also include the identifier of the service provider.
The path structure was introduced to ease readability: this way all files do not appear in the same
directory.
The other aspects of this guideline can be easier explained in the next guideline on Version Impact
Analysis, so we defer that until then.
5.5.3.3 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 version number. The arrows indicate that a
schema is imported in another schema, or that a WSDL is imported into another WSDL.
NisseLegalInfo_V2.wsdl
.../LegalInfo/Nisse/V2
NisseAffiliation_V1.wsdl
.../Affiliation/Nisse/V1
LegalInfo_V2.wsdl
.../LegalInfo/V2
Legal_V2.xsd
.../WS/schema/Legal/V2
SifAffiliation_V2.wsdl
.../Affiliation/Sif/V2
Affiliation_V1.wsdl
.../Affiliation/V1
Legal_V3.xsd
.../WS/schema/Legal/V3
Affiliation_V1.xsd
.../WS/schema/Affiliation/V1
imported
in
MetaInfo_V5.xsd
.../schema/MetaInfo//V5
Base_V3.xsd
.../schema/Base/V3
Figure 1 - Example Configuration
Some notes on the example configuration:
Cegeka N.V.
page 53 of 70
B2B Web Service Guidelines V2
-
RSVZ Enterprise Architecture
Of Legal there are two versions used at the same time, V2 and V3. V2 is used by LegalInfo web
service, V3 is used by Affiliation web service.
The SIF provider WSDL of the Affiliation web service has evolved more quickly than the NISSE
counterpart (V2 vs V1).
The path structure of the WSDL and XML Schema files also follows a fixed pattern, as shown below.
|-- Affiliation
|-- Affiliation_V1.wsdl
|-- NisseAffiliation_V1.wsdl
|-- SifAffiliation_V2.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_V3.xsd
|-- MetaInfo
|-- MetaInfo_V5.xsd
Cegeka N.V.
page 54 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.4 Modifications and Version Impact Analysis
5.5.4.1 Guideline
Whenever a structural change is applied to a WSDL or XML Schema, its version number MUST be
augmented.
When the version of a WSDL or XML Schema is augmented, then the following algorithm MUST be
applied recursively to determine the version of an importing WSDL or XML Schema:
a) if none of the changes are needed in an importing CI, then we have 2 options for the importing
CI:
a. the importing CI sticks to the older version
 the importing CI does not change version
b. the importing CI imports the upgraded version
 the importing CI updates the namespace of the imported CI
 the importing CI increments its version
b) if at least one change is needed in an importing CI, then
a. the importing CI must import the upgraded version
 the importing CI updates the namespace of the imported CI
the importing CI increments its version
c) stop recursion if there is no importing CI anymore (i.e. when a WSDL CI has been treated)
5.5.4.2 Explanation
To determine if a configuration item undergoes a version upgrade or no change, it suffices to follow the
import-relation between configuration items (see “
Figure 1 - Example Configuration” on page 53 for an example) and apply the above algorithm. The figure
below also shows the import relationship on Configuration Elements, the identifying name, major and
minor, and what concrete types of Configuration Elements exist.
class Configurations
+importer 0..*
CfgElement
+imported 0..*
+
+
NisseWsdlFile
SifWsdlFile
name: string
version: int
WsdlFile
SchemaXsdFile
Note that Schema files can import other Schema files, and that WSDL files can import other WSDL files or
Schema files. However, Schema Files cannot import WSDL files.
To allow having multiple versions of the same Service in production in parallel the version must be
included in the namespace and filename. In a sense a major change is exactly the same as a completely
new Schema or Service Definition if you look at the consequences.
Cegeka N.V.
page 55 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.5 Releases
5.5.5.1 Guideline
1. A Release and Release Candidate MUST be named as follows:
Release
RCV_s
V: version
Candidate
s: sequence starting at 0
Release
RV
V: version
2. A Release MAY contain multiple versions of the same Web Service Definition, i.e. the same Name
but different Versions, 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.
 Avoid an upgrade of another Service that does not use a changed Schema.
5.5.5.2 Explanation
A Release is a consistent set of schemas and web services that is put in production as a whole. An
example of a release might be all the schemas and web services depicted in “
Figure 1 - Example Configuration” on page 53.
As seen in this example a release, identified as say R2, consists of multiple specific versions of a schema
or web service. Even more, the same schema may be included under multiple (major) versions, as is the
case for Legal schema.
It is important to realize that currently only the versions of the Service Definitions really matter, because
Schema versions are implicitely defined through the imports of these Service Definitions, and Schema’s
are never used on its own. So a Release determines essentially what Versions of which Services can be
used between NISSE and SIFs.
It is also important to note that this guideline does not say that all services of the current Release must
be used or implemented (i.e. consumed or provided). It is virtually impossible that all 15 communicating
partners would switch to another version of a Service at about the same time. Therefore a Release will
keep the older Service version together with the newer Service version. NISSE will have both Service
versions available at the Release date, but SIFs will continue to use the older version (“phasing out”) for
a few more days or weeks and then switch to the newer version. More on this follows in the next
guideline.
Before a Release is put into production it has been the result of earlier tests, like System testing and
Acceptance. In these preliminary phases we do not yet speak of Release, but of Baselines and Release
Candidates. The following figure defines these terms.
Cegeka N.V.
page 56 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
Figure 2 – Baseline, Release Candidates and Releases
In this figure, a Baseline is a consistent set of schema and web service files, represented by CfgElement.
CfgElements are files where the filename is a direct derivative of the name and version.
A Baselines has a ‘revisionNr’, this is a label private to NISSE that completely identifies the Baseline 9.
Once a Baseline is considered ready for public availability, a special kind of Baseline is created, the
“Release Candidate”. This is a package that will be distributed to all SIFs and NISSE so that everybody
can start developing and testing the new or changed services. It is different from a Baseline in that it
should be stable, should be linked to a list of Change Requests (see Change Control Board procedure),
and that it has a Version and Sequence number. The Sequence is a sequence number – it is very unlikely
that the first Release Candidate will be bug free and will become a Release; instead many Release
Candidates with the same Version will be issueduntil all bugs are fixed.
Once development and then acceptance testing have finished successfully, the latest Release Candidate
used at that time becomes a Release. Note that a Release has exactly the same contents as the
successful Release Candidate, and has the exact same version. In other words it can be viewed as just
taking the Release Candidate package and attaching an additional Release ‘tag’.
A Release has 3 phases: ready to be put into production (‘ready’), in production (‘current’), and retired
from production (‘retired’). Releases are also special in that they are published on the web site of RSVZINASTI, and that they have to be stored ‘for eternity’.
9
This is the so-called revision number of the versioning system used, SubVersion.
Cegeka N.V.
page 57 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.6 Service Implementation Aspects & Versioning
5.5.6.1 Guideline
1. All parties MUST conform to one-and-the same Release for a given period of time. This Release and
time period is communicated by NISSE. This Release is called the ‘Current Release’.
2. NISSE MUST support all versions of all services of the current Release, both as a service provider and
service consumer.
3. SIFs MUST inform NISSE of which Version of a Service they provide. This way NISSE knows what
version to use as a service consumer.
4. Versions MAY be marked “PhasingOut”, implying that:
a. it MUST only be used for smooth installation of the new release
b. it MUST NOT be used to start new flux instances, or being used in new flux instances10
c. The new version MUST be used ASAP.
5.5.6.2 Explanation
First we list the requirements that form the basis of these guidelines:
1. With 15 communicating parties it is very difficult to install a release at the same time. All systems
should be taken down at the same time, install the new release and go up more or less together.
This is very difficult to organize. Moreover, if one party fails to install the new release, all should
go back to the older Release.
 Therefore, putting a release in production should be possible in a larger time frame, e.g. a
week, and all SIF’s can do this independently of each other and after NISSE has itself put the
current Release into production.
2. Sometimes a new Service version is only required by a limited number of SIF’s. The impact
should be limited to these SIF’s only.
 Support for multiple versions of a Service within a Release.
3. Versioning is a complex problem, which needs to be handled by all SIFs consuming resources.
 Shield SIFs as much as possible from these issues, and centralize work as much as possible
with NISSE.
Let’s see how these requirements and the above guidelines work together, using the scenarios in the
table below.
Sif 1
Sa_V1
Release R1.0.0 is the current release of service
‘Sa’. It includes version ‘V1’ of the ‘Sa’ service.
R1
Nisse
All SIFs and NISSE use the R1 release, and as a
result they all use the V1 version of Sa.
Sa_V1
Not shown is that there is a ‘Ready’ release R2
Sif 2
Sa_V1
10
which will go in production on December 6th. It has
a new version V2 of service Sa.
Note that this implies that the flux is also phasing out.
Cegeka N.V.
page 58 of 70
B2B Web Service Guidelines V2
Sif 1
Sa_V1
RSVZ Enterprise Architecture
December 6th. NISSE puts into production its new
implementation for Sa V2, and keeps Sa V1
running.
R2
Nisse
Sa_V1
Sif 2
Sa_V1
Sa_V2
The SIFs still use Sa V1 while communicating with
NISSE, and NISSE also uses Sa V1 when
communicating with the SIFs. Since Sa V1 is still
valid the SIFs also conform to R1.
Meantime SIF 1 works on implementing Sa V2.
December 25th. This is a quiet day.
Sif 1
Sa_V1
Sa_V2
R2
Nisse
Sa_V1
Sa_V2
Sif 2
Sa_V1
SIF 1 puts its service Sa V2 into production. It then
informs NISSE that Sa V2 is ready. All new Sa
operation invocations will use V2, regardless of
whom – NISSE or SIF – initiates the operation.
If Sa is used in a Flux, new Flux instances, will use
V2. Existing fluxes using Sa will continue to use V1
– the phasing out version.
SIF 2 is still using Sa V1.
The above depicted approach enables a number of important features:
 A SIF can, within reasonable boundaries, determine the moment it enables a newer version of a
Service.
 Transitioning to a newer version of a Service can happen without service interruption.
 It is up to NISSE to make sure that a SIF will only get message operation belonging to the
service versions that the SIF supports. (Of course, these versions must be supported in the
Current Release).
Regarding supporting an older version of a Service in a new Release the following table can serve as a
guideline. Say that the Current Release contains version V1 of Service A, what can happen in the next
release?
Contents of next Release
Service A, V1 ‘Phase Out’
Service A, V2
Service A, V1
Service A, V2
Service A, V1
Service A, V2
Cegeka N.V.
When to use
There is new legislation and V1 must phase out. Or V2 has more
information and it is agreed that this one should be used instead.
Service A is used in existing fluxes, and these existing fluxes must
still be completed using V1.
Only a limited number of SIFs need new functionality and the
functionality offered by V1 is still valid. Both versions can be used,
but a SIF MUST choose only one.
V1 must not be used anymore by any SIF or NISSE. Perhaps
because of legal reasons, or serious flaws in the service design.
Of course, smooth transition is not possible, and therefore this
possibility should be avoided.
page 59 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.7 Life Cycle of Releases
The figure below summarizes the life cycle or releases.
Nisse
Current
Release
Rv
Retired
Retired
Retired
Releases
Releases
Releases
Ready
Release Rv
Nisse
Public Website
consult/
download
Release
Candidates
RCv_s
consult/
download
Sif
Development
Integration/
System Test
Development
Implementation
RCv_s
communicate
Integration/
System Test
copy
copy
Acceptance
Implementation
RCv_s
Implementation
RCv_s
communicate
Implementation
RCv_s
Implementation
Ready Rv
Acceptance
Implementation
Ready Rv
Production
Production
Implementation Rv
communicate
Implementation Rv
The public website of NISSE contains the following items of all retired, current and ready Releases11:
 WSDL’s
 XML Schema’s
 Interface Documentation
 B2B Web Service Guidelines
Note that since not all services evolve at the same pace, multiple versions of the B2B Web Service
Guildeines may apply to a given release.
11
Release Candidates are not covered here.
Cegeka N.V.
page 60 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
As soon as a Release Candidate appears, it can be downloaded by a SIF’s development team. To test this
Release Candidate a System-Test environment is available at NISSE with which the SIFs can test the new
Release Candidate.
If no more bugs are found in the System-Test environment, then the latest Release Candidate is copied
to the Acceptance Environment, where formal testing takes place.
If a bug is found during Acceptance Tests, a new Release Candidate is created which is first tested again
in the System-Test environment and only after successful tests copied to Acceptance.
If a Release Candidate has no more bugs in Acceptance, it is promoted as a “ready” Release, awaiting
production at the agreed date.
In Production there is only one active Release, the “Current Release”.
It is quite possible that there is a R3 “active” release, a R4 “ready” release, and a RC5_3 in Acceptance.
When a “ready” release is put into Production, the removed Release becomes “retired” and is marked as
such in the public website.
Cegeka N.V.
page 61 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.5.8 About Downloading Schema & WSDL Files
TODO Punt is dat we uit-productie genomen releases nog steeds moeten bijhouden op de website.
We moeten ook op één of andere manier kunnen aangeven wat de current release is.
Ook vraag ik me af – niet opgenomen in het voorstel – of we de service documentatie niet mee onder
http://www.rsvz-inasti.fgov.be/schemas/WS/ moeten steken, b.v. in een subfolder “documentation”;
release beheer wordt dan veel makkelijker.
5.5.8.1 Guideline
1. Communicating partners MUST use a local copy of the XML Schema and WSDL files.
2. The “Current Release” will be available at two places
a. http://www.rsvz-inasti.fgov.be/schemas/WS/Current
b. http://www.rsvz-inasti.fgov.be/schemas/WS/RV where RV is the release label of the
current release
3. The “Retired Releases” will be available at http://www.rsvz-inasti.fgov.be/schemas/WS/RV where
RV is the release label of the retired release
5.5.8.2 Explanation
For optimal performance and robustness XML Schema and WSDL files must be kept locally.
Certain Web Services frameworks require access to the XML Schema and WSDL files to obtain meta-data
that is not available in the generated proxy classes, and need to be explicitly configured to use local
copies.
Unexpected or planned down-time of the RSVZ-INASTI website should not affect day-to-day B2B
operations.
5.5.8.3 Example
<xsd:import
namespace="http://www.rsvz-inasti.fgov.be/schemas/WS/schema/LegalInfo/V1"
schemaLocation="./schema/LegalInfo.xsd">
</xsd:import>
The Current Release as of October 2008 is the following:
Note that there are no “Retired Releases” yet in the above screenshot. If it were, there would be a
http://www.rsvz-inasti.fgov.be/schemas/WS/R1/Affiliation etc.
TODO RV voor current release
Cegeka N.V.
page 62 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
5.6 Security
5.6.1 Message Security
5.6.1.1 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-repudiation also requires these technologies, by using a digital signature generated either by the
SIF’s key or the individual user’s key.
The client and server certificates of RSVZ are available for download from
http://www.rsvz-inasti.fgov.be/schemas/B2B-certificates.
5.6.2 Audit Logging
5.6.2.1 Guideline
All incoming and outgoing messages MUST be logged in an audit log.
The information listed in the table below MUST be logged:
Cegeka N.V.
page 63 of 70
B2B Web Service Guidelines V2
Security Policy
Algemeen
Timestamp
Communicatie type
Transport type
Bestemmeling
ServerOrg Id
ServerOrg MatrixId
ServerOrg MatrixSubId
ServerOrgUserId
ServerOrgPgmId
Verzender
ClientOrg Id
ClientOrg MatrixId
ClientOrg MatrixSubId
ClientOrgUserId
ClientOrgPgmId
Bericht informatie
MessageID
MessageEnveloppe
MessageTimeRequest
MessageServiceId
MessageVersion
CorrelationId
Message
RSVZ Enterprise Architecture
Web Services SVF --> RSVZ
Log SVF as Sender
Log RSVZ as Receiver
Web Services RSVZ --> SVF
Log RSVZ as Sender
Log SVF as Receiver
sent time
POW or RR
HTTP
received time
POW or RR
HTTP
sent time
POW or RR
HTTP
received time
POW or RR
HTTP
ApplHeader.Destination
ApplHeader.Destination
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.Destination
ApplHeader.Destination
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.Destination
ApplHeader.Destination
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.Destination
ApplHeader.Destination
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.Origin
ApplHeader.Origin
N/A
ApplHeader.UserID
ApplHeader.RequestInitiatorID
ApplHeader.Origin
ApplHeader.Origin
N/A
ApplHeader.UserID
ApplHeader.RequestInitiatorID
ApplHeader.Origin
ApplHeader.Origin
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.Origin
ApplHeader.Origin
N/A
N/A
ApplHeader.RequestInitiatorID
ApplHeader.MessageID
SOAP-WS-2B
ApplHeader.TimestampSent
ApplHeader.MessageID
ApplHeader.MessageID
SOAP-WS-2B
SOAP-WS-2B
ApplHeader.TimestampSent
ApplHeader.TimestampSent
namespace naam + '/' + porttype-name + ':' + operation-name
namespace naam + '/' + porttype-name + ':' + operation-name
ApplHeader.FluxID
ApplHeader.FluxID
{soap}Envelope
{soap}Envelope
ApplHeader.FluxID
{soap}Envelope
ApplHeader.MessageID
SOAP-WS-2B
ApplHeader.TimestampSent
ApplHeader.FluxID
{soap}Envelope
5.6.2.2 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 who 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.
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 describe 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.
- 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”
Cegeka N.V.
page 64 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
6. Appendix
6.1 Certificate Request
The B2B systems at RSVZ and the Social Insurance Funds (SIFs) run on a predefined server
infrastructure.
Organizations are advised to design this infrastructure for high-availability. One part of this design is to
set-up a cluster of B2B servers.
B2B
SERVER
B2B
SERVER
Certificate
Certificate
B2B
SERVER
SVF/
CAS
RSVZ/
INASTI
Certificate
RSVZ offers a high-available and fault tolerant server infrastructure in which each B2B server has been
assigned a separate server certificate. These X.509 certificates contain the same Subject Distinguished
Name - as they are considered a single endpoint to the outside world.
For establishing communication with partners, all servers of a given B2B environment use the same client
certificate. This certificate identifies the B2B system as a whole. Partners use this X.509 certificate to
authenticate and authorize the B2B system that initiated the request.
As part of a typical SSL setup, we can distinguish two types of certificates:


Server
Application (Client)
6.1.1 Server certificate
Each server on which the SSL connection is terminated MUST be assigned a server certificate.
Depending on the network topology within the organization, this can be the server hosting the B2B
application or a (reverse) proxy server that shields the B2B system.
The certificate(s) will be assigned to the server(s) on which the SSL connection is terminated.
Cegeka N.V.
page 65 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
When establishing the Subject Distinguished Name (Subject DN) that must be supplied when requesting
server certificates, the following principles should be applied:
CN : Common Name
This must be the Fully Qualified Domain Name (FQDN) with which the Social Insurance Fund
wants to expose its server(s) to RSVZ (or other partners).
eg. “b2b.steuntelkander.be” for the production environment of Steunt-Elkander.
This attribute MUST have an indication of the environment, if the certificate is not destined for
the production environment.
eg. “b2b-tst.steuntelkander.be” for the test environment of Steunt-Elkander.
RFC2396 states that a hostname is a sequence of “domains labels” that are separated by a dot.
Each domain label moet start and end with an alpfanumeric character, and may also contain a
hyphen.
O : Organization
The name of the Social Insurance Fund is mentioned here.
eg. Acerta.
OU : Organizational Unit
This attribute holds the company number of the Social Insurance Fund.
eg. 0416377646 for Acerta.
C : Country code
The country code of the Social Insurance Fund as defined in ISO-3166:
http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm
eg. BE for Belgium.
For its B2B platform, RSVZ has established the following Subject distinguished names:
production environment
CN =
O=
OU =
C=
b2b.rsvz-inasti.fgov.be
RSVZ/INASTI
0208044709
BE
acceptance environment
CN =
O=
OU =
C=
Cegeka N.V.
b2b-acc.rsvz-inasti.fgov.be
RSVZ/INASTI
0208044709
BE
page 66 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
test environment
CN = b2b-tst.rsvz-inasti.fgov.be
O=
OU =
C=
RSVZ/INASTI
0208044709
BE
6.1.2 Client certificate
When a Social Insurance Fund initates communication with RSVZ, it MUST use a client certificate to
confirm its identity.
SIFs that are currently using a server certificate when initiating communication MUST obtain a client
certificate – and use it to initiate communication with RSVZ - when their server certificate is up for
renewal.
The distinguished name for the subject of that client certificate MUST contain the following attributes:
CN : Common Name
This attribute MUST contain the name of the system – with an indication of the environment, if
the certificate is not destined for the production environment - that will exchange messages with
RSVZ.
eg. Ventouris (test) for the Ventouris application in the test environment.
When a central system (gateway or esb) is used to exchange messages with partners, a single
certificate SHOULD be used that identifies this gateway instead of using a separate certificate for
each backend application.
O : Organization
The name of the Social Insurance Fund is mentioned here.
eg. Acerta.
OU : Organizational Unit
This attribute holds the company number of the Social Insurance Fund.
eg. 0416377646 for Acerta.
C : Country code
The country code of the Social Insurance Fund as defined in ISO-3166:
http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm
eg. BE for Belgium.
For its B2B platform, RSVZ has established the following Subject distinguished names:
production environment
CN =
O=
OU =
C=
Cegeka N.V.
B2B
RSVZ/INASTI
0208044709
BE
page 67 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
acceptance environment
CN =
O=
OU =
C=
B2B (acceptance)
RSVZ/INASTI
0208044709
BE
test environment
CN =
O=
OU =
C=
B2B (test)
RSVZ/INASTI
0208044709
BE
6.1.3 Key Length
In cryptography, the key size determines how hard it is to crack a block of encrypted data. When
deciding upon the key length one must consider two tradeoffs:


Long keys provide more security
Short keys provide greater efficiency in terms of time required to encrypt/decrypt data
RSA acknowledges that 1024-bit keys are likely to become crackable before 2010, while 2048-bit keys are
deemed sufficient until at least 2030.
Therefore both RSVZ and the SIFs MUST use 2048-bit RSA keys.
6.1.4 Procedure
To obtain certificates from Fedict, the following procedure must be executed by the Social Insurance
Fund (SIF) for each certificate:
1. Contact Fedict to obtain the Certificate Request Form (FedICT-PKI-RequestForm).
2. Select the Certificate Type of the certificate that you want to obtain:
o Application: client certificate (see 6.1.2)
o Server: server certificate (see 6.1.1)
3. Complete the Distinguished Name and Certificate Signing Request sections on that form.
4. Enter the following text in the zone “Description what the certificate is used for”:
o B2B communicatie RSZV - netwerk sociaal statuut der zelfstandigen
5. Complete the requested information in the following boxes:
o Federal Civil Servant authorizing the request (mandatory)
o Technical Operator generating the request (optional)
6. Send the form to [email protected].
7. Finally, fax the signed form to Fedict: +32-2-212.96.94 (attn: CA SERVICES).
Repeat these steps for each certificate that you need.
Note that the certificate services offered by Fedict are free of charge for governmental institutions.
A Social Insurance Fund can request certificate from an alternate Certification Authority, but this
should be done after consulting RSVZ. The guidelines with regards to the distinguished name remain in
effect though.
Cegeka N.V.
page 68 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
6.2 Certificate Renewal
The validity of an X.509 certificate is always limited in time – both the start date, and the end date.
Different steps need to be taken when a certificate approaches its expiration date, depending on whether
the certificate represents a Social Insurance Fund or RSVZ.
6.2.1 Social Insurance Fund
A Social Insurance Fund MUST use the following procedure to renew a certificate:
1. The SIF obtains the serial number and common name (CN) from the certificate that need to be
renewed.
On Windows, double-clicking a certificate in PEM format (usually with extension .crt or .cer)
opens a certificate viewer. On the Details tab, the values of the Serial number and Subject
(containing the CN) attributes can be read.
For example:
Alternatively, one can use openssl to obtain this information.
For example:
openssl x509 -noout -serial –subject -in "b2b.rsvz-inasti.fgov.be.crt"
subject=/CN=b2b.rsvz-inasti.fgov.be/C=BE/OU=0208044709/O=RSVZ/INASTI
serial=01000000000120611F51AA
2. Send an e-mail to the CA – in case of Fedict: [email protected] – asking for the renewal of a
certificate mentioning the common name and serial number you obtained from step 1.
3. Once the SIF has obtained the new certificate – in case of Fedict this should be within 2 to 3
working days – it MUST be distributed to RSVZ ([email protected]) as soon as possible.
4. RSVZ adds the new certificate to its trust, and - in case of a client certificate - authentication
store.
5. The SIF imports the new certificate into its security store to start using it.
6. RSVZ removes the original certificate from its trust or authentication store.
Cegeka N.V.
page 69 of 70
B2B Web Service Guidelines V2
RSVZ Enterprise Architecture
When we put these steps into a timeline, this leads to the following result:
1. T-30
3. T-25
2. T-30
5. T-15
4. T-20
6. T-5
T is the expiration date of the certificate. The point in time of each event on the timeline is expressed as
the number of days before T.
So the renewal procedure MUST be started about 30 days before the certificate expires, and the renewed
certificate becomes active 15 days before the original certificate expires.
6.2.2 RSVZ
When a certificate from RSVZ need to be renewed, the following procedure MUST be executed:
1. RSVZ obtains the serial number and common name (CN) from the certificate that need to be
renewed.
2. RSVZ sends an e-mail to [email protected] asking for the renewal of a certificate providing the
common name and serial number of the certificate to renew.
3. Once RSVZ has obtained the new certificate it MUST be distributed to all SIFs as soon as
possible, and published on the public web site.
4. The SIFs add the new certificate to their trust and/or authentication store.
5. RSVZ imports the new certificate into its security store to start using it.
6. The SIFs remove the original certificate from their trust or authentication store.
This leads to the following timeline:
1. T-45
3. T-40
2. T-45
5. T-15
4. T-35
6. T-5
T is the expiration date of the certificate. The point in time of each event on the timeline is expressed as
the number of days before T.
Since more parties (multiple SIFs and RSVZ) are involved, the renewal procedure MUST be started about
45 days before the certificate expires, and the renewed certificate becomes active 15 days before the
original certificate expires.
As the certificates for the individual environments at RSVZ (test, acceptance and production) expire at
about the same time, all steps – except step 5 – will be executed in parallel for all environments.
Step 5 will first be executed in test, then acceptance and finally in production. This allows SIFs to test
the effects of the certificate renewel first in non-critical environments.
Note:
The latest version of the client and server certificates of RSVZ for each environment is available for
download from http://www.rsvz-inasti.fgov.be/schemas/B2B-certificates.
Cegeka N.V.
page 70 of 70