Guide d'intégration

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

Avant de vous lancer, nous vous recommandons d'avoir une solide compréhension de la configuration de votre 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. Ces connaissances de base vous aideront à tirer le meilleur parti de ce guide.

1. Intégration d'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 il est puissant, configurable et ne nécessite pas l'écriture de code complexe.

1.1. Configuration de l'API EDS​

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

La vue suivante illustre la première étape de la 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 d'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 ventilation 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 d'EDS : C'est un paramètre crucial. En sélectionnant Api, vous débloquez 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 essentiel 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 les 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 autorisations de création, lecture, mise à jour ou suppression, vous pouvez appliquer les politiques de sécurité de votre organisation au niveau de la source de données. Dans cet exemple, nous accordons des autorisations 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 d'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. Chaque point de terminaison représente une action spécifique, telle que la récupération d'une liste d'éléments, la création d'un nouvel élément ou la suppression d'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 des fonctionnalités supplémentaires.

• retrieve : Récupère un seul enregistrement, généralement par son ID unique.
• list : Récupère une collection d'enregistrements, avec prise en charge de la pagination.
• count : Renvoie 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 API EDS Google Calendar.

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 du point de terminaison de l'API.

1.3.1. Personnalisation avancée des requêtes​

Softyflow offre plusieurs moyens de personnaliser la requête sortante pour chaque point de terminaison.

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

L'onglet Script de pré-exécution offre un moyen puissant de personnaliser les requêtes.

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

Les onglets En-têtes et Paramètres offrent 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 la définition du Content-Type ou la transmission de clés d'API.

Lorsque vous écrivez des scripts de pré-exécution ou une autre logique personnalisée, vous avez accès à un riche ensemble de variables de contexte. Ces variables fournissent des informations sur la requête en cours 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 la requête.
• SF_table : Le nom de la table ou de la ressource consultée.
• SF_postData : La charge utile de 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 par lequel trier.
• SF_page : Le numéro de page actuel pour les requêtes paginées.
• SF_direction : La direction du tri (1 pour croissant, -1 pour décroissant).

  

  

1.3.3. Test de vos points de terminaison​

L'une des fonctionnalités les plus essentielles 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 complète de l'API, y compris le code d'état, les en-têtes et le corps. C'est un outil inestimable pour le débogage et la vérification, vous faisant gagner des heures de dépannage.

Le panneau de test montrant une réponse d'API réussie.

1.4. Mettre le tout en œuvre : Utiliser 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​

Dans le 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 flux de travail automatisés.

Appel de l'EDS depuis une action de processus.

1.4.2. Dans les widgets de l'interface web​

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

Les images suivantes montrent comment connecter un widget de tableau à notre EDS API.

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

   

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

2. Mappez les champs de données :

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

1. Sélectionnez la source de données : Source de données : Avant cette étape, vous auriez choisi votre source de données. Il peut s'agir d'une EDS (source de données externe), qui peut ê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 à partir d'une base de données, vous pouvez spécifier le tri, par exemple 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 êtes en train de "mapper" :
   • Le champ de résumé de la réponse de l'API au libellé (le texte que l'utilisateur voit).
   • Le champ id à la valeur (la valeur interne de la sélection).

En bref, 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 de l'API aux 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 offre, Softyflow vous permet d'écrire des scripts d'intégration personnalisés en utilisant la populaire bibliothèque 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, une gestion des erreurs ou des interactions d'API en plusieurs étapes.

2.1. Effectuer votre premier appel d'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 sur 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 montre une simple requête GET pour récupérer un seul élément todo à partir d'une API publique. Le mot-clé await est utilisé pour attendre que la promesse se résolve, et les données de la réponse sont ensuite consignées.

Une simple requête GET 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 attribué par le serveur, est ensuite consigné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 mis en œuvre avec axios.

2.3.1. Jeton porteur​

L'authentification par jeton porteur 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 des 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 porteur dans l'en-tête d'autorisation.

2.3.2. Clé d'API​

Une autre méthode courante consiste à utiliser une clé d'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é d'API en tant que paramètre de requête.

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

2.4. Exemple avancé : Intégration en plusieurs étapes​

La véritable 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 lorsque l'on travaille avec des API modernes.

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

3. API entrantes : Exposer votre application au monde​

Les intégrations sont une voie à double sens. Jusqu'à présent, nous nous sommes concentrés sur la manière dont Softyflow peut consommer des API externes. Mais que se passe-t-il si vous avez besoin que des systèmes externes communiquent avec votre application Softyflow ? C'est là que les API entrantes entrent en jeu.

Cette fonctionnalité puissante vous permet de créer vos propres points de terminaison d'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 le moyen idéal de mettre en œuvre des webhooks, de créer une API publique pour votre application ou de permettre des intégrations avec des systèmes qui ont besoin d'initier un contact avec Softyflow.

3.1. Création de 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ès aux données de la 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 la 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 d'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 de mise en œuvre d'une API​

Une implémentation simple d'une API entrante dans Softyflow est illustrée ici. Le script accède au corps de la requête en utilisant la variable SF_body et le renvoie 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 simple API d'écho qui renvoie le corps de la requête.

3.3. Consommation de votre API entrante​

Une fois votre API créée, vous pouvez l'appeler depuis divers endroits, à la fois à l'intérieur et à l'extérieur de Softyflow.

3.3.1. Depuis Softyflow : L'action InvokeApi​

Le moyen le 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 offre un moyen simple et sans code d'appeler vos API, de leur transmettre des données et de 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 à des 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.

URL 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 attribuant à des groupes d'utilisateurs spécifiques.
• Accès public : Pour les webhooks ou d'autres services accessibles au public, vous pouvez marquer une API comme "publique" pour autoriser l'accès sans authentification.
• Surveillance de l'utilisation : Tous les appels d'API sont journalisés, ce qui vous permet de surveiller l'utilisation, de savoir qui appelle vos API et quand.

3.4.2. Tests d'API intégrés​

Les tests sont un citoyen de première classe dans le module d'API de Softyflow. L'éditeur d'API comprend 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​

La création d'intégrations robustes et fiables nécessite plus que la simple connexion de systèmes. Voici quelques bonnes pratiques à garder à l'esprit lorsque vous travaillez avec l'une des méthodes d'intégration dans Softyflow.

4.1. La sécurité avant tout​

• Validez 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.
• Appliquez 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.
• Utilisez 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.
• Désinfectez les données : Avant de stocker ou de traiter des données provenant de systèmes externes, assurez-vous de les désinfecter pour prévenir les attaques de type cross-site scripting (XSS) et autres.

4.2. Gestion robuste des erreurs​

• Attendez-vous à l'inattendu : Les systèmes externes peuvent tomber en panne 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'attente et les réponses d'API inattendues.
• Retournez des erreurs significatives : Lorsque vous créez des API entrantes, fournissez des messages d'erreur clairs et significatifs à vos consommateurs. Utilisez les codes d'état HTTP standard pour indiquer la nature de l'erreur.
• Journalisez tout : Une journalisation complète est votre meilleur ami lorsqu'il s'agit de déboguer des problèmes d'intégration. Journalisez toutes les requêtes et réponses d'API, ainsi que toutes les erreurs qui se produisent.

4.3. La performance compte​

• Les délais d'attente sont cruciaux : Ne laissez pas votre application attendre une API externe lente. Mettez en œuvre des délais d'attente agressifs et ayez un plan de secours pour quand une API ne répond pas.
• Mettez en cache lorsque c'est 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.
• Surveillez 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​

• Documentez vos API : Si vous créez des API entrantes, fournissez une documentation claire et complète à vos consommateurs.
• Fournissez des exemples : Incluez des exemples de code et des exemples pour faciliter le démarrage des développeurs avec votre API.
• Versionnez vos API : Si vous devez apporter des modifications de rupture à 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 créer 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é axée sur les développeurs des scripts axios et au potentiel entrant des API 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: Intégrez vos intégrations dans vos processus métier pour automatiser les flux de travail 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 des API externes.
• Rapports: Créez des rapports et des tableaux de bord pertinents qui combinent des données de toutes vos sources intégrées.
• Tests 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 une expérience plus pratique, nous vous recommandons vivement nos tutoriels pas à pas. Et pour des informations détaillées sur des fonctionnalités spécifiques, n'oubliez pas de consulter nos guides de référence pour les API, les EDS et la documentation du SDK.