L'activité Service web intègre un service web dans un workflow et permet à celui-ci d'échanger des données avec d'autres systèmes.
Vous pouvez par exemple utiliser un service web dans un workflow pour créer, mettre à jour ou supprimer des informations dans des applications tierces. Le service web peut également récupérer des données depuis des applications métier telles qu'un CRM ou une comptabilité, et les mettre à disposition d'un workflow DocuWare. Les workflows DocuWare prennent en charge l'intégration des services web REST et SOAP.
Remarque : ajoutez d'abord un service web
Ajoutez d'abord le service web à votre organisation DocuWare. Avant d'intégrer un service web dans un workflow, vous devez créer une connexion à ce service dans Configurations DocuWare > Services web.
Voici une vue d'ensemble de la configuration :
Pour ajouter un service web à un workflow, accédez à Configurations DocuWare > Collaboration > Workflow Designer.
Cliquez sur Nouveau workflow ou Modifier pour ouvrir un workflow nouveau ou existant dans le canevas.
Dans la barre latérale gauche, cliquez sur Service web.
Choisissez votre méthode : REST ou SOAP. La configuration des services web REST et SOAP est décrite en détail ci-dessous.
Vous pouvez également créer des sorties conditionnelles pour une activité Service web.
Une fois la configuration terminée, vous devez connecter l'activité Service web aux autres activités du workflow.
.png)
La boîte de dialogue de l'activité Service web dans le Workflow Designer basé sur le web
Service web REST
Vous configurez l'échange de données via un service web RESTful dans un assistant comportant trois onglets : Général, Affectation des données et Codes de statut.
Général : sélectionner un service web
Adresse
Avant de pouvoir utiliser un service web REST dans un workflow, il doit être enregistré dans Configurations DocuWare > Services web. Seuls les services enregistrés apparaissent dans cette section.
Tous les services web REST installés dans votre organisation DocuWare et auxquels vous avez accès sont listés dans la section Général > Adresse.
Service web défini : sélectionnez le service web REST à appeler.
URL du service web : URL du service web REST sélectionné. Ce champ est renseigné automatiquement en fonction de la sélection dans Service web défini et est en lecture seule.
Pour modifier l'URL, mettez à jour l'enregistrement du service web dans Configurations DocuWare > Services web.Format : indiquez le format d'échange des données (JSON ou XML). L'affectation des données diffère selon le format choisi.
Endpoint
Un Endpoint est une URL spécifique du serveur web vers laquelle la requête est envoyée. L'endpoint reçoit les données et définit l'action à exécuter.
L'endpoint par défaut est la racine ou l'URL de base (/). Il s'agit du point d'entrée initial du service web.
Si le service web fournit un fichier de spécification OpenAPI (*.json, .txt, .yml ou *.yaml), vous pouvez l'importer à l'aide du bouton d'importation. Une fois importé, tous les endpoints disponibles sont listés dans la liste déroulante.
Information : DocuWare Platform API par défaut
Lorsque vous utilisez les endpoints d'une spécification OpenAPI, l'API DocuWare Platform API par défaut ou DocuWare E-Invoicing, tous les routes et paramètres requis sont automatiquement préconfigurés en fonction de l'endpoint choisi, ce qui simplifie la configuration de la requête HTTP du service web.
Configuration des paramètres : définir la requête HTTP
Cliquez sur l'URL affichée après l'endpoint sélectionné pour ouvrir l'assistant Configuration des paramètres. Vous y indiquez les informations et les propriétés nécessaires à l'exécution de la requête HTTP, par exemple les routes, les paramètres de requête ou l'en-tête et le corps de la requête. Ces informations sont nécessaires pour fournir au service web toutes les données dont il a besoin.
.png)
Requête
Dans cette section, vous configurez la requête envoyée à l'endpoint. Les options de configuration disponibles dépendent du service web sélectionné et de l'endpoint. Un aperçu de la requête (URL) s'affiche en haut.
Méthode : la méthode HTTP indique ce que vous voulez faire avec l'endpoint. DocuWare prend en charge GET, POST, PUT et DELETE.
Si vous utilisez un fichier de spécification OpenAPI, l'API DocuWare Platform API par défaut ou DocuWare E-Invoicing, la méthode HTTP est définie automatiquement en fonction de l'endpoint choisi.
Routes : utilisez les routes pour cibler précisément les ressources individuelles de l'endpoint.
Si vous utilisez un fichier de spécification OpenAPI, l'API DocuWare Platform API par défaut ou DocuWare E-Invoicing, la route est définie automatiquement en fonction de l'endpoint choisi.
Vous pouvez transmettre des valeurs fixes, des valeurs d'index de document ou encore des variables globales ou système.Paramètres de requête : saisissez ici des paires clé/valeur pour indiquer au service web ce qu'il doit interroger précisément. Les paramètres de requête sont souvent facultatifs et sont utilisés avec les endpoints qui emploient la méthode GET pour filtrer ou affiner un résultat.
Si vous utilisez un fichier de spécification OpenAPI, l'API DocuWare Platform API par défaut ou DocuWare E-Invoicing, les paramètres de requête sont définis automatiquement en fonction de l'endpoint choisi.
Vous pouvez transmettre des valeurs fixes, des valeurs d'index de document ou encore des variables globales ou système.Pièce jointe : indiquez si le document actuellement dans le workflow doit être joint à la requête. Le document peut être joint dans son format d'origine ou au format PDF. Si le document DocuWare contient plusieurs fichiers (agrafés), tous les fichiers sont exportés et joints séparément. La requête HTTP contient alors plusieurs objets fichier.
Cela vous permet, par exemple, d'envoyer un document tel qu'une facture à un service externe.Encodage : indiquez l'encodage des valeurs transmises dans les routes et les paramètres de requête. Selon les valeurs transmises dans votre requête, vous pouvez choisir d'encoder ou non les caractères dans l'URL. Trois options sont disponibles pour l'encodage :
Encoder les caractères spéciaux (recommandé) : tous les caractères spéciaux sont encodés. Par exemple, « AT&T » devient « AT%26T » et « Rapid Transport » devient « Rapid%20Transport ».
Encoder les caractères spéciaux (sauf les caractères d'URL réservés) : (*&^%$#@!:
Tous les caractères spéciaux sauf les caractères d'URL réservés sont encodés. Par exemple, « AT&T » reste inchangé, mais « Rapid Transport » devient « Rapid%20Transport ».
Ne pas encoder les caractères spéciaux : ni les caractères spéciaux ni les espaces ne sont encodés.
L'encodage s'applique à toutes les valeurs spécifiées dans les routes et les paramètres de requête.
En-têtes HTTP
Les en-têtes se trouvent au début de la requête, juste après la ligne de statut. Les en-têtes HTTP sont des paires clé-valeur qui fournissent des métadonnées sur la requête : par exemple, l'expéditeur, le format des données envoyées, l'authentification ou la forme attendue de la réponse du service web — dans les limites fixées par le service web lui-même.
Corps HTTP
Le corps HTTP est la partie de la requête dans laquelle vous envoyez des données (par exemple avec POST ou PUT).
Indiquez les informations et les propriétés nécessaires à l'exécution de l'opération sélectionnée, par exemple le GUID du tampon à appliquer. Ou, si vous créez un nouvel utilisateur, le corps HTTP contient les données utilisateur au format JSON. La validation du corps HTTP s'effectue soit lors de l'envoi, soit automatiquement lors de l'enregistrement de la configuration. Si une partie du contenu est jugée non valide, l'erreur correspondante est mise en évidence et un message approprié s'affiche. La configuration peut également être enregistrée même en cas de problèmes de validation.
Structurez le contenu du corps HTTP à l'aide de valeurs fixes, de données d'index ou de variables globales et système. Notez que même en cas de problèmes de validation, vous pouvez toujours enregistrer la configuration.
Test
Testez la requête à l'aide du bouton Envoyer la requête et examinez la « Réponse » pour vérifier le succès de l'opération. Gardez à l'esprit que vous devez fournir une valeur de test pour chaque variable afin d'exécuter le test. Vous pouvez également indiquer ici un document de test, qui sera inclus dans la requête de test du service web.
Affectation des données : utiliser les données de la requête dans le workflow
Les informations renvoyées par la réponse du service web peuvent être utilisées dans le workflow. Dans Affectation des données, vous indiquez où ces données doivent être stockées dans le workflow. La structure de la réponse est définie par le service web, pas par le workflow DocuWare. Dans le Workflow Designer, vous décidez seulement si et quelles parties de la réponse seront utilisées.
Affectez les valeurs de la réponse à des variables globales ou à des données d'index. Choisissez les valeurs souhaitées directement dans la structure JSON ou XML de la réponse.
Exemple : le service web récupère les détails d'une entreprise depuis le CRM ou des informations complémentaires sur une commande depuis le système ERP.
Si vous souhaitez traiter toutes les entrées renvoyées, remplacez manuellement l'index par un astérisque (*) dans l'indexeur du tableau. Cela permet un traitement complet de toutes les entrées du tableau.
Codes de statut
Les services web REST renvoient ce que l'on appelle un code de statut HTTP après leur exécution. Ce code indique si la requête a abouti ou si une erreur s'est produite.
Voici quelques codes de statut courants :
200 = OK (tout s'est bien passé)
201 = Created (un élément a été créé)
400 = Bad Request (erreur dans les données envoyées)
404 = Not found (ressource introuvable)
500 = Erreur serveur
Si vous activez la fonction Affecter le code renvoyé à une variable de workflow, le code de statut renvoyé sera enregistré dans une variable globale de workflow.
Le code stocké dans la variable peut ensuite être évalué dans le workflow, par exemple pour la gestion des erreurs ou la journalisation.
Gestion des erreurs
Passez à l'onglet Erreurs pour configurer la suite du workflow en cas d'échec de l'appel du service web. Si, par exemple, le service web externe est indisponible, vous pouvez configurer le workflow pour acheminer le document vers une autre action automatisée, telle que l'envoi d'une notification par e-mail demandant la saisie manuelle des informations manquantes.
Choisissez l'une des options suivantes :
Aucune gestion des erreurs : cette option est activée par défaut.
Redémarrer le workflow : le document est automatiquement réacheminé depuis le début à travers les étapes du workflow.
Terminer le workflow : le document est automatiquement acheminé vers la fin du workflow. Toutes les modifications effectuées jusqu'à ce point sont conservées.
Aller à l'étape : cette option ajoute une sortie Erreur à l'activité Affecter des données. Connectez-la à une autre activité pour acheminer manuellement le document du workflow.
Service web SOAP
SOAP (Simple Object Access Protocol) est un protocole de messagerie standardisé qui utilise XML pour l'échange de données. Contrairement à REST, où vous configurez manuellement les méthodes HTTP, les en-têtes, les routes et le corps de la requête, les services web SOAP sont décrits par un fichier WSDL (Web Services Description Language). Le WSDL définit les opérations disponibles, leurs paramètres et le format des données. Le Workflow Designer récupère donc ces informations automatiquement et les présente sous forme d'options sélectionnables.
Après avoir sélectionné Service web SOAP dans l'onglet Méthode, cliquez sur Définir le service web pour ouvrir le panneau de configuration :
Adresse : sélectionner le service web
Avant de pouvoir utiliser un service web SOAP dans un workflow, il doit être enregistré dans Configurations DocuWare > Services web. Seuls les services enregistrés apparaissent dans cette section.
Tous les services web SOAP installés dans votre organisation DocuWare et auxquels vous avez accès sont listés dans la section Général > Adresse.
Service web défini : sélectionnez le service web SOAP à appeler. Chaque service enregistré pointe vers un endpoint WSDL spécifique qui décrit les opérations et les structures de données fournies par le service.
URL du service web : URL de l'endpoint WSDL du service sélectionné. Ce champ est renseigné automatiquement en fonction de la sélection dans Service web défini et est en lecture seule.
Pour modifier l'URL, mettez à jour l'enregistrement du service web dans Configurations DocuWare > Services web.
Méthode : choisir l'opération
La liste déroulante Méthode répertorie toutes les opérations exposées par le service web SOAP sélectionné. Ces opérations sont récupérées automatiquement à partir de la définition WSDL du service.
Sélectionnez l'opération que le workflow doit exécuter. Dans cet exemple, la méthode « DeleteUnsignedDocument » est sélectionnée. Il s'agit d'une opération fournie par le service de signature qui supprime un document non signé. Une fois la méthode sélectionnée, la section Paramètres ci-dessous est mise à jour automatiquement pour afficher les paramètres d'entrée requis par cette opération.
Paramètres : définir la requête HTTP
La section Paramètres affiche les données d'entrée requises par la méthode sélectionnée. Ces paramètres sont définis dans le WSDL et apparaissent automatiquement : vous n'avez pas besoin de les ajouter ou de les supprimer manuellement. Chaque paramètre possède un nom, un type de données et des champs à configurer :
Type de source : détermine d'où provient la valeur. Les sources suivantes sont disponibles :
Index de document : valeur d'un champ d'index du document actuellement dans le workflow.
Valeur fixe : valeur statique que vous saisissez directement.
Variable globale : variable de workflow qui peut être définie et modifiée pendant l'exécution du workflow.
Variable système : valeur prédéfinie fournie par DocuWare, telle que le GUID de l'armoire ou l'ID du document.
Valeur : champ, variable ou valeur fixe spécifique à transmettre. Les valeurs disponibles dans la liste déroulante dépendent du type de source sélectionné.
Dans l'exemple de la capture d'écran ci-dessus, la méthode « DeleteUnsignedDocument » nécessite trois paramètres :
DocId : mappé à l'ID du document depuis l'index de document)
FileCabinetId : mappé à la variable système GUID de l'armoire,
Token : mappé à une variable globale.
Affectation des données : utiliser les données de la réponse dans le workflow
Après son exécution, le service web SOAP renvoie une réponse contenant les données de résultat. La section Affectation des données vous permet de mettre ces données à disposition du workflow en mappant les champs de la réponse à des variables globales.
La structure de la réponse est déterminée par le service web SOAP lui-même et s'affiche automatiquement sous forme d'arborescence repliable. Chaque champ affiche son nom et son type de données. Vous ne configurez pas la structure : vous décidez uniquement quels champs récupérer.
Pour affecter une valeur, sélectionnez une variable globale pour le champ de réponse à utiliser. Les champs non affectés sont ignorés. L'affectation s'effectue automatiquement à l'exécution : à chaque fois que le workflow exécute cette activité, les valeurs de la réponse sont écrites dans les variables globales mappées. Ces variables peuvent ensuite être utilisées dans les étapes suivantes du workflow, par exemple dans des conditions, des notifications ou d'autres activités.
Contrairement aux services web REST, où les données de réponse peuvent être affectées à la fois à des variables globales et à des champs d'index de document, l'affectation des données SOAP prend en charge uniquement les variables globales.
Dans l'exemple de la capture d'écran, la méthode « DeleteUnsignedDocument » renvoie un « DeleteUnsignedDocumentResult » contenant un champ « Message » de type chaîne. Ce champ pourrait être mappé à une variable globale pour récupérer un message de confirmation ou d'erreur du service de signature.
Gestion des erreurs
Passez à l'onglet Erreurs pour configurer la suite du workflow en cas d'échec de l'appel du service web. Si, par exemple, le service web externe est indisponible, vous pouvez configurer le workflow pour acheminer le document vers une autre action automatisée, telle que l'envoi d'une notification par e-mail demandant la saisie manuelle des informations manquantes.
Choisissez l'une des options suivantes :
Aucune gestion des erreurs : cette option est activée par défaut.
Redémarrer le workflow : le document est automatiquement réacheminé depuis le début à travers les étapes du workflow.
Terminer le workflow : le document est automatiquement acheminé vers la fin du workflow. Toutes les modifications effectuées jusqu'à ce point sont conservées.
Aller à l'étape : cette option ajoute une sortie Erreur à l'activité Affecter des données. Connectez-la à une autre activité pour acheminer manuellement le document du workflow.