Duplicating an ONYX Server instance on Linux

Autres langues :

English • ‎français

Introduction

This process is applied in the following cases

Upgrade, even minor (excluding corrective upgrades)
Mapping instance migration to another server
Duplication to install 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

Check if MAPPING is configured in UNICODE or non UNICODE
Check if the "XPS" format is applied (partially, or completely)
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:

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.
A target environment is installed with the destination version of the ONYX Server.
The configuration of the production environment is copied onto the target environment
Tests are run on the new target environment
Launch production
Rollback in case there is any problem
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 parameters 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 admin 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 elements 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.

Then, there are two options:

Re-generating the projects solves the issue (with or without editing the template) You do not need to do anything else. Simply make sure to classify source files of the project (mpi, mpp and mpw) in a specific folder to know if it was opened and generated with the latest version of Designer.
Re-generating the projects does not solve the issue. In this case, the template needs to be edited to solve the issues.

ADVANCED Migration: Re-generating all templates

This type of migration requires that all templates be re-generated, and converted to XPS if this was not already the case.

Regenerating Designer projects

Install the latest Designer setup (corresponding to the version of your server)
Open each template and generate manually in code page 1200 and in XPS language on the new server

Note: If the templates are already in XPS format, their generation can be scripted. To do so, you need to:

For each project, identify the type of input file (XML and SPOOL texte) ) and sort them in separate folders per type of input file
Run the following script to launch the generation automatically

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

N.B. Paths must be changed depending on your context.

Solving incidents

Depending on the problem:

Zones are not aligned correctly:
- Edit the template so that the zone alignment is OK in the preview. Check that the document (printed, PDF, etc) matches the preview
Barcodes:
- Barcodes not aligned correctly: Check the preview on the template and fix it if necessary
- Data printed under barcode distorted or missing: Uncheck and re-check the box Data printed under barcode (in the Properties of the Barcode zone)

If the changes made to the template did not solve the issue. You will need to make a request to the MAPPING technical support. All you need to do is make sure to store the project source files (mpi, mpp and mpw) in a folder so you can find them easily and know they have been opened and generated with the new version of Designer.

Tests

Tests run in an interactive way.

The aim is to run each command manually for each input file and each template to test.

Validation

Production

Production will be based on the new environment B once the customer validates all documents in writing.

Once the customer has validated the documents, the environment is used for production. Depending on the method used to export files in Mapping, the export to production can be gradual (per site, per application...) this can be done either by changing the input of files in the different folders supported by the scanfolder robots one by one, or by changing the application scripts which send jobs in the Mapping spooler queues...

Troubleshooting

Problem 1: You notice a disparity between the document produced with the old version (before upgrade) and the new (after upgrade)

Solution: See the steps detailed above, depending on the type of upgrade.