Stiftung Auffangeinrichtung BVG Fondation institution supplétive LPP Fondazione istituto collettore LPP Anleitung Command Line Client Demo Client Version 1.1
Inhalt 1. Allgemein... 3 1.1. Installieren und Starten der Anwendung... 3 2. Demo... 4 3. Command Line Client... 4 3.1. submit... 5 3.2. receive... 5 3.3. run 5 3.4. logs 5 3.5. prod 6 3.6. Verzeichnisse... 6 3.7. Dateien manuell editieren... 6 Anleitung Client.docx Seite 2 von 6
1. Allgemein Viele Einrichtungen werden nicht sofort eine vollständige Webservice Einbindung von BVG Exchange in ihre Verwaltungsapplikation realisieren können oder wollen. Für diese Einrichtungen stellt die Auffangeinrichtung ein Java-basiertes Kommandozeilen Tool zur Verfügung das die gesamte Funktionalität von BVG Exchange abbildet. Dieses Tool kann in allen Systemumgebungen (Windows, Linux, Unix, etc.) in automatisierte Batchläufe integriert werden. Einrichtungen können damit ohne Anpassung ihres Verwaltungssystems BVG Exchange verwenden. Um exemplarisch die Funktionsweise von BVG Exchange darzustellen, enthält der Client eine vollständige Demo Applikation, die die gesamte Funktionalität des angebotenen Webservices zeigt. Beide Anwendungen liegen im Sourcecode vor und können als Vorlage für eigene Implementierungen verwendet werden. Diese Dokumentation beschreibt ausschliesslich die Verwendung des Clients und hat nicht den Anspruch BVG Exchange oder die verwendeten XML Schema zu erklären. Diese Anleitung setzt grundlegendes Wissen über Windows/Linux sowie minimales Wissen über Java Kommandozeilen Aufrufe voraus. 1.1. Installieren und Starten der Anwendung Auf der BVG Exchange Webseite (https://exchange.aeis.ch) erhalten Sie die aktuelle Version des BVG Exchange Client (BVGExchangeClient-x.x.x.zip). Entpacken Sie diese Zip-Datei in ein Verzeichnis Ihrer Wahl. Die Zip-Datei enthält zwei Dateien. Diese Dokumentation sowie eine Jar-Datei (BVGExchangeClient.x.x.x.jar). Windows: Unix/Linux: Starten Sie cmd.exe ( Dos-Console ) Öffnen Sie eine Console. Geben Sie bitte auf der Console java jar pathtojar/bvgexchangeclient-x.x.x.jar ein. Ersetzten Sie dabei bitte pathtojar mit dem Dateisystempfad zur Jar-Datei relativ zum aktuellen Verzeichnis der Console entsprechend dem Format Ihres Betriebssystems. Auf der Console erscheint folgende Kurzanleitung der Anwendung. usage: java -jar pathtojar/bvgexchangeclient-x.x.x.jar -?,--help print this message -basedir <arg> path to local base directory. If not set the default java workdirectory will be used. (This may be an absolute or a relative path.) -demo runs demo app and logs output to console. Username and password must be set. -incomingdir <arg> optional path to local incoming directory that all received XML will be saved to. Overrides the default '$basedir/incoming' - This may be an absolute or a relative path. -logdir <arg> path to local log directory - optional path to the directory that logs will be written to. Overrides the default '$basedir/logs' - This may be an absolute or relative path. -logs recreates all local logs from BVG Exchange. (Incremental updates are done by default. Only Anleitung Client.docx Seite 3 von 6
-outgoingdir <arg> -p,--password <arg> -prod -receive -run -submit -u,--username <arg> required if logs got lost and a complete download is required.) optional path to local outgoing directory that will be polled for XML to be sent to BVG Exchange. Overrides the default '$basedir/outgoing' - This may be an absolute or a relative path. password if set the production server is called. Default is test server. receives records submits and receives records submits records - files MUST be utf-8 encoded username 2. Demo Die Demoanwendung sendet reale Beispieldaten an die Testinstanz der BVG Exchange und eignet sich auch für einen grundsätzlichen Test ob die Anbindung aus Ihrer Systemumgebung funktioniert. Um die Demoanwendung zu starten geben sie auf der Kommandozeile bitte: java jar BVGExchangeClient-x.x.x.jar u username p passwort demo Username und Passwort erhalten Sie von Ihrem Kundenberater bei der Stiftung Auffangeinrichtung BVG. (Diese sind für die Demoanwendung wie für den CLI gleich.) Die Demoanwendung gibt ein detailliertes Ablaufprotokoll auf die Console aus. 3. Command Line Client Der Command Line Client (CLI) sendet und empfängt Ihre realen Daten. Folgende Aktionen stehen Ihnen dabei zur Verfügung: submit receive run logs Die Struktur des Aufrufs ist dabei immer java jar BVGExchangeClient-x.x.x.jar action u username p passwort Username und Passwort erhalten Sie von Ihrem Kundenberater bei der Stiftung Auffangeinrichtung BVG. (Diese sind für die Demoanwendung wie für den CLI gleich.) Anleitung Client.docx Seite 4 von 6
3.1. submit java jar BVGExchangeClient-x.x.x.jar -submit u username p passwort submit liest XML Dateien mit FZK Übertragungsdaten (Schema: http://www.chaeis.ch/xsd/fzl- 1.2) aus dem Default Verzeichnis outgoing und sendet dies an BVG Exchange. Um den Status des Dokuments wird die Originaldatei umbenannt wobei der Originalname immer erkennbar bleibt. Nachdem alle anstehenden XML Dateien übertragen wurden, wird BVG Exchange nach anstehenden Empfangsbestätigungen gefragt und diese im Dateinamen der XML Datei vermekrt. Als letztes wird ein Update der Logdateien im Verzeichnis logs durchgeführt. Die Logdateien dokumentieren vollständig und revisionssicher die Verarbeitung Ihrer Dokumente. Alle Aktionen werden lokal im Verzeichnis logs protokolliert. XML Dateien, die versandt werden, werden wie folgt umbenannt: Original: testfzl-1-2.xml Submit: testfzl-1-2-4a9574fd-950b-4c49-8f03-f97f6595152e-acksubmit.xml => testfzl-1-2-4a9574fd-950b-4c49-8f03-f97f6595152e-submit.xml Delivered: testfzl-1-2-4a9574fd-950b-4c49-8f03-f97f6595152e-delivered.xml Dabei ist 4a9574fd-950b-4c49-8f03-f97f6595152e der vom BVG Exchange vergebene Document Ident, der ein abgesandtes Dokument eindeutig identifiziert. 3.2. receive java jar BVGExchangeClient-x.x.x.jar -receive u username p passwort receive fragt BVG Exchange nach eingehenden FZL Übertragungsdaten. Stehen Daten an werden diese im Verzeichnis incoming gespeichert. Der Empfang wird BVG Exchange gegenüber verbindlich gemeldet. Als letztes wird ein Update der Logdateien im Verzeichnis logs durchgeführt. Die Logdateien dokumentieren vollständig und revisionssicher die Verarbeitung Ihrer Dokumente. Alle Aktionen werden lokal im Verzeichnis logs protokolliert. 3.3. run java jar BVGExchangeClient-x.x.x.jar -run u username p passwort run führt zunächst ein submit und dann ein receive aus. 3.4. logs java jar BVGExchangeClient-x.x.x.jar -logs u username p passwort logs lädt vollständig alle Logdateien BVG Exchange. Sollten Ihre Logdateien gelöscht oder verloren gehen, können sie jederzeit eine vollständige Kopie von BVG Exchange laden. Da sehr detailliert protokolliert wird und daher erhebliche Datenmengen entstehen können, bitte wir Sie diesen Aufruf nur bei Bedarf manuell zu starten. Anleitung Client.docx Seite 5 von 6
3.5. prod java jar BVGExchangeClient-x.x.x.jar action prod u username p passwort Alle Aufrufe ohne den Parameter prod werden gegen die Testinstanz der BVG Exchange ausgeführt. 3.6. Verzeichnisse Ohne weitere Angaben liest und schreibt der CLI in folgende Verzeichnisse: basisverzeichnis/logs basisverzeichnis/incoming basisverzeichnis/outgoing Dabei ist Basisverzeichnis das Workingdirectory der verwendeten Java VM meist das Verzeichnis aus dem der Aufruf erfolgte. Dieses Verhalten wird in den meisten Systemumgebungen nicht erwünscht sein. Es besteht daher die Möglichkeit das Basisverzeichnis als Parameter anzugeben: java jar BVGExchangeClient-x.x.x.jar -basedir verzeichnis... Wird der Parameter -basedir gesetzt leiten sich alle weiteren Verzeichnisse von diesem ab. Darüber hinaus kann auch jedes einzelne Verzeichnis explizit definiert werden. Dazu stehen die Parameter logdir verz -outgoingdir verz -incomingdir verz zur Verfügung. Mit diesen kann explizit ein bestimmtes Verzeichnis bestimmt werden unabhängig von Alle Verzeichnisangaben können sowohl absolut als auch relativ sein. Relative Verzeichnisse werden jeweils gegen ihre Basis aufgelöst. (basedir gegen das Workingdirectory, alle anderen gegenüber basedir). 3.7. Dateien manuell editieren Sollten Sie in beim Implementieren oder Testen Ihrer Lösung XML Dateien manuell anpassen müssen, beachten Sie bitte, dass manche Windows Tools wie Notepad nicht verlässlich UTF-8 encoded speichern, siehe: http://en.wikipedia.org/wiki/notepad_(software) Dies äussert sich in scheinbar unerklärlichen Fehlermeldungen wie received xml could not be parsed. error: Unexpected element: CDATA bei einer auf ersten Blick einwandfreien XML Datei. Anleitung Client.docx Seite 6 von 6