Join hooks: sloučení příloh s dokumenty

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.

Jak join hook funguje?

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)
Konfigurace výrazů

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

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

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.

Vytvoření join hook

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}
Parametry
ParametrPovinnýVýchozíPopistargetAno—URL-kódovaný výraz určující, zda je událost primárním dokumentemwhenAno—URL-kódovaný výraz propojující matching události s target událostíttlNe1.00:00:00 (1 den)Maximální čekací doba na shodu. Po uplynutí PSB publikuje téma *JoinedErrordelayNežádnýČekací doba po detekci target události, která umožní příchod více příloh před zahájením sloučení
Konfigurace témat

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: čekací doba a detekce chyb

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.

Delay: sloučení více příloh

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.

Praktický příklad

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.

Praktický příklad: spojení XML a PDF ze stejné SFTP složky

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.
  • Join publikuje topic 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 na SendInvoiceJoined, aby dál dostával sloučené XML a PDF.

SendInvoiceJoinedError: TimeToLive reached

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í:

  1. Zjistěte, která událost chybí: primární dokument (target) nebo odpovídající událost (when).
  2. Chybějící část znovu dodejte nebo opravte dodání u zdroje.
  3. Pokud je výchozí TTL jednoho dne pro rytmus dodávek krátké, upravte parametr ttl na hooku.

Tip: nastavte webhook nebo e-mailový hook na topic SendInvoiceJoinedError, abyste hned dostali signál, když sada dorazí neúplná.

Často kladené otázky
Proč musí být výrazy target a when URL-encoded v action?

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.

Co se stane, pokud v rámci ttl nevznikne úplná shoda?

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.

Kdy nastavit delay vedle ttl?

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.

Co je SendInvoiceJoinedError a jak to vyřeším?

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