Upgrading Percussion CMS

Upgrading Percussion to a newer version is a simple process that ensures all your existing sites, content and configuration are preserved while adding the latest new features and bug fixes available. Upgrades are certified for the two releases prior to the one you are upgrading to. Upgrades from earlier releases may work, but are not supported upgrade paths. Contact your Percussion representative if you have questions about an upgrade path. If you are installing Percussion for the first time, see Installing the Percussion Server.

NOTE: A full publish must be performed before and after completing the upgrade. Running a full publish before you upgrade will help confirm that all of your pages are publishing as expected.

Upgrade Notice: 

If you previously implemented the Security Updates from April 2016 and are upgrading, you will need to review these procedures again, as the upgrade will overwrite them.

Upgrade Path

Percussion fully tests and supports the migration to the most recent version from the two prior released versions. For example, if you are on version 4.0, you could upgrade directly to 4.1 or 4.2, but not 4.3 or higher. If you are more than two versions behind, you will need to perform multiple upgrades to ensure that the process runs smoothly. For this reason, we recommend that you upgrade at least every other time a new release is made available.

You can download the most recent version of CM1 on the Downloads page. To identify which updates you can move to from your current version, please see the Prior Releases page.

Before You Upgrade

To ensure a smooth upgrade, verify the following before you begin the upgrade process:

1. You have performed a backup of your entire directory tree and CM1 database.
2. You have performed a backup of your entire DTS directory tree and DTS database (if using an external database).
3. Shutdown your Percussion server. Refer to Operating the Server for details.
4. The upgrade will overwrite any changes made to Percussion system files. This includes delivering updated files to the percussion theme directory. To ensure that any themes you have created are not overwritten, you should verify that you have created your themes according to the instructions detailed here. This ensures that your theme directory and files were created by modifying and re-naming a copy of the percussion theme directory. If necessary, recreate your site themes according to the procedure above. Then edit each template to point to a new theme.
5. Copy following files to <InstallDir>/rxconfig/trusted_certificates
   1. Private authority keys,
   2. internal certificates, and
   3. LDAP Server certificates
6. Check the <installDir>/rxconfig/server/startupProcessManager.properties has the following property set "PSImportCustCertificates=true" Find Detailed instructions here.

Note: An upgrade error has been identified [CMS-2190] regarding Custom Styles in the Rich Text Editor whereby the Custom Styles definition file <Percussion-root>/rx_resources/css/PercRichTextCustomStyles.properties is being overwritten on upgrade. It is recommended to backup this file prior to upgrade and replace it after upgrade is complete. 

Upgrading on Windows

1. Download and unzip the Windows installation file. The unzipped file should include a folder including the CM1 and DTS installers, as well as a readme file.
2. Run the Setup.exe for upgrading CM1 and SetupDTS.exe for your DTS. Remember to upgrade your Staging DTS as well as Production!
3. The installation wizard starts, and displays the Welcome dialog. Click the Next button, accept the license agreement and click Next again. The latest license agreement can be found at http://www.percussion.com/legal/percussion-standard-agreement.
4. 'Upgrade existing install' should already be highlighted. If this radio button is not selected, it may be that CM1 is not already installed in which case you should double check you are upgrading the correct location.
5. In the Directory drop list, choose the directory of the Percussion server you would like to upgrade, then click Next.
6. The installation wizard displays the Installation Information dialog.
7. Use the Other option to select an installation that is not listed. When you choose Other, the wizard displays a browse dialog you can use to select the installation directory to upgrade.
8. The License Information dialog lists the codes you used to install Percussion. These codes remain valid for upgrades. Click [Next] to continue. 
9. (NOTE: These codes are only valid for a new install for 30 days after Percussion Software issues them.)
10. The installation wizard displays the Pre-installation Summary dialog. Review the installation summary.
11. To start the installation, click [Next].
12. The installation begins. The installation wizard displays a progress bar showing the progress of the installation.
13. When the installation is complete, the installation wizard displays a link to the readme file.
14. If an error occurs during installation, the installation wizard displays a message informing you of the error and the location of a detailed log file. Look at the log file to determine the error.

After the upgrade installation completes, your server will be offline. See Operating the Server for details about restarting the Percussion server after you complete the installation.

Upgrading Linux

To upgrade Percussion on Linux:

1. Download the Linux installation file.
2. Untar the installation file to a convenient location on the machine where you want to install Percussion CM1. The unzipped file should include the following contents:
   • src (directory)
   • linux (directory)
   • readme.html (html file)
3. Change to the directory /CM1/linux/setup, where CM1 is the location where you copied the Percussion directory.
4. Run the script SetupConsole.sh.
   The system extracts and starts the installation wizard.
5. The first section of the installation is the introduction. Read the introduction and press the < Enter > key to continue.
6. The installation wizard displays the URL of the license agreement. Access and read the License Agreement before responding to the installation wizard request:
   DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT?
   Enter "Y" (Note: case-insensitive; it can be either upper-case or lower-case) to accept the license agreement.
7. The following section asks whether you are performing a new installation or an upgrade. If you have installed Percussion on the machine previously, the option defaults to upgrade (2). Press the < Enter > key to accept this entry and continue.
   
   NOTE: If the option defaults to (1), Percussion is not installed on the machine. Stop the installation and restart from the machine where Percussion is installed.
8. The wizard displays a list of Percussion servers installed on the machine. Enter the option for the server you want to upgrade. The final option in the list is "Other". Use this option to upgrade a directory not included in the list.
9. The wizard next requests your license number and displays the license number you entered when you installed Percussion. This license number remains valid for upgrades. Press the < Enter > key to accept the license number and continue.
10. The wizard then requests the installation code and displays the installation code you entered when you installed Percussion. This code remains valid for upgrades. Press the < Enter > key to accept the installation code and continue.
    (NOTE: These codes are only valid for a new install for 30 days after Percussion Software issues them.)
11. The wizard requests the Admin user name and Admin password. Enter the name of a user in the Admin role, and that user's password. The installer runs as this user during upgrade processing. (NOTE: This user must be user created in Percussion; the installer cannot run as an LDAP user.) Press the <Enter> key to continue.
12. The installation wizard displays the Installation summary. Press the <Enter> key to continue the installation.
13. When the installer is finished, the installation wizard displays the the URL of the readme file. Access the readme file to view the latest update details.
14. If an error occurs during installation, the installation wizard displays a message informing you of the error and the location of a detailed log file. Look at the log file to determine the error.

After the upgrade installation completes, your server will be offline. See Operating the Server for details about restarting the Percussion server after you complete the installation.

After You Upgrade

To prevent potential upgrade issues, perform these steps after the upgrade is completed:

1. Attempt to log into Percussion as a User.
2. Preview pages that use each of your templates and verify that the styling remains unchanged.
3. Publish your sites locally to verify that they publish correctly.

Other items to consider:

Pagination

The Pagination on the Blog List and Results widgets has been improved for better ADA compliance. This change will impact customer's that are currently using Pagination as the HTML markup and CSS has changed in the widgets.

After upgrade, and prior to performing a Publish, customers should update their site Theme based on the steps below.  NOTE: If your theme doesn't have the CSS to be replaced, still add the new CSS to your theme.

Replace the following CSS:

 .perc-pagination-container .perc-goto-next:after {
   content: '>'
}
.perc-pagination-container .perc-goto-last:after {
   content: '>>'
}
.perc-pagination-container .perc-goto-first:after {
   content: '<<'
}
.perc-pagination-container .perc-goto-pre:after {
   content: '<'
}

Pagination does not work in Preview, so we recommend applying the CSS, and publishing a Copy of your Blog Index page to test that the styling is looking good, prior to running a full publish.

Canonical Links

The 5.3 Service Release 1 (and subsequent upgrades/installs) will provide a Canonical Link feature.  This option will need to be configured to match the specifics of your site.  For example, if your site is configured with the http protocol, you will need to configure the feature this way.

As always, if you require assistance with an upgrade step, please email percussion.support@intsof.com.  We are glad to help. 

We also recommend viewing the release notes as they provide current recommendations pertaining to each upgrade.