Sage X3

Upgrading to v12
August 2023 – v3

©2021 THE SAGE GROUP PLC OR ITS LICENSORS. SAGE, SAGE LOGOS,SAGE PRODUCT AND
Course disclaimer
The course material provided (“Material”) is the property of The Sage Group plc or its licensors (“Sage”). Please do not
copy, reproduce, modify, distribute or disburse the Material without express consent from Sage.

The Material is intended to provide you with general guidance and is for information purposes only. All information in the
Material is valid at the time of publishing and is provided ”as is” with no guarantee of completeness, accuracy, timeliness
or of the results obtained, and without any warranty of any kind, express or implied. Whilst Sage has made every attempt to
ensure that all information in the Material has been obtained from reliable sources, it is not responsible for any errors or omissions in
the information. As such, the information in the Material does not constitute legal or professional advice and before making any
decision or taking any action you should consult a professional adviser. Sage may provide links to certain third-party websites.
Sage does not accept any responsibility for, nor makes any representations as to the accuracy of, any content on such
third-party websites. Whilst Sage may make changes to the Material at any time without notice, Sage is under no
obligation to update the Material whatsoever. In no event will Sage be liable to you for any direct, indirect, consequential, or
incidental loss or damage arising out of or in connection with your use of the Material.

The Sage product(s) and service(s) described herein is/are governed by Sage’s standard terms and conditions ("Sage
Product Terms"). Nothing in this document supplements, modifies, or amends any Sage Product Terms.

© 2020 The Sage Group plc or its licensors. All rights reserved. Sage, Sage logos, and Sage product and service names
mentioned herein are the trademarks of Sage Global Services Limited or its licensors. All other trademarks are the
property of their respective owners.

SAGE X3 2
Table of Contents
Welcome & Introduction .................................................................................................................... 5
Upgrade Resources .......................................................................................................................................................... 7
Upgrade Phases ................................................................................................................................................................ 8
Pre-migration Tasks ...................................................................................................................................................... 10
Installation & First Pass ................................................................................................................... 11
Technical & Functional Steps – First Pass ..................................................................................................................12
Production Folder Copy to U9PROD .............................................................................................................................13
YVERIFSPE Customization Detection Program .......................................................................................................... 14
Pre-Upgrade Mandatory Processes ...............................................................................................................................15
Table Preparation .......................................................................................................................................................... 18
Data Extraction Methods............................................................................................................................................... 20
New Version Installation ............................................................................................................................................... 22
Activity Code & Parameter Values ............................................................................................................................... 23
Copying the U9PROD Folder ......................................................................................................................................... 25
Validating the Folder .................................................................................................................................................... 27
Sequence Monitor .......................................................................................................................................................... 29
Applying Add-ons & Patches ......................................................................................................................................... 32
Fixing Customizations .................................................................................................................................................. 33
Additional Validations .................................................................................................................................................. 35
Customer Post-migration Tasks .................................................................................................................................. 36
Troubleshooting Tips .................................................................................................................................................... 37
Dry Run & Go Live Phases ................................................................................................................. 39
Customer Pre-Cutover Tasks ....................................................................................................................................... 40
Technical & Functional Steps – Dry Run & Go Live .................................................................................................... 41
Steps to Complete.......................................................................................................................................................... 42
Copying Directories – Step 8....................................................................................................................................... 44
Dictionary Copy – Step 10 .............................................................................................................................................46
Customer Post-migration Tasks .................................................................................................................................. 49
Miscellaenous Notes/Setup .......................................................................................................................................... 50
MongoDB Upgrade Tasks.................................................................................................................. 51

SAGE X3 3
 U9 Server ......................................................................................................................................................................... 52
V12 server ......................................................................................................................................................................... 54
MongoDB Restore of U9 data ........................................................................................................................................ 55
MongoDB Upgardes........................................................................................................................................................ 56
Appendix ........................................................................................................................................... 63
Folder Copy .....................................................................................................................................................................64
Appendix B – Table List................................................................................................................................................. 66
Summary............................................................................................................................................ 67

SAGE X3 4
Welcome & Introduction
Welcome to the Sage X3 Upgrading to v12 course. This course is intended to provide you with details
on the technical elements required to upgrade Sage X3.
This course is designed to provide you with knowledge of:
• Understand the three distinct phases for upgrading.
• Understand how to prepare the data for upgrading.
• Understand how to copy, import, and validate a folder.
• Understand the technical steps associated with upgrading data as part of the First Pass phase.
• Understand the differences between the Dry Run and Go Live phase steps compared to the
First Pass phase.

SAGE X3 5
Training image
During this course, you will have access to a training image for hands-on exercises. On the training
image, you will find everything you need to complete the upgrade.

SAGE X3 6
Upgrade Resources
Resources for Sage X3 Upgrades can be found on the Sage X3 Help website.
• Sage City is a great resource for upgrade information. The Tech corner has an upgrade section
for upgrading Sage X3. https://www.sagecity.com/us/sage_x3/sage-x3-global/w/ccoe-
tools/3326/upgrading-sage-x3---consultant-package
• Sage Version 12 help website has an upgrade process you can use as a guide to upgrade.
https://online-help.sageerpx3.com/erp/12/public/index.html

SAGE X3 7
Upgrade Phases
Before reviewing the upgrade process, it is important that you have an understanding of the three
phases specific to upgrading within the project planning process.

• Installation & First Pass Phase: This is the first pass of the upgrade and includes the new
version install, performing all steps required to migrate a copy of the production data to the
new version, and upgrading the customizations.
o The purpose of this phase is to test the upgrade of the data, documenting, and resolving
any errors that occurred and addressing customization issues.
o A best practice, that is highly recommended, is to fully document all
changes/customizations made during the upgrade process and ensure the customer is
given a copy, so they are aware of all the modifications made to the application.
o During this phase, you also must address any additional product add-ons that will be part
of the install, the upgrade of customizations and custom reports, functional configuration,
customer training and setup, unit testing, key user testing preparation, and user testing
and verification of data.
• Dry Run Phase: This is a repeat of the First Pass phase but does not include the installation or
customization changes. During the First Pass phase any errors encountered during the
upgrade should have been resolved providing for an environment in which the Customer can
test the upgraded data and customizations.
o The installation and program changes required to upgrade the customizations are still in
place from the First Pass and do not need to be done for the Dry Run phase

SAGE X3 8
• Go-Live Phase: This is a repeat of the Dry Run and considered the final step in the upgrading
of data. The previous phases should result in the elimination of critical go-live issues
allowing for the creation of the final production folder.
• Both the Integrator and the Customer have tasks they are responsible for in each step of the
upgrade process.
• It is important to keep in mind that production data is converted three separate times. One
time for each of the First Pass, Dry Run, and Go-Live phases.

SAGE X3 9
Pre-migration Tasks
Prior to the installation and upgrade of existing data, there are several pre-migration tasks that must
be completed by both the Customer and the Integrator. For the Pre-migration tasks, use the Upgrade
Configuration and Cutover Checklist spreadsheet.

• Make sure you review any comments on the Discussions tab in the spreadsheet for any further
information specific to tasks in this phase.

Customer tasks
For the Customer tasks, refer to the tasks associated with the Customer Pre-Migration Tasks (Prep/1st
Pass Only) phase. The steps in this phase include:
• The purchase and configuration of hardware necessary for the install.
• Building a list of custom reports to be upgraded and any customizations done in house, by the
partner, or by a 3rd party.
• Verifying activity codes are assigned to custom elements such as personalization’s and
assigned to standard statistical triggers and import/export templates.
Special Note: If the customer has Business Intelligence with Sage ERP X3 v6, you must also create a
list of Business Intelligence reports.

SAGE X3 10
Installation & First Pass
In the following lesson, you will learn about the various tools used throughout the various phases of
the upgrade project.
The topics in this lesson include:
• Technical & Functional Steps – First Pass
• YVERIFSPE.src Program and Log Review
• Execute Pre-upgrade U Programs
• Removing N.A. Addon Activity Codes
• Table Preparation
• Data Extraction
• V12 Installation
• Parameter Values
• Timeout Setting
• Copying the U9PROD Folder
• Validating the Folder
• Apply Add-ons & Patches
• Fixing Customizations
• Additional Validations
• Customer Post-migration Tasks
• Troubleshooting Tips

SAGE X3 11
Technical & Functional Steps – First Pass
The Upgrade Configuration & Cutover Checklist spreadsheet also includes both Technical and
Functional Steps completed by the Integrator throughout the First Pass process.

• For the Integrator tasks, refer to the tasks associated with the Technical Tasks (1st Pass),
Technical – Patches (1st Pass), Technical – Important Issues (1st pass), Financial Tasks (1st Pass),
and Dist. & MFG Tasks (1st pass) phases.
• The Financial, Distribution, and Manufacturing steps listed are specific to steps that must be
completed within the program for a successful upgrade.
• These steps are normally completed by individuals experienced with Financials, Distribution,
and Manufacturing processes and tasks in the program.
• All these tasks and steps serve as a checklist for the person(s) responsible for completing the
installation and initial upgrade of data.

SAGE X3 12
Production Folder Copy to U9PROD
For First Pass and Dry Run, you must make an exact copy of the production environment.
• Rename the copied environment to U9PROD where # is the number of the version you are
upgrading from.
o Note: To do this, reference addendum A at the end of this document.
• Make sure all batch jobs are completed, all users are out of the current Sage X3 program and
the accounting tasks show 0 journals/matching on hold.

SAGE X3 13
YVERIFSPE Customization Detection Program
The YVERIFSPE program is used to identify any Non-Standard bespoke changes to the child folders in
Sage X3.
• THE YVERIFSPE PROGRAM MUST BE EXECUTED BEFORE UPGRADING. If you have another
process for identifying bespoke changes, this step can be skipped.
• YVERIFSPE completes this by comparing elements of the X3 folder and the Child folder. Based
on the results, a log is created and is Formatted in Categories to display customizations that
it found.

List of Customized Elements in the logs

• Tables • Screen Field Actions
• Indexes • Objects
• Screens • Windows
• Screen Field Actions • Function
• Objects • Local Menus
• Windows • Misc Tables
• Function • Reports
• Tables • Parameters
• Indexes • Entry Points
• Screens • Processes

SAGE X3 14
Pre-Upgrade Mandatory Processes
Multiple mandatory processes have been created to prepare the pre-upgrade folder for extraction.
The following U processes MUST be executed prior to the extraction of the folder.
Note: The below processes can be launched in batch execution.
Module Procedure Description
Financials UUMGCTLCTP00 Entries
A/P-A/R accounting UUMGCTLTRS00 BP invoices
UUMGCTLSAL01 Quotation
UUMGCTLSAL02 Orders
Sales UUMGCTLSAL06 Deliveries
UUMGCTLSAL07 Returns
UUMGCTLSAL08 Invoices
UUMGCTLPUR01 Purchase requests
UUMGCTLPUR02 Normal orders
UUMGCTLPUR03 Contract orders
Purchasing
UUMGCTLPUR06 Receipts
UUMGCTLPUR07 Returns
UUMGCTLPUR08 Invoices
UUMGPRETRC04 Pre-loading of fields GACCDUDATE table: BPAPAY
Pre-loading of fields BPCUSTOMER table: BPAPYR, BPCRSK, CUR,
UUMGPRETRC07
Common data NTNAM, BPAADD, DAYMON, UVYCOD2
Pre-loading of fields BPSUPPLIER table: BPAPAY, BPAINV, BPSRSK,
UUMGPRETRC08
CUR, CNTNAM, BPAADD
UUMGPRESAL01 Pre-loading of fields SQUOTE table: BPAORD, BPIEECNUM, EECICT,
EECLOC SQUOTED table: PJT
UUMGPRESAL02 Pre-loading of fields SORDER table: BPAORD, BPAPYR , BPAINV,
EECICT, EECLOC SORDERQ table: PJT
UUMGPRESAL03 Pre-loading of fields SORDERC table: BPIEECNUM, EECICT, EECLOC
UUMGPRESAL04 Pre-loading of fields VSORDER table: BPAORD, BPAINV, EECICT,
EECLOCC
Sales
UUMGPRESAL05 Pre-loading of fields VSORDERC table: BPIEECNUM, EECICT,
EECLOC
UUMGPRESAL06 Pre-loading of fields SDELIVERY table: BPAINV SDELIVERYD table:
PJT
UUMGPRESAL07 Pre-loading of fields SRETURN table: BPIEECNUM, EECICT, EECTRN
SRETURND table: PJT
UUMGPRESAL08 Pre-loading of fields SINVOICE table: BPAPAY SINVOICED table: PJT

SAGE X3 15
 Module Procedure Description
UUMGPREPUR02 Pre-loading of fields PORDER table: EECICT, EECLOC, EECNUM,
BPOADD, BPONAM, BPOADDLIG, BPOPOSCOD, BPOCTY, BPOSAT,
BPOCRY, BPOCRYNAM, BPAPAY, BPAINV PORDERC table: EECNUM2
UUMGPREPUR04 Pre-loading of fields UPORDER table: EECICT, EECLOC, EECNUM,
Purchase BPOADD, BPONAM, BPOADDLIG, BPOPOSCOD, BPOCTY, BPOSAT,
BPOCRY, BPOCRYNAM, BPAPAY, BPAINV UPORDERC table: EECNUM2
UUMGPREPUR06 Pre-loading of fields PRECEIPT table: FFWADD, BPAINV, EECNUM
UUMGPREPUR07 Pre-loading of fields PRETURN table: FFWADD, BPAINV, BPRPAY,
BPAPAY, EECNUM PRETURND table: POHTYP

• Go Live Only Exports: If using the activity code removal program against the Production
folder, before going live, you must export all the “A” tables into a directory called SVG_A. The
purpose is to restore the activity codes after the main extract of all tables. This will allow the
customer to use their old version to compare against the new version.

• Best Practice: Always make a copy of the production folder to work from instead of the
production folder. This avoids the need for the A tables to be extracted as we will not make any
changes to the production folder and only the copy of production.
• The Y*, and Z* activity codes are removed from screens, screen fields, objects, windows,
window tabs, functions, and entry points that block standard components from being
upgraded. Keep the YVERIFSPE log file for the activity codes that were removed.
• The utility also creates the v7-v12 activity codes (XA*) in the U9 folder and reassigns the X*
Addon tables to use the new XA activity code. This is necessary for updates to occur to these
tables during the folder validation in the new version.
• The utility is made available by applying the ####ACTRM.dat patch update for the version
you are upgrading to, where #### is the current version number.
• The patch is available for download from the Partner portal under Sage X3 version of Product
Updates & Add-on Downloads > NA Upgrade Utilities. If you do not have access to the partner
portal, please contact your Sage representative to get information on how to access.
• Once completed, you should see a log report like the one on the following page showing the
appropriate utility.
• It is important to note that the activity code removal program will not impact table data.

Patching the ####ACTRM program

Patch the current version to the current activity removal program as stated previously.

SAGE X3 16
Running the ####ACTRM program
After the patch is applied, compile the process using the Process Script function then use the Process
Execution function under the Development > Utilities > Miscellaneous menu to run the appropriate
program.

• To determine which components are to be modified and to find any issues with customer
customizations, it is recommended that you run the program in simulation mode.
o You are given the option of running in Simulation mode after clicking OK to execute the
program.
o A log report is generated showing each of the activity codes affected.
o Important: This is the list that will need to be given to the customer and project manager.

Log report
The Log report displays automatically after the process has been completed. The report details all
activity codes affected and the end of the report displays changes.

Customer customizations
The log file should be used to help determine which Y and Z activity coded protected modifications
need to be reviewed under the new upgraded version.

SAGE X3 17
Table Preparation
There are several tasks that must be completed to prepare specific tables for the upgrade process.

Matching & accounting journals

The validation process in the new upgraded version checks to see if certain matching tables are
empty. It is important to note the following:
• Use the Accounting Task function under the Usage > Batch Server menu to determine if there
are any suspended journals or suspended matching processes. IMPORTANT: There can be no
Suspended Journals or Suspended Matching shown in accounting tasks or the Folder
Validation will not allow you to upgrade.
• Matching cannot be in process. The table Batch Matching (MTCBATCH) must be empty. (Note:
if there are journals on hold, export the MTCBATCH table to excel and send to customer and PM
and verify these are valid and should be corrected. If not valid, clear the MTCBATCH table and
continue upgrade)
• Accounting journals cannot be in the process of validation. The following tables must be
empty:
o GACCTMP
o GACCTMPA
o GACCTMPD
o GACIASTMP
o GACIASTMPD
o Note: Depending on the installation not all these tables may be present

Clear working tables

Using the Tables function under Development > Data and parameters, clear the following tables using
the Clear option. This process helps to make the upgrade process faster as the data in these tables is
temporary.
• ALSTRD
• ALISTER
• AWRKLOG
• AWRKLOGIND
• AWRKLOGMES
• ATMPTRA

SAGE X3 18
Removing N.A. Addon Activity Codes
• A special utility is used to remove N.A. Addon activity codes (X*) as well as Y* and Z* activity
codes from standard software components. This is required to allow those components to be
updated as part of the upgrade process. If doing this on a production folder, it is highly
recommended to perform a database backup beforehand.
• Run the process XTOV12ACTRM and you can choose to run in Simulation Mode to see what will
be removed. This is encouraged but be cautious not to run in Simulation Mode then forget to
run the program again. If you do not run again, your upgrade may fail in V12.
Note: To learn more about how to copy a folder, refer to the Folder Copy topic in the Appendix.
Go Live Only
• There are times a customer needs to access their old server and after you remove activity
codes and extract, they need to be restored by importing the ACTIV and AENTREE Tables from
the SVG_A folder.
• Use the DOSINTEG program and import back into the current extracted version. Only import
the 2 tables listed above.

SAGE X3 19
Data Extraction Methods
Once you have completed all the necessary changes and fixes for the U9PROD folder, you are ready to
extract the data. Now you must identify which method you are going to use. Currently, there are 2
methods, Automatic and Manual extract.

Console Export
As of Console version 2.57, multithreading is used by VCPU for additional extracted processes running
in unison. Make sure to update your Console version on your U9 server to Console 2.57 or higher before
starting the extract.
1. Open the console and click Folders in the solution.
2. Select the folder you want to export in the folders section.

3. Click the Export button.

• Using the Activate multithreads option with the number of Virtual CPUs on the server will
increase the output of the extract and decrease the time.

SAGE X3 20
Deleting unused directory files & preparing for transfer
1. Open the directory to the folder that you will be upgrading. Delete all files in the following
directories:
o Patch
o TMP
o TRA
o Any additional SVG directories not including the extract we made in the steps above.
2. Shut down X3 services for the next step.
3. Zip the upgrade folder directories in the Folders and X3Pub directories using 7z.
4. Move the files to your V12 server.

SAGE X3 21
New Version Installation
Prior to installing Sage X3, you must verify specific prerequisites are met as well as perform specific
checks in the version you are upgrading from.
1. From the Partner portal, download the install files for the current released Sage X3 version.
2. Once downloaded, click the index.htm file from the downloaded media for prerequisites and
install instructions.
3. The Index page displays each component, its version, and any linked documents.
4. The prerequisites and requirements are available through various links under Sage X3
Prerequisites and Installation requirements.

Installation
Once all the software requirements and prerequisites have been met, you are ready to install Sage X3
in a new environment.
• The most current version patches should also be installed (if applicable).
• Set the database back to simple mode on the upgrade server.

SAGE X3 22
Activity Code & Parameter Values
After installation Sage ERP X3, there are several parameter value changes that must be made prior to
copying the MIGVX folder created. All parameter values are changed through the Parameters values
function in the Parameters > General Parameters block. All changes should be made at the X3 Folder
level.

MIG activity Code

Activate the MIG Activity Code in the X3 folder.

NOSTOPERR & NBRTACSIM

Both the NOSTOPERR and NBRTACSIM parameter values must be changed for the SUP chapter an FDR
group.

• The NOSTOPERR parameter value should be changed to Yes.

• It is changed only for the first upgrade attempt and allows the upgrade to continue even if
issues exist.
• The issues can then be reviewed, and potential corrections implemented.
• It is recommended that the Number of tasks for migration field be changed to a minimum
which is defined below. With the sequence monitor, changing the number of tasks allows the
program to run multiple data conversions at the same time.
o NBRTACSIM - The standard setting is no number higher than the number of VCPU’s on the
V12 server.

SAGE X3 23
MAXUPDTRS
The MAXUPTRS defines the number of transactions that are written to a table before they are
committed. This is important during the validation process, which is run after copying the U9PROD
folder. For this parameter, set the value to 5000. The parameter value is changed under the SUP
chapter and the PRF group for the X3 folder.

SAGE X3 24
Copying the U9PROD Folder
Once the new version is installed and the appropriate parameters and settings are changed, you are
ready to copy the U9PROD folder into the new version environment.
• Use Windows Explorer to copy the entire U9PROD folder into the new environment. You must
also copy the folder under the X3_Pubs directory.
• Once copied, rename the folder. Typically, the name of the new folder is the same as the
production folder; however, for the First Pass, it is best practice that you name it U9PROD for
future readability.
• Remember to also change the folder name in the X3_Pubs directory.
• When copying the folder, check to see at what level any customized source code or crystal
reports reside. For example, some source/report may exist under the X3 folder. You would want
to copy those to the child folder under the new version so that they are not missing.

Importing the Folder

Use the SAFE X3 management console to import the folder. Use the following steps:
1. In the SAFE X3 management console, open the solution.
2. Click the folders icon.
3. Click the import icon.
4. In the Import a folder window, select U9PROD as the folder to be imported and SVG as the directory
containing the data. In the example below, we are importing the folder named U9PROD.

o At the SAFE X3 user and Password fields, enter the user and password for the X3 folder. In
most cases, the password can be left blank.

SAGE X3 25
 o Select X3 as both the Reference and Copy folder.
5. Click Ok to start the import. The Configuration window displays the progress of the import. Click
Details to view the status of each action.

o If an error occurs, the status indicates “Error !!!” and all additional actions are placed on
hold.
o You can view details of the error on the Trace tab.
6. Once the Folder import is complete, click Close to close the Configuration window.
7. The U9PROD folder should now display in the Folders list. We used U9PROD for the example.

8. Close the SAFE X3 V2 management console.

SAGE X3 26
Validating the Folder
Before validating the folder, you must verify the licensed features against the license file. After
importing the folder, you must validate the folder in Sage X3 v12. Use the Folders function under the
Setup > General parameters menu to validate the folder.
Note: You must be logged into the X3 folder to access the Validation option in the Folders function.

• Verify the parameters defined for the U9PROD folder including activating/deactivating the
appropriate activity codes and localizations. This will be defined by the license provided.
• On the Init tab, turn off copying statistics.
• Save the U9PROD folder definition.
• Once the appropriate parameters are set for the folder, click Validation in the Right panel.
• It is important to note the time it takes to complete this process as it is a good indicator for
the length of time needed when completing the Dry Run and Go Live phases.
• For the First Pass, clear the Deferred validation check box. For the Dry Run and Go Live, this
checkbox should be selected.
• While the validation process is running, you can monitor the status by opening the log file
under the …\X3\TRA directory.

SAGE X3 27
• Open the file in a utility that does not lock the file such as Notepad++.
• Once the log file indicates the migration plan has been created, it will be automatically
launched and can be checked using the Sequence monitor function.

Migration phases
There are five phases to the migration process.
• First Phase – Used to make a temporary copy of the larger dataset tables. These temp tables
begin with “U”.
o After the copy is made, the original tables are then cleared of data.
o This results in the upgrade running faster when those tables are updated.
• Second Phase (AMAJ in SUBADS2) – Used to update any table in which the old V6 data needs
to be converted.
• Third Phase – Normal folder validation. This is where the technical elements of the child
folder are compared to the X3 folder and if different, they are updated.
o If the child elements do not exist at the X3 level and they are not activity coded, then the
elements are deleted.
• Fourth Phase (MAJ in SUBADS2) – Used to update any table after the table itself has been
converted to the v7-v12 format.
• Fifth Phase – Sequencing monitor. Used to populate the larger dataset tables from the V6
temp tables that were created in the first phase.

SAGE X3 28
Sequence Monitor
Use the Sequencing monitor function in the Usage > Migrations block on the X3 folder to check and
make sure that the post migration data conversions are running properly. If the Sequencing Monitor
Jobs are not running, make sure that your batch server has been started.
• The top portion of the window identifies the migration plan being run, the folder, and number
or parallel launches allowed.

• The Monitor section shows the number of processes in each state listed such as the number of
processing pending or completed.
• Use the options in the Control section to Launch/resume process after they have been
suspended or interrupted, Interrupt, Suspend, Refresh, Block, and Unblock the list.
o If for some reason the servers require a restart or the SQL Server transaction log needs to
be truncated, the Suspend option may be used.
• The lower portion of the window lists the processes included in the migration plan created and
the status.

SAGE X3 29
• For each line item, it will display the status such as Completed, Launched, or Pending.
• Once each process has completed, you can view a Log report by clicking the Actions icon for
the appropriate process. You should review the log report for any errors.
o If errors occur, they must be addressed, or the migration will not continue.
• Once errors are corrected, you can click the Actions icon for the line and select to Restart,
Resume, or Bypass the process.
o Select Restart to restart the process from the beginning. This will clear the table and start
the process again. Do not use the Restart option on a cloned process.
o Select Resume to resume the process from the point of error.
o Select Bypass to bypass the error. This is done if the error can be ignored. For example,
some processes will validate screens before they run and there may be a space issue. All
the data converts fine but because of the space issue, the step is marked as in error. If you
bypass a process, the global time never stops and continues to increment until only X’s
appear.

Cloning
As discussed previously, it is possible to clone some of the processes for the large dataset to process
quicker.

SAGE X3 30
Blocking & Unblocking
Blocking can be useful in case there is a process you want to run after a certain phase is complete.
Simply right click in select block. To unblock, exit the function, go back in, right click on the blocked
line, and select unblock.

Troubleshooting – Correcting Errors

Correcting errors is a manual step. Most times the errors are related to data or programming bugs. If
this occurs, fix the data or the bug and restart or resume the process.

SAGE X3 31
Applying Add-ons & Patches
Once the migration is completed, you must apply any purchased NA add-ons as well as the V#
Migration patch.

Applying v# North American Add-ons

Turn on any purchased (optional software) activity codes and install the associated optional software
patches, if necessary.
• After the add-ons are applied, verify all X* activity code settings.
• Purchased add-on activity codes must be turned off if they are not installed.
• Turning of these activity codes may require a dictionary validation of all screens and windows
for the activity to be run.

Apply the Migration Patch for New Versions

The Migration patch includes the ###ADDUPG program that performs the Add-on/Cleanup process.
This process removes the old ADC functions (e.g. XACC, XADC, etc.), correctly sets the local menu
numbers and the associated global variables for the US-Addon Parameters and adds any missing
standard entry points.
• The patch is downloaded from the Partner portal under the NA Addon Patch download section.
Patch 27 is the last version of Sage X3 NA addons. Use this version to update the NA addons.
• Execute the ###ADDUPG program using the Run processes function under Miscellaneous in
the Development > Utilities block.
• When running the program, you are prompted if you want to upgrade the Add-ons. At this time,
you should select Yes.
• When completed, verify the add-ons were converted properly by reviewing the data.
• If data was converted correctly, run ###ADDUPG a second time by select No when prompted to
convert the add-ons and select Yes when prompted to clean up the old add-ons.

SAGE X3 32
Fixing Customizations
For the First Pass, you must test each customization that the Customer wants to keep in the new
version. Use the YVERIFSPE program results to find and resolve any issues and correct
customizations.
• Refer to the Customizations List spreadsheet for a list of customizations that should be
checked.
• You may need to manually fix some issues that the migration process has removed. Use the log
from the YVERIFSPE program on U9 and look for the log named List of modified objects on the
folder.
• Any issues encountered can be found by reviewing the ####ACTRM log files.
• Refer to the original X3 solution and production folder for reference, if needed.

Standard Activity Codes

Any standard activity code changes between old and new versions are lost and you must remember to
compare all activity codes between versions.
At this point you can optionally use the ATP process to check for customizations in X3 element:
You are executing ATP scripts to detect custom modifications. Each script will be executed one by
one to identify if the customized fields are where they were prior to the upgrade.
• The screen must be executed after the tables. If the script fails, it means the field was not found
on the screen and the script will add the field at this point.

ATP Customization Test - Tables

1. Log onto the v12 image assigned by the instructor.
2. In X3 make sure the U9PROD folder is setup as an Endpoint with the Nature set to Test and Enable
test robot selected.
3. Log out/into X3 and select the U9PROD folder just to confirm.
4. Open VS code and expand the workspace section.
5. In the parameters file change the endpointName1 and endpointName2 fields to U9PROD
6. In the Samples>03-Sample>0301-Connection folder run 0301A-DynamicLoginConnection.feature
7. Click on the TBLCustomFields_BPC.feature
8. Press F5 Connect to execute the script.
9. If the script shows an error that when the field is being added to the screen, this means the script
failed and the field is in the screen.

SAGE X3 33
10. Upon success of the script, it will add the customization back to the screen which is what we want
to see.
11. Repeat line 3. To 6. For the following scripts in the order below:
o TBLCustomFields_BPS.feature
o TBLCustomFields_ITS.feature

ATP Customization Test - Screens

In this lab, you are executing ATP scripts to detect custom modifications. Each script will be executed
one by one to identify if the customized fields are where they were prior to the upgrade.
• The tables must be executed first then the screens. If the script fails, it means the field was not
found and the script will add the field at this point.
1. Log onto the v12 image assigned by the instructor.
2. Open VS code and expand the workspace section.
3. Click on the SCRCustomFields_BPC.feature
4. Press F5 Connect to execute the script.
5. If the script shows an error that when the field is being added to the screen, this means the script
failed and the field is in the table.
6. Upon success of the script, it will add the customization back to the table which is what we want to
see.
7. Repeat line 3. To 6. For the following scripts in the order below:
o SCRCustomFields_BPS.feature
o SCRCustomFields_ITS.feature

SAGE X3 34
Additional Validations
In addition to validating the folder, you must also validate all screens, windows, objects, inquiries
and menus using the validation functions under Dictionary > Validations in the Development >
Utilities block.
• Run the Transaction generation function under Dictionary in the Development > Utilities
block.
• Run the Function Validation function under Dictionary in the Development > Utilities block.
• Run the Menus function for ALL menus (*). This is also found under Dictionary in the
Development > Utilities block.

SAGE X3 35
Customer Post-migration Tasks
After the U9PROD folder is validated and available in v#, there are several post-migration tasks that
must be completed by the Customer. For the Post-migration tasks task, use the Upgrade
Configuration and Cutover Checklist spreadsheet.

• Make sure you review any comments on the Discussions tab in the spreadsheet for any further
information specific to tasks in this phase.

Customer tasks
For the Customer tasks, refer to the tasks associated with the Customer Post-Migration Tasks (Prep/1st
Pass Only) phase. The steps in this phase include:
• Setting up backups and upgrading custom reports, requesters, workflows, purchasing/sales
signatures, and user menus.
• Updating printer destination to new server, setting up server for workflows and outbound
emails.
• Reviewing Left lists and memo codes and making any necessary adjustments.
• Testing financials postings.
o Select No for the following activity codes: SCTE, SFRPT, and SMI.
o Keep the differed validation check box selected.
• Review the TRA file to see the progression of the validation.

SAGE X3 36
Troubleshooting Tips
During the validation process, you may encounter errors. It is important to understand where those
errors occurred and how to resolve the errors to complete the validation process.
• Below is an example of how an error show in the TRA file.

• The Validation process will also indicate if errors were encountered, and you can view the
errors in the log file.

SAGE X3 37
• Use the Next error and Next warning options in the Right panel to navigate to errors and
warnings in the log file.
• The error message and location of the error will indicate where the problem occurred.
• It is critical that you understand that you CANNOT run the validation again on a folder where a
previous validation was run with errors.
• You can optionally start over to correct the issues prior to validation.

Table abbreviation duplicate error

A common error found during the validation is a duplicate key on a table index. In this case, you must
identify the duplicate(s) and make corrections.
• This can be done using SQL Server and logging onto the database.
• The table affected should have been identified in the log file. You should review the table for
duplicates.
• For any duplicates found, randomly make up abbreviations.
• Depending on what steps you take, you can either fix the table in the folder prior to starting
the validation and running the process again or modify the SUBADS2 program as discussed
previously.

Things to keep in mind.

During the First Pass phase, keep the following in mind:
• Keep the U9PROD and SVG directories. If things go wrong with trying to fix issues, can always
start over.
• The Sequence monitor values for record processed may not always be accurate. For accurate
values, you must check the associated log file.

SAGE X3 38
Dry Run & Go Live Phases
The steps for the Dry Run & Go Live phases are identical. The Dry Run is a complete test for the
eventual go live. Go Live is the final extraction and upgrading of data into v# in preparation for the
Customer to go live in the new installation.
All issues should have been resolved as part of the First Pass phase, so no new technical issues should
be encountered. Many of the steps are the same as those completed in the First Pass phase.
Only differences are discussed in this lesson.
The topics in this lesson include:
• Customer Pre-Cutover Tasks
• Technical & Functional Steps – Dry Run & Go Live
• Steps to Complete
• Copying Directories – Step 8
• Copying Tables – Step 9
• Dictionary Copy – Step 10
• Miscellaneous Notes/Setup

SAGE X3 39
Customer Pre-Cutover Tasks
Like the pre-migration tasks completed in the First Pass, there are several tasks that must be
completed before the Dry Run and Go-live Phases take place. These tasks are typically completed by
the Customer.

The tasks to complete are listed in the Upgrade Configuration and Cutover Checklist under Customer
Pre-Cutover Tasks – Existing Version (Dry Run & Go Live). These steps include such tasks as:
• Posting all invoices and receiving inter-site shipments.
• Running the Accounting Interface and WIP Accounting Interface.
• Ensuring no suspended journals exist.
• Executing financial reports.
Note: Refer to the Dry Run and Go Live columns to determine which tasks should be completed as
part of the Dry Run phase Memory and storage

SAGE X3 40
Technical & Functional Steps – Dry Run & Go Live
The Upgrade Configuration & Cutover Checklist spreadsheet also includes both Technical and
Functional Steps that are completed by the Integrator throughout the Dry Run/Go Live phases.

• For the Integrator tasks, refer to the tasks associated with the Technical Steps (Dry Run & Go-
Live Tasks), Financial Steps (Dry Run & Go-Live Tasks), and Dist. & MFG Steps (Dry Run & Go-
Live Tasks) phases.
o The tasks listed are both technical and functional in nature and consists of tasks that take
place before and after the upgrade of data during the Dry Run/Go Live phase.
o The Financial, Distribution, and Manufacturing steps listed are specific to steps that must
be completed within the program for a successful upgrade.
o All of these tasks and steps serve as a checklist for the person(s) responsible for
completing the Dry Run/Go Live phase.
o The Dry Run and Go Live columns in the Upgrade Configuration & Cutover Checklist
spreadsheet should be updated to indicate if specific tasks and steps are to be completed
in the Dry Run/Go Live phase.

SAGE X3 41
Steps to Complete
The steps for the Dry Run and Go Live phases are similar and are discussed together in the steps
below.
Source Server Dry Run Prep
1. From the source folder run Data Extract for all A* tables into an SVG_A directory. This is to protect
the integrity of the A tables in Production.

2. If applicable run any region-specific add-on upgrade processes.

3. On the source folder, execute program ####ACTRM to remove activity codes X*, Y*, and Z*.
4. Extract the data from the production folder copy.
o Because you are extracting data from the production folder (Go Live only) or the copied
production folder (U9PROD), it is important that no other users be on the system entering
data during this process.
o Verify the customer understands that X3 will not be available during this time.
o Once the extraction is completed, the Customer can resume normal day-to-day operations
for the Dry Run phase only.
o When completing the Go-Live phase, no new data should be entered in the previous
version. All security should be removed once data is extracted so users can no longer
access the program.
5. Under the Sage\XXXX\folders directory, make a copy of the U9PROD folder directory and rename
the copy to the Dry Run/Go Live folder name specified by the customer or PM.
6. Do the same steps for the U9PROD folder under the Sage\XXXX\folders\X3_PUB directory.
7. Copy the production folder to the new v# installation. This is considered your Dry Run/Go Live
folder.

SAGE X3 42
V12 Server
1. Validate the new Dry Run/Go Live folder in v12.
2. *NEW - Once the validation is complete, technical elements from the U9PROD folder created in
the First Pass phase are copied to the Dry Run/Go Live folder. Install regional specific add-ons (for
example XA14 import tracking will need to be updated after folder validation). Refer to the
instructions for installing the add-ons for your region.
o Note: Only patch the child folder with region specific add-ons and not the X3 folder.
o Note: Additional information is provided in the following topics for this lesson.
3. *NEW - Perform a data extraction of the specific tables from the U9PROD folder and integrate
them into the Dry Run/Go Live folder.
o Note: Additional information is provided in the following topics for this lesson.
4. *NEW – Define access rights to the First Pass/Dry Run folders so that dictionary elements can be
copied to the Go live folder.
o Note: Additional information is provided in the following topics for this lesson.

SAGE X3 43
Copying Directories – Step 8
Once the Dry Run/Go Live folder validation is complete, technical elements from the U9PROD folder
created as part of the First Pass phase are copied to the Dry Run/Go Live folder (newly created
production folder U9PROD).
Copying this information carries over any fixes that were performed against the U9PROD folder as
part of the First Pass \ Dry Run phase.
1. Stop All X3 services.
2. Under the folders directory, go to the Dry Run/Go Live folder directory (U9PROD) and rename the
following directories:
o ECR to ECR_OLD
o ETM to ETM_OLD
o MENG to MENG_OLD
o REPORT to REPORT_Old
o TRT to TRT_old
3. Copy the following directories/files from the \folders\source (FIRSTPASS) folder to the
Destination folder directory. You will need to overwrite the Menu* and Text* files.
o ECR
o ETM
o MENG
o REPORT
o TRT
o Atx.ind
o Menu* (all files that start with menu)
o Text* (all files that start with text)

Copy Tables from Source folder to Destination folder.

Before you can copy the dictionary elements, you must set the appropriate access rights between the
Dry Run/Go Live folder and the SOURCE folder to allow dictionary elements to be copied between
folders.

SAGE X3 44
1. In the Folders function, select the SOURCE (FIRSTPASS) folder.
2. In the Access Rights to the Folder section on the Links tab, select ALL at the Authorization granted
for field for the Dry Run/Go Live folder.
3. Perform a data extraction of the following tables in Appendix B from the Source folder and
integrate them into the Dry Run/Go Live folder. This must be completed before
copying/revalidating any technical elements from the Source folder. To do this, export out tables
into a blank SVG directory.

Data Extraction
4. Ensure you are connected to the source folder and perform a data extraction of the following
tables in Appendix B
5. Open the navigator and type DOSEXTRA and press enter.
6. Cut the SVG directory from the source folder that was created in the last step and paste it in the
destination folders directory for importing into the destination.

Data Integration
7. Connect to the destination folder.
8. Open the navigator and type DOSINTEG and press enter.
9. Perform a data Integration and select the SVG directory above and use * for all tables. Import all 35
or so tables into the destination folder.
10. It is important that you check with the Customer if any additional tables should be copied in case,
they made additional changes.
11. Refer to the Upgrade Configuration and Cutover Checklist for the tables to extract data from.

SAGE X3 45
Dictionary Copy – Step 10
Dictionary elements are copied from the Source folder to the Dry Run/Go Live folder.
This step is only performed during the Dry run and Go Live phases.
1. Log into the destination folder and go to Dev > Dictionary > copies and click on Dictionary and set
source folder.
2. Set the destination folder to the production folder and check the following

3. Click OK.
4. Open new session of X3 in the same browser, go to Dev>Dictionary>copies click on Transactions.
o Set the source and destination folders like we did for the dictionary copy.
o Change to Yes to all on the Copy.
o Click Ok. If you get an error, click ok and continue. These are normal for when they already
exist.
5. V9-V12 - In X3, under the X3 Folder, go to copies > postal Codes. Run for US, CA and MX or any other
countries address information you need.
o Note: Make sure you have the X3 admin password for the original version as it will ask for
that password when attempting to copy to another folder.

6. Select Yes to Geographical subdivisions.

7. Click OK

SAGE X3 46
Dictionary Validation/Transaction Generation
1. Log into production folder and run Dictionary validation.
o Check Tables, Views, Screens, Objects, Windows, Inquiry, and menus. Do not check any
generated because the next step is transaction validation.
o Make sure the Deferred is not Checked and click ok.
o When the Dictionary validation has completed, you can now start the transaction
generation process.
2. Go to Transaction Generation in Production folder and uncheck deferred validation. Click ok
3. If you receive any errors, investigate.
4. Note: Run only after Go Live has been online live for 1 month. The U* temp tables from the folder
validation are not automatically deleted. These can be deleted by running the process
TRTMIGDEL.
5. Make sure the publish the Production folder Print server and ADC servers.
o In the ADC server, go to the list of elements and update the ctermconfig
o In Sage X3, log into the production folder and update all print server destinations to the
new Print server address.

6. Run from another tab Dev > Dictionary > validations > Site function profiles.
7. On a new tab go into x3>Administration>Usage>Search Index Management. Uncheck “Update
modified records only” and then click on update index.
8. Set the database back to Full mode on the upgrade server.
9. Restore all Custom activity codes.
10. Change Default Endpoint to the appropriate folder on Syracuse Groups.

ATP – custom elements

As you did in the First Pass/Dry Run you can also optionally use the ATP process to check for custom
elements:
You are executing ATP scripts to detect custom modifications. Each script will be executed one by
one to identify if the customized fields are where they were prior to the upgrade.
• The screen must be executed after the tables. If the script fails, it means the field was not found
on the screen and the script will add the field at this point.

SAGE X3 47
ATP Customization Test - Tables
1. Log onto the v12 image assigned by the instructor.
2. In X3 make sure the U9PROD folder is setup as an Endpoint with the Nature set to Test and Enable
test robot selected.
3. Log out/into X3 and select the U9PROD folder just to confirm.
4. Open VS code and expand the workspace section.
5. In the parameters file change the endpointName1 and endpointName2 fields to U9PROD
6. In the Samples>03-Sample>0301-Connection folder run 0301A-DynamicLoginConnection.feature
7. Click on the TBLCustomFields_BPC.feature
8. Press F5 Connect to execute the script.
o If the script shows an error that when the field is being added to the screen, this means the
script failed and the field is in the screen.
o Upon success of the script, it will add the customization back to the screen which is what
we want to see.
9. Repeat line 3. To 6. For the following scripts in the order below:
a. TBLCustomFields_BPS.feature
b. TBLCustomFields_ITS.feature

ATP Customization Test - Screens

You are executing ATP scripts to detect custom modifications. Each script will be executed one by
one to identify if the customized fields are where they were prior to the upgrade.
The tables must be executed first then the screens. If the script fails, it means the field was not found
and the script will add the field at this point.
1. Log onto the v12 image assigned by the instructor.
2. Open VS code and expand the workspace section.
3. Click on the SCRCustomFields_BPC.feature
4. Press F5 Connect to execute the script.
o If the script shows an error that when the field is being added to the screen, this means the
script failed and the field is in the table.
o Upon success of the script, it will add the customization back to the table which is what we
want to see.
5. Repeat line 3. To 6. For the following scripts in the order below:
o SCRCustomFields_BPS.feature
o SCRCustomFields_ITS.feature

SAGE X3 48
Customer Post-migration Tasks
After the U9PROD folder is validated and available in v#, there are several post-migration tasks that
must be completed by the Customer. For the Post-migration tasks task, use the Upgrade
Configuration and Cutover Checklist spreadsheet.

• Make sure you review any comments on the Discussions tab in the spreadsheet for any further
information specific to tasks in this phase.

Customer tasks
For the Customer tasks, refer to the tasks associated with the Customer Post-Migration Tasks (Prep/1st
Pass Only) phase. The steps in this phase include:
• Setting up backups and upgrading custom reports, requesters, workflows, purchasing/sales
signatures, and user menus.
• Updating printer destination to new server, setting up server for workflows and outbound
emails.
• Reviewing Left lists and memo codes and making any necessary adjustments.
• Testing financials postings.
o Select No for the following activity codes: SCTE, SFRPT, and SMI.
o Keep the differed validation check box selected.
• Review the TRA file to see the progression of the validation.

SAGE X3 49
Miscellaenous Notes/Setup
Keep in mind the following about the Dry Run and Go Live phases.
• If running EDI, you must change the import/export parameters to point to the correct
directories within the new v# solution.
• Make sure to install any stored procedures/views required for any add-ons (i.e. shipping
system, etc.).
• Recurring tasks must be recreated by the Customer.

Going Live
When preparing and getting ready to go live with the completed production folder in Sage X3 v#,
keep the following in mind:
• No users should be connected to Sage X3.
• Batch server is stopped, and no batch task is running.
• Add database backups are disabled.
• Ensure no servers will reboot during the process.
o For instance, this could happen if Windows automatic updates is configured to do so.
o Be sure it will not do this during the Go Live process.
• From the First Pass and Dry Run, you should have a good idea of how long the upgrade process
will take for Go live.
• Try to have the customer give you the system as soon as possible so that it finishes on time.
• For large customers, it may be necessary to upgrade them over a 3 day weekend/holiday.
• Keep in mind that issues can always pop-up during the process. Do not promise the customer
that the system will be ready at a certain time without giving yourself breathing room in case
something does happen.

SAGE X3 50
MongoDB Upgrade Tasks
The topics in this lesson provide information on how to upgrade a U9 MongoDB with SSL/NOSSL to a
new V12 instance already installed on the new V12 server.
The topics in this lesson include:
• U9 Server
• V12 Server
• MongoDB Restore of U9 data
• MongoDB Upgrades

SAGE X3 51
U9 Server
1. Create a directory on the U9 server named MongoBackup in the c:\Temp\ directory to store our
MongoDB backup from the pre-upgraded version of U9.
2. Copy the MongoDump.cmd file to the c:\Temp\ directory and edit the file in Notepad++.
3. MongoDump.cmd script consist of the following lines in the MongoDump.cmd file that need to be
updated with the parameters from the U9 server.
4. Open the MongoDump.cmd by right clicking on the file and selecting “Edit with Notepad++”.
5. set "mongodb_rootdir=C:\Sage\FreeComponents\X3PU9MONGO ".
6. set "mongodb_bindir=%mongodb_rootdir%\mongodb-win32-x86_64-2008plus-ssl-3.6.14\bin".
o This is within the MongoDB root directory.
7. set "connectionstring=X3PU9TRAINVM:27017"
o Here are the steps to get the hostname and port # if you need it:
▪ Open CMD, type hostname, and hit enter for the server’s name. Copy and paste or type
the name and replace Server name. Do not use Localhost.
▪ Replace the port with the port # identified in the MongoDB.conf in the above steps.
8. Set "mongodump_dir=c:\Temp\MongoBackup "
9. This directory will store the syracuse backup files from the MongoDBDump program.
10. Set "ssl_enabled=1"
11. If your MongoDB.conf has the ssl: mode setting showing “requiredSSL”, then you must have this
set to 1.
12. If there are no ssl certificates used, then the entry would be ssl: disabled as shown below.
o With SSL:

o Without SSL:

SAGE X3 52
13. If SSL is used on this MongoDB server,
o Set to 1. Otherwise, set to 0.
o Set the Syracuse rootdir to use the MongoDB certifications within the Certs directory
inside syracuse directory structure.
▪ set "syracuse_rootdir=C:\Sage\SAFEX3\X3PU9SYRA"
▪ set "mongodb_certsdir=%syracuse_rootdir%\syracuse\certs\mongodb
14. If not using SSL, Disregard this step.
15. Save the file in c:\Temp.
16. Open a command Window with administrator privileges.
17. Type “cd/” and press enter.
18. Type “cd temp” and press enter.
19. Type Mongodump.cmd and press enter.
o If you receive any errors, you must correct the issues and retry.
20. If it says it cannot find the server, one of your path strings are not set correctly. This is the primary
reason for failure. Double check each parameter and verify it is set correctly. Also, verify MongoDB
Service is running.
21. Now that you have the extracted data, use 7-Zip to compress the “syracuse” directory located in
the MongoBackup directory.
22. When the directory finishes zipping, copy the mongodb backup file to the V12 server.

SAGE X3 53
V12 server
You must download and install the same version of MongoDB that you are using on the pre-upgrade
version server. Mongodb versions, 3.6.14, 4.0.18, 4.2.8, and 4.4.12 will need to be used for the Mongodb
upgrade. These files will be installed after the restore of the data.
1. Click the Stop all X3 Services shortcut on the Windows Desktop. This will stop all the services for
the normal V12 server.
2. Open Task Manager by right clicking on your Task Bar.
3. Click the Details Tab and scroll down to find any Node.exe programs running.
4. Click on the Node.exe and select End Task for all the Node.exe instances displayed.
5. Install the same Mongo version as the source system using a different port than the MongoDB
running on V12. Make sure to consult the mongodb.conf in the %rootdirectory%\config directory.
This will show you the port you are running on the production instance of MongoDB.
6. Create a new directory named “MongoDB36” in the following location.
D:\Sage\Safex3\MongoDB36.
7. Use the SageX3 MongoDB 3.6.14 installation jar file to install MongoDB 3.6.14 to the MongoDB36
directory. This is the same version of MongoDB used in our U9 version. We will restore the Data to
this installation of MongoDB.
8. Accept the license agreement.
9. Click New installation and use the D:\Sage\SafeX3\MongoDB36 directory.
10. Name the node MONGO02.
11. Change the port to 27018, click Next.
12. We are not using SSL to import the data into this new instance. It is an unnecessary step if you are
not moving the data over private or public networks. Make sure the checkbox for the server is
unchecked.
13. Make sure the Import and initialize checkbox is unchecked.
14. Click Next, until it finishes the install from here.
15. Click Done.

SAGE X3 54
MongoDB Restore of U9 data
We must restore the U9 MongoDB data back to the original version of mongodb on this new server.
1. Copy the MongoDump.cmd and MongoRestore.cmd to the D:\temp directory.
2. In D:\Temp, create a new directory named restoreU9.
3. Extract the Syracuse backup from U9 to the restoreU9 directory.
4. Open the MongoRestore.cmd file in Notepad++ from the D:\Temp directory. Changes must be made
like the changes made in the MongoDump.cmd file.
5. Change the MongoDB root directory to "mongodb_rootdir=D:\Sage\Safex3\MongoDB36"
6. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\
D:\Sage\SafeX3\MongoDB36\mongodb-win32-x86_64-2008plus-ssl-3.6.14\bin"
7. Change the connection string to X3ERPV12SQLVM:27018.
8. Change the mongodump directory to D:\Temp\restoreU9\syracuse.
9. Change ssl_enabled to 0.
10. Save the file in the D:\Temp directory as MongoRestoreU9.cmd.
11. Open a command window and change directory to D:\Temp. (C:
12. Type MongoRestoreU9.cmd and press enter.

SAGE X3 55
MongoDB Upgardes
4.0.18 Upgrade
1. Close all CMD windows.
2. To install MongoDB 4.0.18, click on the SageX3 MongoDB 4.0.18 jar file.
3. Click OK and accept the Mongo warning and the license agreement.
4. Click on the modify installation selection and choose the MongoDB 3.6.14 version.
5. Click Next 2 times.
6. Keep the default setting in the service configuration screen.
7. We are not using SSL to import the data into this new instance. It is an unnecessary step if you are
not moving the data over private or public networks. Make sure the checkbox for the server is
unchecked.
8. Click Next until installation has completed.

MongoDB 4.2.8 Upgrade

1. To install MongoDB 4.2 click on the SageX3 MongoDB 4.2.8 jar file.
2. Click OK and accept the Mongo warning and the license agreement.
3. Click on the modify installation selection and choose the MongoDB 4.0.18 version.
4. Click Next 2 times.
5. Keep the default setting in the service configuration screen.
6. We are not using SSL to import the data into this new instance. It is an unnecessary step if you are
not moving the data over private or public networks. Make sure the checkbox for the server is
unchecked.
7. Click Next until installation has completed.

MongoDB 4.2 WiredTiger setup

This step is due to the MongoDB requirements for upgrading Mongodb 4.2 to 4.4. We are dumping
the MongoDB 4.2 data into the Mongodump42 directory to be used to restore to the same
database after making the directory changes required for this version.
1. In D:\Temp, create a new directory named mongodump42.
2. Open the MongoDump.cmd file in Notepad++ from the D:\Temp directory.
3. Change the MongoDB root directory to "mongodb_rootdir=D:\Sage\Safex3\MongoDB36 "
4. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\
D:\Sage\SafeX3\MongoDB36\mongodb-win32-x86_64-2012plus-4.2.8\bin"
5. Change the connection string to X3ERPV12SQLVM:27018.
6. Change the mongodump directory to D:\Temp\MongoDump42.

SAGE X3 56
7. Change ssl_enabled to 0.
8. Save the file in the D:\Temp directory as Mongodump42.cmd.
9. Open a command window and change directory to D:\Temp.
10. Type Mongodump42.cmd file and press enter.
11. Data dump has completed. Close the command window.

MongoRestore42
1. Stop the Safe X3 MongoDB MONGO02 service.
2. Open the MongoDB 4.2 installation directory at D:\Sage\SafeX3\MongoDB36 and rename the data
directory to data_back.
3. Create a new data directory.
4. Start the Mongo02 service.
5. This recreates the data directory file structure to the new WiredTiger format.
6. Now we must restore our Mongo42 backup to the Mongo36 empty database.
7. Open the MongoRestore.cmd file in Notepad++ from the D:\Temp directory. Changes must be made
like the changes made in the previous files.
8. Change the MongoDB root directory to "mongodb_rootdir=D:\Sage\Safex3\MongoDB36"
9. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\
D:\Sage\SafeX3\MongoDB36\mongodb-win32-x86_64-2012plus-4.2.8\bin"
10. Change the connection string to X3ERPV12SQLVM:27018.
11. Change the mongodump directory to D:\Temp\MongoDump42.
12. Change ssl_enabled to 0.
13. Save the file in the D:\Temp directory as MongoRestore42.cmd.
14. Open a command window and change directory to D:\Temp.
15. Type MongoRestore42.cmd and press enter.
16. Close the Command window.
17. Review the Mongodb36 data directory files to ensure the data has been imported. You should see
the size change, but it may take up to 30 seconds to display the change.

Upgrade Mongo 4.4

1. To install MongoDB 4.4.12 click on the SageX3 MongoDB 4.4.12 jar file.
2. Click OK and accept the Mongo warning and the license agreement.
3. Click on the modify installation selection and choose the MongoDB 4.2.8 version.
4. Click Next 2 times.

SAGE X3 57
5. Keep the default setting in the service configuration screen and click next.
6. We are not using SSL to import the data into this new instance. It is an unnecessary step if you are
not moving the data over private or public networks. Make sure the checkbox for the server is
unchecked.
7. Click Next until installation has completed.

MongoDB upgraded 4.4 dump

1. In D:\Temp create a directory named mongodump44. This backup is for the upgraded 4.4 data.
2. Open the Mongodump42.cmd file in Notepad++ from the D:\Temp directory. Changes must be
made like the changes made in the MongoDump42.cmd file but for the MongoDB 4.4 server .
3. Change the MongoDB root directory to "mongodb_rootdir= D:\Sage\SafeX3\MongoDB36"
4. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\ mongodb-
database-tools-windows-x86_64-100.5.2\bin"
5. Change the connection string to X3ERPV12SQLVM:27018.
6. Change the mongodump directory to D:\Temp\MongoDump44.
7. Change ssl_enabled to 0.
8. Save the file in the D:\Temp directory as Mongodump44.cmd.
9. Open a command window and change directory to D:\Temp.
10. Type Mongodump44.cmd and press enter.
11. Stop the Mongo02 service so not to back up the wrong instance.

Remove SSL
1. Stop the Mongo01 service for the MongoDB installation of the production 4.4 server.
2. Open the D:\Sage\SafeX3\MongoDB\config directory and make a copy of the file mongodb.conf.
3. Open the Mongodb.conf file and update the line 20, “mode: requireTLS” and change this to “mode:
disabled”.
4. Add # to beginning of line numbers, 21 and 22.
5. Before the change

6. After the change

SAGE X3 58
7. Save the file and start the Mongo01 service.

MongoDB 4.4 production dump

1. In D:\Temp create a directory named MongoDump44ProdBack. This backup is for the production
4.4.
2. Open the Mongodump44.cmd file in Notepad++ from the D:\Temp directory.
3. Change the MongoDB root directory to "mongodb_rootdir= D:\Sage\SafeX3\MongoDB"
4. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\ mongodb-
database-tools-windows-x86_64-100.5.2\bin"
5. Change the connection to use the production port of 27017.
6. Change the mongodump directory to D:\Temp\MongoDump44ProdBack.
7. Change ssl_enabled to 0.
8. Save the file in the D:\Temp directory as MongoDump44ProdBack.cmd.
9. Open a command window and change directory to D:\Temp.
10. Type MongoDump44ProdBack.cmd and press enter.

MongoDB upgraded 4.4 restore to production 4.4.

1. In D:\Temp create a directory named mongodump44_backup.
2. Open the D:\Temp\mongodump44 directory and cut/paste the following files to the
mongodump44_backup directory.
o CaCertificate.bson.gz
o CaCertificate.metadata.json.gz
o Certificate.bson.gz
o Certificate.metadata.json.gz
o Host.bson.gz
o Host.metadata.json.gz
o license.bson.gz
o license.metadata.json.gz
o X3solution.bson.gz
o X3solution.metadata.json.gz
3. Open the MongoRestore42.cmd file in Notepad++ from the D:\Temp directory.

SAGE X3 59
4. Change the MongoDB root directory to "mongodb_rootdir= D:\Sage\SafeX3\MongoDB"
5. Change the MongoDB bin directory location to "mongodb_bindir=%mongodb_rootdir%\ mongodb-
database-tools-windows-x86_64-100.5.2\bin"
6. Change the connection string to X3ERPV12SQLVM:27017.
7. Change the mongodump directory to D:\Temp\MongoDump44\syracuse.
8. Change ssl_enabled to 0.
9. Change ‘X3Solution’ to ‘Application’ on lines 224 and 227

10. Save the file in the D:\Temp directory as MongoRestoreProd.cmd.

11. Open a command window and change directory to D:\Temp.
12. Type MongoRestoreProd.cmd and press enter.
13. This will restore only the collections that we want to use in the Production V12.

Import Prod X3Solutions collection.

1. In D:\Temp create a directory named prodx3solution.
2. Copy the following files from D:\temp\Mongodump44Prodback to D:\temp\prodx3solution
Directory for restoring key collections.
o CaCertificate.bson.gz
o CaCertificate.metadata.json.gz
o Certificate.bson.gz
o Certificate.metadata.json.gz
o Host.bson.gz
o Host.metadata.json.gz
o license.bson.gz
o license.metadata.json.gz
o X3solution.bson.gz
o X3solution.metadata.json.gz
3. Open the MongoRestoreX3Solution.cmd file in Notepad++ from the D:\Temp directory.
4. Change the mongodump directory to D:\Temp\prodx3solution
5. Change ssl_enabled to 0.

SAGE X3 60
6. Change ‘Application’ to ‘X3solution’ on lines 225 and 228

7. Save the file in the D:\Temp directory as MongoRestoreX3Solution.cmd.

8. Open a command window and change directory to D:\Temp.
9. Type MongoRestoreX3Solution.cmd and press enter.

Add SSL back to mongodb.conf in the production mongo installation.

Stop the Mongo01 service for the MongoDB installation of the production 4.4 server.
1. Open the mongodb.conf from D:\Sage\SafeX3\MongoDB\config directory.
2. Update the line 20, “mode: disabled” and change this to “mode: requireTLS”.
3. Remove the # from the beginning of line numbers 21 and 22.
4. Save the file.

Access Sage X3
1. On the desktop, click the start X3 Standard services.
2. Open X3 V12 on the production server with the username/password of admin/admin. This is the
password from U9 so you must update the administrator password.
3. You will receive an error message because it will try to load a folder it does not have from U9.
4. Change the folder to the Syracuse administration and click Administration>Endpoints>Endpoints.
5. Delete the X3 endpoint and create a new X3 endpoint by making the following changes.
6. Change the name to X3ERPV12_X3.
7. Change the description to X3ERPV12 / X3.
8. Choose the X3 ERP application server.
9. Select the X3ERPV12 X3 solution from the drop-down menu.
10. Choose the X3 folder.
11. In Groups, add the Super Administrators Group
12. Click Save.
13. Delete the SEED endpoint and create a new SEED endpoint by making the following changes.
14. Change the name to X3ERPV12_SEED.

SAGE X3 61
15. Change the description to X3ERPV12 / SEED.
16. Choose the X3 ERP application server.
17. Select the X3ERPV12 X3 solution from the drop-down menu.
18. Choose the SEED folder.
19. In Groups, add the Super Administrators Group
20. Click Save.
21. Open the U9PROD Endpoint and add the X3 solution (X3ERPV12)
22. Set the Nature to ‘Test’ and check ‘Enable test robot’
23. Click Save
24. Exit X3 in the browser and log back into X3.
25. Load the SEED Endpoint and the X3 Endpoint so there are no issues that show.
26. Load the U9PROD Endpoint
27. Create Endpoint user for UpgradeTest (copy ADMIN Endpoint user).
28. Click Administration>Users and make sure the UpgradeTest user is showing.
29. Edit the UpgradeTest user, change the password to password and save.
30. Log out of X3 and back into X3 as the UpgradeTest user.

SAGE X3 62
Appendix
Includes the following appendixes:
• Appendix A – Folder Copy
• Appendix B – Table List

SAGE X3 63
Folder Copy
The first step of the First Pass phase is to create a copy of the current production folder in either
Sage X3 PU9. This copy is typically called MIGVX, where X represents the version. This folder should
reside on the current production system.

Table Report
When making a copy of the production folder, it is important that you ensure sufficient disk space is
available prior to creating the copy. To aid you in determining the size of the current production
folder, log into the production folder and use the Table Report function under the Development >
Utilities > Verifications > Database menu.

• The total folder size displays at the bottom of the window.

• Once it’s ran select all (or just the larger files that will take the most time) and export to Excel.
o This can be used to help you track the tables that you have upgraded. This is so you don’t
duplicate the data. See example in the class documents.

Copying a Folder
Although there are several methods you can use to copy a folder, it is recommended that you use the
Sage X3 management console. Depending on how the management console was configured you may
need to switch Windows users.
In the Sage X3 management console, click Solutions in the Left bar.
1. Once the solutions display, click the folders icon.
2. Once the folders display, select the folder you want to copy from and click the Copy icon.

SAGE X3 64
3. Enter the name of the folder to be created. This should be MIGVX, where X represents the version.
For example, when creating a copy of a v6 folder, the folder name would be MIGV6.

4. Click OK.
5. In the Folder import window, verify the appropriate reference folder and copy folder are selected
and click Next to begin the copy and configuration process.

SAGE X3 65
Appendix B – Table List
Table Name Description
ACCCOD Access Codes
ACCES Access by User
ACODNUM Doc sequence numbers
ACTIV Activity codes
ADOVALAUS User parameter values
AENTREE Entry Points
AFCTFCT User function profile
AFCTFCY Site profile function
AFCTPRF Functional authorization
AGLOBVAR Global variables
AMENUSER User profile menu
APRINTER Destinations
APROFIL User profile
APRTAUS Destinations by user
AREPORT Report dictionary
AREPORTD Report parameters
AREPORTV Reports
AREPORTX Reports
PARSTOACC Stock interface setup
AUTILIS Users
AVOCAB Personalized vocabulary
BPCCATEG Customer Category
BPSCATEG Supplier Category
DIAHOU Time table schemas
GACCCODE Accounting codes
GACCCODLIG Accounting codes Lines
GACCDENCOD Payment attribute
GJOURNAL Journal Codes
PARWIPACC Wipcost-interface parameter
PARWIPACCS Wipcost-interface parameter
TABCOSTMET Valuation methods
TABCOUAFF Sequence No assignments
TABDEPAGIO Early discount/late charge table
TABFOR Formula table
TABPRTMOD Print template table

SAGE X3 66
Summary
You have learned:
• The three distinct phases for upgrading.
• How to prepare the data for upgrading.
• How to copy, import, and validate a folder.
• The technical steps associated with upgrading data as part of the First Pass phase.
• The differences between the Dry Run and Go Live phase steps compared to the First Pass
phase.

SAGE X3 67
 www.sageu.com

©2022 THE SAGE GROUP PLC OR ITS LICENSORS. SAGE, SAGE LOGOS,SAGE PRODUCT AND
SERVICE NAMES MENTIONED HEREIN ARE THE TRADEMARKS OF THE SAGE GROUP PLC OR ITS
LICENSORS. ALL OTHER TRADEMARKS ARE THE PROPERTY OF THEIR RESPECTIVE OWNERS.