B2B-Messenger

Übersicht

Der B2B-Messenger ist eine Komponente, die als Windows-Service auf einem Application-Server installiert werden muss.

Die Messages (Inbound und Outbound) werden dateibasiert in Inbound- bzw. Outbound-Verzeichnissen erstellt.

OpaccOXAS-Komponenten wie F-Script können eine über ein Inbound-Verzeichnis empfangene Inbound-Message entgegennehmen oder eine zu sendende Message in einem Outbound-Verzeichnis bereitstellen. Die Outbound-Kommunikation wird vom B2B-Messenger direkt abgewickelt. Voraussetzung dafür ist eine aktive Internet-Verbindung.

Die Inbound-Kommunikation sollte aus Sicherheitsgründen über einen in der DMZ stehenden Reverse-Proxy geleitet werden.

Der B2B-Messenger schreibt Meldungen ins zentrale OpaccOXAS-Log, welches via Log-Viewer (OpaccOXAS Studio BC 98235) einsehbar ist.

Der aktuelle Status des B2B-Messengers wird im System-Monitor (OpaccOXAS Studio BC 98800) angezeigt.

Der B2B-Messenger kann im OpaccOXAS Studio BC 98122 (B2B Messenger einrichten) konfiguriert werden.

Die für die XML-Konfigurations-Dateien des B2B-Messenger liegen im Verzeichnis \ServiceBus\Config\Data\

Die XML-Schemas (Opacc.B2B....xsd) im Verzeichnis \ServiceBus\Config\MetaInfo enthalten eine Beschreibung aller Konfigurations-Möglichkeiten.

Komponenten

Der B2B-Messenger stellt verschiedene Channels bereit. Jeder Channel ist in einer eigenen Assembly/DLL implementiert, hat einen bestimmten Verwendungszweck und verfügt über eine eigene Konfiguration.

Pro Channel können jeweils mehrere Kommunikationspartner definiert werden.

Channel

Assembly

Funktion

Konfiguration

PostFinance

Opacc.B2B.Channel.PostFinance.dll

E-Invoices an PostFinance senden (Outbound only)

Notiz

Beachten Sie, dass der Zugriff auf den PostFinance WebService nach 3 Fehlversuchen gesperrt wird. Wenn der Zugriff gesperrt ist, kann dieser lediglich durch die PostFinance wieder freigeschaltet werden.

0001_Opacc.B2B.Channel.PostFinance.xml

PayNet

Opacc.B2B.Channel.PayNet.dll

E-Invoices an PayNet senden (Outbound only)

0001_Opacc.B2B.Channel.PayNet.xml

XmlOverHttp

Opacc.B2B.Channel.XmlOverHttp.dll

Beliebige XML-Messages senden und empfangen

0001_Opacc.B2B.Channel.XmlOverHttp.xml

Grafische Darstellung des Datenflusses beim PostFinance- und beim PayNet-Channel:

Erläuterungen

Die zu versendenden Rechnungen werden durch ein F-Script (XML- und PDF-Repräsentation) im Verzeichnis Outbound bereitgestellt.

Der B2B-Messenger verpackt die beiden Dateien in eine Message und verschickt diese aus dem Unterverzeichnis Processing an PostFinance respektive PayNet.

Die von PostFinance/PayNet bereitgestellten "Feedback-Daten" werden ausgewertet und in Abhängigkeit davon die XML-/PDF-Dateien in das Unterverzeichnis Done oder Failed verschoben.

Die "rohen" empfangenen Feedback-Daten werden ebenfalls gespeichert, im Unterverzeichnis Protocols.

Notiz

Da für jede Rechnung zusätzlich ein Info- oder Error-Log-Eintrag erstellt wird, müssen die Verzeichnisse normalerweise nicht manuell kontrolliert werden. Es genügt den in OpaccOXAS Log-Viewer (BC 98235) zu konsultieren!

Schnittstellen

Die Schnittstelle des B2B-Messengers wird im Wesentlichen durch die speziellen Verzeichnisse für den Datenaustausch gebildet. Diese werden beim erstmaligen Starten des Messengers falls nötig automatisch angelegt.

Transfer-Verzeichnisse

Jeder Channel verfügt über eigene Transfer-Verzeichnisse. Der PayNet- und der PostFinance-Chanel haben jeweils ein Verzeichnis Outbound mit den Unterverzeichnissen Done, Failed, Processing und Protocols" der Xml-Channel verfügt zusätzlich über ein Verzeichnis Inbound, ebenfalls mit den Unterverzeichnissen Done, Failed, Processing und Protocols.

Die Verzeichnisse werden automatisch innerhalb des OpaccOXAS-Installations-Shares unterhalb "\B2B\") angelegt und sie sollten auch dort verbleiben. Die Datensicherung kann sehr einfach zusammen mit den übrigen OpaccOXAS-Daten erfolgen.

Verzeichnisstruktur der vom B2B-Messenger benutzten Transfer-Verzeichnisse:

Dateinamen

Alle Inbound- und Outbound-Dateien haben dasselbe Format: [PartnerID]_[TransactionID].[Extension]

Sie werden jedoch pro Channel auf unterschiedliche Weise verwendet.

PostFinance

Dateien	Typ	Erläuterung
Outbound-Message-Datei	.xml / .pdf	Erst wenn beide Dateien zum Tupel PartnerID/TransactionID vorhanden sind, wird die Message gebildet und versendet. Beispiel für Dateinamen: 41100000000056303_10RE481923.xml 41100000000056303_10RE481923.pdf
Outbound-Zusatz-Dateien	_adjusted.xml .error	Durch B2B-Messenger erstellte Zusatzdateien in den Outbound-Unterverzeichnissen "Processing", "Done", "Failed" Tatsächlich versendete Message (XML mit Embedded PDF) Fehlermeldung(en) zu einer Message (nur im Fehlerfall vorhanden)
Outbound-Protocol	.xml	Dateien wie z.B.: Process_Protocol_....xml

PayNet

Dateien	Typ	Erläuterung
Outbound-Message-Datei	.xml / .pdf	Erst wenn beide Dateien zum Tupel PartnerID/TransactionID vorhanden sind, wird die Message gebildet und versendet. Beispiel für Dateinamen: 41010137004939513_10RE481923.xml 41010137004939513_10RE481923.pdf
Outbound-Zusatz-Dateien	_adjusted.xml .error	Durch B2B-Messenger erstellte Zusatzdateien in den Outbound-Unterverzeichnissen "Processing", "Done", "Failed" Tatsächlich versendete Message (XML mit Embedded PDF) Fehlermeldung(en) zu einer Message (nur im Fehlerfall vorhanden)
Outbound-Protocol	.xml	Dateien wie z.B.: SC-....EIXML_BANSTA.xml oder SC-....EIXML_CONTRL.xml

XmlOverHttp

Dateien	Typ	Erläuterung
Outbound-Message-Datei	.xml	Die Datei wird sofort versendet (http-POST) Beispiel für Dateinamen: TestPartner_00000001.xml
Inbound-Message-Datei	.xml	Beispiel für Dateinamen: TestPartner_2010-06-24-17.05.17.197.xml oder TestPartner_00000001.xml¹ (¹ Unterschiedliche Benennung je nach eingestelltem Transaktions-ID-Verfahren)
Outbound-Zusatz-Dateien	_adjusted.xml .error	Durch B2B-Messanger erstellte Zusatzdateien in den Outbound-Unterverzeichnissen "Processing", "Done", "Failed" Tatsächlich versendete Message (XML mit Embedded PDF) Fehlermeldung(en) zu einer Message (nur im Fehlerfall vorhanden)
Outbound-Protocol	.xml	Dateien wie z.B.: SC-....EIXML_BANSTA.xml oder SC-....EIXML_CONTRL.xml

PartnerID

Alle Channels unterstützen die parallele Kommunikation mit mehreren Partnern.

Damit die Dateien dem richtigen Partner zugeordnet werden können, muss für jeden Partner eine (pro Channel) eindeutige PartnerID verwendet werden, die Bestandteil der Dateinamen ist.

PostFinance- / PayNet-Channel

Die PartnerID (in der Konfiguration auch als "BillerID" bezeichnet) wird von PostFinance/PayNet vergeben
Die von PostFinance vergebenen IDs beginnen mit "410"
Die von PayNet vergebenen IDs beginnen mit "411"

XmlOverHttp-Channel

Die PartnerID kann selbst definiert werden
Falls für einen Partner Inbound-Kommunikation (= Empfangen von XML-Daten) unterstützt werden soll, muss diese ID natürlich dem Partner mitgeteilt werden, weil die PartnerID normalerweise Bestandteil der Inbound-Endpoint-URL ist, die Adresse an die der Partner seine Messages senden soll.

TransactionID

Jede Message muss eine (pro Partner) eindeutige TransactionID haben, die wiederum Bestandteil des Dateinamens sein muss

PostFinance- / PayNet-Channel

Für die Bildung der TransactionIDs wird folgendes Schema empfohlen: [Mandant][RE|GS][DocNo]

Beispiel: "10RE481923"

XmlOverHttp-Channel

Das Verfahren für die Bildung der TransactionID für via den XmlOverHttp-Channel empfangene Messages, kann in der Konfiguration eingestellt werden:

Timestamp

Die TransactionID wird ausgehend von der aktuellen Zeit gebildet.

Beispiel: "2010-06-24-17.05.17.197"

Achtung

Im Timestamp-Mode werden im Inbound-Ordner mehrere Messages erzeugt, wenn ein Partner ein und dieselbe logische Message mehrfach schickt.

UrlSuffix

Die TransactionID wird ausgehend von der adressierten URL gebildet.

Beispiel:

Der B2B-Messenger läuft auf "LABFS2008", mit [[HTTP_PORT]] == 9985 und [[PARTNER_ID]] == "TestPartner"

Bei einer Endpunkt-URL-Einstellung auf:

http://+:[[HTTP_PORT]]/Opacc/B2B/Channel/XmlOverHttp/[[PARTNER_ID]]/[[TRANSACTION_ID]]

lautet die Basis-URL:

http://LABFS2008:9985/Opacc/B2B/Channel/XmlOverHttp/TestPartner/

Wenn der Partner seine Messages an diese URL plus einen Suffix für die TransactionID schickt , z.B.:

http://LABFS2008:9985/Opacc/B2B/Channel/XmlOverHttp/TestPartner/00000001

legt der B2B-Messenger die empfangenen Daten in der Datei TestPartner_00000001.xml im Inbound-Verzeichnis ab.

Achtung

Im UrlSuffix-Mode wird nur eine Message im Inbound-Verzeichnis erzeugt, wenn ein Partner ein und dieselbe logische Message mehrfach schickt! Falls wider Erwarten nicht jedes Mal derselbe Content verschickt wird, wird der letzte empfangene Content im Inbound-Folder gespeichert!

Validierungen Outbound Messages

XML-Content

In allen Channels wird geprüft, ob der Inhalt der ausgehenden XML-Dateien "well-formed" ist.
Im PostFinance- und im PayNet-Channel wird zusätzlich geprüft, ob die XML-Daten dem von PostFinance/PayNet vorgegebenen XML-Schema entsprechen.

Dateinamen versus Inhalt

Damit der B2B-Messenger bzw. der Empfänger (z. B. PostFinance) die Daten verarbeiten kann, werden pro Channel zusätzlich folgende Konsistenz-Prüfungen auf Datei-Namen (PartnerID, TransactionID) und Inhalt durchgeführt:

PostFinance

Die PartnerID/BillerID: muss in XML-Content in den folgenden Elementen enthalten sein:
```
/Envelope/Header/From
/Envelope/Body/DeliveryInfo/BillerID
```
Die TransactionID: muss in XML-Content in den folgenden Elementen enthalten sein:
```
/Envelope/Body/DeliveryInfo/TransactionID
```

PayNet

Die PartnerID/BillerID: muss in XML-Content in den folgenden Elementen enthalten sein:
```
/XML-FSCM-INVOICE-2003A/INTERCHANGE/IC-SENDER/Pid
/XML-FSCM-INVOICE-2003A/INVOICE/HEADER/BILLER/PARTY-ID/Pid
```
Die TransactionID: muss in XML-Content in den folgenden Elementen enthalten sein:
```
/XML-FSCM-INVOICE-2003A/INTERCHANGE/IC-Ref
```

XmlOverHttp

Keine Prüfung

Know-How

PostFinance und PayNet

Authentication mit UserId/Passwort

Sowohl mit PostFinance als auch mit PayNet ist vereinbart, dass UserId/Passwort für die Authentifizierung verwendet wird. Es ist kein Client-Zertifikat nötig/unterstützt.

Daher müssen kundenspezifischen Anmeldungen entsprechend vorgenommen werden.
Keine rechtssichere Archivierung der Invoices auf unserer Seite.

PostFinance: Eine Auslieferung der signierten Rechnungen auf CD ist möglich.
Keine automatisierte Abonnierung/Abbestellung von E-Invoices.

Lediglich bei Postfinance ist eine "Registration/Cancellation“ möglich.
WebService-Zielpunkte und Portal-Adressen

Die Web-Service-Endpunkte müssen korrekt konfiguriert sein.

Es sind Portal-Zugriffe notwendig, um zu kontrollieren, ob die Übermittlung einwandfrei funktioniert hat. Dies ist allerdings nur während der Entwicklung relevant.

	Biller-WebService-Zielpunkt	Portal-Adresse
PostFinance-Test	ebill-test.yellowworld.ch	https://ebill-ki.postfinance.ch/B2BService/B2BService.svc
PostFinance-Produktiv	ebill.yellowworld.ch	https://ebill.postfinance.ch/B2BService/B2BService.svc

PayNet-Test	dws-test.paynet.ch/DWS/DWS	https://bsp0.billingservices.ch
PayNet-Produktiv	dws.paynet.ch/DWS/DWS	https://bsp1.billingservices.ch

Notiz

Beachten Sie, dass PayNet als "outdated" gilt und nicht mehr verwendet werden sollte.

XmlOverHttp

Inbound

Basic-Authentication / Keine Authentication unterstützt
Erwartet http POST mit "text/xml"-Content

Wenn dies nicht erfüllt ist, wird eine "BadRequest"-Antwort zurückgeschickt.
SSL-Support muss via vorgeschalteten Reverse-Proxy realisiert werden (z. B. basierend auf IIS URL Rewrite Rule)
Max. 10 MBytes Content-Length unterstützt -> Wenn grösser, wird eine eine "BadRequest"-Antwort zurückgeschickt
Scheduling-Einstellungen (Zeitfenster und Intervall) sind aktuell nur für Outbound-Kommunikation relevant

Die Inbound-Endpunkte nehmen Messages entgegen solange der B2B-Messenger läuft.

Outbound

Akzeptiert nur Antworten von folgenden Typen: text,text/plain,text/html,text/xhtml,text/xml

Installation, Konfiguration und Betrieb

Installation des B2B-Messengers als Windows Service

Die Installation erfolgt im Programmverzeichnis \insyde\B2B\ über die Batch-Datei Opacc.B2B.Messenger.InstallWinService.bat.

Sie muss mit einem für diesen Zweck dedizierten Domain-Account mit lokalen Admin-Rechten durchgeführt werden.

Installation auf einem dedizierten Server

Die Installation muss zwingend über den UNC-Pfad erfolgen.

Beispiel: \\OpaccOXAS_APS\OpaccERP\Insyde\B2B\
Installation direkt auf dem OpaccOXAS-APS (die empfohlene Variante)

Die Installation muss über den lokalen Pfad erfolgen.
Beispiel: D:\Daten\OpaccERP\Insyde\B2B\

Konfiguration des B2B-Messengers und der Channels

Die Konfiguration des B2B-Messengers und der Channels erfolgt im OpaccOXAS Studio über das BC 98122 (B2B Messenger einrichten).

Testen des B2B-Messengers

Nach erfolgreicher Installation kann der B2B-Messenger interaktiv getestet werden.

Starten Sie hierzu den B2B-Messenger über die Batch-Datei: Opacc.B2B.Messenger.StartAsWinApp.bat (Aus dem Verzeichnis \insyde\B2B\).

Beobachten Sie nun die Konsolen-Fenster. Eventuelle Fehler werden direkt hier im Konsolen-Fenster angezeigt. Das Protokollieren erfolgt in jedem Fall auch in den Logfiles.

Test des XmlOverHttp-Inbound-Endpunkts

Die konfigurierte Endpunkt-URL kann direkt in einem Browser eingegeben werden. Nach einer allfälligen Abfrage des Benutzers und seines Passworts (falls Authentication auf "UserPassword" eingestellt), wird folgende Meldung angezeigt:

Da der Browser bei der simplen Eingabe einer URL in der Adresszeile einen http-GET-Request sendet, ist die "Fehlermeldung" in diesem Fall zu erwarten und richtig und der "Beweis", dass der XmlOverHttp-Inbound-Endpunkt prinzipiell funktioniert.

Reverse-Proxy basierend IIS

Nur, wenn Sie die XmlOverHttp-Inbound-Funktionalität nützen möchten, muss ein Reverse-Proxy basierend IIS eingerichtet werden. Dabei unterstützt Sie auf Anfrage unsere Systemtechnik.

Kontrolle des B2B-Messengers

Sie können die Verarbeitungen des B2B-Messengers im OpaccOXAS Studio BC 98235 Log-Viewer kontrollieren. Dazu wählen Sie im Attribut Quelle den Eintrag B2B-Messenger aus.

Unter der Quelle Opacc.B2B.Messenger werden alle Meldungen der einzelnen Channels angezeigt. Im Attribut Quell-Detail wird der Name des Channels angezeigt, der die Meldung generiert hat, z. B. Opacc.B2B.Channel.PostFinance.

Tech Notes

B2B-Messenger

Übersicht

Komponenten

Notiz

Notiz

Schnittstellen

Transfer-Verzeichnisse

Dateinamen

PartnerID

TransactionID

Achtung

Achtung

Validierungen Outbound Messages

Know-How

PostFinance und PayNet

Notiz

XmlOverHttp

Installation, Konfiguration und Betrieb

Installation des B2B-Messengers als Windows Service

Konfiguration des B2B-Messengers und der Channels

Testen des B2B-Messengers

Test des XmlOverHttp-Inbound-Endpunkts

Reverse-Proxy basierend IIS

Kontrolle des B2B-Messengers