Understanding and troubleshooting Sage X3 "Updates" patching mechanism

7 minute read time.

You are having trouble applying a patch through the "Updates" function, launched via Administration, Administration, Utilities, Update and want to understand better what is going on and where to look for further information

Good that I have decided to try and lift the lid a little bit more on how this function works, and where to look when you need to troubleshoot issues


The "Updates" function has been with us for a long time now.  Version 11 saw this function available, but you could ignore it and continue to apply patches with the "classic" method of applying patches through "Patch Integration".

By contrast, with Version 12 the only correct and supported mechanism to apply Sage supplied patches, such as the quarterly update patches, is to use the "Updates" function.  This was originally because there are updates to MongoDB collections which cannot be applied using the "classic" patching method, however with the advent of Cumulative patching since 2019 R4 (Patch 19) there is a lot more going on, specifically dealt with in the "Updates" function.   This makes it essential for you to apply the patches using the correct process.

NOTE: the old-style classic "Patch Integration" method can still be used with Version 12 to apply some X3 patch hotfixes and most add-on/custom code packages

Online Help

Before I delve too deep, let me mention the online help as this does cover a lot of the basics, which I am not duplicating in this article.  You may want to have read through these help articles first:

How do I apply a patch?

When you have uploaded and saved a patch using "Updates" you have got various options as to what to do with it.

The main options are:

Test update
This allows you to run the patch without applying any changes, which verifies there is nothing immediately blocking the patch from being applied.  

Apply update
Executes the patch update interactively.  You see an on-screen log which is dynamically updated to show progress and result

Schedule update
Executes the patch update on the date and time you specify.  You can then logout and leave it to run unattended

What happens when the patch is executed

The following sequence of events are executed.  Bear in mind the X3 folder is updated first and if there are no errors, is followed by the child folders which are run in parallel

Called once at the beginning of an update operation.  Checks global information regards folder setup, etc.

Called once at the beginning for each folder.  Writes record into AUPDATE table

Called for each patch on each folder.  Checks information.
Called for each patch on each folder.  Applies the patch

Called once at the end of each folder. 

Called once at the end of the update, assuming everything so far has finished successfully.  Runs some scripts.

What log files can I see?

There are a lot of log files created by the patch update, all of them in the "..\Folders\X3\TRA" directory (with filename format "F*.tra").   Each log file is for a different phase/folder, however the same information is collated into the log file you can download from the "Updates" function.

In my example patch update, I have 25 log files created!

If I go into the "Updates" function and call up my patch, I can see these separate logs collated into one log file per folder.  Having said that, you still need to look at the first 4 individual logs to see the messages relating to the initial START_UPDATE phase

If a folder is at status Warning or Error, you can check the log file here, and/or review the statuses in the Update Catalog (Development, Utilities, Patches, Updates function, discussed below)

Other information in the filesystem

In the file system, I will see in the "..\Folders\X3\PATCH" directory the ZIP file has been extracted, and a "<FOLDERNAME>_resultvcatalog.csv" created for each folder processed

What is the "Update Catalog" and where is it stored?

Updates are recorded in the "Update Catalog", which you can see in Development, Utilities, Patches, Update.    
You see here the "Upgrade status" of each update, and any details in the "Catalog" section.   In this case there is a warning, which we can find in F847.tra

The same warning is in the log file we downloaded from the Updates screen, although it shows warning messages in green text so is not always easy to find

The information shown in this function is stored in database tables AUPDATE, AUPDATELINE and AUPDATEPATH.  If I want to interrogate the database directly, I could run SQL to extract the current data, for example:

--     Updated 29 January 2020
      ,[UPDTYP_0]       -- 1=Standard, 2=Hotfix, 3=Specific, 4=Add-on, 5=Internal
      ,[UPDSTATUS_0]    -- 1=OK, 2=InProgress, 3=Complete, 4=N/A, 5=Error, 6=Warning
      ,[UPDPROCESS_0]   -- 1=Integration, 2=Validation
order by UPDDATTIM_0 desc
      ,[APATHSTATUS_0]  -- 1=OK, 2=InProgress, 3=Complete, 4=N/A, 5=Error, 6=Warning
order by UPDDATTIM_0 desc
      ,[OPERATION_0]   -- 1=Creation, 2=Modification, 3=Deletion
order by UPDDATTIM_0 desc
--     END OF SQL

NOTE: The test patch I applied did run successfully, but doesn’t actually update anything, which is why I do not see any data for 2021-10-07 date from the third SQL statement…

Is there any more detailed logging I can obtain?

If there are issues with applying the patches, you may find that adding some Syracuse debug logging  helps to identify the issue.

Navigate to Administration, Administration, Settings, Global Settings

In the logs section, set the following parameters to ensure the log files can grow big enough for the logging needed, and the log files do not get removed too quickly.  These suggested settings assume you have the default values currently set:
-- Maximum file size (MB) set to "200" (10 default)
-- Maximum number of days "15"  ( 5 default)

-- Enable web client logs  (Check the box, default is unchecked)
-- Web client logs level = Error

In the "Server Logs" section, set the following sections to "Debug" log level
-- x3Comm--> patch
-- x3Comm--> sadfsq
-- x3Comm--> conn

You will then need to reproduce the issue again, before then reverting the above logging back to default "Error" log level

What if the patch fails?

  • Check the patch log files available in the relevant folder update details in Administration, Administration, Utilities, Update, Updates  NOTE: You may need to use the "Refresh" button, or reload the screen to see the log files.
  • Check existing Syracuse log files and your database logs for any relevant errors or issues
  • Review Sage Knowledgebase to confirm if there are any known issues with the same error message(s) you are seeing
  • Enable additional Syracuse logging to see if this gives additional information (as mentioned above)
  • If you cannot identify the issue to progress, then request assistance from Sage Support.  Do not be tempted to try and "force" the patch in by taking unsupported steps, it will come back to bite you!

Once the error is remedied, you can simply reapply the patch using the "Apply update" action again.  Items already processed will be skipped, so will install any remaining actions using incremental logic based on the existing patch catalog data.

Common problems/known issues?

Issue: My Archive folder has not been updated
Solution: this is expected.  Archive folders need to be updated manually

Issue: Error: "Create session error: The folder version is different from the version of the root folder." when attempting to Patch folder to 2019 R5 https://gb-kb.sage.com/portal/app/portlets/results/viewsolution.jsp?solutionid=220924360103610
Solution: The Upgrade status has not been updated in GESAUPD

Issue: Can you rollback an installed application patch for X3 (X3)? https://gb-kb.sage.com/portal/app/portlets/results/viewsolution.jsp?solutionid=225924550092731
Solution: No.   

Issue: Using "Updates" from Administration module updates all folders regardless of the selection 
Solution: Remove any child folders that the user does not want to patch before running the patch.  NOTE: You cannot remove X3 folder itself but will be ignored if patch is already applied.

Issue: Error: The patch has been cancelled (ACTION_GETPATCH VERSION)
Solution:  Corrupted X3 endpoint entry.

Issue: Error "The update failed with error: <Folder> The patch is already being integrated" https://gb-kb.sage.com/portal/app/portlets/results/viewsolution.jsp?solutionid=220924660108415 
Solution:  The folder has the incorrect upgrade status in the (Development, Utilities, Patches, Update) (GESAUPD) function. Follow the resolution in the above KB article.

Issue: Error: "Patch integration in progress" when validating a folder  https://gb-kb.sage.com/portal/app/portlets/results/viewsolution.jsp?solutionid=221924660118610 
Solution:  Another folder is running a patch or update, or a previous run failed without updating status correctly.


I hope this article has helped you understand a little more about the "Updates" patch functionality and given you some guidance as to how to troubleshoot.  Please let me know any feedback you have on this article by adding your comments below…