Process de migration/en

==Introduction==

This article describes the process that must be applied to upgrade OPALE Server on a IBM i 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 IBM i spooled files (in an outq: MAPREF/MAPQUALREF) with their corresponding Mapping output results (PCL, ZPL, TEC, etc) generated with the current Mapping production server.

'''Be careful''': 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 certified 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 objects 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
*Sub-system 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 Upgrade: 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 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

====Step 3: Copying rules and actions====

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

<u>Copying the new SPLMAP</u>
 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====

#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)
#Copy the content of "home/mapping/ttf/" to "home/MAPQUAL/mapping/ttf/"
#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.<br />

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 (code page 1200)
* Run the template in UNICODE on the server
If this fixes the problem then it's all good.<br />
If not, you will need to make a request to the MAPPING technical support.<br />

'''Caution: The issue will be solved in Unicode only.'''

===Advanced upgrade: 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====
#Install the latest Designer setup (for use with the server side OPALE or 7.2 Server)
#Open each template and generate it again manually in code page 1200 on the new server<br />


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

To do so, you will need to:
#Identify the input file (XML and SPOOL) and generation language (PCL, ZPL, etc.) for each project, and store them in folders per generation language AND input file type
#Run the script below to generate all files automatically:
<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>
       
Note: The paths must be changed according to context.

The input file type is set using parameter XXXXXXXXXXXXXX

The generation language is set using parameter YYYYYYYYYYYY

====Step 2 : Copying OUTQ settings====
<u>Copy files from MAPPINGCPY to MAPPINGQUA</u> :
 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

<u>Copying the new SPLMAP</u>
 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====

#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)
#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:
#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 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)
##To be completed

Then, there are two options:
#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 and mpw) so you can find them easily and know they have been opened and generated with the new version of Designer.

#The changes made to the template did not solve the issue.
You will need to make a request to the MAPPING technical support.<br />. 
All you need to do is make sure to 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.


Caution: The issue will be solved in Unicode only.

===Advanced XPS upgrade: generating all templates in XPS===
In the advanced XPS upgrade, all document templates are generated in XPS language (in UNICODE: Code page 1200 in Designer and generation in XPS). Only the resource files for rules and relations between Outqs will be copied over to the new system.


====Step 1: Generating Designer projects again====
#Install the latest Designer setup (for use with the server side OPALE or 7.2 Server)
#Open each template and generate it manually in code page 1200 in XPS on the new server<br />


Note: You can script the generation process of projects by following the steps described below. To do so, you will need to:
#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
#Run the script below to generate all files automatically:
<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>

Note: The paths must be changed according to context.
The input file type is set using parameter XXXXXXXXXXXXXX 
The generation language is set using parameter YYYYYYYYYYYY


====Step 2 : Copying OUTQ settings====
<u>Copy files from MAPPINGCPY to MAPPINGQUA</u> :
 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

<u>Copying the new SPLMAP</u>
 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====

#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)
#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:
#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 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)
##To be completed

Then, there are two options:
#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 and mpw) so you can find them easily and know they have been opened and generated with the new version of Designer.

#The changes made to the template did not solve the issue.
You will need to make a request to the MAPPING technical support.<br />. 
All you need to do is make sure to 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.


Caution: The issue will be solved in Unicode only.

===Special cases===
The 3 upgrade types defined above are always true. However, there can be some special cases:

====Partial upgrade to XPS====
There are several reasons why a customer may want to upgrade only a few documents to XPS:
#To simplify the management of templates if there are multiple templates for one given document. One XPS template can be produced in multiple output languages.
#Need to implement more post-processing actions for one document:
##Merging one document with other Mapping or non Mapping documents
##Converting one datastream from one language to another (e.g. PDF to XPS and then concatenate with another document)
##Etc.

====Thermal languages (Zebra, TEC)====
It is strongly recommended to convert all thermal templates to XPS. The main reasons are:
#Designer preview and printed output are more reliable in XPS as in the direct thermal language
#XPS to TEC or to ZPL is more reliable and user-friendly in XPS

==Testing==
===Test cases executed interactively===
The idea is to run each command manually for each spool file and each template you wish to test.

===Test cases executed automatically===
The idea is to send the input spool files to the input outq used for testing. The robot will pick up the spool files and run the commands set in the Mapping robot. In this case, you need to make sure that the input outq is configured properly and that the default printer is specified in the rules.

*Open the rules used for testing and add a test printer (Option 14, 3 and 8)
*Copy the customer's input spool files one by one to the Mapping output queue that is monitored and check the results in comparison with the reference files.



== Validation==

The final move to production shall not be carried out until the customer has confirmed that they are happy with all the documents.

==Move to production==
Once the customer has validated all the documents, we can now move to production. What you want to do is install the product again and use the new library as the production library. This way, we are not even touching the old production library, and you can easily roll back if anything happens with the new production environment.

*Copy the MAP400 production library to MAPPRODCPY
*Run the setup and specify MAP400_XX as the installation library and MAPSRBT_XX as the sub-system (where XX is the version number: 71,72 or OP e.g. MAP400_OP and MAPSRBT_OP) 

CAUTION: Do not keep MAP400 as the default library

*Enter the software activation codes
*Copy the following objects (rules, actions and outqs relations) from MAPPRODCPY to MAP400_XX: OUTOUT, SPLMAP, ACTLIG and ACTION (see copy procedure above)

BE CAREFUL: MAKE SURE YOU CHOOSE MAP400_XX, NOT MAP400

*Copy the following objets from MAPPINGQUA to MAP400_XX: MAPLNK, MAPLNKL1, MAPOBJ, MAP1, MAP2D, MAP2H, MAP3, MAP3L1, MAP (see copy procedure above) 

BE CAREFUL: MAKE SURE YOU CHOOSE MAP400_XX, NOT MAP400

*Stop the production sub-system MAPSROBOT
*Rename the old library MAP400 to MAP400OLD
*Start the sub-system MAPSRBT_XX
*Start running the processes in production mode

==Rollback==

*Stop the MAPSRBT_XX sub-system
*Rename the MAP400_XX library to MAP400_KO
*Rename the MAP400OLD library to MAP400
*Restart the MAPSROBOT sub-system (old sub-system)

 This way, the previous version of Mapping will be restored.

==Troubleshooting==
<u>Problem 1</u>:  There is a gap between the previous version and the new version of the same document (before and after an upgrade).

<u>Solution</u>: See details above, depending on the type of upgrade.

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

<u>Problem 2</u>: E-mailing is not working and the job called MAPSMTP won't start.

<u>Solution</u>: Check the content of dataq MAP400_XX:
 DSPDTAQ DTAQ(MAP400_XX/MAPSMTP)

If it has any STOPs, then clear the dataq with:
 CLRDTAQ DTAQ(MAP400_XX/MAPSMTP)

Send e-mails again.

<u>Problem 3</u>: Check that everything went right during the installation
Run this command to see installation messages:
 DSPJOBLOG OUTPUT(*PRINT)

Other things to check:
* At the end of the process, read the DSPJOBLOG
* If you ever get disconnected, run the SIGNOFF *LIST command to retrieve errors or installation warnings

To check restoration errors (locked object, wrong owner, etc.), run the following command in STRSQL: 
 SELECT * FROM qtemp/RSTMAP400 WHERE RSOSTA = '0'