Managing workflows - The fundamentals

Introduction

Workflows make up the ONYX Server execution engine. A Workflow is defined as a set of conditions and configurable commands, run as a new file is received by input connectors (Scanfolder robots, listening server, entry point, or Web Service query). Commands are processed sequentially which means the second command is processed once the first one was processed correctly, and so on until the end of the Workflow.

A Workflow is defined graphically by several command objects, conditions and/or parameters connected together. Its name is unique and it must be associated with at least one connector to be active.

Workflows are saved on disk in XML files in the workflow sub-folder of the rule folder specified by the RULES_PATH configuration variable.

The administration and Workflow configuration pages are accessible from the ONYX Server Web interface using the Administration Menu, go to Managing Workflows, or use the direct link: http://127.0.0.1:8004/JS_Common/workflow/index.html

Tip: Firefox is the recommended browser for a better user experience.

Configuration

A new WORKFLOW section is added to the ONYX Server configuration file which contains configuration parameters for the Workflows execution engine and for the Web Service features (SOAP_*):

Name	Meaning / Example
SOAP_DEBUG	Activates verbose mode for Web Services On / Off (by default)
SOAP_PATH_TEMP	Local path to access temporary files E:\MappingWindows\Temp\HTTPServer
SOAP_PATH_LOG	Local path to access the logs E:\MappingWindows\Temp\HTTPServer
SOAP_LOCAL_URL	Local path to the shared folder (file exchanges) http://127.0.0.1:8004/shareFolder
SOAP_DOCUMENT_URL	Remote path to the shared folder (file exchanges) http://127.0.0.1:8004/shareFolder
SOAP_LOCATION	Remote path of the Mapping Web Services engine http://127.0.0.1:8004/cgi-bin/mapsoapserver.exe
SOAP_HOST_PROXY	IP address or DNS name of the Proxy server (if needed)
SOAP_PORT_PROXY	Connection port to the Proxy server (if needed)
USE_NEW_RULES	Activates the Workflows engine or returns to the v6 engine On (by default) / Off
MAIL_SERVER	IP address or DNS name of the SMTP server (Mail commands) outlook.office365.com
MAIL_DOMAIN	Domaine name of the outlook.com SMTP server
MAIL_PORT	Connection port of the SMTP 587 server
MAIL_LOGIN	Login ID for the SMTP server
MAIL_PASSWORD	Password for the previous ID
MAIL_FROM	Default sender's address
TRACKING_SERVERADDRESS	IP address of the tracking PostGreSQL 127.0.0.1 database
TRACKING_SERVERPORT	Connection port to the tracking 5432 database
TRACKING_SERVERUSER	Login ID for the tracking database
TRACKING_SERVERPASSWORD	Password for the previous ID
TRACKING_SERVERBASENAME	Name of the tracking database tracking
TRACKING_LIB_PATH	Path of the PostGreSQL executables C:\Program Files\PostgreSQL\9.0\bin
TRACKING_SERVERSCHEMA	Schema of the tracking database public
DEFAULT_ADMINISTRATOR_RESPONSE	Chemin d’un fichier HTML de réponse par défaut (commandes Web Interactivity)
DEFAULT_ADMINISTRATOR_RESPONSE_HEADER	Type (content-type) de la réponse par défaut text/html
DEFAULT_RESPONSE_BODY	Chemin d’un fichier HTML de corps de réponse par défaut (commandes Web Interactivity)
DEFAULT_FILE_TYPE	Chemin d’un fichier HTML d’entête de message par défaut (commandes Web Interactivity)
DEFAULT_MAIL_BODY	Chemin d’un fichier HTML de corps de message par défaut (commandes Web Interactivity)
PATH_CONFIG_CUSTOM_ACCESS	Chemin des préférences utilisateurs d’affichage (MOM 2.0) E:\MappingWindows\Settings\configCustomAccess
PATH_DJDE	Chemin des ressources DJDE (conversions Xerox) E:\MappingWindows\Temp\DJDE
RESOLVE_PERPAGE	Nombre de lignes par page pour l’affichage des tables de résolution 25
MAP_CURRENT_DATE	Contrôle de syntaxe pour la récupération de la date courante %d/%m/%Y
MAP_CURRENT_TIME	Contrôle de syntaxe pour la récupération de l’heure courante %H:%M:%S
MAP_CURRENT_TIMESTAMP	Contrôle de syntaxe pour la récupération de date et heure courante %d-%m-%Y_%H%M%S

Toolbar

• Créer un nouveau Workflow. Saisir un nom pour le Workflow, l’extension .rules.xml est automatiquement ajoutée.
• Ouvrir un Workflow. Sélectionner un Workflow dans la liste.
• Sauvegarder le Workflow actif.
• Sauvegarder le Workflow actif sous un autre nom.
• Supprimer le Workflow actif.
• Insérer une condition dans le Workflow actif. La nouvelle condition sera ajoutée après la boite sélectionnée.
• Insérer une commande dans le Workflow actif. La nouvelle commande sera ajoutée après la boite sélectionnée.
• Insérer un paramètre dans le Workflow actif. Le nouveau paramètre sera ajouté après la boite sélectionnée.
• Redessiner le Workflow actif = permet de redessiner graphiquement le Workflow : alignements des boîtes, des liens, etc…
• Dupliquer un objet = permet de dupliquer, à l’identique (nom, paramètres, etc.) l’objet sélectionné, sans ses liens.
• Gérer les tables de résolution= permet de créer, modifier et supprimer des tables de résolutions

Creating a new workflow

Click on the icon and name the Workflow (here called Invoices) then, validate.

The new Workflow is displayed in the editing window with a first box which corresponds to the starting point of the processing sequence:

Note: to import a Workflow, copy it under C:\ProgramDta\M-Processing Server\Settings\rules\workflow

To view the imported Workflow, Go to Menu->Administration Menu->Managing Workflows, then, click on open.

Adding a parameter

Definition

Parameter objects define the value of a parameter or create a new one. A parameter can then be used as a condition or command. A value can then be reused in several commands, for example, without having to be defined each time.

Create/Edit

To create a new parameter, select the box after which the new parameter needs to be added, then, click on the icon. To edit an existing parameter, double-click on the corresponding box. The editing window opens so as to define the different fields:

Note: A parameter is usually reused later on in the Workflow in a condition or command, sometimes even in another Workflow. Choosing names which correspond to the information conveyed is therefore recommended.

Valorisation

Pour valoriser le paramètre, différentes méthodes sont disponibles par le menu contextuel sur le champ de saisie :

• param = valeur dynamique d’un paramètre d’environnement du système, de M-Processing Server, du Workflow ou du spool d’entrée.
• value = valeur statique saisie par l’utilisateur.
• rulefile = valeur dynamique lue dans un fichier texte ou XML (peut être le spool d’entrée, ou tout autre fichier).
• command = valeur dynamique résultant de l’exécution d’une commande prédéfinie Onyx Server.
• cmd = valeur dynamique résultant de l’exécution d’un script utilisateur.
• SQL = valeur dynamique résultant de l’exécution d’une requête SQL (de type SELECT en l’occurrence).
• resolve =: valeur dynamique résultant de la recherche dans une table de résolution.
• rulefile_multiple = permet de définir en une fois plusieurs paramètres valorisés dynamiquement par des informations contenues dans le même fichier en entrée (en mode XML uniquement.

Suivant le type de champs voulu, une fonction d’aide à la saisie est proposée affichant une nouvelle interface pour paramétrer la récupération dynamique de la valeur :

Type de fonction	Contenu	Icône	Indicateur de type
Paramètre	Paramètre de l’application		Texte en bleu
Aucune	Texte libre ou liste	aucun	Texte en noir
RuleFile	Valeur lue dans un fichier de données	Texte de la cellule	rulefile : keyword(Test)
Commande	Retour d’une commande prédéfinie	Texte de la cellule	Command : cutposition
Cmd	Retour d’une ligne commande	Texte de la cellule	cmd : chemincomplet...
SQL	Retour d’une requête SQL	Texte de la cellule	SQL : Select...
Table de résolution	Retour d’une table de résolution	Texte de la cellule	Resolve : TABLE[PARAM]
Rulefile multiple	Valeurs lues dans un même fichier (XML)	Texte de la cellule	rulefile_multiple : xml

Adding a condition

Definition

Les objets de type condition permettent de définir deux traitements différents en fonction de la validité d’une condition. Les boites conditions sont donc les seules à avoir deux sorties :

• en bas (chemin direct) si la condition est vraie (= Vrai)
• à droite (chemin détourné) si la condition est fausse (= Faux)

Une condition est une comparaison entre au moins deux valeurs. Une valeur peut être un paramètre, une constante, le résultat d’une commande ou d’un script, d’une recherche dans une table de résolution, d’une requête SQL, d’une lecture dans un fichier de données.

Creat/Edit

Pour créer une nouvelle condition, sélectionner la boite après laquelle la condition doit être ajoutée puis cliquer sur l’icône . Pour éditer une condition existante, il suffit de double-cliquer sur la boite correspondante. La fenêtre d’édition de condition s’ouvre afin de définir les différents champs :

• Condition: Nom de l'objet condition (1)
• title: Titre de l'objet
• AND , OR: Outils pour définir la logique de la condition : ajout/suppression d’un filtre, opérateurs logiques AND et OR.
• Param1 egal value1: Filtres de condition
• Note: Note (champ libre pour commentaires).

Une condition doit avoir au moins un filtre de condition.

Conseil : Le champ Nom de l’objet (1) est optionnel, mais il est vivement conseillé de le renseigner. En effet, cette information sera reprise dans le journal d’événements associé à l’exécution du Workflow permettant de facilement identifier les différentes étapes du Workflow. Exemples : « Condition failed » si pas de nom, « Condition 'Nom de la condition' failed » sinon.

Filtre de condition La création d’une nouvelle condition propose automatiquement un premier filtre à paramétrer. Un double-clic sur un filtre de condition permet de l’éditer.

Param1 EGAL Valeur1

• parma1:Valeur à comparer
• EGAL:Opérateur de comparaison
• à la valeur:Valeur de comparaison

Les opérateurs de comparaison disponibles sont :

• égal / différent : comparaison alphanumérique stricte entre deux valeurs,
• contient / ne contient pas : recherche alphanumérique d’une valeur dans une autre,
• est vide / n’est pas vide : un paramètre a-t-il ou non une valeur ?
• supérieur à / supérieur ou égal à : comparaison numérique,
• inférieur à / inférieur ou égal à : comparaison numérique.

Une condition peut être définie par plusieurs filtres de conditions. Le bouton permet d’ajouter un nouveau filtre de condition. La logique complète entre ces filtres est définie graphiquement en utilisant les cases à cocher devant chaque filtre et les outils et

Dans l’exemple, la logique de condition vaut : filtre A et (filtre B ou filtre C). Le bouton permet de supprimer un filtre de condition sélectionné ou une logique de condition (et ses filtres associés) sélectionnée.

Ajouter une commande

Définition

Les objets de type commande permettent d’exécuter un traitement unitaire. Un même Workflow comportera autant de commandes qu’il y a de traitements à effectuer. Les objets de type commande permettent d’exécuter quatre grandes familles de traitements : des commandes prédéfinies natives ONYX Server, des scripts utilisateurs, des requêtes SQL, ou des appels à d’autres Workflows.

Création/Édition

Pour créer une nouvelle commande, sélectionner la boite après laquelle la commande doit être ajoutée puis cliquer sur l’icône . Pour éditer une commande existante, double-cliquer sur la boite correspondante. La fenêtre d’édition de commande s’ouvre afin de définir les différents champs :

• Type d'objet: Type de traitement au choix entre Command, Cmd, Sql, Call,
• Nom de l’objet,
• titre: Titre de l’objet,
• File: groupe de commandes prédéfinies
• Copier vers un dossier: la commande prédéfinie à exécuter
• Source et Dossier de destination: Paramètres de la commande

                 o Présente l’ensemble des paramètres requis ou optionnels pour la bonne exécution de la commande
                 o L’onglet Standard regroupe les paramètres principaux de la commande
                 o En fonction des commandes, d’autres onglets spécifiques présentent les paramétrages avancés Advanced

• Note: champ libre pour commentaires.

Les commandes prédéfinies (COMMAND)

Cette première famille de traitement regroupe les commandes génériques et natives Onyx Server. Elles sont organisées par groupes de commandes en fonction de leur utilisation : Spooler, File, Mapping, XPS Toolbox, Mail…

Parmi les plus utilisées, nous pouvons citer notamment :

Mapping / Text M-Designer : application d’un format Designer sur un fichier de données en mode texte

• Standard:

-Nom du format Designer à appliquer. La liste des formats importés sur le serveur est disponible par le bouton l’aide à la saisie

-Numéro de séquence (00010, ou *MRG, ou *ALL, etc.)

-Fichier d’entrée (le fichier de données)

-Fichier de sortie (le document XPS produit)

• Advanced:

-Langue de traduction (consulter le Guide Utilisateur de Designer pour l’utilisation des traductions)

-Fichier XPS à incorporer comme calque, avec possibilité de reprendre ses index

• Text options:

-Nombre de lignes maximum = possibilité de fixer un overflow sur le fichier de données en entrée et de provoquer un saut de page automatique, -Largeur de page : nombre de caractères maximum par ligne à lire dans le fichier de données en entrée,

-Page de code du fichier en entrée : permet de réaliser une conversion à la volée en Unicode UTF-16 si besoin. La liste des codes pages gérés dans Onyx Server est disponible par le bouton d’aide à la saisie .

• Output options:

-Page de début / page de fin : intervalle de pages à produire,

-Bac d’entrée / bac de sortie : ajout d’options de finition (PrintTicket) sur le document XPS produit pour la gestion des bacs d’imprimantes.

Spooler / Imprimer : envoi d’un spool dans une file d’attente du Spooler Onyx Server

• Standard:

-Nom de la file d’attente de destination. La liste des files d’attente déclarées dans le Spooler est disponible par le bouton d’aide à la saisie ,

-Nom du fichier à envoyer,

-Titre : nom donné au spool dans la file d’attente, -Envoyer le spool en état suspendu dans la file d’attente de destination,

-Conserver le spool après traitement dans la file d’attente de destination,

-Conserver les attributs courants = affecter au spool en sortie les attributs du spool en cours,

-Ajouter les paramètres courants = affecter au spool en sortie les paramètres de la session en cours,

• Page:

-Page de début / page de fin : positionne les attributs correspondants sur le spool de destination pour son intervalle de traitement,

-Nombre de copies : positionne l’attribut correspondant sur le spool de destination.

• Security:

-Propriétaire du spool de destination,

-Droits d’accès sur le spool de destination,

-Code comptabilité : affectation de l’attribut correspondant.

• Userdatas:

-Possibilité de définir des attributs supplémentaires sur le spool de destination.

• Advanced :

-Priorité du spool de destination,

-Nombre de jours de conservation du spool de destination,

-Nombre de jours avant compression du spool de destination (attribut hérité du monde AS/400, parfois utilisé par les applications clientes en amont et en aval),

-Type de support papier,

-Fidélité : attribut hérité du monde AS400 parfois utilisé par les applications clientes en amont et en aval

-Nom du fichier spool de destination.

La liste exhaustive des commandes prédéfinies Onyx Server est détaillée dans le Chapitre 4.

Les scripts utilisateurs

Le mode CMD permet de passer l’objet de type commande en mode éditeur de texte afin de taper une commande complète comme il serait fait en mode telnet ou en fenêtre de commandes MS-DOS. Tous les paramètres d’environnement (système et Mapping) ainsi que les attributs du fichier en cours de traitement sont accessibles. La commande exécutée peut être une commande Onyx Server spécifique et non disponible en commande prédéfinie ou alors un script (*.bat ou *.sh) complexe.

Les requêtes SQL

Le mode SQL permet de passer l’objet de type commande en mode éditeur de texte afin d’exécuter des ordres SQL. Tous les paramètres d’environnement (système et Mapping) ainsi que les attributs du fichier en cours de traitement sont accessibles. Les paramètres de connexion à la base de données doivent être définis dans la configuration de Onyx Server.

Les appels à des WORKFLOWS(CALL)

Le mode CALL permet d’exécuter, dans le Workflow en cours, un autre Workflow puis de continuer l’exécution du Workflow en cours une fois que le second est correctement terminé. Tous les paramètres d’environnement (système et Mapping) ainsi que les attributs du fichier en cours de traitement sont automatiquement transmis au sous-Workflow et utilisables dans celui-ci.