Altova FlowForce Server 2024 Advanced Edition

Cet exemple illustre comment créer une tâche FlowForce Server qui prend en tant qu'entrée plusieurs fichiers XML et retourne en guise de sortie plusieurs fichiers PDF. La tâche FlowForce Server invoquera aussi bien MapForce Server (pour générer la sortie XML depuis plusieurs fichiers XML de source) et StyleVision Server (pour convertir la sortie XML en PDF).

Cet exemple exige une compréhension de base pour le fonctionnement des mappages MapForce et des transformations StyleVision. Si vous ne connaissez pas du tout StyleVision et MapForce, nous vous recommandons de lire tout d'abord les chapitres "Tutoriels" de la documentation MapForce et StyleVision, respectivement :

•Tutoriel Démarrage rapide (MapForce)

•Tutoriel Démarrage rapide (StyleVision)

Prérequis

•Licences requises :

oÉdition MapForce Enterprise ou Professional. Cet outil vous permet de concevoir une transformation de mappage (fichier .mfd) qui convertit (dans cet exemple) des fichiers XML d’un schéma vers l’autre.

oÉdition MapForce Server ou MapForce Server Advanced. Cet outil vous permet d’exécuter le mappage sur un serveur, en tant que tâche.

oÉdition StyleVision Enterprise ou Professional. Cet outil vous permet de concevoir une feuille de style (fichier .sps) qui convertit un fichier d’entrée XML dans un fichier PDF.

oStyleVision Server. Cet outil vous permet d’exécuter la transformation sur un serveur, en tant que tâche.

oFlowForce Server. Cet outil donne les moyens d’exécuter les transformations ci-dessus en tant que tâche programmée ou à la demande, modifier les entrées le cas échéant, et surveiller l’exécution.

•Les services FlowForce Web Server et FlowForce Server doivent écouter les adresse réseau et port configurés.

•Votre compte d'utilisateur FlowForce Server comporte des permissions vers un des conteneurs (par défaut, le conteneur /public est accessible à tout utilisateur authentifié).

•La tâche créée dans cet exemple génère plusieurs fichiers sur le disque. C’est pourquoi, sur le système d’exploitation sur lequel FlowForce Server est exécuté, vous devez posséder des droits pour créer des fichiers dans certains répertoires. Cet exemple utilise le répertoire C:\FlowForceExamples\GeneratePdfs.

Fichiers de démo utilisés

Cet exemple utilise les fichiers d'exemple suivants, que vous trouverez sous : <Documents>\Altova\MapForce2024\MapForceExamples.

•MultipleInputToMultipleOutputFiles.mfd (le fichier de mappage MapForce)

•PersonListWithGrouping.sps (le fichier de transformation StyleVision)

•Nanonull-Branch.xml, Nanonull-HQ.xml (les fichiers d'entrée XML)

Que fait le mappage MapForce ?

Comme illustré ci-dessous, le mappage consiste en un composant de source (Altova_Hierarchical), un composant cible (PersonList), et plusieurs fonctions intégrées intermédiaires MapForce utilisées pour générer des strings divers à rédiger dans la sortie.

MultipleInputToMultipleOutputFiles.mfd

Le mappage prend, en guise d'entrée tout fichier XML qui commence avec "Nanonull-", depuis le répertoire <Documents>\Altova\MapForce2024\MapForceExamples . Cela est défini dans les paramètres de composant MapForce source (dans MapForce, cliquer avec la touche de droite dans l'en-tête du composant Altova_Hierarchical illustré ci-dessous, et sélectionner Propriétés depuis le menu contextuel). Veuillez noter que "Input File" est configuré sur Nanonull-*.xml, où l'astérisque est un caractère générique. Littéralement, l'entrée est tout fichier dont le nom débute avec "Nanonull-" et qui a l'extension .xml.

Le composant cible, PersonList, est configuré pour générer des noms de fichier dynamiquement sur la base du nom de fichier du fichier de source XML. Cela est défini en cliquant avec la touche de droite sur la touche File/String en haut du composant, puis en sélectionnant l'option de menu Utiliser les noms de fichier dynamiques fournis par le mappage. La connexion au nœud "File <dynamic>" signifie qu'un nouveau fichier sera créé pour chaque valeur dans la source. La fonction remove-folder a uniquement pour but de récupérer le nom de fichier (sans le dossier) depuis le chemin de source. Il est ensuite passé en tant que valeur à la fonction concat supérieure, qui génère un string tel que Persons-<Source filename>.

La deuxième fonction concat génère un string comme Generated by Altova... suivi par le chemin complet vers le fichier de mappage. Le résultat est écrit en tant que commentaire dans le fichier XML cible.

La troisième fonction concat utilise la sortie de la fonction count pour générer un string qui indique combien d'entrées de personnes ont été mappées depuis la source. Une fois de plus, le résultat est écrit en tant que commentaire dans le fichier cible XML.

Enfin, la connexion au nœud Person cible copie les données des personnes depuis la source vers la cible. Une connexion individuelle existe pour chaque élément enfant de Person qui doit être mappé.

De plus, le composant cible est configuré pour convertir la sortie générée en PDF, pour chaque fichier XML généré. Cliquer avec la touche de droite sur l'en-tête du composant cible, choisir Propriétés, et notez que le champ de texte StyleVision Power StyleSheet file spécifie un chemin relatif à une feuille de style StyleVision .sps. Cette dernière effectue la conversion réelle de XML en PDF (voir ci-dessous).

Pour obtenir un aperçu de ce mappage directement dans MapForce, cliquer sur l'onglet Sortie disponible dans le volet de mappage. Pour un aperçu du résultat PDF de la transformation StyleVision, cliquer sur l'onglet PDF. Vous remarquerez que plusieurs XML (ou PDFs, respectivement) sont générés dans le volet Sortie, par exemple :

À ce niveau, il est recommandé d'enregistrer un des deux fichiers XML de sortie sur le disque (puisque, par défaut, MapForce génère des fichiers temporaires). Le fichier fonctionnera en tant que modèle (working XML) si vous souhaitez ouvrir et tester la feuille de style StyleVision dans StyleVision (voir section suivante). Pour enregistrer un fichier de sortie, tout d'abord cliquer sur l'onglet Sortie, puis, dans le menu Sortie, cliquer sur Enregistrer fichier de sortie.

Que fait la transformation StyleVision?

Exécuter StyleVision et ouvrir le fichier de transformation PersonListWithGrouping.sps. Ne pas oublier que ce fichier se trouve dans le même répertoire que le mappage MapForce discuté plus haut et qu'il est référencé par le composant cible MapForce.

PersonListWithGrouping.sps

La feuille de style StyleVision .sps illustrée ci-dessus utilise un seul XML en tant que source et crée un document PDF depuis cet XML. Le document PDF consiste en un en-tête ("h2"), un paragraphe d'introduction, une table remplie dynamiquement et un paragraphe de fin. L'en-tête et le paragraphe d'introduction contient du texte statique alors que la table et le paragraphe de fin sont remplis à partir des nœuds du fichier XML de source, comme indiqué par les onglets de wrapping.

Pour consulter cette transformation directement dans StyleVision, suivre les étapes suivantes :

1.Dans le volet Aperçu de design, à côté de XML de travail, cliquer sur .

2.Choisir Attribuer le fichier de travail XML et chercher le fichier de sortie XML enregistré précédemment depuis MapForce (voir la section précédente).

3.Cliquer sur l’ongletPDF.

Chose importante, la feuille de style .sps est indépendante du nom ou de l'origine du fichier XML de source ; elle traite simplement le fichier XML fournit en tant qu'entrée (tant qu'elle est conforme au schéma XML spécifié), et créé un PDF à partir de cela. Afin d'automatiser cette feuille de style, pour qu'elle génère plusieurs fichiers PDF, il faudra déployer vers FlowForce Server, comme indiqué ci-dessous.

Déployer les fichiers vers FlowForce Server

Jusqu'à présent, vous vous êtes familiarisé avec l'objectif des mappages MapForce et des transformations StyleVision utilisés dans cet exemple. Pour plus d'informations concernant la conception de mappages MapForce et de feuilles de style StyleVision, veuillez vous référer à la documentation de ces produits (https://www.altova.com/fr/documentation.html).

Pour rendre possible l'automatisation, les deux fichiers doivent être déployés sur FlowForce Server. Comme spécifié dans la section "Conditions préalables" ci-dessus, FlowForce Server doit être mis sous licence et être en cours, et MapForce Server et StyleVision Server doivent tous les deux être mis sous licence et être en cours d'exécution sous la gestion de FlowForce Server. Sur Windows, vous pouvez utiliser la commande verifylicense de chaque produit de serveur pour vérifier le statut de sa licence. Dans d'autres systèmes d'exploitation, l'exécution de la tâche échouera et sera accompagnée d'un message d’erreur si la licence n'est pas trouvée ou n'est pas valide.

Pour déployer la feuille de style StyleVision sur FlowForce Server :

1.Dans le menu Fichier, cliquer sur Déployer sur FlowForce. (Si cette commande est grisée, passer d’abord à l’onglet Design.)

2.Un message vous informant que le fichier de design sera enregistré en tant que PXF (Portable XML Form), cliquer sur OK.

3.Lorsque vous serez invité à sélectionner les fichiers désirés à inclure dans le package déployé, laissez les paramètres par défaut tels qu'ils sont. Bien que seuls le PDF est généré dans cet exemple, l'inclusion d'autres sorties vous économisera du temps plus tard si vous changez d'avis et que vous souhaitez générer des formats supplémentaires comme un HTML et RTF.

4.Une fois invité à le faire, remplissez les détails de connexion vers le FlowForce Web Server. Pour plus de simplicité, dans l'image ci-dessous, la transformation est déployée sur la machine locale sur le port 8082, par un HTTP simple. Il est également possible de spécifier une adresse à distance et de déployer les fichiers par une connexion chiffrée SSL, si FlowForce Web Server a été configuré pour accepter ce type de connexion voir Définir les paramètres de réseau. Les valeurs utilisateurs et mot de passe sont illustrées pour le compte racine FlowForce ; néanmoins, tout autre compte d'utilisateur FlowForce peut aussi être utilisé, s'il possède la permission d'écrire des données dans le chemin spécifié. Dans cet exemple, la case à cocher Ouvrir navigateur pour créer une nouvelle tâche a été laissé vide délibérément parce que la création et la configuration de la tâche seront des étapes séparées comme discuté ci-dessous.

5.Dans un soucis d’homogénéité avec les autres exemples, il est recommandé d’utiliser le chemin de cible/public/Examples/PersonListWithGrouping.transformation.

Pour déployer le mappage MapForce sur FlowForce Server :

•Dans le menu Fichier, cliquez Déployer sur FlowForce Server. Remplir les détails de connexion illustré ci-dessous de la même manière que dans l'exemple abordé ci-dessus pour StyleVision. Également dans un souci d’homogénéité avec les autres exemples, il est recommandé d’utiliser le chemin de cible/public/Examples/PersonListWithGrouping.transformation.

Une fois que les fichiers ont été déployés avec succès, les entrées correspondantes apparaîtront dans le conteneur FlowForce spécifié (dans ce cas, "/public/Examples") lorsque vous vous connectez à FlowForce Server :

Veuillez noter que les entrées ci-dessus ne sont pas encore des tâches ; elles sont maintenant des fonctions FlowForce à partir desquelles des vraies tâches doivent encore être créées, comme indiqué ci-dessous.

Créer et configurer la tâche FlowForce

Maintenant que le mappage MapForce et la transformation StyleVision ont été déployés sur FlowForce Server, ils peuvent être utilisés pour créer la tâche requise, comme suit :

1.Se rendre dans le conteneur /public/Examples FlowForce, et cliquer sur la fonction MultipleInputToMultipleOutputFiles.mapping déployée précédemment. Veuillez noter que le composant de source du mappage MapForce discuté au tout début de cet exemple est à présent devenu un paramètre d'entrée de la fonction FlowForce. De même, il a une valeur de défaut qui est le chemin de l'instance des fichiers XML traités par le mappage. Cette valeur peut être surmontée si nécessaire. Le paramètre "Working-directory" a été ajouté automatiquement par FlowForce ; son rôle sera clarifié dans les étapes suivantes.

2.Cliquez sur Créer la tâche.

3.Saisir un nom et en option une description pour la tâche que vous créez.

4.Configurer la partie "Execution Steps" de la tâche comme indiqué ci-dessous.

5.Sous "Service", choisir la case à cocher "Rendre cette tâche disponible via HTTP..." et saisir le nom du service Web qui déclenchera la tâche à la demande, par exemple "GeneratePdfsService". Isi vous préférez exécuter la tâche en tant qu’une tâche programmée, ou en tant qu’un déclencheur de système de fichier, définir les déclencheurs appropriés (voir Gérer les déclencheurs).

6.Sous "Identifiants", saisir le nom d'utilisateur et le mot de passe du compte d'utilisateur du système d'exploitation (la tâche sera exécutée en tant que cet utilisateur). Veillez à ne pas confondre ce mot de passe avec le mot de passe de l’interface d’administration FlowForce Web (voir aussi Identifiants).

7.Cliquez sur Enregistrer.

Pour comprendre comment comment la tâche fonctionne réellement, examinons la section "Étapes d'exécution" de la tâche. La première étape d'exécution appelle le mappage déployé précédemment. Il cherche tout fichier XML commençant avec "Nanonull-" dans le répertoire de travail. Dans cet exemple, le répertoire de travail est C:\FlowForceExamples\GeneratePdfs.

La sortie retournée par la première étape d'exécution représente les données retournées par le mappage. Il a été explicitement nommé output, afin de le rendre possible pour y référer dans une étape suivante.

La deuxième étape de cette tâche est une étape "for-each". Veuillez noter que l'étape "for-each" utilise une expression FlowForce results(output) pour obtenir l'accès pour les données retournées par la première étape (c'est à dire, la sortie retournée par le mappage). Spécifiquement, l'appel d'expression appelle la fonction results() qui prend en tant qu'argument la sortie retournée par l'étape précédente, voir aussi Fonctions de résultat d'étape. Pour une introduction aux expressions FlowForce, voir Expressions FlowForce.

L'étape "for-each" consiste en deux étapes d'exécutions plus petites :

1.La première étape appelle la fonction intégrée /system/compute pour convertir la sortie de mappage dans un fichier réel (nommé génériquement file). Chose importante, la sortie de l'expression results(output) est un stream, pas un fichier. Si le mappage retourne plusieurs sorties (comme dans ce cas), la sortie de mappage représente une séquence de streams. Pour cette raison, une fonction d'expression FlowForce (as-file) est utilisée pour convertir le stream actuel (celui en cours d'itération) dans un vrai fichier.

2.La seconde étape appelle, pour chaque stream itéré, la transformation StyleVision déployée précédemment. Concrètement, avec chaque itération, StyleVision Server est appelé, un fichier XML est fourni en tant qu'entrée et un fichier PDF est retourné en tant que sortie. L'expression FlowForce {filename(file)}.pdf crée le nom de fichier PDF réel sur le disque. Cette opération a lieu dans le répertoire de travail spécifié par le paramètre"Working-directory".

Exécuter la tâche

Pour préparer les données d’entrée pour la tâche, copier le fichier Nanonull-Branch.xml et Nanonull-HQ.xml depuis <Documents>\Altova\MapForce2024\MapForceExamples vers le répertoire de travail (C:\FlowForceExamples\GeneratePdfs). Ainsi, la première étape de la tâche recoit des fichiers XML d’entrée pour lire des données lorsque la tâche est exécutée.

Pour exécuter la tâche, suivez l’une des étapes suivantes :

•Se rendre sur Accueil, puis cliquer sur Afficher tous les déclencheurs et les services actifs. Ensuite, cliquer sur l’URL de la tâche affichée dans la colonne "Info ».

•Saisir http://127.0.0.1:4646/service/GeneratePdfsService dans la barre d'adresse du navigateur. Noter que cette URL fonctionne uniquement si le service FlowForce Server écoute l’adresse d’hôte par défaut et le nom de port. Si vous avez défini d’autres paramètres d’hôte et de port dans la Page de Configuration, modifier l’adresse.

•Si vous définissez Ile champ optionnel Nom d’hôte du FlowForce Server depuis la Page de configuration, vous pouvez exécuter l'appel de service Web directement depuis la page de configuration de la tâche, en cliquant sur la touche adjacente à la case à cocher Rendre cette tâche disponible via HTTP. Sinon la touche ne sera pas affichée.

Lorsque vous êtes invité à accéder au service Web, fournissez les mêmes identifiants que vous utilisez pour vous connecter à FlowForce Server.

Si l’exécution de la tâche est réussie, les fichiers PDF générés par la tâche seront disponibles dans le répertoire de travail C:\FlowForceExamples\GeneratePdfs. Le navigateur affiche "Cannot output the job" même dans le cas d'une exécution réussie (cela est attendu puisque la tâche produit des fichiers PDF qui ne peuvent pas être des sorties pour le navigateur). Si la tâche ne peut pas être exécutée pour une raison quelconque, le navigateur affichera un message "Service execution failed". Dans ce cas, vérifier le journal d'erreur de la tâche. Pour résoudre les problèmes, vous devrez éventuellement vérifier à nouveau toutes les conditions préalables regroupées en haut de cette page.