Manchmal stammen die Teile eines Dokuments aus verschiedenen Quellen. Denken Sie an eine XML-Rechnung, die über Peppol ankommt, und einen PDF-Anhang, der separat zugestellt wird, oder an mehrere Anhänge, die zur selben Rechnung gehören. Mit einem Join-Hook kombiniert die PSB diese separaten Ereignisse automatisch zu einem einzigen Dokument.

Ein Join-Hook lauscht gleichzeitig auf mehrere Topics und erkennt, welche Ereignisse zusammengehören. Der Hook unterscheidet zwei Arten von Ereignissen:

• Target-Ereignisse: das primäre Dokument (zum Beispiel eine Rechnung oder Bestellung).
• Matching-Ereignisse: Anhänge oder Ergänzungen, die mit dem primären Dokument verknüpft werden müssen.

Über Ausdrücke legen Sie fest, welches Ereignis das primäre Dokument ist (target) und wie Anhänge zugeordnet werden (when). Sobald die PSB eine Übereinstimmung findet, fügt sie die Anhänge mit dem primären Dokument zusammen und veröffentlicht ein neues Topic.

Der Ablauf ist wie folgt:

1. Die PSB empfängt Ereignisse auf den konfigurierten Topics (zum Beispiel SalesInvoiceReceived und AttachmentReceived)
2. Der Join-Hook prüft jedes Ereignis anhand des target-Ausdrucks, um das primäre Dokument zu identifizieren
3. Bei jedem neuen Ereignis prüft der Hook den when-Ausdruck, um eine Übereinstimmung zu finden
4. Sobald Target- und Matching-Ereignis(se) verknüpft sind, fügt die PSB die Anhänge zum primären Dokument hinzu
5. Ein neues Topic wird veröffentlicht (zum Beispiel SalesInvoiceJoined)

Die Stärke der Join-Hooks liegt in den Ausdrücken. Sie schreiben zwei Ausdrücke: einen zur Identifizierung des primären Dokuments und einen zur Zuordnung von Anhängen.

Der Target-Ausdruck bestimmt, ob ein Ereignis das primäre Dokument ist. Ein häufig verwendetes Muster ist der Abgleich über das Topic:

topic=="SalesInvoiceReceived"

Der When-Ausdruck verknüpft ein Matching-Ereignis mit dem richtigen Target-Ereignis. Hier vergleichen Sie Felder zwischen dem Quellereignis (source) und dem Target-Ereignis (target):

target.id == source.id && target.sender == source.sender

In diesem Beispiel werden Ereignisse zugeordnet, wenn sie dieselbe Dokument-ID und denselben Absender haben.

Hinweis: Alle Ausdrücke müssen in der Action-URL URL-kodiert sein. Der Ausdruck topic=="SalesInvoiceReceived" wird zu topic%3D%3D%22SalesInvoiceReceived%22. Vergessen Sie das nicht, da die PSB die Ausdrücke aus dem Query-String parst.

Registrieren Sie einen Hook über die API mit einer join://AddAttachment-Action:

{
  "id": "1",
  "name": "join hook",
  "action": "join://AddAttachment?target=topic%3D%3D%22SalesInvoiceReceived%22&when=target.id%20%3D%3D%20source.id%20%26%26%20target.sender%20%3D%3D%20source.sender&ttl=00:15:00&delay=00:30:00",
  "topics": [
    "AttachmentReceived",
    "SalesInvoiceReceived"
  ],
  "publishTopics": [
    "SalesInvoiceJoined"
  ],
  "isActive": true
}

Die Action hat folgendes Format:

join://AddAttachment?target={target-ausdruck}&when={when-ausdruck}&ttl={ttl}&delay={delay}

Das topics-Array des Hooks muss alle Topics enthalten, auf denen der Join-Hook lauschen soll. Dies umfasst Topics sowohl für das primäre Dokument als auch für die Anhänge.

Das Feld publishTopics bestimmt, auf welchem Topic das zusammengeführte Dokument veröffentlicht wird. Sie können einen regulären Webhook oder E-Mail-Hook auf dieses Topic konfigurieren, um das Ergebnis zu empfangen.

Die ttl (Time to Live) bestimmt, wie lange die PSB auf eine Übereinstimmung wartet. Wenn nach Ablauf der TTL das primäre Dokument oder der Anhang fehlt, veröffentlicht die PSB ein Fehler-Topic (*JoinedError). So können Sie erkennen, wenn ein Set unvollständig ist.

Setzen Sie die TTL auf einen Wert, der Ihrer erwarteten Bearbeitungszeit entspricht. Wenn Anhänge normalerweise innerhalb einer Stunde eintreffen, ist eine TTL von 01:00:00 ausreichend.

Tipp: Konfigurieren Sie einen Webhook oder E-Mail-Hook auf dem *JoinedError-Topic. So erhalten Sie ein Signal, wenn ein Anhang oder eine Rechnung fehlt, und können rechtzeitig handeln.

Ohne Delay beginnt die Zusammenführung, sobald das Target-Ereignis und ein Matching-Ereignis gefunden werden. Wenn Sie mehrere Anhänge für dasselbe Dokument erwarten, setzen Sie einen delay. Die PSB wartet die angegebene Zeit nach Erkennung des Target-Ereignisses und führt dann alle in diesem Zeitraum zugeordneten Anhänge auf einmal zusammen.

Angenommen, Sie erwarten drei PDF-Anhänge für eine Rechnung und diese treffen innerhalb von 20 Minuten ein. Ein Delay von 00:30:00 bietet genügend Spielraum, um alle Anhänge zu sammeln.

Eine Organisation empfängt Rechnungen über Peppol (Topic SalesInvoiceReceived) und zugehörige PDF-Anhänge über einen separaten Kanal (Topic AttachmentReceived). Die Anhänge werden anhand von Dokument-ID und Absender zugeordnet. Nach der Zusammenführung wird das vollständige Dokument auf SalesInvoiceJoined veröffentlicht, woraufhin ein Webhook es an das ERP-System weiterleitet.

Benötigen Sie Hilfe beim Einrichten der richtigen Ausdrücke? Kontaktieren Sie TechSupport unter techsupport@econnect.eu. Die vollständige API-Spezifikation finden Sie unter psb.econnect.eu mit allen Konfigurationsoptionen.