Upgrading an existing Sage X3 solution

This document explains how to upgrade an existing Sage X3 solution to the latest version release.

Caution: Before you perform the upgrade, make sure you:

Contact your local Sage Sales office in order to get your new license.
Perform a full backup of your system.

Updating the console

Run the console-M.m.P.jar file located in the X3Installs\Console folder of the V12 DVD-ROM.
Note that the Console can only be installed on platforms running Windows Operating System.

Caution: If the prior version of the Console belongs to the "SAFE X3 V1" generation (for example, CFG.124), you have to unistall it first.

Updating the main runtime

Caution: Before the update, make sure that the batch server and the accounting tasks are disabled, and that there is no other active session connected to the X3 server.

Note: For Linux Red Hat and Oracle servers, the libunwind library is mandatory since release 2022 R4/V12.0.32.

Open a command prompt and enter yum install libunwind to install the libunwind library before installing the runtime.
Go in the console 2.55 to define the path (or paths if it is a multi-runtime configuration). Follow the instructions given in the console documentation.
You can then update the runtime.

Run the runtime-M.m.P.jar file located in the X3Installs\Runtime folder of the V12 DVD-ROM.
Select Modify installation.
Select the installation path of the existing runtime component.
On platforms running the Windows Operating System, the update mode detects all existing runtime components and it lists them in a display panel with their corresponding paths. Select the runtime component you want to upgrade and follow the rest of the process.

Updating Microsoft PowerShell

PowerShell is a cross-platform task automation solution composed of a command-line shell, a scripting language, and a configuration management framework. PowerShell runs on Windows, Linux, and macOS.

For more details regarding Powershell, consult the pre-requisites documentation.

PowerShell for Microsoft SQL Server architectures

Install the MSI package.
Open an MS-DOS command prompt with administrator rights.
Enter Pwsh.exe to execute the PowerShell installation wizard.
Enter $PSVersionTable to check that you are in version 7.2 or higher.
Enter Install-Module -Name SqlServer -Scope AllUsers -force to install the Microsoft SQL Server PowerShell module.
Enter Get-InstalledModule -Name SqlServer to make sure that the installation went well.

Note: You can follow these procedures to install a PowerShell MSI package or module in offline mode:

PowerShell for Red Hat architectures

You can install via direct download Microsoft PowerShell 7.2 or later, or you can follow these steps:

Connect to the machine via PuTTy.
Enter sudo -i to execute the PowerShell installation wizard.
Enter curl https://packages.microsoft.com/config/rhel/8/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo to register the Microsoft Red Hat repository.
Enter sudo yum install --assumeyes powershell to install PowerShell.
Enter pswh to launch PowerShell and make sure that the installation went well.
Enter exit to close PowerShell.

Updating the application

Run the x3-application-M.m.P.jar file located in the X3Installs\Application folder of the V12 DVD-ROM.
Select Modify installation.
Select the installation path of the existing application.
On platforms running the Windows Operating System, the update mode detects all existing applications and it lists them in a display panel with their corresponding paths. Select the application you want to upgrade and follow the rest of the process.

Note: The update can take up to 30 minutes.

Updating the "Full" or "Test" additional runtimes

Update the additional runtimes if any were previously installed.

Updating the Print Server

Run the print-server-M.m.P-win.jar file located in the X3Installs\PrintServer folder of the V12 DVD-ROM.
The Print Server can only be installed on platforms running the Windows Operating System.
Select the installation path of the existing Print Server component.
The update mode detects the correct repository and finishes the update process.

Updating Elasticsearch

Elasticsearch is an open-source, distributed real-time search and analytics engine. Sage X3 is now compatible with Elasticsearch version 7.16.

Although Sage X3 is still compatible with previous releases, it is strongly recommended to install the latest version of Elasticsearch compatible with your release (to be checked in the prerequisites overview page) as older versions will be no longer maintained by Elastic.

It is highly recommended to host Elasticsearch on a dedicated server. Before upgrading Elasticsearch to a higher version you should delete the indexes on your current version.

Make sure you write down the Elasticsearch host name and its corresponding http service port number. These two parameters are defined in the elasticsearch.yml file. You will need to set these hostname and port parameters in the nodelocal configuration file. These parameters are equivalent to network.host and http.port in the elasticsearch.yml file. Note: For network.host, 0.0.0.0 will bind to all network interfaces. The value 0 has the same effect as 0.0.0.0.

For further information, consult Elasticsearch's network settings documentation.

For further information on Elasticsearch set up, consult the installation guide available in their online documentation and especially the prerequisites.

Updating MongoDB server

The MongoDB server should be at least in version 3.4.16. Although Sage X3 is still compatible with previous releases, it is strongly recommended to install the latest version of MongoDB compatible with your release (to be checked in the prerequisites overview page) as older version will be no longer maintained.

For further information on how to upgrade MongoDB, consult the pages below:

Note: If you initially installed MongoDB manually, you have to perform a new installation using a different MongoDB port than before. Make sure you select Import and initialize db with data from another instance to retrieve the administration data from the previous database if your initial instance is not configured on SSL/TSL mode or use mongodump mongorestore after finishing the installation to retrieve the administration data from the previous database. Caution: Make sure the agent sage Syracuse and sage Syracuse services are stopped before updating MongoDB.

Updating Sage X3 Syracuse server

Run the syracuse-server-M.m.P.jar file located in the X3Installs\SyracuseServer folder of the V12 DVD-ROM.
Select Modify installation.
Select the installation path of the existing Syracuse component.

Caution: You need to specify a user/password with rights to create and modify a service, as well as the passphrase that was initially used during the first installation of the component.

Note: The update process launches a series of scripts that initialize the MongoDB database with the data required for the administration of Sage X3, as well as the administration of the menu pages by the Sage X3 Syracuse Server. The component update can take up to 30 minutes.

Reconfiguring the components of the solution with the console

In the Console, load the solution and click Application to reconfigure the application and runtime.
This operation can take 30 minutes or more.
Reconfigure "Full" and "Test" additional runtimes, if any was installed in the previous version.
Reconfigure the print server.
Reconfigure the Java Bridge component, if it was installed in the previous version.
Reconfigure the webservice and ADC server component, if it was installed in the previous version.

Updating the supervisor

Before you update the license, you have to launch the supervisor update function. To do that:

Log into Syracuse with a super administrator account.
Connect to the root folder X3 endpoint in the Welcome panel.
Go to Setup > Users > Users (GESAUS). When entering the function, the message The product Sage X3 is only licensed until V11 but V12 is requested is displayed.

You can then update the license by following the steps detailed below.

Updating the license

You can then update the license:

Go to Administration > Licenses > License upload.
Option 1:
1. Click Select file.
2. Locate the license file on your server or local repository and select it.
3. Click Open. The file is uploaded and a document icon appears in the Upload panel indicating that the license is ready to be uploaded.
4. Click Upload license.
Option 2
1. Open the license file with a text editor.
2. Copy/paste the content of the file in the Content block.
3. Click Upload license.

When leaving the function opened before launching the license update, the message Supervisor update is displayed, meaning that the Supervisor update is done.

Personalizing and initializing the menus

Log into Syracuse with a super administrator account.
Connect to the root folder X3 endpoint in the Welcome panel.
Click the Personalization and Menus intialization from X3 folder (on the right panel).
Wait until the end of the import.

Updating the privileges of the ADX_SYS role (Only for upgrades from V7, or U8 patch 3 or lower)

For Unix Oracle

Connect as a user who has DBA rights on the concerned database using a command line.
Go to the Runtime directory of the solution:
"cd /Patch_Runtime/runtime" (with "Patch_Runtime" corresponding to the Runtime installation complete path)
Run the .profile command to get the available environment variables: ". ./.profile"
Go to the ebin runtime directory: "cd ebin"
Run the update command:
"sqlplus system/manager @update_SYS_role_17R301.sql X3 >$ADXDIR/tmp/update_SYS_role_17R301.log"
Check the content of the log file to make sure there are no errors:
"cat $ADXDIR/tmp/update_SYS_role_17R301.log"

For Windows Oracle

On the server, run the following command:
"path_Runtime\ebin\Update_Role_17r3xx.bat path_Runtime" (with "patch_Runtime" corresponding to the Runtime installation complete path)
Check the content of the log file to make sure there are no errors.
This file is located in the runtime tmp directory.

Revalidating the child folders

To finalize the update, every child folder needs to be revalidated:

Log in to the Sage X3 Syracuse Server with a super administrator account.
Connect to the root folder X3 endpoint in the Welcome panel.
Go to Setup > General Parameters > Folders (GESADS).
Check the settings and save the definition of every folder except X3 and SEED.
You have to save each folder definition as the folder revalidation cannot be done afterwards.
For the Save button to be accessible, you need to enter each folder, make a change and then cancel it.
ClickValidationto launch the folders revalidation.
Caution:Before confirming your choice, be aware that the folders revalidation can last for several hours, depending on the number and the settings of the selected folders.
You can select several folders and add them in the Folder validation grid to process them at the same time.
Option 1:
Click OK on the right-hand panel to trigger the revalidation process.
Selected folders are successively processed.
Option 2:
1. Click Deferred on the right-hand panel.
2. Select the date and time for the process launch.
3. Click OK
4. On the Folder validation page, click OK again.
  The deferred folder revalidation query is generated and transmitted to the server.
  You can verify, update or delete the query in Usage > Batch server > Query management (AREQUETE). The deferred revalidation query is identified by a number and by its root folder X3, and associated to task code "VALDOS".
Option 3:
1. If all folders have already been saved as stated in Option 2, go to Usage > Batch server > Query management (AREQUETE).
2. Locate the queries with task code "VALDOS".
3. Select the date and time, and click Validation on the right-hand panel.
4. Select the folders that have to be revalidated.
5. Click OK on the right-hand panel.
  A new deferred folder revalidation query is generated, and the corresponding new entry is added to the Query management grid list.

After revalidation, the folders are up to date in V12, and are ready to use.

Applying the list of patches

If there is a zip file in the Patch directory of the installation support:

Go to Administration > Utilities > Update > Updates and click Add an update.
Upload the zip file located in the Patch directory.
Refer to Updates Management for more information.

Managing the Seed folder upgrade

You can manage the Seed folder upgrade in one of two ways:

Keep the existing Seed folder and install the V12 Seed folder:
1. Unzip the V12 Seed folder directories in a folder with a different name.
2. Copy these directories in the appropriate directories of the application.
3. Import the V12 new Seed folder with the console.
4. Make sure you revalidate the existing Seed folder.
Delete the existing Seed folder and install the V12 Seed folder:
1. Delete all existing database objects related to the Seed user (tables, indexes, sequences, etc.) with a database management tool.
2. Delete the Seed and X3_PUB directories located in the application folder directory.
3. Delete the Seed folder definition in Setup > General Parameters > Folders (GESADS).

Note: It is technically possible to overwrite the Seed folder but this method is not certified by Sage because it could cause unexpected issues in the usage of the folder.

Refreshing the browser cache

Clean your browser cache by pressing Ctrl + F5 after logging into Sage X3.

Updating the search index

Execute the search re-indexation for each endpoint after the upgrade.

Go to Administration > Usage > Search Index Management.
Select the data source endpoint to index.
Enter the Locale for which the index must be updated.
Select Delete index before update.
Click Update index.

Updating the Java Bridge component

Perform this step only if the Java Bridge component was previously installed.

Run the java-bridge-M.m.P.jar file located in the X3Installs\JavaBridge folder of the V12 DVD-ROM.
Select Modify installation.
Select the installation path of the existing Java Bridge component.
The update mode detects the correct repository and finishes the update process.

Updating Web Services and ADC server component

Run the vt-web-server-M.m.P.jar file located in the X3Installs\VTWebServer folder of the V12 DVD-ROM.
Select Modify installation.
Select the installation path of the existing webservice and ADC server component.
On platforms running the Windows Operating System, the update mode detects the correct repository and finishes the update process.