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 procedure includes the following steps:

• Set up a development environment where OPALE Server will be installed
• Copy the production environment settings to the development environment
• Create an OUTQ monitored by Mapping and edit print routing rules accordingly
• Execute tests
• Move to production
• Troubleshooting

Any changes made to templates will need to be made using a Designer in the same version as OPALE Server.

REQUIREMENTS

USER PROFILE

You will need to be allowed to use the QSECOFR profile to install the product.

ELEMENTS GATHERING

You will need to:

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

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

Important : The fonts used must be in TTF format. (any other type of font will need to be replaced with TTF font by the customer)

KNOWING THE CUSTOMER ENVIRONMENT

TO BE DONE BY MAPPING OR A CERTIFIED PARTNER

Existing Mapping environment:

• Check whether Mapping is configured in UNICODE: use option 14/1
• Check the rules and actions used
• Check the company name entered in the settings (option 14/1) and use the same in the test library
• 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

MAKING A COPY OF THE PRODUCTION ENVIRONMENT

The first thing to do is to make a copy of the production library and call it MAPPINGCPY.

CPYLIB FROMLIB(MAP400) TOLIB(MAPPINGCPY)

The goal is to avoid making mistakes and work with the new 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 as explained in the installation guide.

CAUTION: 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 BELOW)

All tests must be carried out on the newly installed environment: MAPPINGQUA

The existing production environment must not be modified!

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.

1. Copying Designer formats

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

If there are a lot of formats and you want to copy them all in one go, you can copy the following physical files: MAPLNK, MAPLNKL1, MAPOBJ, MAP1, MAP2D, MAP2H, MAP3, MAP3L1, MAP.

Special case - MAPLNK/MAPLNKL1:

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

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

Copy 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 old MAP3 with the new one
strpdm
Option 2
Library: MAPPINGCPY
Name: MAP3
Option 3 before MAP3
To library: MAPPINGQUA
Delete existing object: Y

Copy new MAP3L1 once MAP3 has been copied
strpdm
Option 2
Libray: 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: Y

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

2. Copying Outq settings

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

3. Copying Rules and Actions

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

Copy new SPLMAP

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

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

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

5. Rebuilding the LSTOBJ.TXT file

Run the following command:

CALL MAP_823

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”

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

In this case, all you need to do is make sure you store the project source files so you can find them easily should you need them again later.

2. Generating the template 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 you're all good. If not, you will need to open a ticket with Mapping support.

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). 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 like this:

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 your 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: Y

Step 3: Copying rules and actions

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

Copy new SPLMAP

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

Repeat the same steps with 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/ttf" to "/home/MAPQUAL/mapping/ttf/"
3. Copy the content of "/home/mapping/lgobitmap" to "/home/MAPQUAL/mapping/lgobitmap/"

Step 5: Creating an Outq monitored by Mapping 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.

In this case, all you need to do is make sure you store the project source files so you can find them easily for when you need them again later.

2. The changes made to the template did not solve the issue.

Open a ticket with Mapping support.

Caution: The issue will be solved in Unicode only.

ADVANCED XPS UPGRADE: GENERATING ALL TEMPLATES IN XPS LANGUAGE

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

Step 1: Generating Designer projects

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

Note: You can script the generation process like this:

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 your 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: Y

Step 3: Copying rules and actions

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

Copy new SPLMAP

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

Repeat the same steps with 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 an Outq monitored by Mapping 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.

In this case, all you need to do is make sure you store the project source files so you can find them easily for when you need them again later.

2. The changes made to the template did not solve the issue.

Open a ticket with Mapping support.

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:

1. 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.
2. Need to implement more post-processing actions for one document:
   1. Merging one document with other Mapping or non Mapping documents
   2. Converting one datastream from one language to another (e.g. PDF to XPS and then concatenate with another document)
   3. Etc.

Thermal languages (Zebra, TEC)

It is strongly recommended to convert all thermal templates to XPS. The main reasons are:

1. Designer preview and printed output more reliable in XPS as in native thermal language
2. XPS to TEC or to ZPL 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

When the customer has validated all the documents, you 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)

CAUTION: Do not keep MAP400 as the default

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

CAUTION: 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)

CAUTION: 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

If for any reason you need to roll back, this is how you do it:

• 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)

If you do that, the previous version of Mapping will be restored.

TROUBLESHOOTING

Problem 1: There is a gap between the previous version and the new version of the same document.

Solution: See details above in one of the three types of upgrade

---

Problem 2: E-mailing is not working and the job called MAPSMTP won't start

Solution: Check the content of dataq MAP400_XX:

DSPDTAQ DTAQ(MAP400_XX/MAPSMTP)

If it has any STOPs, then clear the dataq:

CLRDTAQ DTAQ(MAP400_XX/MAPSMTP)

Send e-mail again.