Migration Process

Introduction

This article describes the process that must be applied to upgrade OPALE Server on a iSeries server. This procedure also applies to an upgrade to M-PS 7.2.

General steps

The procedure below is based on the assumption that the production environment that will be migrated is set up in a library called MAP400.

The update procedure for OPALE Server includes the following steps:

• Setting up of a development environment where OPALE Server will be installed
• Copying the production environment settings to the development environment
• Creating an OUTQ monitored by Mapping and edit print routing rules accordingly
• Running tests
• Moving to production
• Rollback in case there is a problem
• Troubleshooting

Any changes made to templates (whether it be intentional or because of a delta following the update) will need to be made using a Designer in the same version as OPALE Server and with UNICODE.

Requirements

User profile

- Access to the QSECOFR profile has to be granted for you to install the product

Elements gathering

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

- Identify the key documents that need to be tested by Mapping or by a certified partner
- Identify the raw spooled files for each of the documents
- Identify the Designer projects (.mpp, .mpw and .mpi files) for each of the documents as well as the possible components
- Have a PDF and/or .dmp file for each document that needs to be printed
- Identify the strategic rules in the production environment
- Gather the different iSeries spooled files (in an outq: MAPREF/MAPQUALREF) with their corresponding Mapping output results (PCL, ZPL, TEC, etc) generated with the current Mapping production server.

Caution: All fonts used have to be in TTF format (all other types of fonts will have to be switched for TTF fonts)

All "Windows" files must be saved in specific folders, one folder per document.

Note: When all the required information has 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.

User environment

To be done by MAPPING or a cetified partner

1. Check whether Mapping is configured in UNICODE: use option 14/1
   
2. Check the rules and actions used by the customer
3. Check the company name entered in the settings (option 14/1) and use the same one in the test library
   
4. Check that the configuration settings (option 14/1) are the same in MAPPINGQUA and MAP400 (except for IFS paths)
5. Check MAPSND settings (MapSend menu, Option 1)

Installation

Copying the production environment

The first thing to do is to make a copy of the customer's production library. Name this copy: MAPPINGCPY and use it for any data manipulation.

CPYLIB FROMLIB(MAP400) TOLIB(MAPPINGCPY)

The goal with these different names is to avoid making mistakes, confusing MAP400 with MAP400CPY, for instance. This is the reason why the name MAPPINGCPY is used. Any manipulation of the production tools will have to be done using the MAPPINGCPY library only. Do not modify anything in MAP400 (assuming MAP400 is the current production library).

Getting the latest setup available

Download the latest setup made available by Mapping.

Installing the product in a new library

Install the new version of OPALE Server: Installation guide for OPALE Server

CAUTION: DURING THE UPDATE, DO NOT KEEP MAP400 as the installation library

• Library name: MAPPINGQUA
• Subsystem name: MAPSQUAL
• IFS path: "/home/MAPQUAL/mapping" (mapsend,mapreport,mapout)

Setting up the environment (as per migration type)

No matter which migration type was chosen (see the list below), all tests must be carried out on the newly installed environment: MAPPINGQUA.

The production environment (ex : MAP400) must never be modified! The production environment has to stay untouched for the entire time of the migration and beyond.

SIMPLE Update: Copying templates

In a simple upgrade, AS/400 resource files are simply copied over to the new system. The files copied over are the Designer formats and the rules and relations between Outqs. The existing document templates are not generated again.

Step 1: Copying Designer formats

Files which have to be copied from MAPPINGCPY to MAPPINGQUA :

Copying formats

The files are copied from MAPPINGCPY to MAPPINGQUA (choose Option 3 then 3/Copy Designer Formats)

Copying all formats at once

If there are a lot of formats and you want to copy them all at once, you can copy the following physical files (MAPLNK, MAPLNKL1, MAPOBJ, MAP1, MAP2D, MAP2H, MAP3, MAP3L1, MAP)

Copying process for M-Designer format files

Special case, MAPLNK/MAPLNKL1:

Delete previous object MAPLNKL1 before copying MAPLNK
strpdm
Option 2
Library: MAPPINGQUA
Name: MAPLNKL1
Option 4 to delete MAPLNKL1

Replace the old MAPLNK with the new one
strpdm
Option 2
Library: MAPPINGCPY
Name: MAPLNK
Option 3 before MAPLNK
In library: MAPPINGQUA
Delete existing object: O

Copy the new MAPLNKL1 once MAPLNK has been copied
strpdm
Option 2
Library: MAPPINGCPY
Name: MAPLNKL1
Option 3 before MAPLNKL1
To library: MAPPINGQUA

Special case, MAP3/MAP3L1:

Delete old object MAP3L1 before copying MAP3
strpdm
Option 2
Library: MAPPINGQUA
Name: MAP3L1
Option 4 to delete MAP3L1

Replace the old MAP3 with the new one
strpdm
Option 2
Library: MAPPINGCPY
Name: MAP3
Option 3 before MAP3
To library: MAPPINGQUA
Delete existing object: O

Copy the new MAP3L1 once MAP3 has been copied
strpdm
Option 2
Library: MAPPINGCPY
Name: MAP3L1
Option 3 before MAP3L1
To library: MAPPINGQUA

Generic case for other objects:

Copy new MAPOBJ
strpdm
Option 2
Library: MAPPINGCPY
Name: MAPOBJ
Option 3 before MAPOBJ
To library: MAPPINGQUA
Delete existing object: O

Repeat the same steps for the following objects: MAP1, MAP2D, MAP2H, MAP

Step 2: Copying OUTQ settings

strpdm
Option 2
Library: MAPPINGCPY
Name: MAPOUTQ
Option 3 before MAPOUTQ
To library: MAPPINGQUA
Delete existing object: O

Step 3: Copying rules and actions

Copy physical files MAPPINGCPY/SPLMAP, ACTLIG and ACTION (not OUTOUT) to library MAPPINGQUA

Copying the new SPLMAP

strpdm
Option 2
Library: MAPPINGCPY
Name: SPLMAP
Option 3 before SPLMAP
To library: MAPPINGQUA
Delete existing object: O

Repeat the same steps for the following objects: SPLMAP, ACTLIG, ACTION

Step 4 : Copying IFS data

1. Copy all different M-Designer projects to "/home/MAPQUAL/mapping/docPC/M-Designer_BACKUP_VersionMPSixxxx/" to keep a copy of the original projects (where you replace xxxx with the release number of OPALE Server)
2. Copy the content of "home/mapping/ttf/" to "home/MAPQUAL/mapping/ttf/"
3. Copy the content of "/home/mapping/lgobitmap" to "/home/MAPQUAL/mapping/lgobitmap/"

Step 5 : Rebuilding the LSTOBJ.TXT file

Run the following command:

CALL MAP_823

Step 6 : Creating a monitored Outq for testing (optional)

If you skip this step, run the test commands in interactive mode.

• OutqName: MAPQUALIN
• DATAQ: DTAQUAL
• LIB: MAPPINGQUA
• Default printer: “To be defined with the customer”

Troubleshooting

No trouble detected

If there is no trouble detected, then it's all good. you just need to ensure that the Designer source files are saved in a way that is easy to understand and find.

Our recommendation is to create one folder per template containing the Designer source files and the input file (PAG or XML) used.

Something wrong is detected

If a problem is detected, you will need to generate the project again using the latest version of the Designer available for your Mapping server (OPALE or 7.2). The project can be generated in Unicode or non Unicode as per existing configuration settings.

Then, there are two options:

1. Generating the template again solves the issue (with or without making changes to the template).

Nothing else needs to be done. In this case, all you need to do is make sure you store the project source files (mpi, mpp and mpw) so you can find them easily and know they have been opened and generated with the new version of Designer.

2. Generating the template again does not solve the issue.

In this case, you will need to generate it in Unicode:

• Generate in Unicode (page code 1200)
• Run the template in UNICODE on the server

If this fixes the problem then it's all good.
If not, you will need to make a request to the MAPPING technical support.

Caution: The issue will be solved in Unicode only.

Advanced update: generating all templates again in their original language

In an Advanced Upgrade, all document templates will be generated again (in UNICODE: Code page 1200 in Designer). Only the resource files for rules and relations between Outqs will be copied over to the new system.

Step 1: Generating Designer projects again

1. Install the latest Designer setup (for use with the server side OPALE or 7.2 Server)
2. Open each template and generate it again manually in code page 1200 on the new server
   

Note : You can script the generation process of templates by following the steps described below.

To do so, you will need to:

1. For each project, identify the input file (XML and SPOOL) and generation language (PCL, ZPL, etc.) and store them in folders per generation language AND input file type
2. Run the script below to generate all files automatically:

for %%X in ("C:\MAPPING\M-Processing Server\Import\docpc\*.mpp") do ("C:\MAPPING\M-Designer\M-Designer.exe" "-Generate" "-ProjectFile:%%X" "-Hide")

Note: The paths must be changed according to context.

The input file type is set using parameter XXXXXXXXXXXXXX (not finished)

The generation language is set using parameter YYYYYYYYYYYY (not finished)

Step 2 : Copying OUTQ settings

Copy files from MAPPINGCPY to MAPPINGQUA :

strpdm
Option 2
Library: MAPPINGCPY
Name: MAPOUTQ
Option 3 before MAPOUTQ
To library: MAPPINGQUA
Delete existing object: O

Step 3 : Copying rules and actions

Copy the physical files MAPPINGCPY/SPLMAP, ACTLIG and ACTION (not OUTOUT) to library MAPPINGQUA

Copying the new SPLMAP

strpdm
Option 2
Library: MAPPINGCPY
Name: SPLMAP
Option 3 before SPLMAP
To library: MAPPINGQUA
Delete existing object: O

Repeat the same steps for the following objects: SPLMAP, ACTLIG , ACTION

Step 4 : Copying IFS data

1. Copy all different Designer projects to "/home/MAPQUAL/mapping/docPC/M-Designer_BACKUP_VersionMPSixxxx/" to keep a copy of the original projects (where you replace xxxx with the release number of OPALE Server)
2. Copy the content of "/home/mapping/lgobitmap" to "/home/MAPQUAL/mapping/lgobitmap/"

Step 5 : Creating a monitered Outq for testing (Optional)

If this step is skipped, the test commands will need to be run in interactive mode.

• OutqName: MAPQUALIN
• DATAQ: DTAQUAL
• LIB: MAPPINGQUA
• Default printer: “To be defined with the customer”

Troubleshooting one document

No trouble detected

The template can be used as is.

Something wrong is detected

Depending on the problem:

1. Zones not aligned correctly: Edit the template to realign the zones and check that the preview is now correct. Print or create the document (print, PDF, etc.) to ensure it is the same as the preview.
2. Barcodes:
   1. Barcodes not aligned correctly: Check the preview on the template and fix it if necessary
   2. Data printed under barcode distorted or missing: Uncheck and re-check the box Data printed under barcode (in the Properties of the Barcode zone)
   3. To be completed

Then, there are two options:

1. The changes made to the template have solved the issue (the printed or PDF version of the file matches the preview).

In this case, all you need to do is make sure you store the project source files (mpi, mpp a,d mpw) so you can find them easily and know they have been opened and generated with the new version of Designer.

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

Attention : La correction se fera uniquement en UNICODE.

Type AVANCÉ XPS: Passage en XPS de toutes les maquettes

Ce type consiste au passage systématique de toutes les maquettes en XPS (En UNICODE : Code page 1200 sur Designer + Génération XPS). Uniquement la copie des fichiers ressources pour les règles et relations entre Outqs sera réalisée.

Etape 1 : Régé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 en XPS sur le nouveau serveur
   

Remarque: 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) et leur langage de génération (PCL,ZPL,etc) et les ranger dans des dossiers séparés par langage de génération ET type de fichier en entrée
2. Exécuter le script suivant qui permettra de lancer automatiquement la génération

for %%X in ("C:\MAPPING\M-Processing Server\Import\docpc\*.mpp") do ("C:\MAPPING\M-Designer\M-Designer.exe" "-Generate" "-ProjectFile:%%X" "-Hide")

A savoir : Les chemins devront être changés en fonction de votre contexte Le type de fichier en entrée est paramétré grace au paramètre XXXXXXXXXXXXXX (A terminer) Le langage de génération est paramétré grâce au paramètre YYYYYYYYYYYY (A terminer)

Etape 2 : Copie du paramétrage des OUTQ

Fichiers à copier de MAPPINGCPY vers MAPPINGQUA :

strpdm
Option 2
Bibliothèque : MAPPINGCPY
Nom : MAPOUTQ
Option 3 devant MAPOUTQ
Dans la bibliothèque : MAPPINGQUA
Suppression de l'objet existant : O

Etape 3 : Copie des règles et action

Copier les fichiers physiques MAPPINGCPY/SPLMAP, ACTLIG et ACTION (pas OUTOUT) dans la bibliothèque MAPPINGQUA

Copie du nouveau SPLMAP

strpdm
Option 2
Bibliothèque : MAPPINGCPY
Nom : SPLMAP
Option 3 devant SPLMAP
Dans la bibliothèque : MAPPINGQUA
Suppression de l'objet existant : O

Répéter l'opération pour les objets suivants : SPLMAP, ACTLIG , ACTION

Etape 4 : Copie des données de l'IFS

1. Copier dans le répertoire "/home/MAPQUAL/mapping/docPC/M-Designer_BACKUP_VersionMPSixxxx/" tous les différents projets M-Designer pour conserver la version d'origine. (remplacer le xxxx par la numéro de version MPS-i)
2. Copier dans le répertoire "/home/MAPQUAL/mapping/lgobitmap/" le contenu de "/home/mapping/lgobitmap"

Etape 5 : Création d'une Outq monitorée par Mapping pour la recette (Optionnel)

Si non réalisé, les commandes de tests devront être lancées en interactif

• OutqName: MAPQUALIN
• DATAQ: DTAQUAL
• LIB: MAPPINGQUA
• Imprimante par défaut: “A définir avec le client”

Gestion des bugs sur un document

Aucun bug détecté

Le client pourra continuer d'utiliser leur document tel quel.

Gestion des bugs détectés

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. Code barre :
   1. Problèmes d'alignements : Vérifier la preview sur la maquette et corriger la maquette si besoin
   2. Problème de labélisation : Cocher ou décocher le label du code barre (propriétés de la zone Code barre)
   3. A compléter

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

1. Les corrections de la maquette corrige bien les problèmes (Preview et sortie cohérents) : Rien d'autre n'est à faire.

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.

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

Attention : La correction se fera uniquement en UNICODE.

Gestion des cas particulier

Les 3 types définis ci-dessus sont de façon générale toujours vrai. Cependant il peut exister quelques cas particuliers :

Passage partiel en XPS

Pour plusieurs raison, un client peut passer en XPS uniquement sur quelques documents. Voici quelques besoins pouvant nécessité cela :

1. Simplifier la gestion des maquettes pour un document donné car celui-ci a trop de maquette (La maquette en XPS pouvant gérer tous les langages)
2. Besoin de post traitement plus important pour un document :
   1. Fusion du document avec d'autres documents Mapping ou autres
   2. Conversion d'un flux vers un autre (PDF vers XPS et ensuite concaténation avec un autre document par exemple)
   3. Autres

Utilisation de flux thermique (Zebra, TEC)

Il est fortement conseillé par Mapping de passer les maquettes thermiques en XPS. Les raisons principales sont :

1. Aperçu Designer et impression finale bien plus fiable en XPS qu'en natif
2. XPS to TEC ou ZPL plus fiable et intuitif en XPS

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 spooled files et chacune des maquettes à tester.

Cas des tests exécutés de façon automatiques

Le principe est de déposer les spooled files d'entrée dans l'outq test d'entrée. Le robot récupèrera alors les spooled files et éxécutera les bonnes commandes paramétrées dans le robot Mapping. Dans ce cas, il faut bien s'assurer que l'Outq d'entrée soit bien paramétrée et que l'imprimante par défaut soit bien renseigné dans les règles.

• Aller sur les règles utilisées pour tester et choisir l'imprimante de test (Option 14, 3 et 8) 
• Copier les fichiers spool d'entrée du client un par un dans l'output queue Mapping monitorée et vérifier les résultats par rapport aux fichiers de référence.

Validation

La mise à niveau finale de l'environnement de production sera réalisée lorsque le client aura validé à l'écrit tous les documents.

Passage en production

Une fois la validation client réalisée, il est temps de passer en production. Le principe est de faire une autre installation et d'utiliser cette nouvelle bibliothèque comme bibliothèque de production. De ce fait, nous ne touchons pas à l'ancienne bibliothèque de production, ce qui pourrait être très utile en cas de besoin de retour arrière si un problème survient sur le nouvel environnement de production.

• Copier la bibliothèque de production MAP400 en MAPPRODCPY
• Lancer le setup de la nouvelle version en spécifiant MAP400_XX pour bibliothèque d'installation et MAPSRBT_XX (avec XX le numéro de version : 71,72 ou OP Exemple : MAP400_OP et MAPSRBT_OP)

ATTENTION : Ne pas laisser MAP400 par défaut

• Entrer les clefs d'activation du logiciel
• Copier les objets (règles, action et relations outqs) suivants de MAPPRODCPY vers MAP400_XX : OUTOUT, SPLMAP, ACTLIG et ACTION (voir procédure de copie d'objets ci-dessus)

ATTENTION : NE PAS FAIRE L ERREUR ENTRE MAP400 et MAP400_XX

• Copier les objets (Formats Designer) suivants de MAPPINGQUA vers MAP400_XX : MAPLNK, MAPLNKL1, MAPOBJ, MAP1, MAP2D, MAP2H, MAP3, MAP3L1, MAP (voir procédure de copie d'objets ci-dessus)

ATTENTION : NE PAS FAIRE L ERREUR ENTRE MAP400 et MAP400_XX

• Arrêter le sous-système de production MAPSROBOT
• Renommer l'ancienne bibliothèque MAP400 en MAP400OLD
• Démarrer le sous-système MAPSRBT_XX
• Lancer des traitements en mode production

Retour arrière en cas de problème

• Arrêter le sous-système MAPSRBT_XX
• Renommer la bibliothèque MAP400_XX en MAP400_KO
• Renommer la bibliothèque MAP400OLD en MAP400
• Redémarrer le sous-système MAPSROBOT (ancien sous-système)

Mapping tourne alors avec son ancienne version.

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

---

Problème 2 : Les mails ne partent pas et le job MAPSMTP ne démarre pas

Solution : Vérifier le contenu de la dataq MAP400_XX :

DSPDTAQ DTAQ(MAP400_XX/MAPSMTP)

Si celle-ci contient des STOP, à ce moment-là, faire un

CLRDTAQ DTAQ(MAP400_XX/MAPSMTP)

Renvoyer les e-mails.

Problème 3 : Vérification que tout se soit bien passé lors de l'installation Exécuter cette commande pour voir les messages d’installation :

DSPJOBLOG OUTPUT(*PRINT)

Autres points à vérifier :

• Lire le DSPJOBLOG à la fin du processus
• En cas de déconnexion, la commande SIGNOFF *LIST permet de récupérer les erreurs ou alertes d’installation

Pour vérifier les erreurs de restauration (objet verrouillé, mauvais propriétaire, etc.), exécuter la commande suivante dans STRSQL :

SELECT * FROM qtemp/RSTMAP400 WHERE RSOSTA = '0'