Guide d'Intégration

Softyflow fournit des capacités d'intégration complètes qui vous permettent de vous connecter avec des systèmes et services externes. Ce guide couvre les trois principales méthodes d'intégration disponibles dans Softyflow.

Avant de commencer, nous vous recommandons d'avoir une bonne compréhension de votre configuration de projet, d'être familier avec les concepts de base de données dans Softyflow et d'avoir une certaine expérience avec le concepteur d'interface web et le modélisateur de processus. Cette connaissance fondamentale vous aidera à tirer le maximum de ce guide.

1. Intégration API EDS (Intégrations Sortantes)​

La fonctionnalité de Source de Données Externe (EDS) est l'approche déclarative de Softyflow pour l'intégration d'API. Elle vous permet de vous connecter à des API REST externes et de les traiter comme s'il s'agissait de sources de données locales. C'est le point de départ idéal pour la plupart des tâches d'intégration, car elle est puissante, configurable et ne nécessite pas l'écriture de code complexe.

1.1. Configuration d'API EDS​

Configurez l'API EDS pour vous connecter avec des APIs REST externes :

La vue suivante illustre la première étape de configuration d'une nouvelle Source de Données Externe (EDS) pour se connecter à une API externe. L'utilisateur a saisi 'Google Calendar API' comme nom et sélectionne 'Api' dans le menu déroulant 'Type EDS'. C'est l'étape initiale pour connecter Softyflow à une API REST externe.

Configuration initiale d'une Source de Données Externe de type API.

Voici une description de la configuration initiale :

1. Nom : Utilisez toujours un nom clair et descriptif. Nous avons utilisé Google Calendar API pour le rendre facilement identifiable.
2. Type EDS : C'est un paramètre crucial. En sélectionnant Api, vous déverrouillez les options de configuration spécifiques aux services web REST et SOAP.

1.2. Sécurisation de Votre Source de Données​

La sécurité est un aspect critique de l'intégration. Softyflow vous permet de définir des droits d'accès granulaires pour chaque source de données, garantissant que seuls les utilisateurs et rôles autorisés peuvent effectuer des opérations spécifiques.

L'image ci-dessous illustre comment vous pouvez configurer le contrôle d'accès basé sur les rôles. En définissant quels groupes d'utilisateurs ont les permissions créer, lire, mettre à jour ou supprimer, vous pouvez appliquer les politiques de sécurité de votre organisation au niveau de la source de données. Dans cet exemple, nous accordons les permissions complètes aux administrateurs, tout en limitant les autres utilisateurs à un accès en lecture seule.

Configuration de l'accès basé sur les rôles pour l'EDS.

1.3. Définition des Opérations API : Points de Terminaison et Scripts​

Une fois la configuration de base en place, il est temps de définir les opérations réelles que votre application effectuera. Cela se fait en configurant des Points de terminaison (Endpoints). Chaque point de terminaison représente une action spécifique, comme récupérer une liste d'éléments, en créer un nouveau ou supprimer un enregistrement existant.

La fonctionnalité EDS de Softyflow fournit un ensemble de types de points de terminaison standard qui couvrent les opérations CRUD (Créer, Lire, Mettre à jour, Supprimer) les plus courantes. Lorsque vous nommez vos points de terminaison en utilisant ces conventions, Softyflow peut fournir des optimisations et fonctionnalités supplémentaires.

• retrieve : Récupère un enregistrement unique, généralement par son ID unique.
• list : Récupère une collection d'enregistrements, avec support pour la pagination.
• count : Retourne le nombre total d'enregistrements qui correspondent à un critère donné.
• insert : Crée un nouvel enregistrement.
• insertMany : Crée plusieurs enregistrements en une seule opération.
• update : Modifie un enregistrement existant.
• delete : Supprime un enregistrement.
• execute : Un type de point de terminaison flexible pour les opérations personnalisées qui ne correspondent pas au modèle CRUD standard.

La liste des points de terminaison pour notre EDS Google Calendar API.

Pour chaque point de terminaison, vous configurerez les éléments suivants :

• Nom : Un nom logique pour l'opération (par exemple, list, create, update).
• Méthode : La méthode HTTP standard (GET, POST, PUT, DELETE, etc.).
• URL : L'URL spécifique pour le point de terminaison de l'API.

1.3.1. Personnalisation Avancée des Requêtes​

Softyflow fournit plusieurs façons de personnaliser la requête sortante pour chaque point de terminaison.

Script de pré-exécution (Prerun Script) : Pour une flexibilité ultime, l'onglet Prerun Script vous permet d'écrire du code JavaScript personnalisé qui s'exécute avant l'envoi de la requête API. Cela est incroyablement puissant pour la modification dynamique des requêtes, comme générer des signatures d'authentification personnalisées, chiffrer des parties du corps de la requête ou ajouter dynamiquement des en-têtes.

L'onglet Prerun Script offre une méthode puissante pour personnaliser les requêtes.

1.3.2. En-têtes et Paramètres :​

Les onglets Headers et Params fournissent une interface conviviale pour ajouter des en-têtes HTTP et des paramètres de requête statiques ou dynamiques. C'est parfait pour les tâches courantes comme définir le Content-Type ou passer des clés API.

Lors de l'écriture de scripts de pré-exécution ou d'autres logiques personnalisées, vous avez accès à un ensemble riche de variables de contexte. Ces variables fournissent des informations sur la requête actuelle et vous permettent de créer des intégrations hautement dynamiques et intelligentes.

• SF_source : Un objet contenant la source de données et les paramètres de requête.
• SF_table : Le nom de la table ou de la ressource accédée.
• SF_postData : La charge utile des données pour les opérations POST et PUT.
• SF_limit : Le nombre maximum d'enregistrements à récupérer (pour les points de terminaison list).
• SF_sortby : Le champ de tri.
• SF_page : Le numéro de page actuel pour les requêtes paginées.
• SF_direction : La direction du tri (1 pour ascendant, -1 pour descendant).

  

  

1.3.3. Test de Vos Points de Terminaison​

L'une des fonctionnalités les plus importantes de l'écran de configuration EDS est la capacité de test intégrée. Avant même d'intégrer l'EDS dans une page web ou un processus, vous pouvez tester chaque point de terminaison pour vous assurer qu'il fonctionne comme prévu.

Le panneau Test vous montre la réponse API complète, y compris le code de statut, les en-têtes et le corps. C'est un outil inestimable pour le débogage et la vérification, vous économisant des heures de dépannage.

Le panneau Test affichant une réponse API réussie.

1.4. Tout Rassembler : Utilisation de Votre EDS​

Une fois votre EDS configuré et testé, vous pouvez commencer à l'utiliser dans toute votre application Softyflow. La beauté de la fonctionnalité EDS est qu'elle abstrait la complexité de l'API, vous permettant d'interagir avec elle comme s'il s'agissait d'une simple base de données.

1.4.1. Dans les Actions de Processus​

Au sein du modélisateur de processus, vous pouvez utiliser votre EDS dans diverses actions. L'image ci-dessous montre comment configurer une action pour interagir avec notre EDS API. Cela vous permet d'intégrer de manière transparente des données externes dans vos workflows automatisés.

Appel de l'EDS depuis une action de processus.

1.4.2. Dans les Widgets d'Interface Web​

La véritable puissance de l'EDS devient apparente lorsque vous commencez à construire des interfaces utilisateur. Vous pouvez lier des widgets directement à votre EDS, créant des expériences utilisateur dynamiques et basées sur les données avec un minimum d'effort.

Les images suivantes démontrent comment connecter un widget Table à notre EDS API.

1. Sélectionner la Source de Données : Tout d'abord, vous configurez le widget pour utiliser une source de données EDS et sélectionnez la Database.

   

   Sélection de l'EDS comme source de données pour un widget.

2. Mapper les Champs de Données :

Cette sélection explique une étape de connexion d'un widget Table d'interface utilisateur à une source de données comme une API.

1. Sélectionner la Source de Données : Source de Données : Avant cette étape, vous auriez choisi votre source de données. Cela pourrait être un EDS (Source de Données Externe), qui pourrait être une base de données (comme MySQL) ou une API.
2. Récupérer les Données : Le système récupère les données de cette source. Lors de la récupération depuis une base de données, vous pouvez spécifier le tri, comme trié par createdAt.
3. Mapper les Champs de Données (C'est ce que décrit le texte) : Après avoir obtenu les données, vous devez indiquer au widget comment les afficher. Le texte et l'image montrent que vous effectuez un "mappage" :
   • Le champ summary de la réponse API vers le label (le texte que l'utilisateur voit).
   • Le champ id vers la value (la valeur interne de la sélection).

En résumé, le texte sélectionné concerne la configuration d'un composant d'interface utilisateur pour afficher correctement les données qu'il reçoit d'une source externe.

Mappage des champs API vers les propriétés du widget.

2. Scripts via Axios : La Boîte à Outils du Développeur pour les Intégrations Avancées​

Lorsque vous avez besoin de plus de contrôle et de flexibilité que ce que la fonctionnalité EDS fournit, Softyflow vous permet d'écrire des scripts d'intégration personnalisés en utilisant la bibliothèque populaire axios. Cette fonctionnalité est disponible dans le SDK du Modélisateur de Processus et est idéale pour les scénarios complexes, tels que les intégrations qui nécessitent une logique personnalisée, la gestion des erreurs ou des interactions API en plusieurs étapes.

2.1. Effectuer Votre Premier Appel API​

La bibliothèque axios est disponible globalement dans vos scripts de processus, vous pouvez donc commencer à effectuer des requêtes HTTP immédiatement. Examinons quelques exemples.

2.2. Méthodes HTTP de Base​

Voici quelques exemples de la façon d'effectuer des opérations CRUD de base en utilisant axios.

2.2.1. GET : Récupération de Données​

Ce script démontre une requête GET simple pour récupérer un élément todo unique depuis une API publique. Le mot-clé await est utilisé pour attendre la résolution de la promesse, et les données de réponse sont ensuite enregistrées.

Une requête GET simple avec axios.

2.2.2. POST : Création de Données​

Pour créer une nouvelle ressource, vous pouvez utiliser une requête POST. Cet exemple envoie une charge utile JSON pour créer un nouvel élément todo. La réponse de l'API, qui contient généralement l'objet nouvellement créé avec son ID assigné par le serveur, est ensuite enregistrée.

Création d'une nouvelle ressource avec une requête POST.

2.2.3. PUT : Mise à Jour de Données​

Une requête PUT est utilisée pour mettre à jour une ressource existante. Ce script envoie une nouvelle charge utile pour remplacer l'élément todo avec id: 1.

Mise à jour d'une ressource avec une requête PUT.

2.2.4. DELETE : Suppression de Données​

Enfin, une requête DELETE est utilisée pour supprimer une ressource. Ce script envoie une requête pour supprimer l'élément todo avec id: 1.

Suppression d'une ressource avec une requête DELETE.

2.3. Gestion de l'Authentification​

La plupart des API du monde réel nécessitent une authentification. Voici quelques modèles d'authentification courants implémentés avec axios.

2.3.1. Jeton Bearer (Bearer Token)​

L'authentification par jeton Bearer est une norme largement utilisée. Le jeton est envoyé dans l'en-tête Authorization de la requête. C'est une bonne pratique de stocker les données sensibles comme les jetons dans des variables sécurisées plutôt que de les coder en dur dans vos scripts.

Envoi d'un jeton Bearer dans l'en-tête Authorization.

2.3.2. Clé API​

Une autre méthode courante consiste à utiliser une clé API, qui peut être envoyée en tant que paramètre de requête, en-tête ou dans le corps de la requête, selon les exigences de l'API. L'exemple ci-dessous montre comment envoyer une clé API en tant que paramètre de requête.

Utilisation d'une clé API comme paramètre de requête.

2.4. Exemple Avancé : Intégration Multi-Étapes​

La vraie puissance des scripts avec axios brille dans les intégrations complexes en plusieurs étapes. Dans cet exemple, le script s'authentifie d'abord auprès d'une API en effectuant une requête POST pour obtenir un jeton JWT. Il utilise ensuite ce jeton pour effectuer une requête GET ultérieure vers un point de terminaison protégé. Ce modèle est très courant lorsqu'on travaille avec des API modernes.

Une intégration en plusieurs étapes : d'abord s'authentifier, puis récupérer les données.

3. APIs Entrantes : Exposer Votre Application au Monde​

Les intégrations sont une voie à double sens. Jusqu'à présent, nous nous sommes concentrés sur la façon dont Softyflow peut consommer des API externes. Mais que faire si vous avez besoin que des systèmes externes communiquent avec votre application Softyflow ? C'est là qu'interviennent les APIs Entrantes.

Cette fonctionnalité puissante vous permet de créer vos propres points de terminaison API sécurisés qui peuvent déclencher des processus Softyflow, interagir avec vos données et exécuter une logique personnalisée. C'est la méthode parfaite pour implémenter des webhooks, créer une API publique pour votre application ou permettre des intégrations avec des systèmes qui doivent initier le contact avec Softyflow.

3.1. Créer Votre Première API Entrante​

La création d'une API entrante se fait via l'interface d'administration de Softyflow. Un éditeur de code vous sera présenté où vous pourrez écrire la logique de votre API en utilisant JavaScript.

3.1.1. Accéder aux Données de Requête​

Softyflow fournit un ensemble de variables globales que vous pouvez utiliser pour accéder aux données de la requête entrante :

• SF_body : Le corps JSON analysé de la requête.
• SF_headers : Un objet contenant les en-têtes HTTP.
• SF_query : Un objet contenant les paramètres de requête URL.
• SF_mode : Le mode d'exécution de l'API (test, uat ou prod).
• SF_initiator : L'objet utilisateur de l'utilisateur qui a initié l'appel API.

L'image ci-dessous montre l'écran de configuration de l'API, mettant en évidence les variables disponibles et l'éditeur de code.

L'écran de configuration de l'API entrante.

3.2. Exemple d'Implémentation d'API​

Une implémentation simple d'une API entrante dans Softyflow est présentée ici. Le script accède au corps de la requête en utilisant la variable SF_body et le retourne dans la réponse. Cela démontre la structure de base d'une API Softyflow, où vous pouvez traiter les données entrantes et renvoyer une réponse à l'appelant.

Une API d'écho simple qui retourne le corps de la requête.

3.3. Consommer Votre API Entrante​

Une fois votre API créée, vous pouvez l'appeler depuis divers endroits, à la fois dans et en dehors de Softyflow.

3.3.1. Depuis Softyflow : L'Action InvokeApi​

La façon la plus simple d'appeler une API entrante depuis votre application Softyflow est d'utiliser l'action InvokeApi dans vos processus ou interfaces web. Cette action fournit une méthode simple, sans code, pour appeler vos API, leur transmettre des données et gérer leurs réponses.

L'image ci-dessous montre la configuration d'une action InvokeApi. Vous sélectionnez simplement l'API que vous souhaitez appeler, fournissez le corps de la requête (qui peut inclure des variables dynamiques) et spécifiez une variable pour stocker la réponse.

Configuration de l'action InvokeApi.

3.3.2. Depuis des Systèmes Externes : Obtenir l'URL de l'API​

Pour permettre aux systèmes externes d'appeler votre API, vous devez leur fournir l'URL de l'API. Vous pouvez l'obtenir depuis l'écran de gestion de l'API, comme indiqué ci-dessous.

URLs spécifiques à l'environnement pour votre API.

3.4. Sécurité et Gestion​

Softyflow fournit un ensemble robuste d'outils pour sécuriser et gérer vos API entrantes.

3.4.1. Contrôle d'Accès à l'API​

• Accès Basé sur les Rôles : Vous pouvez restreindre l'accès à vos API en les assignant à des groupes d'utilisateurs spécifiques.
• Accès Public : Pour les webhooks ou autres services orientés public, vous pouvez marquer une API comme "publique" pour permettre l'accès sans authentification.
• Surveillance de l'Utilisation : Tous les appels API sont enregistrés, vous permettant de surveiller l'utilisation, suivre qui appelle vos API et quand.

3.4.2. Test d'API Intégré​

Le test est un citoyen de première classe dans le module API de Softyflow. L'éditeur d'API inclut un outil de test intégré qui vous permet de :

1. Définir des Charges Utiles de Test : Vous pouvez définir des données de test SF_body, SF_query et SF_headers dans un éditeur JSON.
2. Exécuter des Tests : Cliquez simplement sur le bouton "Test" pour exécuter votre API avec les données de test.
3. Afficher les Résultats : La réponse de votre API est affichée dans un panneau de résultats dédié, vous permettant de déboguer et d'itérer rapidement sur votre code.
4. Surveiller les Journaux : Vous pouvez également surveiller les journaux de l'application pour des informations de débogage plus détaillées.

4. Meilleures Pratiques d'Intégration​

Construire des intégrations robustes et fiables nécessite plus que de simplement connecter des systèmes. Voici quelques meilleures pratiques à garder à l'esprit lorsque vous travaillez avec l'une des méthodes d'intégration dans Softyflow.

4.1. Sécurité Avant Tout​

• Valider Tout : Ne faites jamais confiance aux données provenant de systèmes externes. Validez toujours les données d'entrée côté client et côté serveur pour vous protéger contre les vulnérabilités courantes comme les attaques par injection.
• Appliquer l'Authentification : Sécurisez vos API avec des mécanismes d'authentification robustes. Utilisez le contrôle d'accès basé sur les rôles de Softyflow pour les intégrations entrantes et sortantes.
• Utiliser HTTPS : Utilisez toujours HTTPS pour toutes les communications API afin de chiffrer les données en transit et de les protéger contre l'écoute clandestine.
• Assainir les Données : Avant de stocker ou de traiter des données provenant de systèmes externes, assurez-vous de les assainir pour prévenir les scripts intersites (XSS) et autres attaques.

4.2. Gestion Robuste des Erreurs​

• Anticiper l'Inattendu : Les systèmes externes peuvent échouer de manière imprévisible. Votre logique d'intégration doit être résiliente et capable de gérer les erreurs réseau, les délais d'expiration et les réponses API inattendues.
• Retourner des Erreurs Significatives : Lors de la construction d'API entrantes, fournissez des messages d'erreur clairs et significatifs à vos consommateurs. Utilisez les codes de statut HTTP standard pour indiquer la nature de l'erreur.
• Tout Enregistrer : La journalisation complète est votre meilleur ami pour déboguer les problèmes d'intégration. Enregistrez toutes les requêtes et réponses API, ainsi que toutes les erreurs qui se produisent.

4.3. La Performance Compte​

• Les Délais d'Expiration sont Cruciaux : Ne laissez pas votre application bloquer en attendant une API externe lente. Implémentez des délais d'expiration agressifs et ayez un plan de secours pour quand une API ne répond pas.
• Mettre en Cache Quand Possible : Si vous demandez fréquemment des données qui ne changent pas souvent, envisagez de mettre en cache les réponses pour améliorer les performances et réduire la charge sur le système externe.
• Surveiller les Performances : Gardez un œil sur les performances de vos intégrations. Les outils de surveillance de Softyflow peuvent vous aider à identifier les goulots d'étranglement et les API lentes.

4.4. Documentation Claire​

• Documenter Vos API : Si vous construisez des API entrantes, fournissez une documentation claire et complète pour vos consommateurs.
• Fournir des Exemples : Incluez des exemples de code pour faciliter le démarrage des développeurs avec votre API.
• Versionner Vos API : Si vous devez apporter des modifications importantes à une API entrante, envisagez de créer une nouvelle version pour éviter de perturber les intégrations existantes.

En suivant ces meilleures pratiques, vous pouvez construire des intégrations sécurisées, fiables et performantes.

5. Conclusion et Prochaines Étapes​

Vous avez maintenant une compréhension complète des puissantes capacités d'intégration disponibles dans Softyflow. De la simplicité low-code des Sources de Données Externes à la flexibilité orientée développeur des scripts axios et au potentiel entrant des APIs Entrantes, vous disposez des outils nécessaires pour connecter votre application à n'importe quel système ou service.

Alors que vous poursuivez votre parcours avec Softyflow, voici quelques prochaines étapes recommandées :

• Conception d'Interface Web : Commencez à créer des interfaces utilisateur qui exploitent les données de vos intégrations nouvellement configurées.
• Conception de Processus : Incorporez vos intégrations dans vos processus métier pour automatiser les workflows qui s'étendent sur plusieurs systèmes.
• Intégration de Base de Données : Apprenez à combiner les données de votre propre base de données avec les données d'API externes.
• Reporting : Créez des rapports et tableaux de bord perspicaces qui combinent les données de toutes vos sources intégrées.
• Test et Déploiement : Comprenez comment tester et déployer efficacement vos applications intégrées.
• Surveillance et Exécution : Apprenez à surveiller la santé et les performances de vos intégrations en production.

Pour plus d'expérience pratique, nous recommandons vivement nos tutoriels pas à pas. Et pour des informations détaillées sur des fonctionnalités spécifiques, assurez-vous de consulter nos guides de référence pour les APIs, EDS et la documentation SDK.