Join hooks: bijlagen samenvoegen

Soms komen de onderdelen van een document uit verschillende bronnen. Denk aan een XML-factuur die via Peppol binnenkomt en een PDF-bijlage die apart wordt aangeleverd, of meerdere bijlagen die bij dezelfde factuur horen. Met een join hook combineert de PSB deze losse events automatisch tot één document.

Hoe werkt een join hook?

Een join hook luistert op meerdere topics tegelijk en herkent welke events bij elkaar horen. De hook onderscheidt twee typen events:

Target events: het primaire document (bijvoorbeeld een factuur of order).
Matching events: bijlagen of aanvullingen die aan het primaire document moeten worden gekoppeld.

Via expressies bepaal je welk event het primaire document is (target) en hoe bijlagen worden gematcht (when). Zodra de PSB een match vindt, voegt hij de bijlagen samen met het primaire document en publiceert een nieuw topic.

De flow verloopt als volgt:

De PSB ontvangt events op de geconfigureerde topics (bijvoorbeeld SalesInvoiceReceived en AttachmentReceived)
De join hook evalueert elk event tegen de target-expressie om het primaire document te identificeren
Bij elk nieuw event controleert de hook de when-expressie om een match te vinden
Als target en matching event(s) gekoppeld zijn, voegt de PSB de bijlagen toe aan het primaire document
Een nieuw topic wordt gepubliceerd (bijvoorbeeld SalesInvoiceJoined)

Expressies configureren

De kracht van join hooks zit in de expressies. Je schrijft twee expressies: een voor het identificeren van het primaire document en een voor het matchen van bijlagen.

Target-expressie

De target-expressie bepaalt of een event het primaire document is. Een veelgebruikt patroon is matchen op het topic:

topic=="SalesInvoiceReceived"

When-expressie

De when-expressie koppelt een matching event aan het juiste target event. Hierbij vergelijk je velden tussen het bron-event (source) en het doel-event (target):

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

In dit voorbeeld worden events gematcht als ze hetzelfde document-ID en dezelfde afzender hebben.

Let op: Alle expressies moeten URL-encoded worden in de action-URL. De expressie topic=="SalesInvoiceReceived" wordt dan topic%3D%3D%22SalesInvoiceReceived%22. Vergeet dit niet, want de PSB parseert de expressies uit de querystring.

Een join hook aanmaken

Registreer een hook via de API met een 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
}

De action volgt het formaat:

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

Parameters

Parameter

Verplicht

Standaard

Beschrijving

target

(verplicht)

URL-encoded expressie die bepaalt of een event het primaire document is

when

(verplicht)

URL-encoded expressie die matching events koppelt aan het target event

ttl

Nee

1.00:00:00 (1 dag)

Maximale wachttijd op een match. Na deze tijd publiceert de PSB een *JoinedError-topic

delay

Nee

geen

Wachttijd na detectie van het target event, zodat meerdere bijlagen kunnen binnenkomen voordat de samenvoeging start

Topics configureren

De topics-array van de hook moet alle topics bevatten waarop de join hook moet luisteren. Dit zijn zowel de topics voor het primaire document als voor de bijlagen.

Het publishTopics-veld bepaalt op welk topic het samengevoegde document wordt gepubliceerd. Je kunt hier een reguliere webhook of e-mail hook op configureren om het resultaat te ontvangen.

TTL: wachttijd en foutdetectie

De ttl (Time to Live) bepaalt hoe lang de PSB wacht op een match. Als na de TTL-periode het primaire document of de bijlage ontbreekt, publiceert de PSB een fout-topic (*JoinedError). Zo kun je detecteren wanneer een set onvolledig is.

Stel de TTL in op een waarde die past bij je verwachte doorlooptijd. Als bijlagen doorgaans binnen een uur binnenkomen, is een TTL van 01:00:00 voldoende.

Tip: Configureer een webhook of e-mail hook op het *JoinedError-topic. Zo krijg je een signaal als een bijlage of factuur ontbreekt en kun je tijdig actie ondernemen.

Delay: meerdere bijlagen samenvoegen

Zonder delay start de samenvoeging zodra het target event en één matching event zijn gevonden. Verwacht je meerdere bijlagen bij hetzelfde document, stel dan een delay in. De PSB wacht na detectie van het target event de opgegeven tijd af en voegt vervolgens alle bijlagen die in die periode zijn gematcht in één keer samen.

Stel dat je drie PDF-bijlagen verwacht bij een factuur en ze druppelen binnen over een periode van 20 minuten. Een delay van 00:30:00 geeft voldoende marge om alle bijlagen te verzamelen.

Praktijkvoorbeeld

Een organisatie ontvangt facturen via Peppol (topic SalesInvoiceReceived) en bijbehorende PDF-bijlagen via een apart kanaal (topic AttachmentReceived). De bijlagen worden gematcht op document-ID en afzender. Na samenvoeging wordt het volledige document gepubliceerd op SalesInvoiceJoined, waarna een webhook het doorstuurt naar het ERP-systeem.

Veelgestelde vragen

Waarom moeten target- en when-expressies URL-encoded in de action staan?

De PSB leest de expressies uit de querystring van de join://AddAttachment-URL. Speciale tekens zoals =, ", spaties en && breken de parsing als je ze niet encodeert, bijvoorbeeld topic%3D%3D%22SalesInvoiceReceived%22 in plaats van de ruwe notatie.

Wat gebeurt er als binnen de ttl geen volledige match ontstaat?

De ttl (Time to Live) is de maximale wachttijd op een geldige combinatie van target en matching events. Loopt die tijd af zonder match, dan publiceert de PSB een *JoinedError-topic, zodat je kunt signaleren dat een set onvolledig is en tijdig kunt ingrijpen.

Wanneer zet ik een delay naast een ttl?

Gebruik delay als je verwacht dat meerdere bijlagen kort na elkaar binnenkomen: na detectie van het target event wacht de PSB de delay af en voegt daarna alle in die periode gematchte bijlagen in één keer samen. Zonder delay start de samenvoeging zodra er één matching event is.

Hulp nodig bij het opzetten van de juiste expressies? Neem contact op met TechSupport via [email protected]. Bekijk de volledige API-specificatie op psb.econnect.eu voor alle configuratiemogelijkheden.

Bekijk de API-documentatie

Gerelateerd