Folder upgrade

The upgrade of a folder can be performed in two ways:

• By updating an existing solution.
  Refer to the technical procedure described in the upgrade procedure.

  	Target version
  Source version		V5	V6.5	V7	U8	U9	V11	V12
  	V5		Direct	Direct	Indirect (via V7)	Indirect (via V7)	Indirect (via V7)	Indirect (via V7)
  	V6.5			Direct	Direct	Direct	Direct	Direct
  	V7				Direct	Direct	Direct	Direct
  	U8					Direct	Direct	Direct
  	U9						Direct	Direct
  	V11							Direct

• By installing the latest version solution, then integrating all existing patch lists to your root folder.
  Follow the optimized upgrade procedures described below.

Main upgrade steps

To upgrade a folder from one major release to another:

1. Carry out controls in the original folder before the upgrade, without stopping the Sage X3 operations.
2. Install the latest version on a dedicated environment, or update an existing environment.
3. Extract the data to be upgraded from the original folder, and reintegrate it.
   Stop the operation and resume it when the upgrade is complete. The data extraction will be carried out in a "flat" format for small folders, or with database extraction tools for larger folders.
4. Revalidate the folder in the latest version environment.
   This step can be divided in several substeps based on the upgrade plan setup. Defining an upgrade plan is optional for smaller folders. However, it is necessary if transfer processing routines need to be run in parallel (to benefit from the power of a multi-processor server), and if their sequencing needs to be checked using resumption marks.
5. Perform post-upgrade controls (setup checks and adaptation).

These steps are detailed in this document.

Performing the pre-upgrade steps

Pre-upgrade steps are launched in the source environment, and can be spread over a period of time, before the actual upgrade. It is not necessary to stop any operation beforehand.

1. Make sure the original folder is at the minimum patch level required to run an upgrade:
   • To upgrade from version 6, the minimum patch level required for the source folder is patch 29.
     You can display this patch level from ? > About.
     
   • To upgrade from version 7, the minimum patch level required for the source folder is patch 9.
     You can display this patch level from Administration > Version information.
   • To upgrade from version 8, the minimum patch level required for the source folder is patch 3.
     You can display this patch level from Administration > Version information.
   • To upgrade from update 9, no minimum patch level is required.
2. Check the functional prerequisites for the upgrade process.
3. Trigger the automated procedures in the original folder, using processing routines with names starting with "UU".
   You can launch these procedures from Development > Utilities > Miscellaneous > Run processes. The processing routines are supplied upon request, according to the release number, as a specific patch list dedicated to upgrading. Two types of procedures are delivered:
   • Control procedures for the data contained in the original folder. These controls can reveal errors or inconsistencies that need to be corrected before launching the upgrade itself. This can be anticipated several weeks ahead of the upgrade to have enough time to correct the data. However, it is still necessary to relaunch these procedures right before upgrading to the next version to make sure everything is correct.
   • Loading procedures that revalidate tables by adding additional fields and populating them. Since these procedures are independent from one another, they can be planned weeks before upgrade. Their purpose is to significantly accelerate the actual upgrade steps. However, they are not mandatory for the execution of the upgrade procedures.

Copying data and adjusting the folder parameters

This step takes place at the beginning of the transfer to the next version. At this stage, operation of the solution must be stopped: it will resume when the upgrade is completed.

1. Extract the data from the folder to be upgraded:
   • In a "flat" format for smaller folders. You can do so by clicking Development > Utilities > Extraction/integration > Data extract.
     The files are created in the default SVG backup directory.
   • As databases for larger folders. The format depends on the database and tool used.
2. Copy the files to be upgraded to the latest version solution.
3. Create a copy of the folder tree structure in the latest version environment.
   Import the exported data in the new environment.
4. Create the folder record in the latest version environment.
   If the import is carried out using the console, the folder record is created automatically. If the import was done using database tools, the folder record will have to be created manually after the import is complete.

Note:

• You can perform these four steps at the same time using the remote import wizard available in the SAFE X3 management console.
• If the standard process has to be relaunched from the data import in the upgrade folder, you can use the TRTMIGDEL function to clear the tables storing the upgrade report.

If you use the console import function, the procedure is as follows:

1. Start the console.
2. Select the solution and display the Folders screen.
3. Click Import.
4. Select the name of the folder to be imported, the directory containing the data to be imported (SVG if this is the directory that has been used to perform the extraction), and complete the other fields.
5. Click OK.

Caution: Before revalidating folders, always adjust the value of the activity codes in the folder record. The modification of the folder record (or its creation) can be carried out by logging in to the Supervisor folder.

You cannot trigger another folder validation without performing this step. An error message is displayed as a reminder when launching the validation.

Revalidating folders

This step triggers the Supervisor and functional upgrade of the folder by running a comparison between the dictionary of the new version and the dictionary of the version to upgrade.

Caution: If an upgrade test is first carried out in a folder containing specific developments, and if it can potentially stop in case of errors, the default size of global variable GTRALIG ("200" for optimization reasons) will not allow the retrieval of the operations carried out before the system stopped. In this case, you have to temporarily set GTRALIG to "1".

Re-enter value "200" after the upgrade, and make sure you log out and then log back in for this value to be taken into account.

Performing the main revalidation steps

The folder revalidation process triggers the following steps in the folder to upgrade:

• Purge of specific temporary or totalling tables whose recreation will be carried out at a later stage. The Supervisor tables impacted by this purge are the following:
  • ALSTRD
  • ALISTER
  • AWRKLOG
  • AWRKLOGIND
  • AWRKLOGMES
  • ATMPTRA
  • Other temporary functional tables are also purged (LABELPRN, PRTSCRWRK, BALANCE, BALANA, GLCONSO, BALCONSO, GAJOUSTA, FUP, FUPTOT, BATCH, TMPEXPENSE).
• Upgrade of the database dictionary and the Supervisor tables necessary for the operation of the database (connection, user management, development environment, and minimum setup). Once this upgrade has been carried out, it is theoretically possible to log on, even though the tables containing the transactions tables application data are still empty.
• Functional upgrade. Whenever there is a change in the structure of a table, the procedure carries out the necessary changes by assigning the appropriate default values through procedures sequenced in steps and phases. This is the lengthy part of the upgrade, depending on the volume of data to upgrade.
• Post-upgrade process (essentially resynchronization of the totalling tables). Some of these steps can be postponed and then resumed, but the software will be functioning in a downgraded mode during the intermediate phase. These stages must have been carried out for the upgrade to be complete.
• Final deletion of the temporary tables. This is a manual phase which can be postponed, for safety reasons, as long as there is no absolute certainty that all the transactions tables data have been correctly upgraded.

Using the upgrade plans

This functional upgrade can take a long time for larger folders. In addition, some updated tables are potentially independent and could be upgraded in parallel. Such tables would benefit from multi-processor architectures, which would, in turn, accelerate this phase.

It is possible, at this stage, to define specific procedures by writing additional processing routines in conformity with the methodology defined here. These specific procedures will be inserted in a relevant way between the standard procedures.

Once an upgrade plan has been defined, you can launch it, temporarily interrupt it, resume its execution, and view its progress.

When a folder is not too large and its upgrade does not require any particular planning, you do not have to create an upgrade plan. The validation of the folder will automatically create an upgrade plan if you do not define one. The code of this upgrade plan will be the folder code, unless it already corresponds to an upgrade plan that does not have the "Pending" status. In such a case, the plan is created with a predefined code: MIGmmddM##, with mm and dd representing the month and the day of the launch, and ## being a sequential number.

To customize the upgrade sequencing options, you can create an upgrade plan with a code that corresponds to the folder name. This can be done from the Supervisor folder before launching the folder validation. If an upgrade plan with the "Pending" status exists, it will be used for the functional upgrade of the folder.

Note: A plan created with a name different from the name of the folder to upgrade will never be used by the automatic folder validation function. Such a plan is restricted to a manual launch.

Operation process in an upgrade plan

Description of the upgrade plan

An upgrade plan is characterized by a folder code and four parameters:

• A title.
• The maximum number of procedures likely to be launched simultaneously. Only procedures that can be run in parallel will be launched simultaneously. Note that this number is limited by the number of batch tasks likely to be run simultaneously (defined in Setup > Usage > Batch server > Batch server parameters) and by the user license.
• An indicator specifying whether the procedures must be launched automatically or not.
• An indicator stating if the post-upgrade procedures must be linked to the upgrade itself.

Upgrade plan values

If the upgrade plan is created by default upon folder revalidation, it is created with the following values:

• Number of simultaneous tasks: Same value as the NBRTACSIM parameter, or value "2" if this parameter does not exist.
• Automatic sequencing: "Yes".
• Post-upgrade operations: "Yes".

You can always modify these values from the upgrade plan control function.

Managing the upgrade plan

You can view the ordered list of the plan procedures in the screen associated with the upgrade plan. Specific buttons make it possible to globally control the run of the plan:

• by launching its execution,
• by temporarily interrupting the launch of new procedures,
• by interrupting all the procedures in progress,
• by relaunching its execution.

Each line of the plan materializes a step in the execution, characterized by:

• the code of the procedure and its title,
• the step and phase the procedure belongs to,
• the functional module the procedure is linked to,
• the execution rank.

The upgrade steps make it possible to split the functional upgrade. If a procedure linked to a given phase is not completed, the next phases cannot be launched. The phases are linked to the following steps:

• The initialization step is a preliminary step that has to be completed first. It allows specific procedures to be executed before the upgrade itself.
• The common data step allows data used by the next steps to be upgraded.
• The module step is used to carry out upgrades linked to each functional module. An operation belonging to this step is associated with a functional module. This association does not have any binding effect on the execution.
  For example, some data upgrades linked to different modules can be run in parallel if they belong to the same phase. Their launch will follow the order of the modules, and then the order of the execution ranks.
• The post-upgrade step is used to carry out synchronization operations, or secondary updates whose execution is not mandatory to restart operations in a downgraded mode. It can be used to postpone the upgrade of old data, for example.
  Caution: Even though this step is not mandatory to restart operations, it must be carried out at some point for a folder to be considered as completely upgraded.
  The post-upgrade operations are launched by default in an upgrade plan but they are optional. They are listed in the appendix describing the upgrade procedures.

The unitary procedures are organized in phases and ranks:

• Two procedures defined in the same phase can be run simultaneously and should therefore be independent. The assignment of a standard procedure to a given phase cannot be changed. As long as all the procedures belonging to a phase are not completed, the next phase cannot be launched.
• The rank order is a purely preferential launch order but it can be modified when the plan is defined, including for standard procedures.

Purging the entry tables

This phase is manual. It is triggered by executing the TRTMIGDEL function. Running it deletes all tables with the "MIG" activity code.

Caution: You first have to make sure that the upgrade processing routines have been carried out successfully as this phase cannot be reversed.

Note: You can resume normal operations while the temporary tables are still in the folder. This allows you to access the original data for comparison or analysis purposes, should any problem occur in the weeks following the upgrade.

Verification after the upgrade

Example of sequencing on transaction tables upgrade

• Initialization step, 7 operations:
  • IN1 and IN2 in phase 1 (ranks 3 and 7)
  • IN3 and IN4, IN5 and IN6 in phase 2 (ranks 1 and 3, 5 and 9)
  • IN7 in phase 3
• Common data (TC) step, 6 operations:
  • TC1, TC2 and TC3 in phase 1 (ranks 3, 6 and 9)
  • TC4 in phase 2
  • TC5 and TC6 in phase 3
• Module step, 5 operations:
  • Step MO1, in the Financials module, in phase 2 (rank 1)
  • Steps MO2 and MO3, in the Stock module, in phases 1 and 2 respectively (ranks 1 and 2)
  • Steps MO4 and MO5, in the Sales module, in phases 1 and 2 respectively (rank 1)
  • Steps MO6 and MO7, in the Purchasing module, in phases 1 and 5 respectively (rank 1)

Assuming the upgrade plan is launched with a sequencing of tasks and a maximum number of two procedures running simultaneously, the sequencing can be as follows:

1. Initialization step:
   1. Procedures IN1 and IN2 are launched in this order.
   2. If procedure IN2 is completed first, no other procedure can be launched until procedure IN1 is completed (the following procedures are included in a phase or a step with a higher rank).
   3. When procedure IN1 is over, procedures IN3 and IN4 are launched in this order.
   4. If procedure IN4 is completed before procedure IN3, procedure IN5 will be launched. If procedure IN5 is completed before procedure IN3 is over, procedure IN6 will be launched, and it will run at the same time as procedure IN3.
   5. When procedures IN3 and IN6 are both completed, the initialization step is over.
2. Common data (TC) step:
   1. Procedures TC1 and TC2 are launched in this order.
   2. Procedure TC3 is launched when one of the two previous procedures has been completed.
   3. Procedure TC4 is launched when procedures TC1, TC2 and TC3 are completed. It will run on its own since there are no other procedures in this phase.
   4. Procedures TC5 and TC6 are launched and run in parallel when procedure TC4 is completed.
3. Module step:
   1. Procedures MO2 and MO6 are launched in this order and run in parallel.
   2. When one of these procedures is completed, Procedure MO4 is launched in parallel with MO2 or MO6, depending on which one of them is not completed.
   3. Procedures MO1 and MO3 are launched when all the previous procedures are completed.
   4. When one of them is completed, procedure MO5 is launched.
   5. Procedure MO7 is launched when procedure MO5 is launched.