Event Streaming

Event Streaming copie des documents d'un site Dokos vers un autre site Dokos. Un site producteur enregistre chaque création, modification, annulation et suppression. Un site consommateur récupère ces changements et les applique à ses propres documents.

La synchronisation va dans un seul sens : du producteur vers le consommateur. Les changements faits sur le consommateur ne reviennent pas au producteur.

L'application n'a pas de traduction française. Ses écrans et ses types de documents s'affichent en anglais. Elle n'a pas d'espace de travail : ouvrez ses listes par la barre de recherche ou par leur adresse, par exemple /desk/event-producer.

L'application n'existe qu'en version next. Elle n'a pas de branche v5.

Comment fonctionne la synchronisation

      
flowchart LR
    D[Document modifié
    

1. Sur le producteur, chaque enregistrement d'un document suivi crée un Event Update Log. Le type de changement est Create, Update ou Delete. Une annulation crée un Update qui change le statut du document.
2. Le producteur prévient chaque consommateur concerné par une tâche de fond.
3. Le consommateur demande au producteur tous les changements postérieurs à sa dernière synchronisation.
4. Le consommateur applique chaque changement, dans l'ordre de création, et l'enregistre dans un Event Sync Log.

Un Event Update Log n'est créé que si au moins un consommateur a fait approuver ce type de document et ne s'est pas désinscrit. Une modification qui ne change aucune valeur ne crée pas de journal. Aucun journal n'est créé pendant l'installation d'une application ou une migration.

Prérequis

• L'application Event Streaming est installée sur les deux sites.
• Les deux sites sont joignables l'un par l'autre en HTTP ou HTTPS.
• Les tâches de fond (workers) et le planificateur de tâches sont actifs sur les deux sites.
• Un même utilisateur, avec la même adresse e-mail, existe sur les deux sites. Cette page l'appelle « l'abonné ». L'application le nomme « Event Subscriber ».
• L'abonné a le rôle Responsable système sur les deux sites. Le producteur refuse l'inscription si l'abonné n'a pas ce rôle chez lui.
• L'abonné a des clés API sur les deux sites. Pour les créer, ouvrez sa fiche Utilisateur, onglet Paramètres, section Accès API, puis cliquez sur Générer des clés. Notez la clé et le secret : le secret ne s'affiche qu'à la génération.

Seul le rôle Responsable système a accès aux types de documents de l'application.

Configurer le consommateur

Toute la configuration se fait sur le site consommateur. Le producteur reçoit l'inscription automatiquement.

1. Sur le site consommateur, ouvrez /desk/event-producer et cliquez sur Ajouter.
2. Dans Producer URL, saisissez l'adresse du site producteur, par exemple https://siege.exemple.fr. Seuls les schémas http et https sont acceptés. La barre oblique finale est retirée.
3. Dans API Key et API Secret, saisissez les clés de l'abonné sur le site producteur.
4. Dans Event Subscriber, choisissez l'abonné. Il doit avoir des clés API sur le site consommateur.
5. Dans le tableau Event Producer Document Types, ajoutez une ligne par type de document à recevoir. Les types de documents uniques (Single) et les tables enfants ne sont pas proposés.
6. Enregistrez.

À l'enregistrement, le site consommateur vérifie que le producteur répond. Il fait trois essais, à cinq secondes d'intervalle. Il inscrit ensuite le consommateur sur le producteur : un document Event Consumer est créé sur le producteur. Son nom est l'adresse du site consommateur. Il contient les clés API de l'abonné sur le consommateur, pour que le producteur puisse le prévenir.

Le consommateur ne reçoit que les changements faits après son inscription. Les documents qui existaient avant ne sont pas copiés, sauf s'ils sont modifiés par la suite (voir Ordre des changements).

Les options de chaque type de document

Si Use Same Name n'est pas coché, l'application ajoute deux champs personnalisés en lecture seule au type de document du consommateur : Remote Document Name (remote_docname) et Remote Site (remote_site_name). Ils gardent le nom d'origine et le site d'origine. Le consommateur s'en sert pour retrouver le document lors des modifications suivantes.

La Condition est évaluée sur le producteur, pour chaque changement :

• une expression Python qui reçoit doc, par exemple doc.disabled == 0 ;
• ou cmd: suivi du chemin d'une méthode Python. Elle reçoit consumer, doc et update_log et renvoie vrai ou faux.

Une erreur dans la condition bloque l'envoi du document. Elle est enregistrée dans le Journal des erreurs du producteur sous le titre has_consumer_access error.

La Naming Expression est une expression Python qui reçoit name, doctype et site. Elle peut aussi commencer par call: suivi du chemin d'une méthode. Avec call-recursive:, la méthode renomme aussi les valeurs des champs Lien du document et de ses tables.

Modifier la liste après coup

Quand vous modifiez la fiche Event Producer et l'enregistrez, le consommateur envoie la nouvelle liste au producteur. Les types de documents déjà approuvés gardent leur statut. Les nouveaux types arrivent en Pending.

Si vous changez API Key ou API Secret, l'enregistrement ne renvoie pas la liste au producteur.

Approuver sur le producteur

Le producteur décide de ce qu'il partage. Tant qu'un type de document n'est pas approuvé, rien n'est envoyé.

1. Sur le site producteur, ouvrez /desk/event-consumer.
2. Ouvrez la fiche du consommateur. Son nom est l'adresse du site consommateur.
3. Dans le tableau Event Consumer Document Types, passez Approval Status à Approved pour chaque type de document à partager, ou à Rejected pour le refuser.
4. Enregistrez.

Le producteur recopie les statuts sur la fiche Event Producer du consommateur. L'indicateur du statut est orange pour Pending, vert pour Approved et rouge pour Rejected.

Quels documents sont synchronisés

Tout type de document qui n'est ni unique ni une table enfant peut être synchronisé. L'application suit tous les types de documents du site. Elle ne crée de journal que pour ceux qui ont un consommateur approuvé.

Pour chaque changement reçu, le consommateur agit ainsi :

• Create : il crée le document. S'il existe déjà un document du même nom, il ne fait rien.
• Update : il applique les champs modifiés, les lignes ajoutées, modifiées et supprimées des tables, puis enregistre. S'il ne trouve pas le document local, il demande le document complet au producteur et le crée.
• Delete : il supprime le document local s'il le trouve.

Avant de créer ou modifier un document, le consommateur crée les documents liés qui lui manquent. Il les demande au producteur et les crée avec le même nom. Il traite d'abord les liens des tables enfants, puis les champs Lien, puis les liens dynamiques. Cochez Skip Dependencies pour ne pas le faire.

Correspondances entre types de documents

Une correspondance (Document Type Mapping) relie un type de document du producteur à un type de document du consommateur, quand leurs champs diffèrent. Créez-la sur le consommateur, dans /desk/document-type-mapping.

Quand vous choisissez Local Document Type, le tableau se remplit avec les champs du type local. Pour chaque ligne :

• Local Fieldname : le champ du consommateur (obligatoire) ;
• Remote Fieldname : le champ correspondant sur le producteur ;
• Default Value : la valeur à mettre quand le producteur n'envoie rien ;
• Mapping Type : Child Table pour une table, Document pour un document lié ;
• Mapping : la correspondance à appliquer à la table ou au document lié ;
• Remote Value Filters : pour Document, un filtre JSON qui trouve le document lié sur le producteur. Une valeur qui commence par eval: est une expression Python sur doc.

Un champ Lien, Lien dynamique ou Table du consommateur doit avoir une Mapping ou une Default Value. Sinon la correspondance ne s'enregistre pas.

Sur la fiche Event Producer, cochez Has Mapping et choisissez la correspondance. Le consommateur s'abonne alors au Remote Document Type chez le producteur.

Ordre des changements

Le consommateur garde la date du dernier changement traité dans un Event Producer Last Update. À chaque synchronisation, il demande les changements plus récents, pour les types de documents approuvés.

Les changements sont appliqués dans l'ordre où le producteur les a créés.

Le producteur note dans chaque Event Update Log les consommateurs qui l'ont lu (champ Consumers). Si un consommateur n'a pas lu le changement précédent d'un document, le producteur lui renvoie aussi les changements non lus de ce document, dans l'ordre. C'est le cas quand un document se met à remplir la Condition : le consommateur reçoit alors son historique.

L'application ne détecte pas les conflits. Un changement reçu du producteur remplace les valeurs locales des champs concernés. Une modification locale sur le consommateur n'est ni protégée ni renvoyée.

Quand la synchronisation a lieu

• Dès qu'un Event Update Log est créé, le producteur prévient les consommateurs concernés par une tâche de fond (file long).
• Si un consommateur ne répond pas, le producteur remet la notification en file d'attente.
• Le consommateur, prévenu, lance la récupération des changements en tâche de fond (file default).
• Chaque jour, le planificateur du producteur prévient tous les consommateurs qui ont au moins un type de document approuvé.

Journaux et relance des échecs

Un changement en échec ne bloque pas les suivants. Le consommateur passe au changement suivant et avance sa date de dernière synchronisation. Un échec n'est donc pas relancé automatiquement.

Pour relancer un échec :

1. Sur le consommateur, ouvrez /desk/event-sync-log et filtrez sur Status = Failed.
2. Ouvrez le journal et lisez le champ Error.
3. Corrigez la cause, par exemple un champ obligatoire manquant ou un document lié absent.
4. Cliquez sur Resync. Le statut passe à Synced si la relance réussit, sinon il reste Failed.

Dépannage

Voir aussi

• Catalogue des applications
• Dokos Data Hub, pour recevoir des fichiers de partenaires externes