Introduction

This document describes the upgrade of a GX WebManager 9 installation into a higher version of GX WebManager 9. Every installation of GX WebManager comes with an "upgrade.txt" that describes the steps of upgrading. This document tries aid engineers doing an upgrade by being more verbose than the "upgrade.txt". However, it just 'tags along' with the official "upgrade.txt" that came with the release, so the "upgrade.txt" should be considered leading.

Please note that this document does NOT describe how to install a local installation. Please refer to 'Appendix B: Documentation resources' at the bottom of this document.

Target audience

This document is written for engineers that want to upgrade a WM 9.2.x or higher installation to a more recent version.

Contents 

1   Preparation

1.1   Check site

Before starting to upgrade several points should be checked, to make sure that errors are not caused by the upgrade

• You should have an working installation (be sure e.g. development-server is production like)
  • Check some important functionalities
    • Check if you can login to the server using the 'Developer' account
    • Check that you have System Utilities (With browse)
    • Check that you have the JCR-browser
    • Check that you have database maintenance
  • Make sure there is a /systemlogs/ directory, since 9.3 Siteworks is closed
  • Check the content
    • Check the website for non-working things (this will save a lot of worries later)
    • E.g. Make some screenshots and save them for later reference. You could also use a program like http://www.surfoffline.com/to download from your devel a significant number of pages
    • Check if the search machine works. On the development environment (only!) wipe the index and reindex to be sure.
    • Try logging in with wrong username and see the message (or is it something like "wm_startuppanel.username_or_password_invalid" )
  • Prepare a regression test for the WCB's
    • i.e. if you have special forms, test them to see what results are and save these.
  • Check some things you might logically know the website uses frequently
    • i.e. Newsletter module (save the source-code of the message)
  • Download and check the log files of the server
• If available, get the document that describes the product issues reported by this specific project that should be fixed by this release.

1.2   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
• upgrade.txt
  

Please be sure that the server you are about to upgrade meets the prerequisites as mentioned in installation.txt.

1.3   Checkout the project

Checkout the complete SVN-tree of the project (trunk) into a new directory.

Tip 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.

1.4   Copy Webmanager into the checkout.

Copy all Webmanager files of the NEW release into the checkout directory. If asked, replace all files.  

Warning Be sure of course to NOT commit anything after you have done this. Do the next step first.

1.4.1   Verify changes

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.

Tip 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.

1.4.2   Merge web.xml

Sometimes the standard web.xml shipped with a webmanager release differs from the previous release e.g. when a filter is added.

Before continuing merge the changes of the standard web.xml with the sites web.xml.

Be careful when using merge programs like Tortoise diff, watch out that you don't merge a piece of code from one file into a comment of the other.

2   Build

2.1   Check settings.xml

Check the "settings(...).xml". Be sure to pick the correct "settings.xml" file for your server (most DTAP-streets have multiple "settings.xml"'s, one for each environment). Be sure all database connections are correct, active profiles etc..

Note Since WebManager 9.11.5, 9.12.3 and 9.13.0 the context path for several settings is configured using the field 'webmanager.contextpath' in the settings.xml. In older versions this field used to be empty. The new default value is 'web'. Make sure you configure your project-specific settings.xml correctly. System administration can provide you with the "settings.xml" if it is not available for your server yet.

Please check that (in the bottom of the document) the copied maven2 directory is used (should be exactly )

Please also consult the "upgrade.txt" file (in the WebManager zip) and check that nothing should be changed due to changes in WebManager.

Note Did you notice you just arrived at point 12 in the "upgrade.txt"?! Well done!

In settings.xml replace the edition-bundles directory:

2.2   Local environment specific

2.2.1   Restore the database

Restore the database backup(s) to your local environment. It is recommended that you restore the database within an environment which is the same as the source (that is, if the source is a Linux MySQL, then restore the database within a Linux MySQL environment in order to avoid any errors caused by platform differences).

Note After restoring the database in a Microsoft SQL Server, you may need to change the owner of tables. The following MS SQL Server stored procedure changes the owner of table 'wmJellyWebTermGrouping' from 'webmanager' to 'dbo': sp_changeobjectowner 'webmanager.wmJellyWebTermGrouping' , 'dbo'

2.2.2   Change environment settings in the JCR

Some settings from the live environment are present in the JCR and they need to be changed to you local environment settings. This can be performed by using the JCR-import-export tool from GX WebManager.

2.2.2.1  Generate the "repository.xml" file

The JCR is going to be accessed at a command line from the JCR-import-export tool. This tool connects directly to the JCR and depends on the "repository.xml" file for the connection settings. To generate a "repository.xml" file that contains the proper connection settings to your local JCR repository, open the "settings.xml" file and change all the values as if you were to install this release locally. Pay special attention to the settings of the JCR database: they will be used by the JCR-import-export tool to connect to the JCR. After changing the "settings.xml", run the following command:

This will generate a "repository.xml" file in the folder C:\migr\project\work\jcr.

2.2.2.2  Install the JCR-import-export tool

The JCR-import-export tool is present in the "maven2-repository" directory. For convenience, copy this tool to the root of your installation and "install" it:

After running above commands there should be two new items in the root of the GX WebManager release:

1. A file "logging.properties"
2. A directory "lib" containing (about) 38 files.
   

2.2.2.3  Create an export of the JCR

Before changing the contents of the JCR it is wise to create an export of the JCR in case something goes wrong and you want to restore the JCR to the initial state. This can be done by running the following command:

In case the JCR needs to be reset to the moment the export was created, the next command will read the contents of the "export.zip" back into the JCR:

2.2.2.4  Create an instructions.xml file for the JCR-import-export tool

Want to know more about the 'instructions.xml' file? We've prepaired a blog for you :)

The JCR-import-export tool is capable of changing the contents of the JCR based on instructions in an XML file. Never use backslashes in the pathnames; always use forward slashes. This also applies to pathnames on a Windows environment.

The example instructions below are placed in the file instructions.xml (inside XML format of course):

In the example above the first three operations (setting the new values for 'backend_hostname', 'backend_hostname' and 'frontend_portnr') speak for themselves: the value for environment B is being set for these properties. The fourth operation adds the frontend_hostname of source environment A to the list of server aliases of environment B. If this is not done, then GX WebManager cannot find certain configuration properties any longer and this can cause minor errors.

In the 'query' and 'property' attributes of the XML there are references to WebManager configuration properties. The values for these properties can easily be retrieved from the /web/setup tool.

 

In the screenshot above, the 'query' value is 'wm:website_settings'. The value for 'property' is 'wm:backend_hostname'. Based on this convention all properties from the [General Configuration] tab of the /web/setup tool can be used in the configuration.xml.

For the properties of the database connections, this convention does not apply. In the table below an overview of the properties is provided.

2.2.2.5  Run the JCR-import-export tool to change the contents of the JCR

To run the JCR-import-export tool and execute the instructions from the file "instructions.xml", type the following command:

2.3   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.

Also check appendix C for some best practices not noted in the "upgrade.txt".

2.4   Build

 In the "settings...xml" find the lines that define your jcr database (yes: also do this when building for acceptance etc. servers, for more info see Jira GXWM-8779):

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 local file 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.

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):

It could be handy for future reference to copy your console session (all the things mvn gave) into a textpad document and save this.

2.5    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.

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.
(Tip: And if it still doesn't work check that you typed the -s !).

Note that the online help functionality is moved to a different package in webmanager 9.4 and changed name. It changed from nl.gx.webmanager.wcbs.webmanager-onlinehelp-wcb to nl.gx.product.wmponlinehelp.
Make sure that your WCB's use the right package.

2.6    WAR's

Use the zip file created by the` assembly:assembly ` command used in §2.3 (you'll see the location just above the summary of mvn in a line containing: [INFO] Building zip: C:\.......

Note Please note that these WAR's contain Webmanager! So in the static war the Webmanager javascripts are placed.

Tip Create a fresh configuration.xml with all needed (and payed) tools for support like Database Maintenance. Ignore what the 'functionalities' panel tells you, be sure to check it in the menu.

Or, if you did not use "assembly:assembly", the WAR's you compiled are now available in:

 \webmanager-webapps\webmanager-backend-webapp\target
 \webmanager-webapps\webmanager-static-webapp\target
 \webmanager-searchengine\target

Store these files very well on a safe location since you will probably need them again exactly like this (if the server.xml is the same for the whole DTAP-street).

2.7   Deploy WAR

Send the WAR files to system administration and wait until you get confirmation from them that the WAR files have been deployed.

Note You could start building changed WCB's over here. But it could be good not to implement them so you know if something breaks what step made it break. Mini steps: Change the WebManager version in the "pom.xml" "mvn -s settings.xml -P build-project clean package"

After step 2.6 has completed you can continue here.

Note that in order to use the JCR Browser or other optional WebManager functionality, these have to be included in your "configuration.xml".

2.8   Setup

FIRST check /web/setup, then upgrade the content.
Check the 'STARTUP_SETTINGS' and 'CENTRAL DATABASE SETTINGS' and 'DATABASE CONNECTIONS' (please refer to a point around point 15 in the "upgrade.txt")

2.9   Upgrade the content

Login with the developer account (otherwise you will not be able to perform this step!) on /web/setup/; Update & Patch: and load the new  \webmanager-upgradecontent-9.x.x.jar (was inside the Webmanager-zip)

(Yes, you may get some coffee here)

2.10 Upload the new WCB's

As usual using the WCB management console.

Applause You have just upgraded the project!

2.11 Disable old development WCB's

If you notice old WCB's like the JCR-browser, you can STOP and UNINSTALL these.

Be sure that you do not uninstall the new versions.

2.12 Update Tomcat startup scripts

Update Tomcat startup scripts with the newest version (changes have been made to bundlecache directory and the mechanism waiting for jcr close).

2.13 Update mod_jk version and configuration

Check with system administration, configuration nowadays is not the same as it used to be.

2.14 Upgrade search engine

Also be sure to upgrade the search engine, i.e. check the configuration files and have system administration replace the binaries.

3   TEST & Check

When ready you should probably update the 'general timestamp' under "Configure > Server configuration > Caching".

Note A new version of WebManager could mean some GUI changes happened. For instance the 'cache' tab has been changed. Please look carefully before clicking where you used to.

Now test around. Click everywhere, frontend and backend.

• Open the log file and check for errors.
• Check the search engine (also after re-indexing manually) - see Appendix B for this one.
• Check (when having multiple webinitiatives) if all webinitiatives have a correct search. (otherwise, check if the crontab has all domainnames)
• Check if things like 'JCR Browser', 'Database maintenance', 'Performance Dashboard' and the filebrowser in 'System Utilities' work.
• Install the 'Consistency Checker' WCB and verify the relevant issues. Be cautious on repairing. In most cases the "repair" button is safe to use, however if the repair option is about to delete an object, be sure to check the object that is about to be deleted.

Finally (if available) check the document with the product-issues that the customer reported for items that should be solved by this upgrade.

Note You could notice this error when using MySQL. That is normal. The database should be available after getting this message once. SEVERE: : Developer ERROR CLIENT Template (289): User: Developer logged in from address: 192.168.16.2 on the Internet Apr 15, 2008 11:11:00 AM org.apache.jackrabbit.core.ConnectionRecoveryManager logException SEVERE: could not execute statement, reason: Communications link failure due to underlying exception: ** BEGIN NESTED EXCEPTION ** java.io.EOFException STACKTRACE: java.io.EOFException         at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1963)         at com.mysql.jdbc.MysqlIO.reuseAndReadPacket(MysqlIO.java:2375)         at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:2874)         at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:1623)         at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:1715)

Appendix A. Documentation resources

Webmanager documentation https://www.gxdeveloperweb.com/Software/Documentation.htm under System Administration
Maven commands https://www.gxdeveloperweb.com/Blogs/Patrick-Atoon/Maven-FTW.htm

Appendix B. BEST PRACTICES / NOTICES

Some changes to the product should be noticed when upgrading. We will walk through them version by version.

9.3.4 Settings.xml properties

Two new properties are introduced in the settings.xml:

Due to these, the servicescachedir will change from   /vol/www/<instance>/work/cache/services
                                                                   into    /vol/www/<instance>/work/osgi/bundlecache

The first is automatically removed by the start/stop script. The second isn't. If your changes are not coming through, you need to change the start/stop script.

9.3.4 Searchengine with SecureFormsCheckingFilter

If the file "credentials.xml" did not include the following line, and the websites uses SecureFormsCheckingFilter, the WebManager search engine will not index correctly. Adding a correct line will prevent this error:

Example of credentials.xml just above the first formpart.