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
Background
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:
- Updates Management https://online-help.sageerpx3.com/erp/12/public/administration-reference_updates.html
- Update history https://online-help.sageerpx3.com/erp/12/wp-static-content/public/Update%20history/Content/How-to%20guides/Platform/Update%20history/Topic%201%20Update%20history.htm
- Cumulative patching https://online-help.sageerpx3.com/erp/12/wp-static-content/public/cumulativepatching/Content/Cumulative%20patching/Cumulative%20patching.htm
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
START_UPDATE
Called once at the beginning of an update operation. Checks global information regards folder setup, etc.
START_UPGRADE_FOLDER
Called once at the beginning for each folder. Writes record into AUPDATE table
CONTROL_PATCH
Called for each patch on each folder. Checks information.
APPLY_PATCH
Called for each patch on each folder. Applies the patch
END_UPGRADE_FOLDER
Called once at the end of each folder.
END_UPDATE
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-- START OF SQL --SELECT [UPDSEQ_0] ,[AFOLDER_0] ,[UPDTYP_0] -- 1=Standard, 2=Hotfix, 3=Specific, 4=Add-on, 5=Internal ,[UPDINTREL_0] ,[UPDSTATUS_0] -- 1=OK, 2=InProgress, 3=Complete, 4=N/A, 5=Error, 6=Warning ,[UPDPROCESS_0] -- 1=Integration, 2=Validation ,[UPDLOGFIL_0] ,[UPDLOGFIL_1] ,[ENDDATTIM_0] ,[CREDATTIM_0] ,[UPDDATTIM_0]FROM [X3].[AUPDATE]order by UPDDATTIM_0 desc----SELECT [UPDSEQ_0] ,[ACATALOG_0] ,[ALEG_0] ,[ALAN_0] ,[APRODUCT_0] ,[APATHSTATUS_0] -- 1=OK, 2=InProgress, 3=Complete, 4=N/A, 5=Error, 6=Warning ,[LOGFIL_0] ,[LOGFIL_1] ,[CREDATTIM_0] ,[UPDDATTIM_0]FROM [X3].[AUPDATEPATH]order by UPDDATTIM_0 desc----SELECT [UPDSEQ_0] ,[ACATALOG_0] ,[UPDLINSEQ_0] ,[TYPENT_0] ,[IDENT1_0] ,[IDENT2_0] ,[FILNAM_0] ,[PATHFIL_0] ,[OPERATION_0] -- 1=Creation, 2=Modification, 3=Deletion ,[CREDATTIM_0] ,[UPDDATTIM_0]FROM [X3].[AUPDATELINE]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.
Conclusion
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…
