Personnalisation des workflows dans Therefore™ Online

Configuration de la tâche « Appeler une fonction » dans Therefore™ Online

La tâche « Appeler une fonction » permet de personnaliser Therefore™ Online. Vous pouvez l'utiliser comme toute autre tâche de workflow automatique. Lorsque la tâche est exécutée, une requête POST HTTP(S) est envoyée à l'URL spécifiée. Cette « URL de requête » est l'unique champ obligatoire de la configuration.

Si besoin est, vous pouvez spécifier une « clé de fonction » qui est transmise dans l'en-tête de la requête HTTP(S) en tant que « x-functions-key ». Si elle est configurée, cette clé est utilisée à des fins d'autorisation par la fonction Azure, qui bloque toute requête qui ne la fournit pas. L'utilisation de HTTPS est facultative, mais fortement recommandée, en particulier lors de l'envoi d'une clé de fonction Azure. Les « paramètres de fonction personnalisés » sont également facultatifs.

Pour en savoir plus sur la fonction d'autorisation, consultez ce didacticiel Microsoft

Vous pouvez régler le nom et la valeur des paramètres sur toute valeur appropriée, qui sera utilisée au sein de la fonction appelée. Ils sont convertis en objet JSON et transmis à la fonction sous la forme « TheSettings ». Les noms de paramètre doivent être uniques et non vides.

Si vous utilisez cette fonctionnalité dans une installation locale, il est recommandé de configurer l'URL de Web API dans les paramètres du serveur. Si tel n'est pas le cas, le paramètre « TheWebAPIUrl » transmis à la fonction est vide.

Structures d'« Appeler une fonction » au sein d'un système Therefore™ Online

Le diagramme suivant illustre les interactions entre les différents composants.

Lorsque la tâche « Appeler une fonction » est exécutée dans le moteur de workflow Therefore™, une requête POST HTTPS est envoyée à la fonction. Si l'appel aboutit, la fonction appelée est exécutée et appelle probablement Therefore™ Server à l'aide de Web API pour récupérer des documents, des données d'index ou toute autre information complémentaire requise.

La fonction appelée peut être une fonction Azure, un service Web ou tout code exécutable capable de répondre à une requête POST HTTPS. Il est toutefois nécessaire que la fonction appelée renvoie un objet JSON contenant la chaîne « TheError » et soit la valeur booléenne « TheRoutingDone », soit l'entier « TheRetryAfterMin ». Si une fonction a été développée par Therefore™, elle peut être hébergée dans l'abonnement Azure de Therefore™ Online.

Pour raisons de sécurité, les fonctions développées par les clients doivent s'exécuter dans leur propre abonnement Azure ou dans leur infrastructure. Comme indiqué dans le diagramme, toutes les connexions entre Therefore™ et la fonction appelée ne sont que des requêtes POST HTTPS et des appels (Web) API. Aucun code client n'est directement exécuté par le service du serveur, et aucun code client ne s'exécute au sein de l'environnement Therefore™ Online. Toutes les permissions doivent être vérifiées normalement pour les appels Web API. Le jeton d'accès fourni avec la requête HTTPS se limite à l'instance de workflow en cours uniquement. En raison de cette architecture, l'utilisation de workflows personnalisés dans Therefore™ Online est sécurisée.

Écriture d'une tâche « Appeler une fonction »

La fonction appelée peut être une fonction Azure, un service Web ou toute application accessible publiquement et capable d'être déclenchée par une requête HTTPS. L'unique élément obligatoire correspond aux « paramètres de retour » suivants que la fonction doit envoyer sous forme de réponse JSON :

• TheError : valeur de chaîne obligatoire. Si la chaîne n'est pas vide, elle s'affiche dans l'historique du workflow. L'instance est marquée comme erronée, à moins qu'une nouvelle tentative ultérieure soit demandée.

• TheRetryAfterMin : valeur entière facultative. Permet de demander une nouvelle tentative à Therefore™.

Si elle est réglée sur une valeur supérieure à zéro, la tâche « Appeler une fonction » se comporte comme une tâche « Attendre » et envoie une nouvelle requête après l'intervalle de temps (approximatif) exprimé en minutes spécifié. Si la valeur « TheError » est définie, elle est traitée comme un avertissement et l'instance de workflow n'est pas marquée comme erronée.

• TheRoutingDone : valeur booléenne obligatoire, à moins que la valeur « TheRetryAfterMin » ne soit spécifiée.

Vous pouvez la régler sur « true » pour indiquer que l'acheminement de l'instance de workflow a déjà été effectué par la fonction à l'aide de la fonction Web API « FinishCurrentWorkflowTask ». Si elle est réglée sur « false », Therefore™ achemine l'instance de workflow vers la tâche suivante. Si vous spécifiez « TheRetryAfterMin », l'acheminement n'est pas encore exécuté et, dans ce cas de figure, le paramètre est donc facultatif. À chaque appel de fonction, Therefore™ envoie les paramètres suivants à la fonction sous forme de jeton JSON avec la requête HTTPS :

• TheWebAPIUrl : contient le paramètre de serveur « URL Web API », que vous pouvez configurer sur l'onglet « XML Web Service » ou dans les paramètres avancés. Ce paramètre est déjà configuré correctement si vous utilisez Therefore™ Online, mais peut rester vide s'il n'est pas configuré.

• TheTenant : nom du locataire en cours. Ce paramètre est vide si le système n'utilise pas plusieurs locataires.

• TheAccessToken : jeton JWT que vous pouvez utiliser pour vous connecter à Therefore™ à l'aide de Web API.

Le jeton est configuré de sorte à permettre à l'utilisateur associé à « $TheWFSystem » d'accéder au document ou au dossier relatif à l'instance de workflow en cours, ainsi qu'à l'instance de workflow et au jeton en cours. Avec les permissions dont il dispose, il peut modifier le document associé, le dossier ou les documents associés au dossier. Les permissions dont il dispose lui permettent également d'autoriser l'acheminement de l'instance de workflow vers une autre tâche. Il n'est pas autorisé à créer des documents ou des dossiers ni à exécuter des requêtes. Il n'est pas non plus autorisé à supprimer le dossier ou le document principal associé à l'instance de workflow, ni l'instance de workflow en tant que telle.

• TheInstanceNo : numéro de l'instance de workflow en cours.

• TheTokenNo : numéro de jeton de l'instance de workflow en cours.

• TheCaseNo : numéro du dossier associé à l'instance de workflow. Ce paramètre est réservé aux workflows associés aux dossiers.

• TheDocNo : numéro du document principal associé à l'instance de workflow. Ce paramètre est réservé aux workflows associés aux documents.

• TheSettings : objet JSON (transmis sous forme de chaîne) de tous les « paramètres de fonction personnalisés » configurés.

Cet objet peut être vide ou utilisé pour transmettre d'autres paramètres à la fonction appelée. Vous pouvez sélectionner le nom et la valeur de votre choix pour chaque paramètre, mais les noms doivent être uniques conformément aux spécifications JSON. Toutes les valeurs sont traitées comme des valeurs de chaîne et doivent être converties dans un autre type au sein de la fonction, si besoin est.

Si vous configurez une clé de fonction associée aux fonctions Azure, la requête HTTPS l'inclut en tant que « x-functions-key » dans l'en-tête de la requête.

Toute information complémentaire requise doit être récupérée à l'aide de Therefore™ Web API, soit à l'aide du jeton JWT fourni, soit en indiquant un nom d'utilisateur et un mot de passe si d'autres droits sont nécessaires. Si des fonctions Azure sont utilisées, les informations de connexion peuvent être indiquées dans les paramètres de l'application sous la forme « WebAPIUser » et « WebAPIPassword ». Si ces paramètres ne sont pas définis, la fonction utilise le jeton JWT par défaut.

Lorsque vous écrivez une fonction, veillez à envoyer une réponse en moins de 4 minutes, sous peine que l'appel de fonction dépasse le délai imparti. Envisagez également d'utiliser le paramètre « TheError » pour renvoyer toute exception interceptée, afin de faciliter l'identification du problème.

Restrictions relatives à la personnalisation

Si des fonctions Azure sont utilisées, Azure impose certaines restrictions (lors du chargement des dépendances, en raison de l'environnement PaaS (Platform as a Service) ou du temps d'exécution (délai HTTPS de 230 secondes), par exemple). D'autres implications sont par ailleurs liées à l'exécution de votre code dans Azure.

Référence externe - Délai imparti à l'application de fonction

Pour contourner la restriction associée au délai imparti, écrivez une fonction asynchrone qui envoie une requête de nouvelle tentative à Therefore™. L'exécution peut ainsi continuer dans une tâche en arrière-plan distincte et le résultat/la réponse peut être renvoyé(e) à Therefore™ lorsque la requête de nouvelle tentative suivante est déclenchée.

En raison des restrictions relatives à la dépendance dans Azure, il est impossible d'utiliser Therefore™ API. Vous devez donc utiliser Web API. Pour contourner cette restriction, exécutez la fonction HTTPS déclenchée sur un ordinateur hébergeant une installation Therefore™. L'unique impératif à respecter dans ce cas de figure est que l'ordinateur doit être accessible depuis l'extérieur.