File/FTP-Empfänger-Adapter konfigurieren 

Verwendung

Sie konfigurieren den File/FTP-Empfänger-Adapter, um damit XML-Messages von der Integration Engine in Dateien abzulegen.

Die Konfiguration besteht im Wesentlichen aus der Angabe

●      eines Verzeichnisses und einer Regel zur Bestimmung von Dateinamen, unter denen ankommende Nachrichten abgelegt werden

·        der Dispatcherklasse (optional) mit den entsprechenden Einstellungen sowie der vom Dispatcher aufzurufenden User-Exits und deren Einstellungen

●      der Adresse (HTTP-Port und URL), unter der der Adapter von der Integration Engine aus erreicht werden kann

·        von Regeln zur Konvertierung einer XML-konformen Textdatei, die eine einfache Tabellenstruktur repräsentiert, in ein Textdokument mit Spalten fester Länge und/oder Spalten, die durch bestimmte Zeichen voneinander getrennt sind (diese Angaben sind optional)

Voraussetzungen

Sie haben

...

       1.      den entsprechenden Adapter installiert

       2.      den Adapter in der Konfigurationsoberfläche ausgewählt

       3.      über Konfigurieren die Konfiguration des Adapters aufgerufen

Vorgehensweise

Für den File/FTP-Empfänger-Adapter besteht die Konfiguration aus fünf funktionalen Teilbereichen:

...

       1.      Der Name der Java-Klasse für den File/FTP-Empfänger-Adapter

Geben Sie den Namen der Klasse folgendermaßen an:

classname=com.sap.aii.messaging.adapter.ModuleXMB2FILE

Diese Angabe ist zwingend.

       2.      Die Versionsangabe für die Konfiguration.

version=30

Diese Angabe ist zwingend. Fehlt die Angabe, wird die Konfiguration als XI 2.0 Adapter-Konfiguration interpretiert. Andere Werte sind nicht zulässig und werden als Fehler ausgegeben.

       3.      Der Modus des File/FTP-Adapters

Geben Sie den Modus des File/FTP-Empfänger-Adapters an. Erlaubte Werte sind

○       mode=XMB2FILE

Hier wird das von der Integration Engine geschickte Dokument direkt als Datei abgelegt.

¡        mode=XMB2FILEWITHCONVERSION

Hier wird eine Textdatei erwartet, die ein XML-Dokument enthält, das eine Tabelle repräsentiert. Dieses Dokument kann zu einer Textdatei konvertiert werden, die den Inhalt des Dokuments als Liste ablegt mit durch Kommata getrennten Elementen oder mit fester Spaltenlänge. Das erwartete XML-Format entspricht dem Ergebnis der Konvertierung des File/FTP- oder JDBC-Sender-Adapters. Die für diese Konvertierung notwendigen Angaben müssen Sie in Schritt 5 festlegen.

¡        mode=XMBSTREAM2FILE

Hier wird ein spezielles Dateiformat erzeugt, das eine vollständig serialisierte Nachricht der Integration Engine darstellt. Dieses Dateiformat kann vom File/FTP-Sender-Adapter im Modus FILE2XMBSTREAM verarbeitet werden. Dieses Format eignet sich damit zum Zwischenspeichern kompletter Nachrichten der Integration Engine einschließlich aller für die Integration Engine spezifischen Parameter, die im File/FTP-Sender-Adapter dann nicht mehr angegeben werde müssen.

Der Vorschlagswert ist XMB2FILE.

       4.      Die Dispatcherklasse und die vom Dispatcher aufzurufenden User-Exits (optional)

Der File/FTP-Empfänger-Adapter bietet einen Dispatcher an, mit dem Sie Messages nach dem Empfangen konvertieren können. Die für den Dispatcher notwendigen Einstellungen werden anhand eines konkreten Beispiels erklärt.

       5.      Die Angaben für die Adressierung von der Integration Engine

¡        XI.httpPort=<port_no>

<port_no> gibt den Port des HTTP-Servers an, der die Nachrichten der Integration Engine entgegennimmt.

¡        XI.httpService=<service>

<service> beschreibt den Serviceteil der Adresse, zu dem die Integration Engine ihre Nachrichten schicken muss.

Diese Angaben sind zwingend.

Haben Sie zum Beispiel XI.httpPort=1234 und XI.httpService=/file/Receiver spezifiziert, muss die Endpunkt-Adresse des File/FTP-Adapters in der Integration Engine wie folgt spezifiziert sein:

http://<fileadapterhost>:1234/file/Receiver

Für die Integration Engine in der Version 1.0 muss die Endpunkt-Adresse wie folgt erweitert werden:

http://<fileadapterhost>:1234/file/Receiver?action=execute&pipelineid=Receiver

Wird die Nachricht von der Integration Engine an einen nicht spezifizierten Service des Adapters geschickt, erfolgt die Fehlermeldung:

No registered listener for <service> found

Die gleiche Fehlermeldung erhält man, wenn der Adapter initialisiert, aber nicht gestartet ist (sich also im Status ANGEHALTEN oder INITIALISIERT befindet).

○       XI.ReceiverAdapterForService=<Service>

Diese Angabe ist optional.

<Service> ist der logische Name eines Business-Systems im System Landscape Directory (SLD). Ist die Verbindung der Adapter-Engine zum SLD konfiguriert, wird für den File/FTP-Empfänger-Adapter eine Assoziation zu diesem Business-System angelegt. Im Integration Directory wird beim Anlegen eines Endpunkts für dieses Business-System, aus dieser Assoziation die Adresse des Adapters als Vorschlagswert ermittelt.

Kann keine Verbindung zum SLD hergestellt werden, oder existiert das Business-System im SLD nicht, ist die Angabe bedeutungslos.

       6.      Die Angaben zur Dateiverarbeitung:

¡        file.createDir=<n>

Geben Sie an, ob ein Zielverzeichnis (targetDir) erzeugt werden soll (1) oder nicht (0), falls nicht bereits eins existiert. Vorschlagswert ist 1 (Verzeichnis erzeugen).

Die folgenden Angaben sind zwingend:

¡        file.targetDir=<directoryName>

Geben Sie das Zielverzeichnis an, in dem eingehende Dokumente gespeichert werden sollen. Dieses Verzeichnis wird automatisch erzeugt, falls Sie unter file.createDir nichts gegenteiliges angegeben haben.

¡        file.targetFilename=<fileName>

Geben Sie den Dateinamen an, unter dem das erste ankommende Dokument abgelegt werden soll.

¡        file.writeMode=<mode>

Geben Sie an, ob ankommende Dokumente alle unter dem Dateinamen abgelegt werden sollen, der unter file.targetFilename spezifiziert wurde. Erlaubte Werte sind

■       file.writeMode=overwrite (veraltet)

Im Modus overwrite wird die Datei überschrieben, so dass immer nur das letzte erhaltene Dokument gespeichert wird.

Dieser Parameter ist durch file.overWrite ersetzt.

§         file.writeMode=append

Im Modus append wird die Datei durch Anhängen der eingehenden Dokumente fortgeschrieben.

§         file.writeMode=addTimeStamp

Im Modus addTimestamp wird für jedes Dokument eine neue Datei erzeugt. Der Dateiname besteht aus dem unter file.targetFilename angegebenen Namen, jeweils erweitert um einen Zeitstempel im Format yyyyMMdd-HHmmss-SSS. Dieser entspricht dem Zeitpunkt der Dokumentverarbeitung – von der Jahreszahl (yyyy) bis zu den Millisekunden (–SSS) –, der vor der Erweiterung des Dateinamens eingefügt wird.

Dieser Modus garantiert, dass keine Dateien überschrieben werden. Dateien, die aus der gleichen Adapter-Konfiguration stammen, können so einfach nach ihrem Eingangsdatum sortiert werden.

■       file.writeMode=addMessageId

Im Modus addMessageId wird für jedes Dokument eine neue Datei erzeugt. Der Dateiname besteht aus dem unter file.targetFilename angegebenen Namen, jeweils erweitert um die vom Integration Server verwendete Message-ID (GUID) im Format xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Dieser Modus garantiert, dass keine Dateien überschrieben werden.

§         file.writeMode=addCounter

Im Modus addCounter wird für jedes Dokument eine neue Datei erzeugt. Der Dateiname besteht aus dem unter file.targetFilename angegebenen Namen, jeweils erweitert um einen Zähler, der vor der Erweiterung des Dateinamens eingefügt wird (zum Beispiel default002.file). Der Zähler wird aus den nachfolgenden Angaben konstruiert.

Der Modus addCounter garantiert, dass keine Dateien überschrieben werden. Gegebenenfalls wird der nächste noch nicht verwendete Zähler gefunden, auf dessen Basis ein noch nicht vorhandener Dateiname konstruiert werden kann.

Im Modus addCounter kann das genaue Format des Dateinamens mit den folgenden Parametern gesteuert werden, für die es jeweils eine Voreinstellung gibt.

¡        file.counterSeparator=<SeparatorString>

Geben Sie ein oder mehrere Zeichen an, die vor dem Zähler im Dateinamen eingefügt werden. Der Vorschlagswert ist eine leere Zeichenfolge (also kein SeparatorString)

¡        file.counterFormat=<FormatString>

Geben Sie den ersten Zähler an, der verwendet werden soll. Es muss sich um eine gültige Integer-Zahl handeln, wobei führende Nullen erlaubt sind. Die Länge des FormatString wird für alle Zähler benutzt (inklusive vorhandener führender Nullen), bis es zu einem Überlauf kommt, der eine Vergrößerung des Formats erzwingt.

Der Vorschlagswert ist 000.

¡        file.counterStep=<StepNo>

Geben Sie eine Zahl ein, die die Schrittweite des Zählers angibt, um die aufeinanderfolgende Zähler jeweils erhöht werden. Der Vorschlagswert ist 1.

¡        file.counterMode=<counterMode>

Geben Sie an, wann ein Zähler angefügt werden soll. Erlaubte Werte sind

■       file.counterMode=afterFirst

Der Zähler soll erst angefügt werden, nachdem der unter file.targetFilename angegebene Dateiname unverändert verwendet wurde.

§         file.counterMode=immediately

Der Zähler soll bereits beim ersten eingehenden Dokument angefügt werden.

Vorschlagswert ist afterFirst.

Wird keiner der Parameter gesetzt, werden aus den angegebenen Vorschlagswerten für nacheinander eingehende Dokumente die Dateinamen <default.file>, <default000.file>, <default001.file>, <default002.file> usw. erzeugt.

Werden anstelle der Vorschlagswerte zum Beispiel explizit folgende Werte gesetzt

file.targetFilename=test.dat

file.counterMode=immediately

file.counterSeparator=_

file.counterFormat=00005

file.counterStep=2

werden die Dateinamen test_00005.dat, test_00007.dat, test_00009.dat usw. erzeugt.

Diese Liste wird auch nach einem Beenden und Neustart des Adapters fortgesetzt, ohne existierende Dateien zu überschreiben.

○       file.overWrite=true|false

Legen Sie fest, ob eine Datei mit einem bereits vorhandenen Dateinamen im Zielverzeichnis überschrieben werden soll. Vorgabewert ist false, eine bereits vorhandene Datei im Zielverzeichnis wird überschrieben. Setzen Sie den Wert auf true, wird die bereits vorhandene Datei nicht überschrieben.

○       file.encoding=<codepage>

Dieser Parameter ist optional.

Der Vorschlagswert ist bei Binärdaten die vom Integration Server verwendete Codepage (das heißt, die Daten werden unverändert gespeichert). Bei Textdaten ist der Vorschlagswert die System-Codepage der Adapter-Engine (das heißt, die vom Integration Server in UTF-8 codierten Textdaten werden entsprechend konvertiert).

Ist file.encoding spezifiziert und schickt der Integration Server Binärdaten, werden diese als in UTF-8 codierter Text interpretiert.

Erlaubte Werte für die Codepage sind die vorhandenen Charsets der Java-Laufzeit. Nach der Spezifikation von SUN für die Java-Laufzeit müssen mindestens die folgenden Standard-Charsets unterstützt sein:

Charsets der Java-Laufzeit

Charset	Beschreibung
US-ASCII	Sieben-Bit ASCII, auch bekannt als ISO646-US, oder Basic-Latin-Block des Unicode-Zeichensatzes
ISO-8859-1	ISO-Zeichensatz für westeuropäische Schriften (Latin Alphabet Nr. 1), auch bekannt als ISO-LATIN-1
UTF-8	Acht-Bit Unicode-Zeichendarstellung
UTF-16BE	16-Bit Unicode-Zeichendarstellung, big-endian Byte-Order
UTF-16LE	16-Bit Unicode-Zeichendarstellung, little-endian Byte-Order
UTF-16	16-Bit Unicode-Zeichendarstellung Byte-Order

Überprüfen Sie in der Dokumentation für Ihre Java-Laufzeit-Implemetierung, welche weiteren Charsets unterstützt werden.

 

¡        file.execute=<operating system command>

Ein hier spezifiziertes Betriebssystemkommando wird nach erfolgreicher Dateiverarbeitung ausgeführt. Der Vorschlagswert ist eine leere Zeichenkette (kein Kommando).

Der aktuell prozessierte Dateiname kann mit dem Platzhalter %f (Dateiname) bzw. %F (absoluter Dateiname inklusive Pfad) im Betriebssystemkommando mitgegeben werden.

¡        file.exactlyOnceHandlingIDsExpiration=<n Days>

Geben Sie die Anzahl an Tagen an, die die Verwaltungsinformation empfangener Nachrichten mit dem Service-Attribut Exactly Once (In Order) aufbewahrt werden sollen. Diese Informationen werden benötigt, um Nachrichtenduplikate zu verhindern, falls die Integration Engine die gleiche Nachricht im Rahmen einer Fehlerbehandlung mehrmals an den Adapter sendet. Der Vorschlagswert ist 60 Tage.

Wird der Wert auf 0 oder eine negative Zahl gesetzt, werden bei jeder Adapter-Initialisierung alle Verwaltungsinformationen gelöscht. Dies kann zu Testzwecken sinnvoll sein, sollte aber keinesfalls im Produktivbetrieb gemacht werden.

Wird eine Nachricht mit Service-Attribut Exactly Once empfangen, wird im Zielverzeichnis zunächst eine temporäre Datei mit dem Namen der Adapter-Konfiguration erzeugt. Diese Datei wird dann während der Behandlung des Exactly Once automatisch in den endgültigen Dateinamen unbenannt und darf keinesfalls manuell bearbeitet oder gelöscht werden (auch nicht im Falle eines Abbruchs), da es sonst zum Verlust der Nachricht kommen kann.

Soll die Dateiablage nicht im Dateisystem, sondern auf einem FTP-Server erfolgen, sind zusätzlich die folgenden Angaben erforderlich:

Im FTP-Client-Modus ist beim Parameter file.writeMode der Wert addCounter nicht erlaubt.

¡        ftp.host=<ftp-server>

Der Host-Name oder die IP-Adresse des FTP-Servers. Ist diese Angabe vorhanden, wird von einem FTP-Server-Zugriff ausgegangen. Die Angaben file.targetDir und file.targetFilename beziehen sich dann auf den FTP-Server.

¡        ftp.port=<port-no.>

Die Port-Nummer des FTP-Servers. Die Angabe ist nicht zwingend; die Voreinstellung ist der Standard-Port für FTP-Server (21).

¡        ftp.user=<user name>

¡        ftp.password=<password>

Ein für den FTP-Server gültiger Benutzername. Die Angabe ist nicht zwingend; die Voreinstellung ist der Benutzer anonymous mit dem Kennwort anonymous.

¡        ftp.connection=perFileTransfer|permanently

Mit dieser Angabe können Sie festlegen, ob für jeden File-Transfer zum FTP-Server eine neue Verbindung geöffnet werden soll (Wert perFileTransfer) oder ob eine bestehende Verbindung permanent genutzt werden soll (Wert permanently). In diesem Fall wird die Verbindung automatisch wiederaufgebaut, falls sie server-seitig geschlossen wurde (z.B. wegen Timeout). Vorschlagswert ist permanently.

○       ftp.putSafe=YES|NO

Mit dieser Angabe können Sie festlegen, ob eine transferierte Datei zunächst unter einem temporären Namen angelegt und erst nach vollständiger Übertragung umbenannt wird (YES) oder bereits zu Beginn der Übertragung unter ihrem endgültigen Namen angelegt wird (NO). Dieser Fall kann zu Problemen führen, wenn eine Anwendung auf dem FTP-Server bereits auf die Datei zugreift, obwohl die Übertragung noch nicht abgeschlossen ist. Durch die Angabe von YES kann dies verhindert werden, da dann die Datei unter dem gesuchten Namen erst dann sichtbar wird, wenn sie vollständig übertragen wurde.

Der Vorschlagswert ist NO.

       7.      Die Angaben zur Konvertierung eines XML-Dokuments (Modus XMB2FILEWITHCONVERSION)

Die nachfolgend als zwingend bezeichneten Argumente beziehen sich auf den Modus XMB2FILEWITHCONVERSION. Bei einem anderen Modus werden die nachfolgend aufgeführten Argumente ignoriert.

Um die Konvertierung einer XML-konform dargestellten Tabelle in reines Textformat vornehmen zu können, wird das gleiche Dokumentenformat erwartet, wie es der File/FTP-Sender-Adapter im Modus FILE2XMBWITHROWCONVERSION(mit Standardwert <row> für die Struktur) sowie der JDBC-Sender-Adapter erzeugen können. Dies bedeutet, dass die Dokumentstruktur folgendermaßen aussieht:

<resultset>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

</resultset>

Dies ist ein Beispiel für 3 Spalten und 2 Zeilen. Erlaubt ist natürlich eine beliebige Anzahl von Zeilen und Spalten. Die kursiv gesetzten XML-Elemente sind frei definierbar, die Elemente einer Zeile müssen innerhalb eines Elements vom Typ <row> ... </row>gruppiert sein. Aus diesem XML-Dokument wird mit Hilfe der folgenden Angaben eine Textdatei konstruiert.

¡        xml.addHeaderLine=<n>

Geben Sie an, ob in der Textdatei eine Kopfzeile mit Spaltennamen vorhanden sein soll. Erlaubte Werte sind

■       0 – keine Kopfzeile

§         1 – Kopfzeile mit den Spaltennamen aus dem XML-Dokument

§         2 – wie 1, gefolgt von einer Leerzeile

§         3 – Kopfzeile ist als xml.headerLinein der Konfiguration hinterlegt und wird übernommen

§         4 – wie 3, gefolgt von einer Leerzeile

Die Angabe ist zwingend.

¡        xml.headerLine=<headerLineString>

Geben Sie die Kopfzeile an, die in der Textdatei erzeugt wird, wenn xml.addHeaderLine den Wert 3 oder 4 hat. In diesem Fall ist die Angabe zwingend.

¡        xml.fieldFixedLengths=<String>

Geben Sie eine Zeichenkette an, die eine Liste von festen Spaltenbreiten enthält, die durch Kommata getrennt sind und die die Anzahl und Länge der in der Textdatei erzeugten Spalten bestimmen.

Die Angabe von xml.fieldFixedLengths ist zwingend, wenn bei xml.fieldSeparator keine Angabe gemacht wird.

¡        xml.fixedLengthTooShortHandling=<handling>

Geben Sie an, wie bei einer Angabe von xml.fieldFixedLengths Überschreitungen von dort definierten Spaltenbreiten durch die tatsächlich im Dokument gefundenen Werte behandelt werden sollen. Erlaubte Werte sind

■       xml.fixedLengthTooShortHandling=Error

Error bedeutet einen Abbruch der Verarbeitung des Dokuments.

§         xml.fixedLengthTooShortHandling=Cut

Cut bedeutet ein Abschneiden des vorgefundenen Wertes auf die maximal erlaubte Länge.

§         xml.fixedLengthTooShortHandling=Ignore

Ignore bedeutet, dass der gefundene Wert ungeachtet der Längenüberschreitung komplett übernommen wird. Nachfolgende Spalten verschieben sich dadurch entsprechend.

Der Vorschlagswert ist Error.

Ist xml.fieldFixedLengths nicht angegeben, ist diese Angabe bedeutungslos.

¡        xml.fieldSeparator=<SeparatorString>

Eine hier angegebene Zeichenkette wird bei allen Spalten außer der letzten als Trennzeichen angefügt. Sie können diese Zeichenkette auch zusätzlich zu xml.fieldFixedLengths angeben.

Haben Sie bei xml.fieldFixedLengths keine Angabe gemacht, ist dies die einzige Angabe zur Identifikation der einzelnen Spalten einer Reihe.

Haben Sie bei xml.fieldFixedLengths eine Angabe gemacht, wird die Länge des Trennzeichens nicht auf diese Länge angerechnet.

Es muss mindestens xml.fieldFixedLengths oder xml.fieldSeparator spezifiziert sein.

Wenn Sie ausschließlich xml.fieldSeparator spezifiziert haben, können die Strukturen des XML-Dokuments unterschiedlich viele Elemente besitzen, die dann in der Textdatei durch den Wert von xml.fieldSeparator getrennt aneinandergefügt werden. Bei der Angabe von xml.fieldFixedLenghts ist das nicht möglich, da durch die Aufzählung der Spaltenbreiten auch die Anzahl der Spalten festgelegt wird.

¡        xml.endSeparator=<lastSeparatorString>

Eine hier angegebene Zeichenkette wird bei der letzten Spalte als Abschlusszeichen angefügt. Diese Angabe können Sie auch zusätzlich zu xml.fieldFixedLengths machen. Ein gewollter Zeilenumbruch nach dem Abschlusszeichen muss explizit durch Anhängen von ´nl´ (einschließlich der Hochkommata) an die Zeichenkette definiert werden.

Der Vorschlagswert ist ein Zeilenumbruch (also kein explizites Trennzeichen nach der letzten Spalte; statt dessen sind die Strukturen zeilenweise angeordnet).

¡        xml.beginSeparator=<firstSeparatorString>

Eine hier angegebene Zeichenkette wird bei der ersten Spalte vorangestellt. Diese Angabe können Sie auch zusätzlich zu xml.fieldFixedLengths machen.

Der Vorschlagswert ist eine leere Zeichenkette (also kein Trennzeichen vor der ersten Spalte).

Sonderzeichen in den Zeichenketten für Trennzeichen:

In allen Zeichenketten für Trennzeichen (xml.fieldSeparator, xml.beginSeparator, und xml.endSeparator) ist die Angabe von nicht-druckbaren ASCII-Zeichen möglich. Diese Zeichen können in der Form ´0xHH´ (einschließlich Hochkommata) jeweils einzeln in die Zeichenketten eingefügt werden, wobei HH das als Hexadezimalwert kodierte Zeichen darstellt. Ein Zeilenumbruch kann als Zeichen ´nl´ (einschließlich Hochkommata) eingefügt werden; nl steht für new line. Das Sonderzeichen ´0´ bedeutet kein Separatorzeichen.

Feste Spaltenbreite des Textdokuments:

xml.absoluteRowWidth=<noOfColumns>

Enthalten die Trennzeichen keine Zeilenumbrüche, wird das Textdokument als einzeiliger Text erzeugt. Soll die Textbreite beschränkt werden, kann dies mit diesem Parameter geschehen, wobei <noOfColumns> die maximal Anzahl der Spalten darstellt. Dieser Parameter funktioniert auch zusammen mit der Angabe eines Zeilenumbruchs bei xml.endSeparator.

Dieser Wert setzt die Angabe xml.addHeaderLine=0 voraus.

       8.      Der Adapter kann ein synchrones System-Acknowledgment zurücksenden, wenn es vom Sender angefordert wird. Das Acknowledgment bestätigt, dass die Nachricht an den Empfänger ausgeliefert wurde.

○       Wollen Sie ein synchrones System-Acknowledgment zurücksenden, setzten Sie XI.AckFinal=true. Dies ist der Vorgabewert.

○       Wollen Sie vermeiden, dass ein synchrones System-Acknowledgment zurückgesendet wird, auch wenn es vom Sender angefordert wird, setzen Sie XI.AckFinal=false.