Parfois, les parties d'un document proviennent de sources différentes. Pensez à une facture XML arrivant via Peppol et une pièce jointe PDF livrée séparément, ou à plusieurs pièces jointes appartenant à la même facture. Avec un join hook, la PSB combine automatiquement ces événements distincts en un seul document.

Un join hook écoute simultanément plusieurs topics et reconnaît quels événements vont ensemble. Le hook distingue deux types d'événements :

• Événements target : le document principal (par exemple une facture ou une commande).
• Événements matching : les pièces jointes ou suppléments qui doivent être liés au document principal.

À l'aide d'expressions, vous déterminez quel événement est le document principal (target) et comment les pièces jointes sont associées (when). Dès que la PSB trouve une correspondance, elle fusionne les pièces jointes avec le document principal et publie un nouveau topic.

Le flux est le suivant :

1. La PSB reçoit des événements sur les topics configurés (par exemple SalesInvoiceReceived et AttachmentReceived)
2. Le join hook évalue chaque événement par rapport à l'expression target pour identifier le document principal
3. À chaque nouvel événement, le hook vérifie l'expression when pour trouver une correspondance
4. Une fois le target et le(s) événement(s) matching liés, la PSB ajoute les pièces jointes au document principal
5. Un nouveau topic est publié (par exemple SalesInvoiceJoined)

La puissance des join hooks réside dans les expressions. Vous écrivez deux expressions : une pour identifier le document principal et une pour associer les pièces jointes.

L'expression target détermine si un événement est le document principal. Un modèle couramment utilisé est la correspondance sur le topic :

topic=="SalesInvoiceReceived"

L'expression when lie un événement matching au bon événement target. Ici, vous comparez des champs entre l'événement source (source) et l'événement target (target) :

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

Dans cet exemple, les événements sont associés s'ils ont le même identifiant de document et le même expéditeur.

Remarque : toutes les expressions doivent être encodées en URL dans l'URL de l'action. L'expression topic=="SalesInvoiceReceived" devient topic%3D%3D%22SalesInvoiceReceived%22. N'oubliez pas cette étape, car la PSB parse les expressions depuis le query string.

Enregistrez un hook via l'API avec une action 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'action suit le format :

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

Le tableau topics du hook doit contenir tous les topics sur lesquels le join hook doit écouter. Cela inclut les topics pour le document principal et les pièces jointes.

Le champ publishTopics détermine sur quel topic le document fusionné est publié. Vous pouvez configurer un webhook classique ou un e-mail hook sur ce topic pour recevoir le résultat.

Le ttl (Time to Live) détermine combien de temps la PSB attend une correspondance. Si après la période TTL le document principal ou la pièce jointe manque, la PSB publie un topic d'erreur (*JoinedError). Cela vous permet de détecter quand un ensemble est incomplet.

Définissez le TTL sur une valeur qui correspond à votre délai de traitement attendu. Si les pièces jointes arrivent généralement dans l'heure, un TTL de 01:00:00 est suffisant.

Conseil : configurez un webhook ou un e-mail hook sur le topic *JoinedError. Vous recevrez ainsi un signal lorsqu'une pièce jointe ou une facture manque, ce qui vous permettra d'agir à temps.

Sans delay, la fusion commence dès que l'événement target et un événement matching sont trouvés. Si vous attendez plusieurs pièces jointes pour le même document, définissez un delay. La PSB attend le temps spécifié après la détection de l'événement target, puis fusionne toutes les pièces jointes associées pendant cette période en une seule fois.

Supposons que vous attendiez trois pièces jointes PDF pour une facture et qu'elles arrivent sur une période de 20 minutes. Un delay de 00:30:00 offre une marge suffisante pour collecter toutes les pièces jointes.

Une organisation reçoit des factures via Peppol (topic SalesInvoiceReceived) et des pièces jointes PDF associées via un canal séparé (topic AttachmentReceived). Les pièces jointes sont associées sur la base de l'identifiant du document et de l'expéditeur. Après la fusion, le document complet est publié sur SalesInvoiceJoined, après quoi un webhook le transmet au système ERP.

Besoin d'aide pour configurer les bonnes expressions ? Contactez TechSupport à techsupport@econnect.eu. Consultez la spécification complète de l'API sur psb.econnect.eu pour toutes les options de configuration.