A volte le parti di un documento provengono da fonti diverse. Pensa a una fattura XML che arriva via Peppol e a un allegato PDF consegnato separatamente, oppure a più allegati appartenenti alla stessa fattura. Con un join hook, il PSB combina automaticamente questi eventi separati in un unico documento.

Un join hook ascolta su più topic contemporaneamente e riconosce quali eventi appartengono tra loro. L'hook distingue due tipi di eventi:

• Eventi target: il documento principale (ad esempio una fattura o un ordine).
• Eventi matching: allegati o supplementi che devono essere collegati al documento principale.

Tramite espressioni determini quale evento è il documento principale (target) e come vengono abbinati gli allegati (when). Non appena il PSB trova una corrispondenza, unisce gli allegati al documento principale e pubblica un nuovo topic.

Il flusso è il seguente:

1. Il PSB riceve eventi sui topic configurati (ad esempio SalesInvoiceReceived e AttachmentReceived)
2. Il join hook valuta ogni evento rispetto all'espressione target per identificare il documento principale
3. Ad ogni nuovo evento, l'hook verifica l'espressione when per trovare una corrispondenza
4. Una volta che il target e gli eventi matching sono collegati, il PSB aggiunge gli allegati al documento principale
5. Viene pubblicato un nuovo topic (ad esempio SalesInvoiceJoined)

La potenza dei join hook risiede nelle espressioni. Scrivi due espressioni: una per identificare il documento principale e una per abbinare gli allegati.

L'espressione target determina se un evento è il documento principale. Un pattern comunemente utilizzato è il matching sul topic:

topic=="SalesInvoiceReceived"

L'espressione when collega un evento matching all'evento target corretto. Qui confronti i campi tra l'evento di origine (source) e l'evento target (target):

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

In questo esempio, gli eventi vengono abbinati se hanno lo stesso ID documento e lo stesso mittente.

Nota: tutte le espressioni devono essere URL-encoded nell'URL dell'azione. L'espressione topic=="SalesInvoiceReceived" diventa topic%3D%3D%22SalesInvoiceReceived%22. Non dimenticarlo, poiché il PSB analizza le espressioni dalla query string.

Registra un hook tramite l'API con un'azione 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
}

L'azione segue il formato:

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

L'array topics dell'hook deve contenere tutti i topic su cui il join hook deve ascoltare. Questo include i topic sia per il documento principale che per gli allegati.

Il campo publishTopics determina su quale topic viene pubblicato il documento unito. Puoi configurare un webhook o un e-mail hook normale su questo topic per ricevere il risultato.

Il ttl (Time to Live) determina per quanto tempo il PSB attende una corrispondenza. Se dopo il periodo TTL manca il documento principale o l'allegato, il PSB pubblica un topic di errore (*JoinedError). Questo ti consente di rilevare quando un set è incompleto.

Imposta il TTL su un valore adeguato al tuo tempo di risposta atteso. Se gli allegati arrivano tipicamente entro un'ora, un TTL di 01:00:00 è sufficiente.

Suggerimento: configura un webhook o un e-mail hook sul topic *JoinedError. In questo modo ricevi un segnale quando manca un allegato o una fattura, permettendoti di intervenire tempestivamente.

Senza un delay, l'unione inizia non appena vengono trovati l'evento target e un evento matching. Se ti aspetti più allegati per lo stesso documento, imposta un delay. Il PSB attende il tempo specificato dopo aver rilevato l'evento target e poi unisce tutti gli allegati abbinati durante quel periodo in un'unica operazione.

Supponiamo che ti aspetti tre allegati PDF per una fattura e che arrivino nell'arco di 20 minuti. Un delay di 00:30:00 fornisce un margine sufficiente per raccogliere tutti gli allegati.

Un'organizzazione riceve fatture via Peppol (topic SalesInvoiceReceived) e allegati PDF di accompagnamento attraverso un canale separato (topic AttachmentReceived). Gli allegati vengono abbinati per ID documento e mittente. Dopo l'unione, il documento completo viene pubblicato su SalesInvoiceJoined, dopodiché un webhook lo inoltra al sistema ERP.

Hai bisogno di aiuto per configurare le espressioni corrette? Contatta TechSupport all'indirizzo techsupport@econnect.eu. Consulta la specifica completa dell'API su psb.econnect.eu per tutte le opzioni di configurazione.