Sloučení příloh s dokumenty pomocí join hooks: target a when výrazy, TTL a delay.
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í:
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í:
SalesInvoiceReceived a AttachmentReceived)target pro identifikaci primárního dokumentuwhen pro nalezení shodySalesInvoiceJoined)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 stanetopic%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}
targetwhenttl1.00:00:00 (1 den)*JoinedErrordelayPole 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.
Join hook slouží i pro odchozí faktury přes SFTP (viz integrace SFTP, volitelně s fileNameFilter, když XML a PDF přijdou do stejné složky).
target=topic=="SendInvoice" — XML je primární dokument.when=source.fileName.contains(target.id) — název PDF obsahuje číslo faktury z XML.SendInvoiceJoined.Pozor: hook, který dříve poslouchal
SendInvoice(například hook Collabrr nebo platformy), sloučenou fakturu na tomto topicu už nedostane. Přesměrujte ho naSendInvoiceJoined, aby dál dostával sloučené XML a PDF.
Pokud vidíte chybu SendInvoiceJoinedError s textem JoinEvent TimeToLive reached without receiving matching event, join hook v nastaveném ttl nedostal všechny potřebné události. Chybí primární dokument (target) nebo odpovídající událost (příloha nebo část faktury), případně dorazila pozdě. Dotčené faktury zůstanou na kanálu zablokované, dokud se situace nevyřeší.
Diagnostika a řešení:
target) nebo odpovídající událost (when).ttl na hooku.Tip: nastavte webhook nebo e-mailový hook na topic
SendInvoiceJoinedError, abyste hned dostali signál, když sada dorazí neúplná.
PSB čte výrazy z query stringu URL join://AddAttachment. Speciální znaky jako =, ", mezery a && naruší parsování, pokud je nezakódujete, například topic%3D%3D%22SalesInvoiceReceived%22 namísto surové notace.
ttl (Time to Live) je maximální čekací doba na platnou kombinaci target a matching událostí. Pokud tento čas uplyne bez shody, PSB publikuje téma *JoinedError, takže můžete signalizovat, že sestava je neúplná, a včas zasáhnout.
Použijte delay, pokud očekáváte, že více příloh dorazí v krátkém časovém odstupu: po detekci target události PSB počká na uplynutí delay a poté sloučí všechny přílohy přiřazené během tohoto období najednou. Bez delay se sloučení zahájí ihned po nalezení jedné matching události.
Chyba SendInvoiceJoinedError s JoinEvent TimeToLive reached without receiving matching event znamená, že join hook v rámci TTL nedostal všechny potřebné události. Dotčené faktury zůstanou na kanálu zablokované. Zjistěte, která událost chybí (target nebo odpovídající), chybějící část znovu dodejte a případně upravte ttl, pokud jeden den nestačí rytmu dodávek.
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.
Zobrazit API dokumentaci