Guide de prise en main ONYX Server

=ONYX Server : Principe général=

==Présentation du logiciel==

ONYX Server est le moteur de production de la Suite Mapping sur Linux et Windows. En dehors des spécificités système propres (système de fichiers, gestion des droits utilisateurs), la philosophie, le paramétrage, le fonctionnement et l’exploitation du moteur sont identiques sur ces deux types de plateformes.

Le moteur ONYX Server repose principalement sur son Gestionnaire de travaux (appelé Spooler ou Output Manager), véritable ordonnanceur des traitements, des impressions et de la diffusion des documents, de leur entrée dans le moteur jusqu’aux sorties vers les utilisateurs finaux. Couplé au Spooler Mapping, le moteur de Workflows permet l’automatisation complète de la chaine éditique et de tous les traitements à exécuter sur les documents : extraction des données, mise en forme et composition graphique, indexation, tri / éclatement, routage, diffusion omnicanal, etc.

==Schéma de fonctionnement général==
[[Fichier:OnyxServerDiagram.jpg|centré|cadre]]

ONYX Server gère l’ensemble de la chaine éditique de l’entreprise. Le centre névralgique de la solution est le '''Spooler''' (ou Output Manager), couplé au moteur d’exécution de '''Workflows'''. Il centralise et ordonnance toutes les demandes provenant de diverses origines et soumises par divers protocoles (LPR, RAW, FTP/SFTP, Web Service), applique des règles de traitement, de composition, de routage et de diffusion omnicanal.

==Interface d’Administration / Exploitation==

Si le moteur ONYX Server est un client lourd installé sur la plateforme cible, son administration et les tâches d’exploitation sont réalisables à distance via un simple navigateur Internet (Internet Explorer 8.0 minimum, Firefox, Google Chrome). Cet accès en client léger est supporté par le logiciel Apache HTTP Server, seul pré-requis logiciel à l’installation de ONYX Server.

===Accès, authentification===

Pour accéder à l’interface Web de ONYX Server, il faut connaître le nom DNS ou l’adresse IP du serveur et le port HTTP choisi pour Mapping (8002 sur une installation « Typical »). L’adresse à taper dans le navigateur est de cette forme : [http://192.168.216.57:8002 http://192.168.216.29:8002]
[[Fichier:OX S auth.png|centré|700x700px]]
L’accès à l’interface Web de ONYX Server est contrôlé et sécurisé. S’il est possible d’interfacer ONYX Server avec un annuaire Active Directory ou LDAP existant, la première connexion à l’interface se fera par une authentification pilotée par le serveur Apache, avec le compte administrateur de la solution renseignée à l’installation du logiciel, soit « '''mapadmin''' » par défaut :
[[Fichier:OX S id.png|centré]]
<br />

===Page d’accueil===
[[Fichier:OX S homepage.png|centré|721x721px]]


Une fois connecté et authentifié, la page d’accueil d'ONYX Server présente les différents menus :

*Menus de Développement (1) : Gestion des formats M-Connect et M-Designer, accès aux menus personnalisés pouvant accompagner les formats M-Connect
*Menu d’Administration (2) : Paramétrage global de la solution, gestion des droits d’accès, création des points d’entrée, des règles de gestion (Workflows), des imprimantes de sortie et règles de diffusion des documents, gestion des déploiements entre serveurs ONYX Server
*Menus d’Exploitation (3) : Gestion des travaux, des files d’attentes, accès aux journaux d’événements

A tout moment de la navigation, un menu déroulant propose un accès rapide à l’ensemble de l’arborescence des menus :
[[Fichier:OX S menu.png|centré|721x721px]]


Enfin, en bas à gauche, en plus des informations de session (utilisateur connecté, date et heure courante) et du numéro de version de ONYX Server, une barre de navigation permet de :

*Revenir au menu précédent (gestion intégrée de l’historique de navigation, à la différence du bouton « Précédent » du navigateur)
*Actualiser la page en cours
*Revenir au menu principal
*Se déconnecter

[[Fichier:OX S version.png|centré]]
<br />

=Menus de Développement=

Les trois premiers menus de l’interface utilisateur sont des écrans dits de « Développement », ils permettent de gérer les bibliothèques de modèles de documents créés avec les outils M-Connect et M-Designer.

==Gestion M-Designer==
[[Fichier:OX S DesignerManagement.png|centré|690x690px]]


Les différents écrans proposés ici permettent respectivement de :

*'''Importer''' les formats M-Designer, générés depuis l’outil, afin de les rendre disponibles et utilisables par les règles de traitements du moteur ONYX Server
*Visualiser et réinitialiser la '''Liste des Objets''' et ressources utilisés dans les formats M-Designer visibles du serveur (importés ou non)
*Visualiser la liste des '''Formats''' M-Designer en production sur le serveur, avec pour chacun les possibilités de suppression du serveur ou de déploiement vers un autre environnement ONYX Server.
*Déclarer, configurer et administrer les différents '''Taux de Conversion''' qui peuvent être utilisés dans les formats M-Designer.

==Gestion M-Connect==
[[Fichier:OX S connectManagement.png|centré|690x690px]]


Les différents écrans proposés ici permettent respectivement de :

*'''Importer''' les formats M-Connect, générés depuis l’outil, afin de les rendre disponibles et utilisables par les règles de traitements du moteur ONYX Server
*'''Gérer''' et visualiser la liste des formats M-Connect en production sur le serveur, avec pour chacun les possibilités de suppression du serveur ou de déploiement vers un autre environnement ONYX Server.
*'''Exécuter''' en interactif un format M-Connect, afin par exemple de valider son bon fonctionnement sur le serveur
*'''Démarrer''' et '''Arrêter''' le moteur de développement M-Connect sur le serveur, permettant ainsi aux utilisateurs de réaliser des aperçus depuis l’outil.
*'''Extraire les Définitions''' des tables de la base de données interfacée avec l’outil M-Connect, les fichiers produits étant ensuite importés dans l’outil afin de créer la structure interne des données des formats M-Connect développés.

==Menus Personnalisés==

Cet écran donne accès à des interfaces interactives permettant d’exécuter à la demande des formats M-Connect pour produire des demandes d’éditions. Ces interfaces sont développées depuis l’outil M-Connect, générées et importées avec le(s) format(s) correspondant(s), et peuvent répondre à un besoin de production à la demande, non automatisable.

=Menu d’Administration=

Ce quatrième menu de la page d’accueil donne accès à l’ensemble du paramétrage de la solution, la création et l’administration des points d’entrée dans ONYX Server (robots Scanfolder, serveur d’écoute, files d’attente de traitements), des règles d’exécution et de routage (Workflows), des points de sorties et de diffusion des documents.

Seuls les principaux écrans sont abordés dans ce support de formation, des informations plus exhaustives sont disponibles dans le Guide Utilisateur de la solution.

==Gestion de la configuration==

Cet écran affiche l’ensemble des paramètres d’environnement décrivant la solution, de son installation à sa configuration générale.
[[Fichier:OX S Config.png|centré|766x766px]]


La plupart des valeurs présentées ici sont à titre informatif et ne doivent pas être modifiées sans y avoir été explicitement invité. Le Guide Utilisateur de la solution fournit davantage d’informations sur les valeurs modifiables et leur comportement, en fonction du contexte d’application.

==Gestion des robots==

Cet écran permet d’administrer l’ensemble des « robots » configurés dans la solution, de type Scanfolder ou Serveur d’écoute. La liste est vierge sur une première installation, mais donne accès aux écrans de création / modification de nouveaux points d’entrée dans ONYX Server :
[[Fichier:OX S robots.png|centré|896x896px]]


Un robot, du point de vue ONYX Server, est un point d’entrée dans la solution, un moyen pour une application tierce d’envoyer une requête d’exécution. Les robots sont des programmes exécutés en tâche de fond (en mode Service sous Windows) pour scruter l’arrivée de données : dans un répertoire pour les robots Scanfolder, sur un port réseau pour les Serveurs d’écoute. Chaque fichier reçu est soumis séquentiellement au moteur d’exécution de Workflows, afin d’effectuer le traitement adéquat.

===Robots Scanfolder===

====Introduction====

*Un robot de type Scanfolder scrute un répertoire du système de fichiers, en attente de dépôts de fichiers (par copies ou transferts FTP/SFTP). Les fichiers détectés dans le répertoire sont envoyés séquentiellement (les uns après les autres) au moteur d’exécution pour être traités, suivant les règles définies dans les Workflows.
*Un robot configuré dans ONYX Server ne peut scruter qu’un et un seul répertoire, un répertoire du système de fichiers ne peut être scruté que par un et un seul robot Scanfolder. Autant de robots Scanfolder pourront être créés et configurés, qu’il y a de répertoires différents à scruter. Chaque robot sera indépendant des autres, plusieurs fichiers pourront ainsi être traités en parallèle par des robots différents.

====Création / Modification / Suppression====

L’écran suivant présente la liste des robots déjà configurés, chacun pouvant être modifié si besoin (s’il n’est pas en cours d’exécution). Le dernier bloc de deux lignes vierges permet de créer un nouveau robot Scanfolder :
[[Fichier:OX S robotsConfig.png|centré|1035x1035px]]


Paramètres à renseigner pour configurer un robot :

'''Nom''' : permet de donner un nom au robot.

*Ce paramètre est facultatif, mais vivement conseillé : le nom de chaque robot est une variable d’environnement qui sera accessible et pourra donc être utilisée dans les Workflows.
*ONYX Server contrôle l’unicité des noms utilisés pour les différents robots.

'''* Répertoire à scanner''' : le chemin complet du répertoire scruté par le robot.

*Ce paramètre est requis.
*Il peut pointer sur un lecteur réseau ou un chemin UNC (sous Windows), attention aux droits d’accès dans ce cas.
*ONYX Server contrôle l’unicité des répertoires scrutés par les différents robots.
*ONYX Server peut créer le répertoire renseigné si celui-ci n’existe pas.

'''* CMD''' : action exécutée sur chaque fichier détecté, après qu’il ait été traité correctement par le moteur d’exécution.

*Ce paramètre est requis.
*Supprimer : les fichiers détectés et traités seront supprimés du répertoire scruté.
*Déplacer : les fichiers détectés et traités seront déplacés dans un autre répertoire, pour historique par exemple.

'''* Répertoire de destination''' : chemin de destination des fichiers traités.

*Ce paramètre est requis si la commande de déplacement a été choisie précédemment.
*ONYX Server contrôle que le répertoire de destination est bien différent du répertoire scruté.
*ONYX Server peut créer le répertoire renseigné si celui-ci n’existe pas.

'''* Temporisation''' : intervalle d’attente (de repos) entre deux scrutations de répertoire, exprimé en secondes.

*Ce paramètre est requis.

'''* On Error''' : définit le comportement du robot lorsqu’une erreur de traitement est remontée sur un fichier détecté.

*Ce paramètre est requis.
*'''Stop''' : le robot s’arrête, le fichier en erreur reste dans le répertoire scruté.
*'''Continue ''': le robot continue de traiter les fichiers suivants, le fichier en erreur reste dans le répertoire scruté, renommé avec le suffixe « _FAILED » (mot clé Mapping évitant que le robot ne traite à nouveau ce fichier à la prochaine scrutation du répertoire).
*'''Retry''' : le robot continue de traiter les fichiers suivants, le fichier en erreur reste dans le répertoire scruté. A la prochaine scrutation, le robot réessaiera de traiter à nouveau ce fichier.

'''Workflow''' : nom du Workflow à exécuter.

*Ce paramètre est optionnel. S’il n’est pas renseigné, c’est le Workflow root qui sera exécuté par défaut.

'''Filtre''' : permet d’exclure des fichiers des scrutations du robot.

*Ce paramètre est optionnel.
*Exemple : *.tmp les fichiers d’extension .tmp dans le répertoire scruté ne seront pas traités par le robot.

'''Accept''' : permet de restreindre le type de fichiers à traiter.

*Ce paramètre est optionnel.
*Exemple : *.xml seuls les fichiers d’extension .xml dans le répertoire scruté seront traités par le robot.

Pour créer un nouveau robot, renseigner l’ensemble des paramètres désirés, puis cliquer sur le bouton [[Fichier:OX S Save 2.png|sans_cadre]] pour ajouter le robot à la configuration du serveur.

Pour modifier un robot existant, modifier le ou les paramètres désirés, puis cliquer sur le bouton[[Fichier:OX S Save 2.png|sans_cadre]] pour modifier le robot dans la configuration du serveur.

<u>Remarque</u> : Pour modifier un robot, celui-ci doit être arrêté.

Pour supprimer un robot existant, cliquer sur le bouton[[Fichier:OX S icone delete.png]]. Le robot sera supprimé de la configuration du serveur.

<u>Remarque</u> : Pour supprimer un robot, celui-ci doit être arrêté.

====Exploitation====

Une fois les robots créés et configurés, ils apparaissent dans l’écran de gestion :
[[Fichier:OX S startRobots.png|centré|766x766px]]


Cet écran permet de :

*Démarrer un robot : [[Fichier:OX S strt rbt.png]]
*Arrêter un robot : [[Fichier:OX S stp rbt.png]]
*Consulter les journaux d’événements d’un robot : [[Fichier:OX S infos rbt.png]]

Une fois démarré, un robot est un processus qui s’exécute en continu, en tâche de fond. Le binaire ONYX Server associé est '''map_scanfolder''', la liste des processus actifs du système (Gestionnaire de Tâches sous Windows, commande '''ps –ef''' sous Unix) montrera autant de processus map_scanfolder[.exe] qu’il y a de robots démarrés.

'''Remarque Windows :'''

Sous Windows, les robots s’installent en tant que Service dans le Gestionnaire de Services Windows. Cet enregistrement se fait au premier démarrage du robot. Le Service correspondant est nommé en se basant sur le nom du robot s’il est renseigné (d’où l’unicité requise de ce paramètre), sur le répertoire scruté sinon (d’où là encore l’unicité requise). Exemple : Mapping_ScanFolder_SCAN_TXT.

Chaque Service Windows créé par robot est configuré en démarrage manuel par défaut, cela peut être modifié par la suite pour un démarrage automatique avec le système.

'''<u>Fichiers temporaires associés aux robots :</u>'''

Une fois démarré, chaque robot crée deux fichiers dans le répertoire temporaire de ONYX Server. Le premier est nommé en se basant sur le nom du répertoire scruté, où les caractères spéciaux sont remplacés par des ‘_’, et suffixé de « map_scanfolder.ID ». Exemple : E__InputData_TXT_map_scanfolder.ID

Le deuxième est nommé par le numéro système du processus map_scanfloder[.exe] associé. Exemple : 75668.pid.

Ces fichiers sont à usage interne au processus uniquement et sont supprimés à l’arrêt du robot.

En revanche, l’interface Web s’appuie sur la présence de ces fichiers pour indiquer l’état des robots.

'''<u>Lignes de commandes utiles :</u>'''

*Pour démarrer un robot nommé :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_scanfolder -name:SCAN_TXT

Windows :

 E:\MappingWindows\Applications\map_scanfolder.exe -name:SCAN_TXT

*Pour arrêter un robot nommé :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_scanfolder -name:SCAN_TXT -stop

Windows :

 E:\MappingWindows\Applications\map_scanfolder.exe -name:SCAN_TXT -stop

*Si le robot n’est pas nommé, il conviendra de passer chacun des paramètres décrivant le robot en argument des commandes précédentes (d’où le conseil quant au nommage des robots).

===Serveurs d’Ecoute===

====Introduction====

*Un robot de type Serveur d’écoute scrute un port réseau, en attente de réception de données (les données sont envoyées par un système distant par transfert direct en protocole RAW). Le robot réceptionne les données et construit localement des fichiers, puis les envoie séquentiellement (les uns après les autres) au moteur d’exécution pour être traités, suivant les règles définies dans les Workflows.
*Un robot configuré dans ONYX Server ne peut scruter qu’un et un seul port réseau, un port réseau ne peut être scruté que par un et un seul Serveur d’écoute. Autant de Serveurs d’écoute pourront être créés et configurés, qu’il y a de ports différents à scruter. Chaque robot sera indépendant des autres, plusieurs fichiers pourront ainsi être traités en parallèle par des robots différents.

====Création / Modification / Suppression====

L’écran suivant présente la liste des robots déjà configurés, chacun pouvant être modifié si besoin (s’il n’est pas en cours d’exécution). La dernière ligne vierge permet de créer un nouveau Serveur d’écoute :
[[Fichier:OX S rawListener.png|alt=|centré]]


Paramètres à renseigner pour configurer un serveur d’écoute :

'''Nom''' : permet de donner un nom au robot.

*Ce paramètre est facultatif, mais vivement conseillé : le nom de chaque robot est une variable d’environnement qui sera accessible et pourra donc être utilisée dans les Workflows.
*ONYX Server contrôle l’unicité des noms utilisés pour les différents robots.

'''* Port''' : numéro du port réseau écouté par le robot.

*Ce paramètre est requis.
*ONYX Server contrôle l’unicité des ports écoutés par les différents robots.

'''Séparateur de travaux''' : caractère ou chaine permettant de découper un large flux réseau en plusieurs fichiers.

*Ce paramètre est optionnel.

'''Clé (début/longueur)''' : permet d’ajouter une information au nom du fichier temporaire construit par le robot.

*Ces 3 paramètres sont optionnels.
*L’information est recherchée dans le flux réseau, à partir du mot clé, en ignorant X caractères après le mot clé (paramètre « début »), en extrayant N caractères (paramètre « longueur »).
*Cette information pourra être utilisée dans les Workflows, comme une condition notamment.

'''Timeout''' : délai d’attente réseau, exprimé en secondes.

*Ce paramètre est optionnel.
*Permet de ne pas bloquer le port réseau en cas de problème du côté de l’émetteur du flux : le robot coupe la connexion au bout de ce délai d’inactivité, considérant que la connexion établie n’est plus active.

Pour créer un nouveau serveur d’écoute, renseigner l’ensemble des paramètres désirés, puis cliquer sur le bouton [[Fichier:OX S Save 2.png|sans_cadre]] pour l’ajouter à la configuration du serveur.

Pour modifier un serveur existant, modifier le ou les paramètres désirés, puis cliquer sur le bouton [[Fichier:OX S Save 2.png|sans_cadre]] pour modifier la configuration du serveur.

<u>Remarque</u> : Pour modifier un serveur, celui-ci doit être arrêté.

Pour supprimer un serveur d’écoute existant, cliquer sur le bouton [[Fichier:OX S icone delete.png]]. Le robot sera supprimé de la configuration du serveur.

<u>Remarque</u> : Pour supprimer un robot, celui-ci doit être arrêté.

====Exploitation====

Une fois les robots créés et configurés, ils apparaissent dans l’écran de gestion :
[[Fichier:OX S startListener.png|alt=|centré]]


Cet écran permet de :

*Démarrer un serveur d’écoute : [[Fichier:OX S strt rbt.png]]
*Arrêter un serveur d’écoute : [[Fichier:OX S stp rbt.png]]
*Consulter les journaux d’événements d’un serveur d’écoute : [[Fichier:OX S infos rbt.png]]

Une fois démarré, un serveur d’écoute est un processus qui s’exécute en continu, en tâche de fond. Le binaire ONYX Server associé est '''map_rawd''', la liste des processus actifs du système (Gestionnaire de Tâches sous Windows, commande '''ps –ef''' sous Unix) montrera autant de processus map_rawd[.exe] qu’il y a de serveurs d’écoute démarrés.

'''Remarque Windows :'''

Sous Windows, les serveurs d’écoute s’installent en tant que Service dans le Gestionnaire de Services Windows. Cet enregistrement se fait au premier démarrage du robot. Le Service correspondant est nommé en se basant sur le port réseau écouté (d’où l’unicité requise) et le séparateur de travaux. Exemple : Mapping_Rawd_13000, Mapping_Rawd_25006_SEP.

Chaque Service Windows créé par robot est configuré en démarrage manuel par défaut, cela peut être modifié par la suite pour un démarrage automatique avec le système.

'''<span class="underline">Fichier temporaire associé aux serveurs d’écoute :</span>'''

Chaque serveur d’écoute, une fois démarré, crée un dossier dans le répertoire temporaire de ONYX Server, nommé en se basant sur le port réseau écouté et le séparateur de travaux, avec un fichier map_rawd.ID contenant le numéro du processus associé. Exemple : …\Temp\map_rawd_25006_SEP\map_rawd.ID.

'''<span class="underline">Lignes de commandes utiles :</span>'''

*Pour démarrer un robot nommé :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_rawd -start -name:RAW_25006

Windows :

 E:\MappingWindows\Applications\map_rawd.exe -start -name:RAW_25006

*Pour arrêter un robot nommé :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_rawd -stop -name:RAW_25006

Windows :

 E:\MappingWindows\Applications\map_rawd.exe -stop -name:RAW_25006

*Si le robot n’est pas nommé, il conviendra de passer les paramètres décrivant le robot (port écouté et séparateur de travaux) en argument des commandes précédentes (d’où le conseil quant au nommage des robots).

==Gestion du Spooler==

Comme évoqué précédemment, le Spooler Onyx Serveur est le cœur de la solution. C’est un véritable gestionnaire de flux, de traitements et d’imprimantes. En naviguant dans le Menu d’Administration, puis Gestion des Impressions, et enfin Gestion du Spooler, l’interface suivante permet de :

*Démarrer le Spooler
*Arrêter le Spooler
*Consulter les statistiques d’éditions
*Consulter les rapports d’utilisation de la solution

[[Fichier:OX S Spooler.png|alt=|centré]]


Une fois démarré, le Spooler est un processus qui s’exécute en continu, en tâche de fond. Le binaire Onyx Server associé est '''map_daemon[.exe]'''.

'''Remarque Windows :'''

Sous Windows, le Spooler s’installe en tant que Service dans le Gestionnaire de Services Windows. Cet enregistrement se fait au premier démarrage du Spooler. Le Service correspondant est nommé Mapping_Spooler. Il est configuré en démarrage manuel par défaut, cela peut être modifié par la suite pour un démarrage automatique avec le système.

'''<span class="underline">Fichier temporaire associé au Spooler :</span>'''

Une fois démarré, le Spooler crée un fichier « map_daemon.ID » dans son répertoire de l’installation de Onyx Server : C:\ProgramData\MappingWindows\Spooler par défaut sous Windows, /apps/mapping/spool par défaut sous Linux.

'''<span class="underline">Lignes de commandes utiles :</span>'''

*Pour démarrer le Spooler :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_daemon start

Windows :

 E:\MappingWindows\Applications\map_daemon.exe start

*Pour arrêter le Spooler :

Linux (après chargement de l’environnement) :

 /apps/mapping/bin/map_daemon stop

Windows :

 E:\MappingWindows\Applications\map_daemon.exe stop

==Gestion des Sites et Files d’attente==

En naviguant dans le Menu d’Administration, puis Gestion des Impressions, et enfin Gestion des Queues / Devices / Entrées, l’interface affichée présente la liste de toutes les files d’attente configurées dans le Spooler, éventuellement organisées par sites :
[[Fichier:OX S SitesAndEntryPoints.png|alt=|centré]]


Ici par exemple, un site « SAMPLE » a été déclaré, dans lequel 3 files d’attente (une entrée et deux sorties) sont configurées. Puis 3 autres files d’attente sont déclarées hors site, affichées dans un site par défaut appelé Principal (ou Main).

Depuis cette interface, il est possible, à l’intérieur de chaque site, de :

[[Fichier:OX S iconeS.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_site.png]] Créer un site. Les sites ne sont qu’une manière logique d’organiser les files d’attente

[[Fichier:OX S iconeF.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_printer.png]] Créer une file d’attente de sortie, rattachée à une imprimante physique

[[Fichier:OX S FP.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_shell.png]] Créer une file d’attente de traitement personnalisé, exécutant un script (shell) client

[[Fichier:OX S FM.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_entry.png]] Créer une file d’attente de traitements Mapping, exécutant un Workflow

'''Remarques importantes :'''

<ul>
<li><p>Tous les objets qui vont être créés et configurés doivent avoir un nom unique, quel que soit leur type (une imprimante de sortie ne pourra pas avoir le même nom qu’un site).</p></li>
<li><p>Une fois créé et configuré, il n’est plus possible de changer le nom d’un objet. Si besoin, il faudra supprimer l’objet, puis le recréer.</p></li></ul>

===Créer un site===

Les sites permettent de classer les files d’attente du Spooler afin de hiérarchiser l’affichage de la gestion des impressions. Cette notion de site pourra également être utilisée comme filtre d’affichage ou recherche dans la vue d’exploitation.

Pour créer un site, cliquer sur le bouton [[Fichier:OX S iconeS.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_site.png]].

'''Remarque :'''

Il est possible de créer des sites dans un site, et ainsi de gérer une arborescence d’affichage complexe. Pour cela, il convient d’utiliser le bouton de création sur la ligne du site concerné.

Dans l’écran de saisie, renseigner chacune des informations suivantes, en les validant par [[Fichier:OX S Save 2.png|sans_cadre]] :

*(1) Un nom pour le site (requis)
*(2) Une description

Le paramétrage du site est achevé, il faut enregistrer ce nouveau site en terminant par [[Fichier:OX S OK.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\ok2.png]] (3).
[[Fichier:OX S createSite.png|alt=|centré]]
<br />

===Créer un point d’entrée (simple)===

Un point d’entrée ONYX Server est une file d’attente chargée d’exécuter des traitements Mapping (Workflows). Il est constitué de deux objets :

*Une file d’attente pour réceptionner les demandes (travaux)
*Une &quot;device&quot; ou moteur, pour prendre en charge les demandes et effectuer les traitements

Pour ajouter un point d’entrée dans un site, cliquer sur le bouton [[Fichier:OX S FM.png|sans_cadre]], sur la ligne du site concerné.

L’écran de saisie suivant propose plusieurs onglets, seul le premier est détaillé dans ce support. Consulter le Guide Utilisateur pour les options avancées de paramétrage.

Renseigner les informations voulues, en les validant par [[Fichier:OX S Save 2.png|sans_cadre]].
[[Fichier:OX S addEntry.png|alt=|centré]]


'''File d’attente'''

*(1) Un nom pour la file d’attente (requis)
*(2) Une description pour la file d’attente

La validation du nom présente le formulaire de création de la device associée.

'''Device'''

*(3) Un nom pour la device associée (requis)
*(4) Une description pour la device

'''Driver'''

*(5) Le type de driver : RULES par défaut, non modifiable (c’est bien le moteur d’exécution qui est appelé)
*(6) Le Workflow exécuté, à choisir dans la liste déroulante. Par défaut (‘Default’ ou ‘undefined’), c’est le Workflow root qui sera exécuté.

'''Monitoring'''

*(7) Le comportement de la device sur les erreurs :
**default ou stop : le traitement en cours s’arrête en erreur, la device s’arrête en erreur.
**continue : le traitement en cours s’arrête en erreur, la device continue avec les demandes suivantes.
**ignore : le traitement en cours est considéré comme ayant été effectué, la device continue avec les demandes suivantes. <span class="underline">Valeur déconseillée</span>, sauf pour des cas très particuliers.
*(8) Reprise automatique : si activé, un traitement provoquant une erreur sera relancé
*Timeout : temps maximum pendant lequel un traitement en erreur sera relancé, avant de réellement être considéré en erreur. Le comportement de la device sur erreur sera alors pris en compte.

'''Remarque :'''

La reprise automatique n’est pas forcément conseillée sur les files d’attentes de type point d’entrée. Si un Workflow provoque une erreur, il y a de fortes chances que l’erreur se reproduise tant que le Workflow n’est pas corrigé.

Le paramétrage (simple) du point d’entrée est achevé, il faut enregistrer ce nouvel objet en terminant par [[Fichier:OX S OK.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\ok2.png]] (9).

===Créer une imprimante (simple)===

Une imprimante ONYX Server est une file d’attente chargée de communiquer avec un matériel physique d’impression. Elle est constituée de deux objets :

*Une file d’attente pour réceptionner les demandes d’impression (travaux)
*Une &quot;device&quot; ou imprimante, pour prendre en charge les demandes et envoyer les données au matériel physique.

Pour ajouter une imprimante dans un site, cliquer sur le bouton [[Fichier:OX S iconeF.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\add_printer.png]], sur la ligne du site concerné.

L’écran de saisie suivant propose plusieurs onglets, seul le premier est détaillé dans ce support. Consulter le Guide Utilisateur pour les options avancées de paramétrage.

Renseigner les informations voulues, en les validant par [[Fichier:OX S Save 2.png|sans_cadre]].
[[Fichier:OX S addPrinter.png|alt=|centré]]


'''File d’attente'''

*(1) Un nom pour la file d’attente (requis)
*(2) Une description pour la file d’attente

La validation du nom présente le formulaire de création de la device associée.

'''Device'''

*(3) Un nom pour la device associée (requis)
*(4) Une description pour la device
*(5) Backup : si activé, permet de créer une imprimante de secours, qui prendra automatiquement le relais d’une imprimante principale en erreur.

'''Driver'''

*(6) Type de connexion : Onyx Server implémente plusieurs types de protocoles de communication, le protocole LPR est le plus répandu et est utilisé ici (consulter le Guide Utilisateur pour les autres protocoles).
*(7) Type d’impression : « default » signifie que le matériel adressé est une imprimante physique, « MAPPING » signifie une communication avec une autre Spooler Onyx Server (distant), et permet d’activer la compression des flux échangés.
*(8) Compatibilité XPS : permet de communiquer en direct avec l’imprimante physique adressée, dans son langage natif d’impression. Les flux XPS sont convertis à la volée suivant le profil sélectionné, puis envoyés à l’imprimante, sans dépendance avec aucun driver.
*(9) Adresse IP de l’imprimante physique
*(10) Nom interne de l’imprimante physique : PASS en général si elle est connectée directement au réseau, nom du port sur le boîtier (HP JetDirect par exemple) si utilisé pour connecter l’imprimante au réseau.
*(11) Délai : délai d’attente maximum d’une communication réseau.

'''Statut'''

Permet d’interroger l’imprimante physique pour obtenir son statut réel, qui sera affichée dans la vue d’exploitation.

'''Monitoring'''

Permet d’interroger l’imprimante physique pour contrôler le statut réel de l’impression. Cette communication supplémentaire est détaillée dans le Guide Utilisateur, les paramètres par défaut proposés conviennent dans l’immédiat.

*(12) Le comportement de la device sur les erreurs :
**default ou stop : le traitement en cours s’arrête en erreur, la device s’arrête en erreur.
**continue : le traitement en cours s’arrête en erreur, la device continue avec les demandes suivantes.
**ignore : le traitement en cours est considéré comme ayant été effectué, la device continue avec les demandes suivantes. <span class="underline">Valeur déconseillée</span>, sauf pour des cas très particuliers.
*(13) Reprise automatique : si activé, une impression provoquant une erreur sera relancée
**Timeout : temps maximum pendant lequel l’impression en erreur est relancée, avant de réellement être considérée en erreur. Le comportement de la device sur erreur sera alors pris en compte.
**Mode de reprise : en intégralité ou à la page

Le paramétrage (simple) de l’imprimante est achevé, il faut enregistrer ce nouvel objet en terminant par [[Fichier:OX S OK.png|C:\PROJETS\Built-Setup\Sources\Branch_trunk_v8\install\AllVersion\httpd\images\ok2.png]] (14).

===Envoyer un fichier dans une file d’attente===

Depuis une application tierce, le Spooler ONYX Server est vu comme une imprimante ‘virtuelle’. Pour envoyer des fichiers dans une file d’attente du Spooler, les commandes d’impression sont donc utilisées.

ONYX Server dispose de ses propres commandes d’impression : '''map_lp''' en local, '''map_lpr''' en distant.

====MAP_LP en local====

Il s’agit d’une requête directe envoyée au Spooler ONYX Server (c’est le programme '''map_daemon''' qui y répond).

Deux paramètres sont requis pour cette commande :

-queue:XXX : le nom de la file d’attente dans laquelle le fichier sera envoyé

-data:XXX : le chemin complet du fichier à envoyer

D’autres paramètres sont disponibles sur cette commande (argument --help pour les lister), dont les plus courants :

-title:XXX : permet de donner un titre au document dans la file d’attente, affiché dans la vue d’exploitation

-user:XXX : permet de définir le nom d’utilisateur propriétaire du document dans la file d’attente

-map_hold : le fichier est envoyé avec l’état « en attente » (ne sera traité qu’après libération)

-map_save : permet de conserver le fichier après son traitement

-map_retention:NN : permet d’ajouter un délai de rétention (en jours) dans les attributs du spool

<u>Exemple :</u> les commandes suivantes ajoutent un spool en attente dans la file d’attente INPUT_DATA appartenant à l’utilisateur mapadmin, qui possède un délai de rétention de 15 jours et qui passera en état conservé lorsqu’il sera traité.

Sous Windows :

 E:\MappingWindows\Applications\map_lp &quot;-queue:INPUT_DATA&quot; &quot;-map_hold&quot; &quot;-map_save&quot; 
 &quot;-map_retention:15&quot; &quot;-user:mapadmin&quot; &quot;-data:D:\Data\extract\FR_DEMO.txt&quot;

Sous Linux :

 /apps/mapping/bin/map_lp &quot;-queue:INPUT_DATA&quot; &quot;-map_hold&quot; &quot;-map_save&quot; &quot;-map_retention:
 15&quot; &quot;-user:mapadmin&quot; &quot;-data:/opt/data/extract/FR_DEMO.txt&quot;

====MAP_LPR en distant====

Il s’agit d’une communication réseau d’impression standard. Les données envoyées à Onyx Server par ce protocole LPR sont réceptionnées en local par le programme '''map_lpd''', puis ce dernier ordonne au Spooler d’insérer le document dans la bonne file d’attente.

Trois paramètres sont requis pour cette commande :

-server :NNN.NNN.NNN.NNN : adresse IP (ou nom DNS) du serveur Onyx Server

-queue:XXX : le nom de la file d’attente dans laquelle le fichier sera envoyé

-data:XXX : le chemin complet du fichier à envoyer

De plus, suivant la configuration, le server d’écoute LPD de Onyx Server n’utilise pas forcément le port 515 (port d’impression standard, peut-être déjà utilisé par une autre application). Dans ce cas, il faudra préciser le port réseau Mapping par l’argument : -port:NNN.

D’autres paramètres sont disponibles sur cette commande (argument --help pour les lister), les plus courants étant identiques à la commande map_lp.

<u>Exemple :</u> les commandes suivantes ajoutent un spool en attente dans la file d’attente INPUT_DATA appartenant à l’utilisateur mapadmin, qui possède un délai de rétention de 15 jours et qui passera en état conservé lorsqu’il sera traité.

Sous Windows :

 E:\App\Mapping_client\map_lpr -server:192.168.217.57 &quot;-queue:INPUT_DATA&quot; -map_hold -map_save 
 -map_retention:15 -user:mapadmin  &quot;-data:D:\Data\extract\FR_DEMO.txt&quot;

Sous Linux :

 /apps/mapping_client/map_lpr -server:192.168.217.57 &quot;-queue:INPUT_DATA&quot; -map_hold -map_save 
 -map_retention:15 -user:mapadmin  &quot;-data:/opt/data/extract/FR_DEMO.txt&quot;

==Gestion des Workflows==

===Introduction===

Les Workflows composent le Moteur d’exécution ONYX Server. Un Workflow est défini comme un ensemble de conditions et commandes paramétrables, exécutées lorsqu’un nouveau fichier arrive sur un connecteur d’entrée (robot Scanfolder, serveur d’écoute, point d’entrée, ou par requête Web Service). Les commandes sont traitées séquentiellement : la deuxième commande sera traitée après exécution correcte de la première, jusqu’à la fin du Workflow.

Un Workflow se définit graphiquement en connectant différents types d’objet : commandes, conditions et paramètres. Il est nommé de façon unique et doit être attaché à au moins un connecteur pour être actif.

Exemple de Workflow :

Le Workflow suivant, qui va être construit dans la suite de ce guide :

*Définit un paramètre en lisant une information dans le fichier en entrée
*Définit une condition en comparant la valeur de ce paramètre avec un mot clé
*Définit deux traitements, suivant que la condition est vraie ou fausse

Les Workflows sont sauvegardés sur disque dans des fichiers au format XML, dans le sous-répertoire « workflow » du répertoire des règles, pointé par la variable de configuration RULES_PATH.

Sur l’interface Web de ONYX Server, la page d’administration et configuration des Workflows s’obtient par le Menu d’Administration, puis Gestion des Workflows.

<u>Conseil :</u> pour un meilleur confort d’utilisation, le navigateur Firefox est vivement recommandé.

===Barre d’outils===
[[Fichier:OX S workflowToolbar.png|alt=|centré]]


[[Fichier:OX S iconewrkflw.png|but_new]] Créer un nouveau Workflow. Saisir un nom pour le Workflow, l’extension .rules.xml est automatiquement ajoutée.

[[Fichier:OX S workflowFolder.png|30x30px|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\menu\but_open.jpg]] Ouvrir un Workflow. Sélectionner un Workflow dans la liste.

[[Fichier:OX S workflowSave.png|28x28px|but_save.jpg]] Sauvegarder le Workflow actif.

[[Fichier:OX S workflowSaveAs.png|28x28px|but_saveAs.jpg]] Sauvegarder le Workflow actif sous un autre nom.

[[Fichier:OX S workflowDelete.png|27x27px|but_delete.jpg]] Supprimer le Workflow actif.

[[Fichier:OX S workflowCondition.png|28x28px|condition.png]] Insérer une condition dans le Workflow actif. La nouvelle condition sera ajoutée après la boite sélectionnée.

[[Fichier:OX S cmd icone.png|28x28px|but_run.jpg]] Insérer une commande dans le Workflow actif. La nouvelle commande sera ajoutée après la boite sélectionnée.

[[Fichier:OX S iconewrkflwParam.jpg|29x29px|but_set.jpg]] Insérer un paramètre dans le Workflow actif. Le nouveau paramètre sera ajouté après la boite sélectionnée.

[[Fichier:OX S workflowReorganize.png|30x30px]] Redessiner le Workflow actif. Permet de redessiner graphiquement le Workflow : alignements des boîtes, des liens, etc…

[[Fichier:OX S workflowDuplicate.png|27x27px]] Dupliquer un objet. Permet de dupliquer, à l’identique (nom, paramètres, etc.) l’objet sélectionné, sans ses liens.

[[Fichier:OX S workflowTables.png|30x30px|but_EditResolve.png]] Gérer les tables de résolution. Permet de créer, modifier et supprimer des tables de résolutions

===Créer un nouveau Workflow===

Cliquer sur l’icône[[Fichier:OX S iconewrkflw.png|but_new]], nommer le Workflow puis valider :
[[Fichier:OX S newWrkfl.png|alt=|centré]]


Le nouveau Workflow s’affiche dans la fenêtre d’édition, avec une première boite, point de départ de la séquence de traitements à venir :
[[Fichier:OX S createWorkflowFactures.png|alt=|centré]]
<br />

===Ajouter un Paramètre===

====Définition====
[[Fichier:OX S WRKFL param.png|alt=|centré]]


Les objets de type paramètre permettent de définir la valeur d’un paramètre ou d’en créer un nouveau. Un paramètre peut ensuite être utilisé dans une condition ou une commande. Cela permet la réutilisation d’une valeur dans plusieurs commandes par exemple, tout en ne la définissant qu’une seule fois.

====Création / Modification====

Pour créer un nouveau paramètre, sélectionner la boite après laquelle le nouveau paramètre doit être ajouté, puis cliquer sur l’icône[[Fichier:OX S iconewrkflwParam.jpg|but_set.jpg]]. Pour éditer un paramètre existant, double-cliquer sur la boite correspondante.

La fenêtre d’édition de paramètre s’ouvre afin de définir les différents champs :
[[Fichier:OX S workflowSetParam.png|alt=|centré]]
<br />

*(1) Nom du paramètre à définir (requis)
*(2) Valeur à affecter (requis)
*(3) Titre de l’objet
*(4) Note (champs libre pour commentaires)

'''Remarque :'''

Un paramètre sera généralement réutilisé ultérieurement dans le Workflow, dans une condition ou une commande, voire même dans un autre Workflow. Il est conseillé de choisir des noms pertinents quant à l’information véhiculée.

====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 Onyx 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 :

{| class="wikitable"
!'''Type de fonction'''
!'''Contenu'''
!'''Icone'''
!'''Indicateur de type'''
|-
|Paramètre
|Paramètre de l’application
|[[Fichier:OX S paramIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_dict.png]]
|Texte en bleu
|-
|Aucune
|Texte libre ou liste
|aucun
|Texte en noir
|-
|RuleFile
|Valeur lue dans un fichier de données
|[[Fichier:OX S rulefileIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_file.png]]
|rulefile : keyword(Test)
|-
|Commande
|Retour d’une commande prédéfinie
|[[Fichier:OX S commandIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_command.png]]
|Command : cutposition
|-
|Cmd
|Retour d’une ligne commande
|[[Fichier:OX S cmdIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_cmd.png]]
|cmd : chemincomplet...
|-
|SQL
|Retour d’une requête SQL
|[[Fichier:OX S sqlIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_sql.png]]
|SQL : Select...
|-
|Table de résolution
|Retour d’une table de résolution
|[[Fichier:OX S resolveIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_resolve.png]]
|Resolve : TABLE[PARAM]
|-
|Rulefile multiple
|Valeurs lues dans un même fichier (XML)
|[[Fichier:OX S rulefileIcon.png|C:\Program Files\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_file.png]]
|rulefile_multiple : xml
|}

Chaque fonction d’aide à la saisie associée aux différents types de champs est détaillée dans le Guide Utilisateur de Onyx Server.

===Ajouter une Condition===

====Définition====

Les objets de type condition permettent de définir 2 traitements différents en fonction de la validité d’une condition. Les boites conditions sont donc <span class="underline">les seules</span> à avoir 2 sorties :

*en bas (''chemin direct'') si la condition est vraie
*à droite (''chemin détourné'') si la condition est fausse

[[Fichier:OX S wrkflFactures.png]]

Une condition est par définition une comparaison entre au moins 2 valeurs. Comme vu précédemment, 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.

====Création / Edition====

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[[File:media/image40.png|condition.png]]. Pour éditer une condition existante, double-cliquer sur la boite correspondante.

La fenêtre d’édition de condition s’ouvre afin de définir les différents champs :
[[Fichier:OX S condition.png|alt=|centré]]
<br />

*(1) Nom de l’objet condition
*(2) Titre de l’objet
*(3) Outils pour définir la logique de la condition : ajout/suppression d’un filtre, opérateurs logiques AND et OR
*(4) Filtres de condition
*(5) Opérateurs logiques entre les filtres
*(6) Note (champs 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' success » 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 :
[[Fichier:OX S conditionParam.png|alt=|centré]]
<br />

*(1) Valeur à comparer
*(2) Opérateur de comparaison
*(3) Valeur de comparaison

Les opérateurs de comparaison disponibles sont :

<ul>
<li><p>égal / différent : comparaison alphanumérique stricte entre 2 valeurs</p></li>
<li><p>contient / ne contient pas : recherche alphanumérique d’une valeur dans une autre</p></li>
<li><p>est vide / n’est pas vide : un paramètre a-t-il ou non une valeur ?</p></li>
<li><p>supérieur à / supérieur ou égal à : comparaison numérique</p></li>
<li><p>inférieur à / inférieur ou égal à : comparaison numérique</p></li></ul><p></p>Une condition peut être définie par plusieurs filtres de conditions. Le bouton [[Fichier:OX S iconeajoutcdt.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_add_elt.png]] 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 [[Fichier:OX S operateurAND.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_and_elt.png]] et [[Fichier:OX S operateurOR.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_or_elt.png]]. Dans l’exemple, la logique de condition vaut : filtre A et (filtre B ou filtre C). Enfin, le bouton [[Fichier:OX S deletecdt.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_del_elt.png]] 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====
[[Fichier:OX S cmdDesigner.png|alt=|centré]]
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 4 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 / Edition====

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[[Fichier:OX S cmd icone.png|but_run.jpg]]. 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 :
[[Fichier:OX S cmdCopy.png|alt=|centré]]
<br />

*(1) Type de traitement, parmi : Command, Cmd, Sql, Call
*(2) Nom de l’objet
*(3) Titre de l’objet
*(4) Sélecteur d’un groupe de commandes prédéfinies
*(5) Sélecteur de la commande prédéfinie à exécuter
*(6) Paramètres de la commande :
**Présente l’ensemble des paramètres requis ou optionnels pour la bonne exécution de la commande
**L’onglet Standard regroupe les paramètres principaux de la commande
**En fonction des commandes, d’autres onglets spécifiques présentent les paramétrages avancés
*(7) Note (champs libre pour commentaires)

====Les commandes prédéfinies (Command)====

Cette première famille de traitement regroupe les commandes &quot;génériques&quot; et natives d'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, citons notamment :

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

*<span class="underline">Standard :</span>

<ul>
<li><p>Nom du format M-Designer à appliquer. La liste des formats importés sur le serveur est disponible par le bouton l’aide à la saisie [[Fichier:OX S format.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_getMapDrawFormat.png]]</p></li>
<li><p>Numéro de séquence (00010, ou *MRG, ou *ALL, etc.)</p></li>
<li><p>Fichier d’entrée (le fichier de données)</p></li>
<li><p>Fichier de sortie (le document XPS produit)</p></li></ul>

*<span class="underline">Advanced :</span>

<ul>
<li><p>Langue de traduction (consulter le Guide Utilisateur de M-Designer pour l’utilisation des traductions)</p></li>
<li><p>Fichier XPS à incorporer comme calque, avec possibilité de reprendre ses index</p></li></ul>

*<span class="underline">Text options :</span>

<ul>
<li><p>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 »</p></li>
<li><p>Largeur de page : nombre de caractères maximum par ligne à lire dans le fichier de données en entrée</p></li>
<li><p>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 via le bouton d’aide à la saisie [[Fichier:OX S codePage.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_getcodepage.png]]</p></li></ul>

*<span class="underline">Output options :</span>

<ul>
<li><p>Page de début / page de fin : intervalle de pages à produire</p></li>
<li><p>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</p></li></ul>

'''Spooler / Imprimer :''' Envoi d’un spool dans une file d’attente du Spooler

*<span class="underline">Standard :</span>

<ul>
<li><p>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 [[Fichier:OX S queueList.png|C:\MAPPING\MappingWindows\MapHTTPServer\JS_Common\workflow\img\button_getqueue.png]]</p></li>
<li><p>Nom du fichier à envoyer</p></li>
<li><p>Titre : nom donné au spool dans la file d’attente</p></li>
<li><p>Envoyer le spool en état suspendu dans la file d’attente de destination</p></li>
<li><p>Conserver le spool après traitement dans la file d’attente de destination</p></li>
<li><p>Conserver les attributs courants : affecter au spool en sortie les attributs du spool en cours</p></li>
<li><p>Ajouter les paramètres courants : affecter au spool en sortie les paramètres de la session en cours</p></li></ul>

*<span class="underline">Page :</span>

<ul>
<li><p>Page de début / page de fin : positionne les attributs correspondants sur le spool de destination pour son intervalle de traitement</p></li>
<li><p>Nombre de copies : positionne l’attribut correspondant sur le spool de destination</p></li></ul>

*<span class="underline">Security :</span>

<ul>
<li><p>Propriétaire du spool de destination</p></li>
<li><p>Droits d’accès sur le spool de destination</p></li>
<li><p>Code comptabilité : affectation de l’attribut correspondant</p></li></ul>

*<span class="underline">Userdata :</span>

<ul>
<li><p>Possibilité de définir des attributs supplémentaires sur le spool de destination</p></li></ul>

*<span class="underline">Advanced :</span>

<ul>
<li><p>Priorité du spool de destination</p></li>
<li><p>Nombre de jours de conservation du spool de destination</p></li>
<li><p>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)</p></li>
<li><p>Type de support papier</p></li>
<li><p>Fidélité : attribut hérité du monde AS/400 parfois utilisé par certaines applications clientes en amont et en aval</p></li>
<li><p>Nom du fichier spool de destination</p></li></ul>

La liste exhaustive des commandes prédéfinies ONYX Server est détaillée dans le Guide Utilisateur.

====Les scripts utilisateurs (Cmd)====

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.
[[Fichier:OX S workflowCmd.png|alt=|centré]]

====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.
[[Fichier:OX S SQL CMD.png|alt=|centré]]
<br />

====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.
[[Fichier:OX S callWorkflow.png|alt=|centré]]
<br />

=Menus d’Exploitation=

Les deux derniers menus de la page d’accueil donnent accès aux deux écrans d’exploitation les plus utilisés de la solution : la gestion des travaux et des imprimantes (contenu du Spooler), et l’accès à l’ensemble des journaux d’événements de la Suite.

==Travaux / Imprimantes==

Cette première vue d’exploitation se présente sous deux onglets :

*La vue des travaux, qui liste l’ensemble des travaux présents dans le Spooler, dans leurs files d’attente respectives
*La vue des &quot;imprimantes&quot;, qui liste l’ensemble des files d’attente déclarées dans le Spooler, dans leurs sites respectifs.

===Gestion des Travaux===

La navigation dans ce menu « Travaux / Imprimantes » présente directement la vue d’exploitation des travaux du Spooler :

[[File:media/image71.png]]

Cette vue se décompose en 3 parties :

*La navigation par onglet entre la vue des travaux et la vue des imprimantes

'''Remarque :'''
<ul>
<li><p>L’arrivée sur la vue d’exploitation rafraichit automatiquement l’affichage avec les filtres proposés par défaut. La variable d’environnement LOAD_SPOOLS_ON_VIEW (on/off) permet de désactiver ce rafraichissement, pour permettre à l’utilisateur de renseigner ses filtres.</p></li>
<li><p>La bascule d’un onglet à un autre n'actualise pas la vue automatiquement, de manière à laisser l’opportunité à l’utilisateur de renseigner ses filtres d’affichage avant d’actualiser les résultats</p></li></ul>

*Un bandeau de filtres de l’affichage, permettant de limiter le nombre de résultats renvoyés ou d’effectuer une recherche sur un élément précis

'''Remarque :'''

Des filtres sont renseignés par défaut à l’arrivée sur la vue : sur le propriétaire des travaux (utilisateur connecté), sur les dates (un jour d’historique). Les filtres peuvent être modifiés, le bouton « Actualiser » actualise la liste des résultats en fonction des filtres renseignés.

*La liste des résultats : tous les travaux correspondant aux différents filtres renseignés, regroupés par site, file d’attente, et état. L’ordre d’affichage des travaux dans chaque groupe d’affichage respecte les priorités affectées à chaque travail, puis les dates d’arrivées dans la file d’attente.

Pour chaque travail, les actions suivantes sont accessibles :

[[Fichier:OX S stopPrn.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\littlestopspool.png]] Suspendre le travail. Les travaux en état conservé, en erreur ou en cours de traitement peuvent être suspendus.

[[Fichier:OX S restartPrn.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\littlestartspool.png]] Libérer le travail. Les travaux en état suspendu, conservé ou en erreur peuvent être libérés.

[[Fichier:OX S deleteWork.gif|C:\MAPPING\MappingWindows\MapHTTPServer\images\littlecancel.gif]] Supprimer le travail.

[[Fichier:OX S transferJob.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\transfert.png]] Transférer le travail dans une autre file d’attente.

[[Fichier:OX S showJob.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\spool_view.png]] Visualiser le contenu du travail.

[[Fichier:OX S printJob.gif|C:\MAPPING\MappingWindows\MapHTTPServer\images\printer.gif]] Imprimer le travail à travers le Web (sous Windows uniquement, permet d’envoyer le travail sur une imprimante déclarée dans le Spooler Windows du poste).

[[Fichier:OX S pageRecovery.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\reprint_page.png]] Effectuer une reprise de page (pour demander la réimpression du travail de la page 5 à la page 12 par exemple).

[[Fichier:OX S infos rbt.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\view_log.png]] Consulter le journal d’événement du travail.

[[Fichier:OX S jobAttribute.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\view_info.png]] Afficher les attributs du travail.

===Gestion des imprimantes===

Dans la vue précédente, seules les files d’attentes contenant des travaux seront affichées dans les résultats. L’onglet « Imprimantes » permet de lister l’ensemble des files d’attente déclarées dans le Spooler :

[[File:media/image81.png]]

Cette vue suit le même principe de décomposition en trois parties :

*Les onglets de navigation
*Le bandeau de filtres
*La liste des résultats.

Pour chaque file d’attente, les actions suivantes sont accessibles :

[[Fichier:OX S Start.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\play.png]] Démarrer une file d’attente (ou une device). Les files d’attentes en état suspendu peuvent être démarrées.

[[Fichier:OX S Stop.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\stop.png]] Arrêter une file d’attente (ou une device). Les files d’attentes en état démarré peuvent être arrêtées.

[[Fichier:OX S jobAttribute.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\view_info.png]] Afficher les informations de paramétrage d’une file d’attente (ou d’une device).

[[Fichier:OX S infos rbt.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\view_log.png]] Consulter le journal d’événement d’une file d’attente.

[[Fichier:OX S showJob.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\spool_view.png]] Visualiser les travaux contenus dans une file d’attente. Renvoi sur l’onglet « travaux », avec un filtre activé sur la file d’attente.

[[Fichier:OX S refreshDevice.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\refresh.png]] Rafraichir l’état d’une device (dans le cas où l’interrogation est paramétrée dans la configuration de la device).

[[Fichier:OX S OK.png|C:\MAPPING\MappingWindows\MapHTTPServer\images\ok2.png]] Réinitialiser une device : permet de redémarrer une device en erreur.

==Consulter la log==

Cet écran permet de consulter l’ensemble des journaux d’événements de la solution Onyx Server :
[[Fichier:OX S logFileList.png|alt=|centré]]


Chaque processus ou objet possède son journal :

*Le Spooler (map_daemon.log)
*Le serveur d’écoute LPD (map_lpd.log)
*Le processus d’écoute des requêtes Web Service (mapsoapserver.log)
*Les robots Scanfolder (scan_folder_XXX.log)
*Les Serveurs d’écoute Rawd (map_rawd_XXX.log)
*Les files d’attente (INPUT_DAT.log par exemple)

Chaque journal d’événement peut être :

[[Fichier:OX S showLog.png|C:\PROJETS\Built-Setup\Sources\Branch_v7_2_0\install\AllVersion\httpd\images\littleview.gif]] Consulté (en cliquant également sur le nom du journal)

[[Fichier:OX S txtConvert.png|C:\PROJETS\Built-Setup\Sources\Branch_v7_2_0\install\AllVersion\httpd\images\small_txt_file.png]] Converti au format texte pour affichage dans un éditeur de texte

[[Fichier:OX S xmlConvert.png]] Converti au format XML

[[Fichier:OX S cleanLog.png|C:\PROJETS\Built-Setup\Sources\Branch_v7_2_0\install\AllVersion\httpd\images\interface_small_cancel_edit.png]] Nettoyé : le journal existe toujours mais son contenu est vidé

[[Fichier:OX S deleteWork.gif|C:\MAPPING\MappingWindows\MapHTTPServer\images\littlecancel.gif]] Supprimé

Exemple de contenu du journal d’événement d’une file d’attente d’impression :
[[Fichier:OX S logExample.png|alt=|centré]]


Les trois types d’événement tracés ici sont :

*OK (succès) : Lancement de la commande d’impression (dialogue LPR avec l’imprimante physique, initié par la commande map_lpr)
*EE (erreur) : Erreur de connexion avec l’imprimante : le délai précisé dans la configuration de la file d’attente est atteint avant que la connexion puisse être établie (raison la plus probable : l’imprimante physique est éteinte, ou débranchée du réseau)
*WW (information) : le comportement de la file d’attente sur les erreurs est pris en compte

Le bandeau de filtres sur ces écrans de consultation permet d’affiner les résultats :

*Niveau : afficher uniquement les événements en erreur par exemple
*Dates : afficher les événements produits sur un intervalle de durée
*Filtre : recherche d’un mot ou expression dans les messages associés aux événements

=Maintenance ONYX Server=

Cette partie traite des tâches régulières de maintenance qui doivent être planifiées sur le serveur, afin de conserver un fonctionnement optimal pour l’environnement ONYX Server.

Les différentes commandes ci-dessous pourront être regroupées dans un script global d’épuration, dont l’exécution sera planifiée automatiquement sur le serveur :

*Gestionnaire des Tâches Planifiées sous Windows
*CRONTAB sous Linux

==Nettoyage des fichiers du Spooler==

Dans son fonctionnement normal, le Spooler créé et conserve un certain nombre de fichiers qu’il est conseillé de régulièrement épurer : travaux conservés, journaux d’événements, statistiques. Ces opérations sont réalisables par une commande ONYX Server : '''map_cron'''.

===Epuration des travaux===

Tous les travaux circulant dans le Spooler possèdent un attribut spécifique : la durée de rétention (en nombre de jours). L’épuration des travaux dans le Spooler se base sur cet attribut pour nettoyer tous les travaux arrivés « à échéance », c’est-à-dire dont la durée de rétention est dépassée.

Deux commandes ONYX Server existent :

*'''Suppression de tous les travaux <span class="underline">conservés</span> (donc ayant été traités) dont la durée de rétention est dépassée :'''

Linux : <code>/apps/mapping/bin/map_cron -date</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -date</code>

*'''Suppression de tous les travaux (quel que soit leur état) dont la durée de rétention est dépassée :'''

Linux : <code>/apps/mapping/bin/map_cron -dateall</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -dateall</code>

'''Remarque :'''

Pour fonctionner, l’exécution de ces commandes doit se faire avec le Spooler en état de marche. En effet, seul le Spooler peut interagir avec ses travaux, les commandes précédentes ne faisant qu’envoyer des requêtes de suppression au Spooler.

===Epuration des journaux d’événements===

La commande <code>map_cron</code> permet également de nettoyer les fichiers correspondants aux journaux d’événements d'ONYX Server. Des options permettent de conserver des archives des journaux d’événements avant leur suppression, pour historique.

*'''Création d’une archive (ZIP) des journaux avant suppression :'''

Linux : <code>/apps/mapping/bin/map_cron -cleanlog</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -cleanlog</code>

L’archive est conservée par défaut à la racine du répertoire des logs (variable PATH_LOG de la configuration), nommée en fonction de la date/heure d’exécution de la commande.

Exemple : 2014_07_25_15_16.zip

*'''Suppression des journaux sans sauvegarde :'''

Linux : <code>/apps/mapping/bin/map_cron -cleanlog -delete</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -cleanlog -delete</code>

===Epuration des statistiques===

Sur le même principe que précédemment, les fichiers correspondants aux statistiques et rapports d’utilisation peuvent être nettoyés :

Linux : <code>/apps/mapping/bin/map_cron -cleanstats [ -delete ]</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -cleanstats [ -delete ]</code>

==Nettoyage des fichiers temporaires==

En fonctionnement normal, un certain nombre de fichiers sont créés dans le répertoire temporaire d'ONYX Server (variable PATH_TEMP dans la configuration) : fichiers de connexion à l’interface Web (cookies), fichiers issus des traitements de Workflows, etc.

La commande <code>map_cron</code> permet de supprimer tous les fichiers cookies, en ne conservant qu’un historique d’un jour :

Linux : <code>/apps/mapping/bin/map_cron -cleanid</code>

Windows : <code>E:\MappingWindows\Applications\map_cron.exe -cleanid</code>

La commande <code>map_del</code> nettoie le contenu d’un répertoire, en filtrant sur un nom ou sur une extension. Les exemples de commandes suivants sont fréquemment utilisés dans un script d’épuration ‘standard’ pour ONYX Server :

Linux :

 /apps/mapping/bin/map_del -path:/apps/mapping/temp -filter_ext:tmp 

 /apps/mapping/bin/map_del -path:/apps/mapping/temp -filter_ext:ttf

 /apps/mapping/bin/map_del -path:/apps/mapping/temp -filter_ext:xps

 /apps/mapping/bin/map_del -path:/apps/mapping/temp -filter_name:*.0

 /apps/mapping/bin/map_del -path:/apps/mapping/temp -filter_name:*.1

Windows :

 E:\MappingWindows\Applications\map_del.exe -path:E:\MappingWindows\Applications\Temp -filter_ext:tmp

 E:\MappingWindows\Applications\map_del.exe -path:E:\MappingWindows\Applications\Temp -filter_ext:ttf

 E:\MappingWindows\Applications\map_del.exe -path:E:\MappingWindows\Applications\Temp -filter_ext:xps

 E:\MappingWindows\Applications\map_del.exe -path:E:\MappingWindows\Applications\Temp -filter_name:*.0

 E:\MappingWindows\Applications\map_del.exe -path:E:\MappingWindows\Applications\Temp -filter_name:*.1
            
            [[Category:PrivateData]]