Duplicating an ONYX Server instance on Linux

Introduction

This process is applied in the following cases

• Upgrade, even minor (excluding corrective upgrades)
• Mapping instance migration to another server
• Duplication to upgrade a backup server
• Implementation of a High Availability architecture (HA)

This document explains how to duplicate a Mapping source instance to a Mapping target instance installed on another server. However, some environments have specific features which may need to be further studied and analysed.

Furthermore, if the existing environment does not rely on "XPS" technology, the upgrade must be considered as a fully-fledged project, even if the existing templates can be retrieved mechanically thus reducing the time taken for the implementation of the new solution.

Note: In the case of an upgrade, do not ever change the production environment, even if you saved it beforehand.

Requirements

The entire configuration of the solution must be perfectly known and identified.

If databases or external applications are used with Mapping, their access paths must be identical (example: call of a *.sh script in a Workflow or a planned task of the server).

User profile

Root access on the target device is required to configure the product.

Elements to gather beforehand

The user should have a relatively good knowledge of the environment. To do so, one should be able to:

• Define key documents which MAPPING or one of their certified partners should test
• Know and find raw data files (text or xml) for each document
• Find the Designer projects (.mpi, mpp and mpw) related to each document, as well as their potential components
• Find Connect projects (.src) related to each document
• Make an inventory of rules or workflows used
• Make an inventory of the spooler data queues (printers, input or processing points, sites...)
• Find the potential and specific scripts (cmd or shell), called upstream, being processed, or called downstream Mapping
• Have example PDFs or paper copies of each document
• List the different applications (ERP, Enterprise software etc...) which are connected to Mapping

All source files must be classified in folders in a structured way: have one folder per document for instance.

Note: When all the required elements have been gathered, a precise upgrade estimate can then be made.

CAUTION: If required information is missing, Mapping or a certified partner will need to study the existing environment and retrieve all the information required.

Mapping or Certified Mapping Partner: knowing the customer's environment

1. Check if MAPPING is configured in UNICODE or non UNICODE
2. Check if the "XPS" format is applied (partially, or completely)
3. Confirm that the configuration (mapping.conf) is the same on the current production environment as on the target environment.

Duplicating process overview

The entire configuration of the Mapping ONYX Server is stored as a file (no database is required to use Mapping). Exporting a server to another is then quite simple, and essentially comes down to copying these files. The following steps should, however, be respected:

The update procedure for ONYX Server includes the following steps:

1. Find the best export strategy for the current production environment to be copied over to the target environment.
   • This depends on the way jobs are injected in mapping:
     • Injected directly in the spooler, via protocole LPR or a WebService call.
     • Using "scanfolder" robots.
     • Mapping binairies are called directly via the entreprise software.
     • A WebService called with simultaneous processing.
     • Different methods are used depending on the type and origin of the job.
2. A target environment is installed with the destination version of the ONYX Server.
3. The configuration of the production environment is copied onto the target environment
4. Tests are run on the new target environment
5. Launch production
6. Rollback in case there is any problem
7. Troubleshooting

Installing the new target Mapping instance

To install the server, see the following documentation: ONYX Server installation on Linux

If the installation is done on a different server, the best is to choose the same installation path and keep the same classification tree so that future copies and retrieval are easier. Information which is inherent to the server must be different (IP address...).
However, if the installation is done on the same server, then the paths and ports specified during the installation (http, spooler and lpd) must be different from the instances that are already on the server (ex: /apps/mapping_bis and ports 8003, 2001, 516)

This information can be found on the Mapping source instance, in the Mapping configuration file "mapping.conf".

Activate the software on the new target Mapping instance (software keys).

Duplicating the configuration

Duplicate the entire configuration and Mapping parameter of the Mapping source instance to the target instance, for instance the following files and/or folders are copied.

• The paths given hereafter are the default paths to install the software in the "/apps/mapping" folder (PATH_BASE_MAPPING variable in the mapping.conf configuration file). The paths and names must thus be replaced with the ones chosen during the installation of server B.

• The following configuration files, which are situated in the Mapping configuration folder, must not be copied from the source server to the target server

• mapping.conf: the Mapping configuration file. Changes made in this file must be retrieved one by one, in comparaison to 2 files.
• mapkey.txt and ucinfo.txt: software keys files, which depend on the server.
• /apps/mapping/map400/key: this subfolder includes page refreshing files, which depend on the server.

Files to copy as is

• "/apps/mapping/conf/queues/*": queues must be declared in the Mapping Spooler (chown -R mapadmin:mapadmin / chmod -R 775)

• "/apps/mapping/conf/XPSConfig.conf": XPS documents conversion profiles must be declared, in particular for printing (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/conf/maprawd.conf": "Raw listening servers" robots must be declared (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/conf/GROUPS.conf": Mapping user groups must be declared (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/conf/USERS.conf": Mapping users must be declared (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/MapHTTPServer/.htpasswd": users accessing Mapping through Apache (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/MapHTTPServer/.htgroup": Apache user groups (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/conf/viewSettings.conf": The different ways in which spooled files are viewed in the Mapping Spooler must be declared (chown mapadmin:mapadmin / chmod chmod 664)

Files to copy after paths were adapted

• "/apps/mapping/conf/robot.conf": "Scanfolder" robots must be declared (chown mapadmin:mapadmin / chmod chmod 664)
• "/apps/mapping/conf/exportSettings.conf": server export methods (chown mapadmin:mapadmin / chmod chmod 664)

Duplicating Designer and Connect Formats

• "/apps/mapping/map400/*": Mapping objects describing all Connect and Designer production formats (chown -R mapadmin:mapadmin / chmod -R 775)

• /apps/mapping/import/lgobitmap/*: external ressources (images, XPS, translations) used in Designer formats (chown -R mapadmin:mapadmin / chmod -R 775)

Other potential duplications

• "/apps/mapping/conf/menu/*.auth" (subfolder included): authorisations to access menus (if the version is changed, the menu classification may differ) (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/spool/logs/*": Log folder of the Mapping Spooler (optional, because this can be seen as depending on the server) (chown mapadmin:mapadmin / chmod chmod 664)

• "/apps/mapping/spool/global/*" and "/apps/mapping/spool/queues/counter.splf": Job folder of the Mapping Spooler and its numbering counter (chown mapadmin:mapadmin / chmod chmod 664)

Depending on the use of the product, other elements can be duplicated, such as scripts called in Mapping Processing Workflows, planned purification tasks or Mapping process triggers, etc. Because these items are specific to each customer, they cannot be listed here, and must be identified by the user.

Managing Mapping Designer templates

Any changes in the template (linked to an intentional change or to a delta because of the upgrade) will then be done with a Designer using the same version as the Mapping server.
All Designer and Connect projects need to be copied before any change is made by a newer version of Designer and Connect.

SIMPLE Migration: template simple copy

This method can only be applied if all the templates are already in XPS.
It consists in a simple copy of resource files to copy Designer formats, as explained below (copy of the map400 and lgobitmap folder). The templates are not re-generated.

Technical problems

If you notice disparities in the mapping of documents (Designer), the project must be re-generated with the latest Designer version which is adapted to the server version.

A ce moment-là, nous avons deux choix possibles :

1. La re-génération permet de résoudre le bug (avec ou sans modification de la maquette) Aucune autre action n'est requise. Il faudra juste bien classer les fichiers sources du projet (mpi, mpp et mpw) dans un répertoire afin de savoir rapidement que celui-ci a été ouvert et généré avec la nouvelle version de Designer.
2. La regénération ne permet pas de résoudre le bug. Dans ce cas, il faut apporter les modifications nécessaires à la maquette afin de corriger les problèmes rencontrés.

Migration AVANCÉE : Re-génération de toutes les maquettes

Ce type de migration impose la re-génération de toutes les maquettes, avec passage en XPS si ce n'est pas déjà le cas.

Regénération des projets Designer

1. Installer le dernier setup de Designer (correspondant à la version de votre nouvelle installation du serveur)
2. Ouvrez chaque maquette et générer manuellement en code page 1200 et dans le langage XPS sur le nouveau serveur
   

Remarque : Si les maquettes sont déjà au format de génération XPS, il est possible de scripter leurs générations. Pour cela, il faut:

1. identifier pour chaque projet, leur type de fichier en entrée (XML et SPOOL texte) ) et les ranger dans des dossiers séparés par type de fichier en entrée
2. Exécuter le script suivant qui permettra de lancer automatiquement la génération

"C:\MAPPING\M-Designer\M-Designer.exe" "-Generate" "-ProjectFile:%%X" "-Hide"

A savoir : Les chemins devront être changés en fonction de votre contexte.

Résolution des incidents

Selon le problème :

1. Alignements de zones :
   • Modifier la maquette pour que l'alignement de zone soit OK en preview. Valider que le document final (imprimé, PDF, etc) soit cohérent par rapport à la preview
     
2. Codes à barres :
   • Problèmes d'alignements : Vérifier la preview sur la maquette et corriger la maquette si besoin
   • Problème de labélisation : Cocher ou décocher le label du code barre (propriétés de la zone Code barre)
     

Si les modifications de la maquette ne sont pas concluantes, un ticket devra être ouvert au support MAPPING. Il faudra juste bien classer les fichiers sources du projet (mpi,mpp et mpw) dans un répertoire afin de savoir rapidement que celui-ci a été ouvert et généré avec la nouvelle version de Designer.

Phase de tests

Cas des tests exécutés de façon interactive.

Le principe est d'exécuter chaque commande manuellement pour chacun des fichiers en entrée et chacune des maquettes à tester.

Passage en production

La bascule de la production sur le nouvelle environnement B sera réalisée lorsque le client aura validé à l'écrit tous les documents.

Une fois la validation client réalisée, il est temps de passer en production. Selon la technique d'injection des fichiers dans Mapping utilisée, il est possible de faire un passage en production progressif (par site, par applicatif...) en modifiant un à un soit les dépôts de fichiers dans les différents dossiers pris en charge par les robots scanfolder, soit en modifiant les scripts côté applicatif permettant d'envoyer les travaux dans les files d'attente du spooler Mapping...

Troubleshooting

Problème 1 : Vous constatez un écart sur un document entre celui produit à l'aide de l'ancienne version (avant upgrade) et la nouvelle (après upgrade)

• Solution : Consulter la marche à suivre ci-dessus selon le type d'upgrade choisi