Někdy části dokumentu přicházejí z různých zdrojů. Představte si XML fakturu přicházející přes Peppol a PDF přílohu doručenou samostatně, nebo více příloh patřících ke stejné faktuře. Pomocí join hook PSB automaticky zkombinuje tyto samostatné události do jednoho dokumentu.

Join hook naslouchá na více tématech současně a rozpoznává, které události k sobě patří. Hook rozlišuje dva typy událostí:

• Target události: primární dokument (například faktura nebo objednávka).
• Matching události: přílohy nebo doplňky, které je potřeba propojit s primárním dokumentem.

Pomocí výrazů určíte, která událost je primárním dokumentem (target) a jak se přílohy přiřazují (when). Jakmile PSB najde shodu, sloučí přílohy s primárním dokumentem a publikuje nové téma.

Průběh je následující:

1. PSB přijme události na nakonfigurovaných tématech (například SalesInvoiceReceived a AttachmentReceived)
2. Join hook vyhodnotí každou událost vůči výrazu target pro identifikaci primárního dokumentu
3. S každou novou událostí hook zkontroluje výraz when pro nalezení shody
4. Jakmile jsou target a matching událost propojeny, PSB přidá přílohy k primárnímu dokumentu
5. Je publikováno nové téma (například SalesInvoiceJoined)

Síla join hooks spočívá ve výrazech. Píšete dva výrazy: jeden pro identifikaci primárního dokumentu a jeden pro přiřazování příloh.

Target výraz určuje, zda je událost primárním dokumentem. Často používaný vzor je shoda na základě tématu:

topic=="SalesInvoiceReceived"

When výraz propojuje matching událost se správnou target událostí. Zde porovnáváte pole mezi zdrojovou událostí (source) a cílovou událostí (target):

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

V tomto příkladu jsou události přiřazeny, pokud mají stejné ID dokumentu a stejného odesílatele.

Poznámka: všechny výrazy musí být URL-kódovány v action URL. Výraz topic=="SalesInvoiceReceived" se stane topic%3D%3D%22SalesInvoiceReceived%22. Nezapomeňte na to, protože PSB parsuje výrazy z query stringu.

Zaregistrujte hook přes API s akcí join://AddAttachment:

{
  "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
}

Akce má následující formát:

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

Pole topics hooku musí obsahovat všechna témata, na kterých má join hook naslouchat. To zahrnuje témata jak pro primární dokument, tak pro přílohy.

Pole publishTopics určuje, na jakém tématu je sloučený dokument publikován. Na toto téma můžete nakonfigurovat běžný webhook nebo e-mail hook pro příjem výsledku.

ttl (Time to Live) určuje, jak dlouho PSB čeká na shodu. Pokud po uplynutí TTL chybí primární dokument nebo příloha, PSB publikuje chybové téma (*JoinedError). Díky tomu můžete detekovat, kdy je sada neúplná.

Nastavte TTL na hodnotu odpovídající vašemu očekávanému času zpracování. Pokud přílohy typicky dorazí do jedné hodiny, TTL 01:00:00 je dostatečný.

Tip: nakonfigurujte webhook nebo e-mail hook na téma *JoinedError. Díky tomu dostanete signál, když chybí příloha nebo faktura, a můžete včas jednat.

Bez delay se sloučení zahájí, jakmile jsou nalezeny target událost a jedna matching událost. Pokud očekáváte více příloh ke stejnému dokumentu, nastavte delay. PSB počká uvedenou dobu po detekci target události a poté sloučí všechny přílohy přiřazené během tohoto období najednou.

Předpokládejme, že očekáváte tři PDF přílohy k faktuře a dorazí v průběhu 20 minut. Delay 00:30:00 poskytuje dostatečnou rezervu pro shromáždění všech příloh.

Organizace přijímá faktury přes Peppol (téma SalesInvoiceReceived) a doprovázející PDF přílohy přes samostatný kanál (téma AttachmentReceived). Přílohy jsou přiřazovány na základě ID dokumentu a odesílatele. Po sloučení je kompletní dokument publikován na SalesInvoiceJoined, načež webhook předá výsledek do ERP systému.

Potřebujete pomoc s nastavením správných výrazů? Kontaktujte TechSupport na techsupport@econnect.eu. Kompletní API specifikace je k dispozici na psb.econnect.eu.