Introduction

The objective of AVS3 web services lies in the opening of the current AVS3 System outward. Therefore an interface has been created which is based on general standards and offers a flexibility for users. At the same time it should not matter from where the data comes from respectively where it goes. The interface does only receive and send XML-coded data, so many scenarios are implementable.

SOAP (Simple Object Access Protokoll) is a RPC- mechanism, which is based on Inernet standards XML (eXtensible Markup Language) and HTTP (Hypertext Transfer Protocol) works.

An enquiry is packed in XML and is send to a server over HTTP. Generally the POST-Method finds usage here. The server processes the enquiry and packs the response also in XML. And then it is sent back to the client.

Because SOAP is based on already pre-existing and very spreading standards and it is also very simple to implement, clients and server can be developed in almost every kind of language. But to simplify work and to relieve from standard tasks there is already support in form of libraries for numerous languages or direct implementation of the protocol.

At this point the most important are:

• Spring Web Services
• Apache Axis
• and other …

Usually when different applications should work together then it is realised over a so called Middleware. This Middleware personates, so to speak, a common language so that different systems can communicate.

But almost all classical Middleware Systems are bounded on a particular platform and so they fail completely as far as the communication over the Internet is concerned. With SOAP those two problems are solved in a very elegant way while working on a basis of independent standards.

DSB reserves to adapt the described XML-structures in this document without notice in advance as long as this adaptations stay completely downwardly compatible. In practice are these mainly complements of elements and attributes.

Example 1: New Element

New elements can be added. All clients should have access to the elements ( for example, only over the name) so that no adaptation is necessary.

Structure BEFORE Extension/Adaptation

<existenting-element1>ABCD</existenting-element1>
<existenting-element2>1234</existenting-element2>

Structure AFTER Extension/Adaptation

<existenting-element1>ABCD</existenting-element1>
<new-element>XYZ</new-element1>
<existenting-element2>1234</existenting-element2>

Example 2: New Attribute

Attributes to elements can be added. All clients should have access to the elements ( for example only over the name) so that no adaptation is necessary.

Structure BEFORE Extension/Adaptation

<existenting-element1>ABCD</existenting-element1>

Structure AFTER Extension/Adaptation

<existenting-element1 **new-attribute="XYZ"**>ABCD</existenting-element1>

To ensure on client side, that you are conform to this upgrade mechanism, there is a special service to check this. Please see service ServiceInfo.checkUpgradeCompatibility

Order of XML Elements

The order of xml elements has to be observed as shown in the description.

As far as in the next sections, for services, not explicitly a different re-arrangements set, apply the generally, following format and coding rules:

The XML documents should be encoded with UTF-8 encoding. ISO-8859-1 can be used alternatively .

A point is used as decimal separator. There is no thousand separator. At format information the value before the comma correspond to numbers of pre-decimal positions, the value after the comma to numbers of post decimal positions. A definition 7,2 comprises 9 digits.

Format for date: YYYY-MM-DD ( DD=day; MM=month; YYYY=year; each with pre zeros).

For example: 2004-08-20

Format for time: HH:MM:SS (HH=hour; MM=minute; SS=Second, each with pre zeros).

For example: 09:54:16

Default Format for copy no.: AAAA/YYYY (AAAA=issue, YYYY=year).

For example: 0012/2002

Or any other client specific format /free text.

• N = numeric
• C = Character / alphanumeric.
• D = Date
• T = Time
• NC = numeral character-fields: Here the inserted number with leading zeros has to be brought up to total length. For example: edition ‚in_subs.__struct‘ which has for example the value ‚10729‘ is then (due to length 8 of the edition) to code as ‚00010729‘.

Following signs in XML are to code as follows if they are not part of XML-own record:

• & → &
• < → <
• > → >

If empty elements are transferred (for example <promotion-source></promotion-source> or <promotion-source/>) is this regarded as cancellation of a possibly existing Default-value for this element. Therefore it should be avoided to transfer empty elements except a Default-value should be cancelled explicitly.

Services that are marked with BETAtag, are still in development and cannot be used in production mode.