ℹ️ Afin de bien visualiser ce qu'est une interface de synchronisation : il s'agit du "tuyau" qui relie votre instance Rgive à un outil tiers.
Une fois le tuyau créé, vous y faîtes couler de la data depuis Rgive lors d'un export, ou vers Rgive lors d'un import.
Quel que soit la nature du transfert pour laquelle vous optez, afin de le rendre opérationnel il vous faudra :
Créer l'interface de synchronisation, cf les 4 options ci-dessous
Sélectionner cette interface dans le ou les exports / imports que vous souhaiterez brancher à cette interface, cf le bas de cet article.
A noter : vous pouvez modifier la configuration de votre interface une fois-celle-ci créée.
⚙️ 4 natures de transfert en fonction de vos besoins techniques
De manière général, la nature du transfert vous est imposée par le système tiers (CRM, mailer, etc.) vers lequel vous souhaitez pousser la data dans le cadre d'exports ou depuis lequel vous souhaitez en récupérer dans le cadre d'imports.
☝🏻 Pour créer votre interface de synchronisation, rendez-vous dans Exports / Imports dans votre menu latéral puis dans Interface de Synchronisation. Cliquez sur le bouton "Créer une Interface".
4 natures de transfert sont ainsi possibles au moment de créer votre interface de synchronisation :
SFTP : transfert ou récupération automatisés de fichiers structurés (type .csv / .json) vers ou depuis un serveur distant
API : synchronisation via des appels HTTP sécurisés avec une clé d'API.
API Oauth : synchronisation sécurisée avec authentification déléguée sans partage de mot de passe. Sert essentiellement dans le cadre d'une synchronisation CRM (Salesforce, Microsoft 365)
lien sécurisé : vous permet d'automatiser l'envoi par email d'un fichier via un lien qui devient obsolète au bout d'une durée de temps que vous configurez. Cela permet de sécuriser la circulation de vos données.
Option 1️⃣ - Création d'une synchronisation SFTP
Une fois le nom donné à votre interface, afin de la configurer il va vous falloir renseigner :
le serveur hôte
le port
le type de clé SSH parmi 5 types possibles :
RCA
ECDSA-NISTP256
ECDSA-NISTP384
ECDSA-NISTP521
ED25519
Si vous le pouvez, nous vous invitons à utiliser ED25519, plus sécurisée et plus performante.
la clé SSH de l'hôte
le chemin du répertoire racine, i.e. le dossier où aura à être poussée ou récupérer la data.
A noter : le chemin peut aussi être affiné dans la configuration de sortie de l'export qui utilisera cette interface de synchronisation
L'authentification au serveur SFTP peut se faire par mot de passe ou par clé SSH.
🔢 Si vous optez pour le mot de passe, il nous faut un nom d'utilisateur et le mot de passe associé.
🔑 Si vous optez pour une clé SSH d'authentification, alors une clé publique sera générée et aura à être stockée du côté de l'interface à connecter.
Option 2️⃣ - Création d'une synchronisation API
Une fois le nom donné à votre interface, afin de la configurer il va vous falloir renseigner :
la méthode HTTP qui définit le type d'action effectué sur les données.
Nous vous invitons à utiliser essentiellement du POST.POST — Création. Envoie de nouvelles données pour créer une ressource. Ex : créer un nouveau donateur dans Rgive.
PUT — Mise à jour. Remplace une ressource existante par les nouvelles données envoyées.
Ex : mettre à jour les coordonnées d'un donateur déjà existant.
GET (non recommandé) — Lecture seule. Récupère des données depuis Rgive sans les modifier.
Ex : récupérer des informations de contacts externes
l'url de healthcheck c'est l'URL que le système tiers appelle avant de lancer la synchronisation pour s'assurer que Rgive est disponible et prêt à recevoir ou envoyer des données, évitant ainsi un export en erreur vers un service indisponible.
le Nom d'utilisateur et le Mot de Passe
les entêtes HTTP permettant l'identification de connexion si nécessaire.
⚠️ L'URL de l'endpoint, vers laquelle sont poussées les data, est configurée dans le dessin d'export lui-même, dans la Configuration de Sortie. Cf en bas de cet article.
Exemple d'entêtes pour la synchronisation avec le CRM Ohme :
Option 3️⃣ - Création d'un synchronisation API OAuth
Une fois le nom donné à votre interface, afin de la configurer il va vous falloir renseigner :
la méthode HTTP qui définit le type d'action effectué sur les données.
Cf plus haut le détail des méthodes dans le chapitre sur les synchro API.Comme pour les API classiques, nous recommandons le POST.
l'URL de base du service auquel se connecter
l'URL de connexion qui se termine généralement par /token (par exemple : https://example.com/services/oauth2/token)
le Nom d’utilisateur OAuth
l'Identifiant du client OAuth
la Clé privée du client OAuth
Option 4️⃣ - Création d'une synchronisation API
☝🏻 Bonne pratique RGPD
Le lien sécurisé est seulement valable pour les exports.
Il vous permet de partager de façon plus sécurisée vos data, grâce à l'envoi par email d'un lien avec une durée de validité finie.
Une fois la durée expirée, les datas ne sont plus accessibles sans rejouer l'export.
Cela évite de transférer des fichiers excels contenant des données personnelles de vos donateurs qui, envoyés par email, restent accessibles dans votre boîte email en cas de faille de sécurité sur votre ordinateur ou celui du destinataire des informations.
Il peut être utilisé à des fins d'envoi ponctuels ou dans le cadre d'envoi de rapports hebdos ou mensuels.
Une fois le nom donné à votre lien sécurisé, sa configuration est ultra-simple, il vous suffit de définir :
la durée de validité du lien qui a une durée de validité de max 6 heures
définir la liste du ou des destinataires du lien
➡️ Configuration d'un Export
Une fois votre dessin d'export créé (i.e. une fois que vous avez configuré les infos que vous voulez recevoir), vous pouvez décider de le pousser dans une interface de synchronisation précise en fonction de critères d'export (nom, format, etc.) et en fonction de déclencheurs prédéfinis (lors d'un don réussi, une fois par jour, etc.).
Pour cela, il vous suffit d'aller dans le dessin d'export choisi, d'aller dans l'onglet "Configuration de Sortie", et de sélectionner l'interface de synchronisation cible en bas de page.
Différents élements vous sont demandés :
Pour une synchro SFTP, il vous est demandé de préciser le chemin du répertoire cible si nécessaire, i.e. le chemin relatif vers le répertoire cible, à partir du répertoire racine défini dans l'interface de synchronisation (cf plus haut). Si vide, le répertoire cible sera le répertoire racine.
Ex. : si votre interface pointe vers le dossier /asso/synchro et que vous voulez aller dans /asso/synchro/dons-ponctuels, alors il vous faut ajouter "dons-ponctuels" dans le chemin du répertoire cible au niveau de votre configuration de sortie.
Cela peut permettre, pour un serveur SFTP identifié, d'envoyer les informations dans différents sous-dossiers.
Pour une synchro API, c'est ici que vous indiquez l'URL de endpoint, i.e.l'adresse précise à laquelle Rgive doit envoyer les données dans le système tiers envoie ou récupère les données lors de la synchronisation — c'est le "point d'entrée".
ℹ️ Une fois que vous avez sélectionnez une interface de synchronisation dans la configuration de votre export, si vous exécutez celui-ci, le fichier extrait de votre base de données sera directement poussé dans l'interface, à destination de l'outil cible (votre CRM, votre mailer, etc.).
Si vous ne sélectionnez pas d'interface de synchronisation, l'Exécution de l'export vient simplement télécharger le fichier exporté sur votre ordinateur.