Niekedy časti dokumentu prichádzajú z rôznych zdrojov. Predstavte si XML faktúru prichádzajúcu cez Peppol a PDF prílohu doručenú samostatne, alebo viacero príloh patriacich k tej istej faktúre. Pomocou join hook PSB automaticky skombinuje tieto samostatné udalosti do jedného dokumentu.

Join hook načúva na viacerých témach súčasne a rozpoznáva, ktoré udalosti k sebe patria. Hook rozlišuje dva typy udalostí:

• Target udalosti: primárny dokument (napríklad faktúra alebo objednávka).
• Matching udalosti: prílohy alebo doplnky, ktoré je potrebné prepojiť s primárnym dokumentom.

Pomocou výrazov určíte, ktorá udalosť je primárnym dokumentom (target) a ako sa prílohy priraďujú (when). Keď PSB nájde zhodu, zlúči prílohy s primárnym dokumentom a publikuje novú tému.

Priebeh je nasledovný:

1. PSB prijme udalosti na nakonfigurovaných témach (napríklad SalesInvoiceReceived a AttachmentReceived)
2. Join hook vyhodnotí každú udalosť voči výrazu target na identifikáciu primárneho dokumentu
3. S každou novou udalosťou hook skontroluje výraz when na nájdenie zhody
4. Po prepojení target a matching udalosti PSB pridá prílohy k primárnemu dokumentu
5. Je publikovaná nová téma (napríklad SalesInvoiceJoined)

Sila join hooks spočíva vo výrazoch. Píšete dva výrazy: jeden na identifikáciu primárneho dokumentu a jeden na priraďovanie príloh.

Target výraz určuje, či je udalosť primárnym dokumentom. Často používaný vzor je zhoda na základe témy:

topic=="SalesInvoiceReceived"

When výraz prepojuje matching udalosť so správnou target udalosťou. Tu porovnávate polia medzi zdrojovou udalosťou (source) a cieľovou udalosťou (target):

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

V tomto príklade sú udalosti priradené, ak majú rovnaké ID dokumentu a rovnakého odosielateľa.

Poznámka: všetky výrazy musia byť URL-kódované v action URL. Výraz topic=="SalesInvoiceReceived" sa stane topic%3D%3D%22SalesInvoiceReceived%22. Nezabudnite na to, pretože PSB parsuje výrazy z query stringu.

Zaregistrujte hook cez API s akciou 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
}

Akcia má nasledovný formát:

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

Pole topics hooku musí obsahovať všetky témy, na ktorých má join hook načúvať. To zahŕňa témy pre primárny dokument aj pre prílohy.

Pole publishTopics určuje, na akej téme je zlúčený dokument publikovaný. Na túto tému môžete nakonfigurovať bežný webhook alebo e-mail hook na príjem výsledku.

ttl (Time to Live) určuje, ako dlho PSB čaká na zhodu. Ak po uplynutí TTL chýba primárny dokument alebo príloha, PSB publikuje chybovú tému (*JoinedError). Vďaka tomu môžete detegovať, kedy je sada neúplná.

Nastavte TTL na hodnotu zodpovedajúcu vášmu očakávanému času spracovania. Ak prílohy typicky dorazia do jednej hodiny, TTL 01:00:00 je dostatočný.

Tip: nakonfigurujte webhook alebo e-mail hook na tému *JoinedError. Vďaka tomu dostanete signál, keď chýba príloha alebo faktúra, a môžete včas konať.

Bez delay sa zlúčenie začne, len čo sú nájdené target udalosť a jedna matching udalosť. Ak očakávate viacero príloh k tomu istému dokumentu, nastavte delay. PSB počká uvedenú dobu po detekcii target udalosti a potom zlúči všetky prílohy priradené počas tohto obdobia naraz.

Predpokladajme, že očakávate tri PDF prílohy k faktúre a dorazia v priebehu 20 minút. Delay 00:30:00 poskytuje dostatočnú rezervu na zhromaždenie všetkých príloh.

Organizácia prijíma faktúry cez Peppol (téma SalesInvoiceReceived) a sprevádzajúce PDF prílohy cez samostatný kanál (téma AttachmentReceived). Prílohy sú priraďované na základe ID dokumentu a odosielateľa. Po zlúčení je kompletný dokument publikovaný na SalesInvoiceJoined, načo webhook odovzdá výsledok do ERP systému.

Potrebujete pomoc s nastavením správnych výrazov? Kontaktujte TechSupport na techsupport@econnect.eu. Kompletná API špecifikácia je k dispozícii na psb.econnect.eu.