Using ONYX Server

ONYX Server: General principles

Software

ONYX Server is the production engine of the Mapping Suite on Linux and Windows. Apart from their specific features (file system, user rights management), the values, configuration, the way the engine works and is used are identical on both platforms.

The ONYX Server engine mainly relies on its job manager (called Spooler or Output Manager), a scheduler which processes, prints and distributes documents, from their input into the engine to their output towards the end users. Combined with the Mapping Spooler, the Workflows engine allows you to automate the entire output production chain as well as all the processings to run on documents: data extraction, graphical formatting and mapping, indexing, sorting / splitting, routing, omnichannel distribution, etc.

Diagram of the general operations

ONYX Server manages the entire output production chain of the company. The Spooler (or Output manager) and the Workflows engine constitute the nerve center of the solution. They centralise and schedule every query coming from various sources and are subject to multiple protocols (LPR, RAW, FTP/SFTP, Web Service), they apply processing, mapping, routing, and omnichannel distributing rules to them.

Administration / Operations interface

If the ONYX Server is a fat client installed on the target platform, its administration and operation tasks can be carried out remotely via web browser (minimum Internet Explorer 8.0, Firefox, Google Chrome). This thin client access is supported by the Apache HTTP Server software which is the only software required to install ONYX Server.

Access, logging in

To access the ONYX Server Web interface, the DNS name or IP address of the server as well as the HTTP port used for Mapping (8002 on a "Typical" installation) must be known. The adress which needs to be typed in your browser uses this syntax: http://192.168.216.29:8002

Access to the ONYX Server Web interface is controlled and secured. Although it is possible to interface ONYX Server with an Active Directory directory service or an existing LDAP, the first login to the interface is done through the Apache server, with the admin account of the solution which was specified upon installation of the software, that is to say "mapadmin" by default:

Home page

Once logged in, the ONYX Server home page offers access to different menus:

• Development Menu (1): Manages M-Connect and M-Designer formats, gives access to customised menus to go along with M-Connect formats
• Administration Menu (2): Manages the overall configuration of the solution, manages access rights, creates input points, managing rules (Workflows), output printers and document distribution rules, manages roll-outs between ONYX Server servers
• Operations Menu (3): Manages jobs, queues, access to event logs

A drop-down menu provides quick access to the entire menu tree-structure at any time during navigation:

Lastly, At the bottom of the screen, on the left, in addition to session information (logged in user, date and time) and the version number of ONYX Server, a navigation bar allows you to:

• Come back to the previous menu (integrated management of the navigation history, unlike the "Previous" button of your browser)
• Refresh the current page
• Come back to the main menu
• Log off

Development Menus

The first three menus of the user interface are called "Development" screens, they allows you to manage document template libraries which were created with the Connect and Designer tools.

Managing Designer

The different screens respectively allow you to:

• Import Designer formats which were generated from the tool, so that they can be available to and used by the processing rules of the ONYX Server engine
• View and reinitiate the List of Objects and resources used in Designer formats which can be seen in the server (imported or not)
• View the list of Designer Formats in production on the server, you can delete each format from the server or roll them out to another ONYX Server environment.
• Declare, configure and manage the different Conversion Rates which can be used in Designer formats.

Managing Connect

The different screens respectively allow you to:

• Import Connect formats which were generated from the tool, so that they can be available to and used by the processing rules of the ONYX Server engine
• Manage and view the list of Connect formats in production on the server, you can delete each format from the server or roll them out to another ONYX Server environment.
• Execute a Connect format in interactive mode, so that, for instance, you can confirm that the server is running smoothly
• Start and Stop the Connect development engine on the server which allows users to create previews.
• Retrieve the definitions of databases tables which were interfaced with the Connect tool, the resulting files are then imported into the tool to create the internal structure of data in the developed Connect formats.

Customised Menus

This screen gives you access to interactive interfaces which allow you to execute Connect formats upon request, to create output production queries. These interfaces are developed from the Connect tool, generated and imported with the corresponding format(s), and can answer to a need of production upon request, they, however, cannot be automated.

Administration Menu

This menu gives access to the configuration of the solution, the creation and administration of ONYX Server input points (Scanfolder robots, listening servers, processing queues), execution and routing rules (Workflows), output points and distribution of documents.

The main screens are the only ones regarded in this documentation, for more information see the User Guide of the solution.

Managing the configuration

This screen displays all the environment parameters of the solution from its installation to its general configuration.

Most values featured here are only informative and must not be changed unless explicitly requested. The User guide of the solution provides more information on values which can be changed as well as their behaviour depending on the context of the application.

Managing robots

This screen can manage all the "robots" configured in the solution, whether they are Scanfolder robots or listening Servers. Upon first installation, the list of robots is blank but it gives access to the creation / editing screen for new input points in ONYX Server:

From the perspective of ONYX Server, a robot is an entry point into the solution, a way for a third party application to send an execution query. Robots are programs executed as background tasks (in Service mode under Windows) to monitor data delivery: in a folder in the case of Scanfolder robots, on a network port in the case of listening servers. Each file received is handled by the Workflow execution engine, to then carry out the appropriate processing.

Scanfolder Robots

Introduction

• Scanfolder robots monitor a file system folder searching for input files (transferred by copy or FTP/SFTP). Files detected in the folder are sent one by one to the execution engine to be processed according to the rules defined in the Workflows.
• A robot which was configured in ONYX Server can only monitor one file, the same way a folder of the file system can only be monitored by one Scanfolder robot. There can be as many scanfolder robots created and configured as there are folders to monitor. Each robot is independent from the others, so several files can be processed by different robots at the same time.

Creating / Editing / Deleting

This screen gives you access to the list of robots which are already configured, each robot can be edited if necessary (and if it is not currently running). The last bloc which contains two blank lines allows you to create a new Scanfolder robot:

Parameters to specify to configure the robot:

Name: gives a name to the robot.

• This parameter is optional, but it is highly recommended: the name of each robot is an environment variable which is accessible and can be used in Workflows.
• ONYX Server checks that the names used for the different robots are unique.

* Folder to scan: Complete path of the folder scanned by the robot.

• This parameter is required.
• It can point to a network drive or a UNC path (under Windows), in this case be careful to have access rights.
• ONYX Server checks that the names of the folders monitored by the different robots are unique.
• ONYX Server can create the folder specified if it does not already exist.

* CMD: action run on every detected file after it was properly processed by the execution engine.

• This parameter is required.
• Delete: Files which were detected and processed are deleted from the monitored folder.
• Move: Files which were detected and processed are moved to another folder, for the history for instance.

* Destination folder: destination path of processed files.

• This parameter is required if the move command was previously chosen.
• ONYX Server checks that the destination folder is different from the monitored folder.
• ONYX Server can create the folder specified if it does not already exist.

* Delay: waiting time interval in between two folder scans, given in seconds.

• This parameter is required.

* On Error: defines the robot's behaviour when a processing error is reported on a detected file.

• This parameter is required.
• Stop: the robot stops, the file in error status stays in the monitored folder.
• Continue : the robot continues to process the next files, the file in error status stays in the monitored folder, renamed with the suffix " _FAILED " (Mapping keyword to prevent the robot from processing this file again during the next folder scan).
• Retry: the robot continues to process the next files, the file in error status stays in the monitored folder. The robot will try to process the file again next time it scans the folder.

Workflow: name of the Workflow to execute.

• This parameter is optional. If not specified the root Workflow is executed by default.

Filter: excludes files from being scanned by the robot.

• This parameter is optional.
• Example: *.tmp files in the monitored folder are not processed by the robot.

Accept: limits the type of files to process.

• This parameter is optional.
• Example: only *.xml files in the monitored folder are processed by the robot.

To create a new robot, all the parameters needed the click on the button to add the robot to the server configuration.

To edit an existing robot, edit it or the parameters concerned then click on the button to edit the robot in the server configuration.

Note: A robot must be stopped for you to edit it.

To delete an existing robot, click on the button. The robot will be deleted from the server configuration.

Note: A robot must be stopped for you to delete it.

Usage

Once the robots created and configured, they appear on the managing screen:

This screen allows you to:

• Start a robot:
• Stop a robot:
• See the log of a robot:

Once started, a robot is a process which is continuously executed as a background task. The ONYX Server binary which is associated with it is map_scanfolder, the list of active system processes (Task Manager under Windows, ps –ef command under Unix) will display as many map_scanfolder[.exe] processes as there are robots started.

Note:

Under Windows, robots are installed as Services in the Windows Service Manager. This is registered the first time the robot is started. The corresponding Service is named base on the name of the robot if specified (which is why the names of the robot must be different) in the monitored folder (which is why the names of the folders must be different). Example: Mapping_ScanFolder_SCAN_TXT.

Each Windows Service created by the robot is configured in manual start by default, this can be switched to an automatic system start afterwards.

Temporary files associated with the robots:

Once started, each robot creates two files in the ONYX Server temporary folder. The first one is named based on the name of the monitored folder, special characters are replaced with ‘_’, and the suffix " map_scanfolder.ID " is added. Example: E__InputData_TXT_map_scanfolder.ID

The second one is named with the system number of the process map_scanfloder[.exe] associé. Example: 75668.pid.

These files are intended for internal use of the process only and will be deleted once the robot is stopped.

However, the Web interface relies on these files to indicate the status of the robots.

Useful command lines:

• To start a robot:

Linux (after the environment was loaded):

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

Windows:

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

• To stop a robot:

Linux (after the environment was loaded):

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

Windows:

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

• If the robot is not named, set each parameter that describes the robot as an argument of the previous commands (hence the prior advice on robots unique names)

Listening Servers

Introduction

• A listening server monitors a network port, searching for received data (data is sent via a remote system by direct transfer in RAW protocol). The robot receives data and builds files locally, it then sends them one by one to the execution engine to be processed according to the rules defined in the Workflows.
• A robot configured in ONYX Server can only monitor one network port, and a network port can only be monitored by listening server. There can be as many listening servers created and configured, as there are ports to monitor. Each robot is independent from the others, so several files can be processed by different robots at the same time.

Creating / Editing / Deleting

The following screen displays the list of robots which are already configured, each robot can be edited if necessary (if it's not currently being run). The last blank line allows you to create a new listening server:

Parameters to specify to configure a listening server:

Name: gives a name to the robot.

• This paramètre is optional, but t is highly recommended: the name of each robot is an environment variable which can be accesed and used by the Workflows.
• ONYX Server checks that the names used for the different robots are unique.

* Port: number of the network port the robot listens to.

• This parameter is required.
• ONYX Server checks that the names of the ports the different robots listen to are unique.

Job separator: character or chain which divides a large network stream into several files.

• This parameter is optional.

Key (start/length): adds information to the name of the temporary file built by the robot.

• These 3 parameters are optional.
• The information is searched in the network stream, using a keyword, ignoring X characters after the keyword (" start " parameter), retrieving N characters (" length " parameter).
• This information can be used in the Workflows, notably as a condition.

Timeout: network waiting time, given in seconds.

• This parameter is optional.
• Prevents the network port from being blocked in case of problem with the stream transmitter: the robot cuts connection after this inactivity period, as it considers the established connection is no longer active.

To create a new listening server, fill in all the needed parameters, then, click on the button to add it to the server configuration.

To change an existing server, edit it or its parameters, then, click on the button to edit the server configuration.

Note: The server must be stopped for you to change it.

To delete an existing listening server, click on the button. The robot is then deleted form the server configuration.

Note: The robot must be stopped for you to delete it.

Usage

Once created and configured, the robots appear on the managing screen:

This screen allows you to:

• Start a listening server:
• Stop a listening server:
• See the log of a listening server:

Once started, a listening server is a process which is continuously executed as a background task. The associated ONYX Server binary is map_rawd, the list of active system processes (Task Manager under Windows, ps –ef command under Unix) will display as many map_rawd[.exe] processes as there are listening servers started.

Note:

Under Windows, listening servers are installed as Services in the Windows Service Manager. This is registered the first time the robot is started. The corresponding Service is named base on the name of the network port the robot listens to (which is why the names of the ports must be different) in the job separator. Example: Mapping_Rawd_13000, Mapping_Rawd_25006_SEP.

Each Windows Service created by the robot is configured in manual start by default, this can be switched to an automatic system start afterwards.

Temporary files associated with the listenign servers

Once started, each listening server creates a file in the ONYX Server temporary folder. It is named based on the name of the network port it listens to as well as the name of the job separator, with a map_rawd.ID file which includes the number of the associated process. Example: …\Temp\map_rawd_25006_SEP\map_rawd.ID.

Useful command lines:

• To start a robot:

Linux (after the environment was loaded):

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

Windows:

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

• To stop a robot:

Linux (after the environment was loaded):

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

Windows:

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

• If the robot is not named, set each parameter that describes the robot (listenin port and job separator) as an argument of the previous commands (hence the prior advice on robots unique names)

Managing the Spooler

As mentioned previously, the Onyx Server Spooler is the heart of the solution. It is a real stream, processing and printer manager. The interface displayed when navigating through the Administration Menu, to Managing print jobs, and finally Managing the Spooler, allows you to:

• Start the Spooler
• stop the Spooler
• See output production statistics
• See solution usage reports

Once started, the Spooler is a process which is continuously executed as a background task. The associated Onyx Server binary is map_daemon[.exe].

Note:

Under Windows, the Spooler is installed as a Service in the Windows Service Manager. This is registered the first time the Spooler is started. The corresponding Service is named Mapping_Spooler. It is configured in manual start by default, this can be switched to an automatic system start afterwards.

Temporary files associated with the Spooler:

Once started, the Spooler creates a "map_daemon.ID" file in in its OnyxServer installation folder: C:\ProgramData\MappingWindows\Spooler by default under Windows, /apps/mapping/spool by default under Linux.

Useful command lines:

• To start the Spooler:

Linux (after the environment was loaded):

/apps/mapping/bin/map_daemon start

Windows:

E:\MappingWindows\Applications\map_daemon.exe start

• To stop the Spooler:

Linux (after the environment was loaded):

/apps/mapping/bin/map_daemon stop

Windows:

E:\MappingWindows\Applications\map_daemon.exe stop

Managing Sites and Queues

The interface displayed when navigating through the Administration Menu, to Managing print jobs, and finally Managing Queues / Devices / Input, gives you access to the list of all queues configured in the Spooler, potentially being organised per site:

Here for example, a "SAMPLE" site was declared in which 3 queues (one input queue and two output queues) are configured. 3 other queues are declared outside of sites and displayed in a default site called Main.

Using this interface, inside each site, you can:

Create a site. Sites are a logical way of organising queues

Create an output queue linked to a physical printer

Create a customised processing queue which executes a client queue (shell)

Create a Mapping processing queue which executes a Workflow

Important notes:

• All the created and configured objects must have a unique name no matter their type (an output printer must not have the same name as a site).

• Once created and configured, the name of an object cannot be changed anymore. If necessary, the object must be deleted and then recreated.

Creating a site

Sites allow you to classify Spooler queues so that print jobs can be managed within a hierarchical way. Sites can also be used as display filters or search filters in the operations view.

To create a site, click on the button.

Note:

It is possible to create sites within a site, this allows you to manage a complex tree view. To do so, use the creation button on the line of the concerned site.

Fill in each of the following information in the input screen and validate it by clicking on :

• (1) Name for the site (required)
• (2) Description

Once the site configuration finished, the new site needs to be saved, click on (3).

Creating a (simple) input point

An ONYX Server input point is a queue which executes Mapping processings (Workflows). It is made up of two objects:

• A queue to receive queries (jobs)
• A "device" or engine, to handle queries and carry out processings

To add an input point to a site, click on the button, on the line of the concerned site.

The following input screen gives you access to several tabs, the first one is the only one this documentation will detail. Refer to the User Guide for more details on the advanced configuration options.

Fill in the needed information and validate it by clicking on .

Queue

• (1) Name for the queue (required)
• (2) Description for the queue

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

Device

• (3) Name for the associated device (required)
• (4) Description for the device

Driver

• (5) Type of driver: RULES by default, this cannot be changed (this is the execution engine which is called)
• (6) Executed Workflow, has to be chosen in the drop down menu. By default (‘Default’ or ‘undefined’), the root Workflow is executed.

Monitoring

• (7) Behaviour of the device upon error:
  • default or stop: the current processing stops in error status, the device stops in error status.
  • continue: the current processing stops in error status, the device continues to process the next queries.
  • ignore: the current processing as considered as done, the device continues to process the next queries. This value is not recommended, except for very specific cases.
• (8) Automatic recovery: if activated, an error inducing processing is relaunched
• Timeout: maximum time during which a processing in error status is relaunched before it is actually considered as being in error status. The behaviour of the device upon error is then taken into account.

Note:

Automatic recovery is not necessarily recommended on input queues. If a Workflow triggers an error, chances are this error will keep happening as long as the Workflow is not fixed.

Once the (simple) configuration of an input point done, the new object needs to be saved, click on (9).

Creating a (simple) printer

An ONYX Server printer is a queue which communicates a physical printer. It is made up of two objects:

• A queue which receives queries (jobs)
• A "device" or printer, which handles queries and sends data to the physical printer.

To add a printer to a site, click on the button on the line of the concerned site.

The following input screens gives you access to several tabs, the first one is the only one this documentation will detail. Refer to the User Guide for more details on the advanced configuration options.

Fill in the needed information and validate it by clicking on .

Queue

• (1) Name for the queue (required)
• (2) Description for the queue

Validating the name of the queue gives you access to the creation form of the associated device.

Device

• (3) Name for the associated device (required)
• (4) Description for the device
• (5) Backup: if activated this allows you to create a backup printer which will automatically replace the main printer in case of error.

Driver

• (6) Connection: Onyx Server implements several types of communication protocols, the LPR protocol is the most used here (refer to the User Guide for more details on the other protocols).
• (7) Print job: "default" indicates a link to a physical printer, "MAPPING" indicates a communication with another (remote) Onyx Server Spooler and allows you to activate the compression of streams.
• (8) XPS compatibility: allows you to communicate with the linked physical printer in its direct printing language. The XPS streams are converted on the fly according to the selected profile then sent to the printer. This operation does not depend on any driver.
• (9) IP address of the physical printer
• (10) Internal name of the physical printer: generally PASS if it is directly linked to the network, or the name of the port on the box (HP JetDirect for instance) is it is used to link the printer to the network.
• (11) Time: maximum waiting time for a network communication.

Status

This allows you to ask the physical printer for its status, which will be displayed in the operations view.

Monitoring

This allows you to ask the physical printer to control the real status of the print job. This additional communication is detailed in the User Guide, the default parameters are enough for the moment.

• (12) Behaviour of the device upon error:
  • default or stop: the current processing stops in error status, the device stops in error status.
  • continue: the current processing stops in error status, the device continues to process the next queries.
  • ignore: the current processing is considered as done, the device continues to process the next queries. This value is not recommended, except for very specific values.
• (13) Automatic recovery: if activated, an error inducing print job is relaunched
  • Timeout: maximum time during which the print job in error status is relaunched before it is actually considered as being in error. The behaviour of the device upon error is the n taken into account.
  • Recovery mode: in its entirety or per page

Once the (simple) configuration of the printer is finished, the new object needs to be saved, click on (14).

Sending a file to a queue

The ONYX Server Spooler is seen as a 'virtual' printer from a third-party application. Print commands are used to send files to a queue of the Spooler.

ONYX Server has its own print commands: map_lp locally and map_lpr remotely.

MAP_LP locally

MAP_LP is a direct query sent to the ONYX Server Spooler (the map_daemon program answers it).

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

Exemple : 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 "-queue:INPUT_DATA" "-map_hold" "-map_save" 
"-map_retention:15" "-user:mapadmin" "-data:D:\Data\extract\FR_DEMO.txt"

Sous Linux :

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

MAP_LPR remotely

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.

Exemple : 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 "-queue:INPUT_DATA" -map_hold -map_save 
-map_retention:15 -user:mapadmin  "-data:D:\Data\extract\FR_DEMO.txt"

Sous Linux :

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

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.

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

Barre d’outils

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

Créer un nouveau Workflow

Cliquer sur l’icône, nommer le Workflow puis valider :

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 :

Ajouter un Paramètre

Définition

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. 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 :

• (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 :

Type de fonction	Contenu	Icone	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		rulefile : keyword(Test)
Commande	Retour d’une commande prédéfinie		Command : cutposition
Cmd	Retour d’une ligne commande		cmd : chemincomplet...
SQL	Retour d’une requête SQL		SQL : Select...
Table de résolution	Retour d’une table de résolution		Resolve : TABLE[PARAM]
Rulefile multiple	Valeurs lues dans un même fichier (XML)		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 les seules à avoir 2 sorties :

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

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ônecondition.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 :

• (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 :

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

Les opérateurs de comparaison disponibles sont :

• égal / différent : comparaison alphanumérique stricte entre 2 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). Enfin, 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 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. 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 :

• (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 "génériques" 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

• Standard :

• Nom du format M-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 M-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 via 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

• 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

• Userdata :

• 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 AS/400 parfois utilisé par certaines 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 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.

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.

Operations Menu

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 "imprimantes", 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 :

Cette vue se décompose en 3 parties :

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

Remarque :

• 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.

• 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

• 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 :

Suspendre le travail. Les travaux en état conservé, en erreur ou en cours de traitement peuvent être suspendus.

Libérer le travail. Les travaux en état suspendu, conservé ou en erreur peuvent être libérés.

Supprimer le travail.

Transférer le travail dans une autre file d’attente.

Visualiser le contenu du travail.

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).

Effectuer une reprise de page (pour demander la réimpression du travail de la page 5 à la page 12 par exemple).

Consulter le journal d’événement du travail.

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 :

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 :

Démarrer une file d’attente (ou une device). Les files d’attentes en état suspendu peuvent être démarrées.

Arrêter une file d’attente (ou une device). Les files d’attentes en état démarré peuvent être arrêtées.

Afficher les informations de paramétrage d’une file d’attente (ou d’une device).

Consulter le journal d’événement d’une file d’attente.

Visualiser les travaux contenus dans une file d’attente. Renvoi sur l’onglet « travaux », avec un filtre activé sur la file d’attente.

Rafraichir l’état d’une device (dans le cas où l’interrogation est paramétrée dans la configuration de la device).

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 :

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 :

Consulté (en cliquant également sur le nom du journal)

Converti au format texte pour affichage dans un éditeur de texte

Converti au format XML

Nettoyé : le journal existe toujours mais son contenu est vidé

Supprimé

Exemple de contenu du journal d’événement d’une file d’attente d’impression :

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 conservés (donc ayant été traités) dont la durée de rétention est dépassée :

Linux : /apps/mapping/bin/map_cron -date

Windows : E:\MappingWindows\Applications\map_cron.exe -date

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

Linux : /apps/mapping/bin/map_cron -dateall

Windows : E:\MappingWindows\Applications\map_cron.exe -dateall

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 map_cron 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 : /apps/mapping/bin/map_cron -cleanlog

Windows : E:\MappingWindows\Applications\map_cron.exe -cleanlog

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 : /apps/mapping/bin/map_cron -cleanlog -delete

Windows : E:\MappingWindows\Applications\map_cron.exe -cleanlog -delete

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 : /apps/mapping/bin/map_cron -cleanstats [ -delete ]

Windows : E:\MappingWindows\Applications\map_cron.exe -cleanstats [ -delete ]

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 map_cron permet de supprimer tous les fichiers cookies, en ne conservant qu’un historique d’un jour :

Linux : /apps/mapping/bin/map_cron -cleanid

Windows : E:\MappingWindows\Applications\map_cron.exe -cleanid

La commande map_del 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