Process de migration/en

==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<br />

===Elements gathering===

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

- Identify the key documents that need to be tested by Mapping or by a certified partner<br />
- Identify the raw spooled files for each of the documents<br />
- Identify the Designer projects (.mpp, .mpw and .mpi files) for each of the documents as well as the possible components<br />
- Have a PDF and/or .dmp file for each document that needs to be printed<br />
- Identify the strategic rules in the production environment<br /> 
- 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===
#Check whether Mapping is configured in UNICODE: use option 14/1<br />
#Check the rules and actions used by the customer
#Check the company name entered in the settings (option 14/1) and use the same one in the test library<br />
#Check that the configuration settings (option 14/1) are the same in MAPPINGQUA and MAP400 (except for IFS paths)
#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: [[OPALE:10.0:Installation:Installation 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.<br /><br />

<big><u>'''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.'''</u><br /></big><br /><br />

===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====
<u>Files which have to be copied from MAPPINGCPY to MAPPINGQUA</u> :
=====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: 

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

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

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

Special case, MAP3/MAP3L1: 

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

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

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

Generic case for other objects: 
 <u>Copy new MAPOBJ</u>
 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

====Etape 3 : Copie des règles et actions====

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

<u>Copie du nouveau SPLMAP</u>
 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====

#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)
#Copier dans le répertoire "home/MAPQUAL/mapping/ttf/" le contenu de "home/mapping/ttf/"
#Copier dans le répertoire "/home/MAPQUAL/mapping/lgobitmap/" le contenu de "/home/mapping/lgobitmap"

====Etape 5 : Reconstruction du LSTOBJ.TXT====

Lancer la commande :
 CALL MAP_823

====Etape 6 : 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é=====
Rien de particulier. Il faudra bien que le client range leurs fichiers sources Designer (mpi, mpp et mpw) de façon à les retrouver façilement.

Conseil : Créer un répertoire par maquette avec le spool d'entrée en PAG ou XML (selon si c'est un fichier texte paginé ou XML)

=====Gestion des bugs détectés=====
Le projet Designer devra être regénéré avec la dernière version Designer adapté à la version du serveur (Opale, 7.2).
Il pourra être regénéré en Unicode ou en Non Unicode (selon configuration du client).<br />

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

1. La regénération résoud le bug (avec ou sans modification de la maquette)

Rien d'autre n'est nécessaire. 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 résoud pas le bug

Dans ce cas-là, il faudra passer le document en UNICODE :
* Génération en Unicode (code page 1200)
* Exécution de la maquette en UNICODE sur le serveur
Si ceci corrige le problème, il ne faut rien faire de plus.<br />
Sinon, un ticket devra être ouvert auprès du support MAPPING.<br />

'''Attention : La correction se fera uniquement en UNICODE.'''

===Type avancé: Régénération systématique des maquettes (dans le langage d'origine)===
Ce type consiste à une régénération systématique de toutes les maquettes (En UNICODE : Code page 1200 sur Designer). Uniquement la copie des fichiers ressources pour les règles et relations entre Outqs sera réalisée.

====Étape 1 : Régénération des projets Designer====
#Installer le dernier setup de Designer correspondant à la version de votre nouvelle installation du serveur
#Ouvrir chaque maquette et la générer manuellement en code page 1200 sur le nouveau serveur<br />


'''Remarque''' : Il est possible d'automatiser la génération des maquettes grâce à un script. 

Pour cela, il faut :
#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
#Exécuter le script suivant qui permettra de lancer automatiquement la génération :
<code>for %%X in ("C:\MAPPING\M-Processing Server\Import\docpc\*.mpp") do ("C:\MAPPING\M-Designer\M-Designer.exe" "-Generate" "-ProjectFile:%%X" "-Hide")</code>
       
À savoir : Les chemins devront être changés en fonction du contexte.

Le type de fichier en entrée est paramétré grâce au paramètre XXXXXXXXXXXXXX (à terminer).

Le langage de génération est paramétré grâce au paramètre YYYYYYYYYYYY (à terminer).

====Etape 2 : Copie du paramétrage des OUTQ====
<u>Fichiers à copier de MAPPINGCPY vers MAPPINGQUA</u> :
 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

<u>Copie du nouveau SPLMAP</u>
 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

====Étape 4 : Copie des données de l'IFS====

#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)
#Copier dans le répertoire "/home/MAPQUAL/mapping/lgobitmap/" le contenu de "/home/mapping/lgobitmap"


====Étape 5 : Création d'une Outq monitorée par Mapping pour la recette (Optionnel)====
Si cette étape n'est pas réalisée, les commandes de test devront être lancées en interactif

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

====Gestion des bugs sur un document====
=====Aucun bug détecté=====
Le client pourra continuer d'utiliser le document tel quel.

=====Gestion des bugs détectés=====
Selon le problème :
#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
#Code barre : 
##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)
##A compléter

A ce moment là, nous avons deux choix possibles :
#Les corrections de la maquette corrige bien les problèmes (Preview et sortie cohérents) : Rien d'autre n'est à faire. 
Rien d'autre n'est nécessaire. 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.

#Les modifications de la maquette ne sont pas concluantes. 
Un ticket devra être ouvert au support MAPPING.<br />. 
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====
#Installer le dernier setup de Designer (correspondant à la version de votre nouvelle installation du serveur)
#Ouvrez chaque maquette et générer manuellement en code page 1200 en XPS sur le nouveau serveur<br />


Remarque: Il est possible de scripter leurs générations. Pour cela, il faut:
#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
#Exécuter le script suivant qui permettra de lancer automatiquement la génération
<code>for %%X in ("C:\MAPPING\M-Processing Server\Import\docpc\*.mpp") do ("C:\MAPPING\M-Designer\M-Designer.exe" "-Generate" "-ProjectFile:%%X" "-Hide")</code>

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====
<u>Fichiers à copier de MAPPINGCPY vers MAPPINGQUA</u> :
 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

<u>Copie du nouveau SPLMAP</u>
 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====

#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)
#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 :
#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
#Code barre : 
##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)
##A compléter

A ce moment là, nous avons deux choix possibles :
#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.

#Les modifications de la maquette ne sont pas concluantes. 
Un ticket devra être ouvert au support MAPPING.<br />. 
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 :
#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)
#Besoin de post traitement plus important pour un document :
##Fusion du document avec d'autres documents Mapping ou autres
##Conversion d'un flux vers un autre (PDF vers XPS et ensuite concaténation avec un autre document par exemple)
##Autres

====Utilisation de flux thermique (Zebra, TEC)====
Il est fortement conseillé par Mapping de passer les maquettes thermiques en XPS. Les raisons principales sont :
#Aperçu Designer et impression finale bien plus fiable en XPS qu'en natif
#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==
<u>Problème 1</u> : Vous constatez un écart sur un document entre celui produit à l'aide de l'ancienne version (avant upgrade) et la nouvelle (après upgrade)

<u>Solution</u> : Consulter la marche à suivre ci-dessus selon le type d'upgrade choisi

-------------------------------------------------------------------------------------------------------------

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

<u>Solution</u> : 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.

<u>Problème 3</u> : 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'