The following needs to be done:
Create a deploy zip
Assuming that only the specific files have been stored in a version management system and not the whole GX Webmanager SDK, the following steps can be used to create a deploy for a new version:
Download Webmanager
Download the latest version of WM (SDK zip, not the community edition (CE)). WebManager 9 releases can be found on GX Developerweb under "Software > Download". To download the full SDK release, you will have to log in first. https://www.gxdeveloperweb.com/Software/download/Other-releases/GX-WM9-releases.htm
There are 2 files inside the zip that are of great importance that could be handy to print:
- installation.txt (contains links to documentation on developerweb)
- upgrade.txt
Please be sure that the server you are about to upgrade meets the prerequisites as mentioned in installation.txt.
Checkout the project
Checkout the complete SVN-tree of the project (trunk) into a new directory. Don't use long filenames, e.g. put all files in C:\migr\project\ or so to prevent running into trouble with long filenames. Possibly some project-specific directories are checked into the tree. These will most probably be in the same directory format as Webmanager self.
Copy Webmanager into the checked out directory
Copy all Webmanager files of the NEW release into the checkout directory. If asked, replace all files. Be sure of course to NOT commit anything after you have done this. Do the next step first.
After copying verify any overwritten files using the "Check for modifications > check for repository" option in SVN. Check each and every file that was overwritten! Are these changes relevant and should you retain them, or should you revert back to what was checked in? After checking everything, commit the changes. When in doubt, consult with the project's architect.
Sometimes there are insignificant changes, like changes in spacing or options being shuffled around. You will want to follow these changes so there will be less changes next time you upgrade. As your files get closer to WebManager's, you will have less to verify. It's wise to also incorporate whitespace's, comments etc in your version of a file to keep the relevant changes to a minimum.
The files most commonly containing changes are:
- web.xml
- settings.xml
- springmvc-servlet.xml (when it's checked in and contains custom stuff)
- properties.txt (search engine)
How do you know whether the changes in e.g. the web.xml are custom or product? One clue with filters etc is the package name that can be found in the description of the filter in the top section of the web.xml. If the package name begins with for example com.gxwebmanager.solutions, it's not product. Check the project/staticlib directory, chances are that the filter is included there. Make a habbit of merging your changes into file from the new SDK so that you keep the differences with the next upgrade to a minimum.
The following things to look out for:
- Use the right settings.xml for the environment you're creating a deploy for.
- Most major versions add/remove settings to the settings.xml. Like the <webmanager.editiondir> in 9.9.x. So diff the settings.xml from the SDK with your settings.xml or multiple settings.xmls' in case of an OTAP setup to find and propagate these differences. The release notes do not always define these changes or do it indirectly.
Check the settings.xml
Diff the standard "settings.xml" of WebManager and the "settings-xxx.xml" of the project. Be sure to pick the correct "settings.xml" file for your server (most DTAP-streets have multiple "settings.xml"'s, possibly one for each environment). It is advised to keep the standard "settings.xml" and the "settings-xxx.xml" as similar as possible, to keep the diffs to a minimum. Also, be on the lookout for new properties, e.g. "<webmanager.editiondir>", and adopt these additions. Keep in mind that the changelog doesn't always mention these additions.
Be sure all database connections are correct, active profiles etc.. System administration can provide you with the "settings.xml" if it is not available for your server yet.
In the "settings.xml" find the lines that define your jcr database (yes: also do this when building for acceptance etc. servers, even though this might seem odd!!):
Replace the marked line with the path to "jcr-standalone-mssql.xml" on your machine, for example:
This example assumes MS-SQL is used for the JCR, if it is not, find the appropriate file for your database. The reason for this is that the "webmanager.project.basedir" will be replaced by the basedir for the server instead of your local machine. To build the deploy file you need the path to point to your own server instead.
Also, don't forget to put an absolute path-name in <localRepository> so that the dependencies can be found.
Again: it is safe to build the deploy with this setting, since it will not be transferred to the live environment. It will only be used for building the deploy.
When building a deploy for a new WebManager (platform upgrade), compare the distribution settings.xml of the original and the new version for changes and update the settings.xml file in the SVN repository. Sometimes a new setting is added or an existing setting is changed.
Note: there is a bug in the settings.xml with WM 9.10 and higher concerning the edition bundles dir. Default dir is wrong, it should be:
And not:
Check for needed changes
Don't forget to check "upgrade.txt" very well now to see if you need to make specific changes based on the WebManager version you upgraded from. It could very well be possible you need to change some WCB's and also re-certify them. Consult with the project's architect when you think the changes have a big impact (like adding SSI's). If you omit some changes from the update.txt, let the architect know. He will assume the changes are made referring to the version number.
Do not commit any changes you make instantly (every committed change is potentionally uploaded to live if someone is working on the project), do this just before uploading them to live or after you tested the upgrade. Make a new tag for each WCB so you can revert to the previous version.
Edition bundles
The idea behind edition bundles is that they are not part of the platform, and thus that your installation may not need them. The most obvious one you don't need would be the community presentation. The idea is to remove the not needed wcb's from being copied to the target edition-bundles directory when you create your deploy. An easier way to this is to change the /src/main/assembly/deploy.xml file within your deploy (be sure you edit this file in the deployfolder, not the WCBs, that has the same files, but will not contain <fileSet> tags).
Find the <directory>edition-bundles</directory>-tag and change:
into:
This excludes the community edition presentation and the solr search engine. Don't forget to save this deploy.xml file in the your version management system for future deploys you'll build.
Build
Build the project by going into the root of the project using the command prompt and executing:
Or use (if you want to mvn to create the zip files for you and the architect specified this):
Build WCB's
It should not be necessary to rebuild your WCB's for the new installation, provided they are compatible with it. The "upgrade.txt" also mentions some necessary changes to certain WCB's. Check if your WCB is affected and if so, rebuild it against the new version of WebManager. Don't forget the change the pom's WM version number and the WCB's version number.
Edit the Webmanager version in the "pom.xml" file of your WCB. For example:
Build your WCB's (in the directory where you have the pom.xml of the wcb) using:
You might have to change the <localRepository>file:./maven2-repository?</localRepository> in your settings.xml (to absolute location) so the build will work. Check the receivedwcb's directory. Are the WCB's compatible?
Request a new configuration.xml
Each new major version of GX Webmanager may contain functionality that has been refactored in such a way that it influences the license definition stored in the configuration.xml. This doesn't apply to minor versions. A new configuration file can be requested from GX Customer Services' portal support or support@gxsoftware.com. Since this configuration.xml is not stored within the deploy zip, it needs to placed seperately on the target environment.
Alter the repository.xml
There are currently 2 reasons for wanting to alter the repository.xml:
- A new underlying JackRabbit version
- Incorporate a custom optimized Persistence Manager
When one of the reasons apply to your upgrade, the next question is whether you want to rebuild the JCR index during upgrade or not. You typically don't need to do this which means you also need to alter the /repository/workspaces/wm9/workspace.xml which is generated only during index construction from the repository.xml
A new underlying JackRabbit version
Within GX Webmanager 9.9.x the JackRabbit version was upgraded from 1.4 to 1.5 and later on to 1.6. (9.9.5/9.10.5/9.11.3/9.12.0)
If the settings.xml contains the right database names, Maven can be used to generate the repository.xml:
Note that the resulting repository.xml is placed into the directory defined in "webmanager.workbasedir" in the settings.xml!
- Keep in mind that no workspace.xml is generated this way! So update this file manually when needed
- In a clustered setup, the generated cluster id relevant:
So either have a settings.xml per node in the cluster or manually change the cluster id to the value in the current repository.xml.
When you decide to manually change the repository.xml and workspace.xml:
Get the repository.xml from the server you want to upgrade and remove the following line if it exists and the server is going to use JackRabbit 1.5 or higher. Note: only remove it at the FileSystem part, not at the PersistenceManager part! This part dbfilesystem independent, so remove it with MySQL, MSSQL as well as Oracle.
When upgrading to JackRabbit 1.6, also add the schemaCheckEnabled to the FileSystem, PersistenceManager and DataStore sections.
In the part:
Incorporate a custom optimized Persistence Manager
In new GX Webmanager versions (>9.12.x) and maintenance versions of older versions:
- 9.6.7
- 9.7.5
- 9.8.3
- 9.9.0
- 9.10.0
- 9.11.0
An optimized persistence manager can be used which needs to be configured for use. This new persistence manager is better in preventing and fixing corruption between the JCR index and database.
This GX WebManager Persistence Manager describes how the new Persistence Manager can be incorporated.