Einführung

Die Zielsetzung der AVS3 Webservices liegt in der Öffnung des bestehenden AVS3-Systems nach außen. Hierbei wurde eine Schnittstelle geschaffen, welche auf allgemeinen Standards beruht und den Anwendern eine größtmögliche Flexibilität gewährt. Dabei soll es keine Rolle spielen, von wo die Daten kommen bzw. wo sie hingehen. Es ist jedoch auch gleichermaßen möglich diese Schnittstelle z. B. als Mittler zwischen dem AVS/3 auf der einen Seite und einem Drittsystem auf der anderen Seite zu sehen. Da die Schnittstelle nichts anderes macht, als XML-codierte Daten zu senden und zu empfangen, sind beide Szenarien gleichermaßen realisierbar.

SOAP (Simple Object Access Protokoll) ist ein RPC-Mechanismus, der auf der Basis der Internetstandards XML (eXtensible Markup Language) und HTTP (Hypertext Transfer Protokoll) arbeitet.

Eine Anfrage wird dabei in XML verpackt und über HTTP an einen Server geschickt. Im allgemeinen findet hierbei die POST-Methode Verwendung. Der Server verarbeitet die Anfrage und verpackt die Antwort ebenfalls in XML. Diese wird dann zurück an den Client gesendet.

Da SOAP auf bereits bestehenden und sehr verbreiteten Standards basiert und sehr einfach zu implementieren ist, können Clients und Server in fast jeder beliebigen Sprache entwickelt werden. Um aber die Arbeit zu vereinfachen und um von Standardaufgaben zu entlasten, gibt es für zahlreiche Sprachen bereits Unterstützung in Form von Bibliotheken oder direkten Implementierungen des Protokolls.

Beispiele:

Wenn verschiedene Anwendungen zusammenarbeiten sollen, dann wird dies üblicherweise über eine Middleware realisiert. Diese stellt quasi eine gemeinsame Sprache dar, über die sich unterschiedliche Systeme unterhalten können.

Fast alle klassischen Middleware Systeme sind aber an eine bestimmte Plattform gebunden und scheitern vollständig, wenn es um die Kommunikation über das Internet geht. Mit SOAP werden diese beiden Probleme auf sehr elegante Weise gelöst, indem einfach auf Basis unabhängiger Standards gearbeitet wird.

DSB behält sich vor die in diesem Dokument beschrieben XML-Strukturen ohne Vorankündigung anzupassen, solange diese Anpassungen komplett abwärtskompatibel bleiben. In der Praxis sind dies hauptsächlich Ergänzungen von Elementen und Attributen.

Beispiel 1: Neues Element

Neue Elemente können hinzugeführt werden. Alle Clients sollten so auf die Elemente zugreifen (z. B. nur über den Namen), dass keine Anpassung notwendig ist.

Struktur VOR der Erweiterung/Anpassung:

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

Struktur NACH der Erweiterung/Anpassung:

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

Beispiel 2: Neues Attribut

Attribute zu Elementen können hinzugeführt werden. Alle Clients sollten so auf die Elemente zugreifen (z.B. nur über den Namen), dass keine Anpassung notwendig ist.

Struktur VOR der Erweiterung/Anpassung:

<existing-element1>ABCD</existing-element1>

Struktur NACH der Erweiterung/Anpassung:

<existing-element1 new-attribute="XYZ">ABCD</existing-element1>

Um dies auf Seite des Clients sicherstellen zu können, gibt es einen speziellen Webservice, mit dem geprüft werden kann, wie der Client auf solche Erweiterungen reagiert.

Siehe hierzu Abschnitt zum Service checkUpgradeCompatibility.

Soweit die in den nächsten Abschnitten beschrieben Dienste nicht explizit eine andere Regelung festlegen, gelten allgemein die folgenden Format und Kodierungsregeln:

Zeichensatz

Die XML-Dokumente sollten mit UTF-8 kodiert sein. Alternativ kann auch ISO-8859-1 verwendet werden. Dies muss dann aber im dokument korrekt konfiguriert sein.

Dezimalwerte

Dezimalwerte sind durch Punkt ( . ) getrennt. Tausenderzeichen werden nicht verwendet. Bei Formatangaben entspricht der Wert vor dem Komma, der Anzahl der Vorkommastellen, der Wert nach dem Komma, der Anzahl Nachkommastellen. Eine Definition 7,2 umfasst also 9 Ziffern.

Datums-/Zeitangaben

Format für Datumsangaben

JJJJ-MM-TT
- TT=Tag
- MM=Monat
- JJJJ=Jahr; jeweils mit Vornullen

Beispiel: 2004-08-20

Format für Zeitangaben

HH:MM:SS
- HH=Stunde
- MM=Minute
- SS=Sekunde, jeweils mit Vornullen

Beispiel: 09:54:16

Format für Zeitpunkte

YYYY-MM-DDThh:mm:ss (gemäß XML Standard)
- YYYY Jahr
- MM Monat
- DD Tag
- T Trenner zwischen Datum und Uhrzeit
- hh Stunden
- mm Minuten
- ss Sekunden

Beispiel: 2002-05-30T09:00:00

Heftnummern / Vertriebsausgaben

Format für Heftnummern: AAAA/JJJJ (AAAA=Heftausgabe, JJJJ=Jahr).

Beispiel: 0012/2002

Datentypen in Elementdefinitionen

N Numerisch
C Character / alphanumerisch
D Datum

T Time
B Boolean (true / false)

NC numerische Character-Felder: hier ist die einzufügende Zahl mit führenden Nullen auf die Gesamtlänge zu bringen. Beispiel: die PVA in ‚in_abo__struct‘ welche z. B. den Wert ‚10729‘ besitzt ist dann (aufgrund der Länge 8 der PVA) als ‚00010729‘ zu kodieren.

Sonderzeichen

Folgende Zeichen sind in einem XML entsprechend der XML Spezifikation zu kodieren, falls sie nicht Teil der XML eigenen Auszeichnung sind:

& → &
< → <
> → >

Leere Tags

Falls leere Elemente übergeben werden (also z.B. <promotion-source></promotion-source> oder <promotion-source/>) so wird dies als Löschung eines evtl. vorhandenen Default-Wertes für dieses Element betrachtet. Es sollte deshalb vermieden werden, leere Elemente zu übergeben, außer ein Default-Wert soll explizit gelöscht werden.

Reihenfolge der Elemente

Die Reihenfolge der Elemente ist wie dargestellt einzuhalten. Dateien, die diesbezügliche Fehler aufweisen, werden als Ganzes abgelehnt.

Dienste, die mit den Kennzeichen BETA versehen sind, befinden sich noch in der Entwicklung und können noch nicht produktiv eingesetzt werden.

Dienste, die mit den Kennzeichen (… mandantenspezifisch) versehen sind → bitte kontaktieren Sie hierzu die zuständige SAP-Beratung.

Einführung

Zielsetzung

Was ist SOAP?

Warum SOAP?

Änderung der XML Strukturen