Czasami części dokumentu pochodzą z różnych źródeł. Pomyśl o fakturze XML przychodzącej przez Peppol i załączniku PDF dostarczonym osobno, lub o wielu załącznikach należących do tej samej faktury. Za pomocą join hook PSB automatycznie łączy te osobne zdarzenia w jeden dokument.

Join hook nasłuchuje na wielu tematach jednocześnie i rozpoznaje, które zdarzenia należą do siebie. Hook rozróżnia dwa typy zdarzeń:

• Zdarzenia target: dokument główny (na przykład faktura lub zamówienie).
• Zdarzenia matching: załączniki lub uzupełnienia, które muszą zostać powiązane z dokumentem głównym.

Za pomocą wyrażeń określasz, które zdarzenie jest dokumentem głównym (target) i jak załączniki są dopasowywane (when). Gdy PSB znajdzie dopasowanie, łączy załączniki z dokumentem głównym i publikuje nowy temat.

Przebieg jest następujący:

1. PSB otrzymuje zdarzenia na skonfigurowanych tematach (na przykład SalesInvoiceReceived i AttachmentReceived)
2. Join hook ocenia każde zdarzenie na podstawie wyrażenia target, aby zidentyfikować dokument główny
3. Przy każdym nowym zdarzeniu hook sprawdza wyrażenie when, aby znaleźć dopasowanie
4. Po powiązaniu zdarzenia target ze zdarzeniem matching PSB dodaje załączniki do dokumentu głównego
5. Publikowany jest nowy temat (na przykład SalesInvoiceJoined)

Siła join hooks tkwi w wyrażeniach. Piszesz dwa wyrażenia: jedno do identyfikacji dokumentu głównego i jedno do dopasowywania załączników.

Wyrażenie target określa, czy zdarzenie jest dokumentem głównym. Często używanym wzorcem jest dopasowanie na podstawie tematu:

topic=="SalesInvoiceReceived"

Wyrażenie when łączy zdarzenie matching z właściwym zdarzeniem target. Tutaj porównujesz pola między zdarzeniem źródłowym (source) a zdarzeniem docelowym (target):

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

W tym przykładzie zdarzenia są dopasowywane, jeśli mają ten sam identyfikator dokumentu i tego samego nadawcę.

Uwaga: wszystkie wyrażenia muszą być zakodowane URL w adresie action. Wyrażenie topic=="SalesInvoiceReceived" staje się topic%3D%3D%22SalesInvoiceReceived%22. Nie zapomnij o tym, ponieważ PSB parsuje wyrażenia z query string.

Zarejestruj hook za pomocą API z akcją 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
}

Akcja ma następujący format:

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

Tablica topics hooka musi zawierać wszystkie tematy, na których join hook powinien nasłuchiwać. Obejmuje to tematy zarówno dla dokumentu głównego, jak i załączników.

Pole publishTopics określa, na jakim temacie publikowany jest połączony dokument. Możesz skonfigurować zwykły webhook lub e-mail hook na tym temacie, aby otrzymać wynik.

ttl (Time to Live) określa, jak długo PSB czeka na dopasowanie. Jeśli po upływie TTL brakuje dokumentu głównego lub załącznika, PSB publikuje temat błędu (*JoinedError). Dzięki temu możesz wykryć, kiedy zestaw jest niekompletny.

Ustaw TTL na wartość odpowiadającą oczekiwanemu czasowi realizacji. Jeśli załączniki zazwyczaj przychodzą w ciągu godziny, TTL 01:00:00 jest wystarczający.

Wskazówka: skonfiguruj webhook lub e-mail hook na temacie *JoinedError. Dzięki temu otrzymasz sygnał, gdy brakuje załącznika lub faktury, i możesz podjąć działanie w odpowiednim czasie.

Bez delay łączenie rozpoczyna się, gdy tylko zdarzenie target i jedno zdarzenie matching zostaną znalezione. Jeśli oczekujesz wielu załączników do tego samego dokumentu, ustaw delay. PSB czeka określony czas po wykryciu zdarzenia target, a następnie łączy wszystkie załączniki dopasowane w tym okresie za jednym razem.

Załóżmy, że oczekujesz trzech załączników PDF do faktury i przychodzą one w ciągu 20 minut. Delay 00:30:00 zapewnia wystarczający margines na zebranie wszystkich załączników.

Organizacja otrzymuje faktury przez Peppol (temat SalesInvoiceReceived) i towarzyszące załączniki PDF osobnym kanałem (temat AttachmentReceived). Załączniki są dopasowywane na podstawie identyfikatora dokumentu i nadawcy. Po połączeniu kompletny dokument jest publikowany na SalesInvoiceJoined, po czym webhook przekazuje go do systemu ERP.

Potrzebujesz pomocy przy konfiguracji odpowiednich wyrażeń? Skontaktuj się z TechSupport pod adresem techsupport@econnect.eu. Pełna specyfikacja API jest dostępna na psb.econnect.eu.