Upgrading exteNd Director Applications

CHAPTER 1

Upgrading Version 5.x Projects

This chapter describes how to upgrade 5.x projects to 5.2.1. It includes these sections:

Overview

Project upgrades allow you take advantage of enhancements and bug fixes made to the subsystems used by your exteNd Director applications. You'll follow a different upgrade path depending on the archive type and version you are upgrading as described in the following table:

Project type and Version	Upgrade steps
Version 5.2 EAR or WAR Version 5.0 WAR	Follow the steps described in Upgrading Version 5.2 archives to Version 5.2.1 NOTE: The structure of the Version 5.0 and 5.2 WARs are the same so you can follow the same set of steps for upgrading a 5.2 WAR.
Version 5.0 EAR	Follow the steps described in Upgrading Version 5.0 EARs to Version 5.2.1

Project type and Version

Upgrade steps

Version 5.2 EAR or WAR

Version 5.0 WAR

Follow the steps described in Upgrading Version 5.2 archives to Version 5.2.1

NOTE: The structure of the Version 5.0 and 5.2 WARs are the same so you can follow the same set of steps for upgrading a 5.2 WAR.

Version 5.0 EAR

Follow the steps described in Upgrading Version 5.0 EARs to Version 5.2.1

Upgrading Version 5.2 archives to Version 5.2.1

The recommended steps are outlined below. They assume that you've already installed exteNd Director Version 5.2.

Step	Task
1	Backup your exteNd Director 5.x project, and copy the entire project directory to a safe location.
2	Setup a test environment in which to upgrade your project. The test environment should include: A new exteNd Director database A connection pool for the exteNd Director database (added via your deployment server's utilities) Deployment settings specific to the test environment The same shared library/nonshared library or 3rd party JARs environment as your production environment. For more information, see the chapter on deploying applications in Developing exteNd Director Applications.
3	Open the project in the 5.2.1 exteNd Director Designer and run the Project Upgrade utility. Rebuild and rearchive it (if the Project Upgrade Wizard did not already do so). If you encounter compile errors, review Handling API Changes for information about the updates you'll have to make and the API Reference for information about deprecation. For more information, see Running the Project Upgrade Wizard.
4	Determine whether you want to change any of the files not changed during upgrade and that the MANIFEST.MF file is accurate. The following file name was changed between 5.2 and 5.2.1 and should be updated in the Manifest.MF: castor-xml.jar is now castor.jar For more information, see What to do after the project upgrade completes.
5	Deploy the upgraded project to your test environment. For more information, see the chapter on deploying applications in Developing exteNd Director Applications
6	Test the upgraded application thoroughly in the test environment. Once you are satisfied with the test results, deploy the upgraded project to your production server.

About the Project Upgrade Wizard

The Project Upgrade Wizard:

Copies the latest subsystem JARs to your project. The new subsystem JARs contain API changes, bug fixes and software enhancements.
Modifies the config and services XML files (for each subsystem) along with the portlet.xml and novell-portlet.xml files, in these ways:
- Adds entries to support new features and enhancements
- Searches the XML files looking for exact key/value matches.
  
  If it finds an exact match and the entry is now considered obsolete, it removes the entry.
  
  If it finds an exact match and the value has changed, it changes the value.
  
  If it doesn't find an exact match, it writes a warning to the Log file. You must review the log file for these occurrences and decide if you should manually make the change.

For more information about API changes, see Handling API Changes, and for information about enhancements and bug fixes, see the Release Notes.

Running the Project Upgrade Wizard

Procedure To upgrade your 5.x exteNd Director project to 5.2.1:

If you have not backed up your 5.x project, do so now before continuing with the project upgrade utility.
Open the 5.x project in the 5.2.1 test environment.
Choose Project>Director>Upgrade.
Click Upgrade 5.x to 5.2.1, then click OK.
Click Next.

Complete the Upgrade Information panel as follows:

Field	What to do
Upgrade Base Location	Accept the default. This specifies the directory containing templates that the wizard uses to upgrade the project.
Upgrade Log File	Accept the default or choose a directory where you want the wizard to write the upgrade log. The upgrade log describes the changes the wizard makes to your XML files. For more information on the upgrade log file, see Using the Project Upgrade Log.

Field

What to do

Upgrade Base Location

Accept the default.

This specifies the directory containing templates that the wizard uses to upgrade the project.

Upgrade Log File

Accept the default or choose a directory where you want the wizard to write the upgrade log.

The upgrade log describes the changes the wizard makes to your XML files.

For more information on the upgrade log file, see Using the Project Upgrade Log.

Click Next.
Review the upgrade settings displayed on the Initiate Project Upgrade Panel.
If you want the upgraded project to be automatically rebuilt, make sure Rebuild project after upgrade has completed is checked. If you choose not to automatically rebuild your project, you will have to do this step manually later.
Click Finish.

The Project Upgrade Wizard performs the upgrade, and displays the Upgrade Summary Panel when it completes.
- (Optional). To view the upgrade log, click the View Upgrade Log File icon.
Click Done to exit the wizard.

Using the Project Upgrade Log

You can view the Project Upgrade Log directly after the upgrade wizard completes or by opening it in the text editor of your choice.

The Project Upgrade Log lists each file that the wizard accessed (or attempted to access) during the upgrade. Many of the messages written to the log file do not require you to take action. For example, you do not need to take any action for entries added to support new features and enhancements.

You should review the entries where the wizard was unable to find an exact match for an entry to remove or update. These are prefaced by Warning messages. The wizard will be unable to find an exact match because:

You changed a value.

For example, if your project includes the Autonomy based searches for the CM subsystem and you changed the value of the QueryPort for your own environment, the wizard will be unable to find an exact match for the default key/value for QueryPort. It generates a warning, but since you probably want to maintain your own QueryPort value for your particular environment you can ignore that warning.
The wizard is searching for a value based on the EAR structure, but your project uses a WAR structure.

You can ignore these warnings. The wizard always first searches for files using the EAR structure followed by the WAR structure. It always generates a log message when it is unable to locate an exact match.

What to do after the project upgrade completes

Once the project upgrade completes, you'll have to make some manual changes to your upgraded projects in the following areas:

Customized system files The following files were changed between Version 5.x and Version 5.2.1, but the Project Upgrade Wizard does not overwrite the existing files to ensure that any customizations that you've made to these files are not overwritten.

javascript\list.js
javascript\pmc.css
jsps\index.jsp

If you have not made changes to these files, replace the copies that reside in your upgraded 5.2.1 project with copies from a newly created Version 5.2.1 project.

If you have changed these files, merge the changes you've made with a copy from a newly created Version 5.2.1 project.

Content Management Subsystem To ensure that you are able to use your content management system after a project upgrade, you must modify the project's config.xml file. You'll find the config.xml in one of these locations:

Project/Archive type	Location
EAR	library/ConfigService/ContentMgmtService-conf/config.xml
WAR	WEB-INF/lib/ConfigService/ContementMgmtService-conf/config.xml

Open the config.xml file and locate the following key:

  <key>com.sssw.cm.fetch.extensions</key>

After upgrade, the value for this key contains an extra greater than symbol (>). (You'll see it right after <value>):

  <value>>.html;.sgml;.xml;.txt;.doc;.pdf;.xls;.xls;.xls;.ppt;.ppt;.ppt;.rtf;.sxw;.stw;.sxc;.stc;.sxd;.std;.sxi;.sti;.sxg;.sxm</value>

Remove the extra symbol so that the entry looks like this:

  <value>.html;.sgml;.xml;.txt;.doc;.pdf;.xls;.xls;.xls;.ppt;.ppt;.ppt;.rtf;.sxw;.stw;.sxc;.stc;.sxd;.std;.sxi;.sti;.sxg;.sxm</value>

Content Administration Portlets exteNd Director 5.2.1 provides a set of Content Administration portlets—called CAP portlets—that allow you to access basic content management functions directly from a shared or personal portal page. The JAR containing these portlets does not get added during the project upgrade process. You can find out more about adding the CAP portlets JAR to your project from TID 10097472. It is available at http://support.novell.com/cgi-bin/search/searchtid.cgi?/10097472.htm

Upgrading Version 5.0 EARs to Version 5.2.1

Before you start your upgrade:

Backup your exteNd Director 5.0 EAR project and database. Copy them to a safe location.
Create a test environment for migration and and post-migration testing.

To upgrade your 5.0 EAR project, follow these steps:

Step	Task	Description
1	Create a new 5.2.1 project	The 5.2.1 project must: Have the same name as the 5.x project that you are upgrading. Be an EAR project. Contain a locksmith unique to the 5.2.1 project. Do not use the same locksmith ID as the 4.x project, or you will encounter duplicate key errors during the migration/upgrade process, and the security system will not migrate properly. For more information, see the chapter on creating new projects in the Developing exteNd Director Applications.
2	Propagate the 5.0 customizations to the 5.2.1 project	For example: Add subprojects Change project lib paths
3	Copy custom artifacts from the 5.0 project to the new 5.2.1 project	For example, copy these directories: Portal\data\portal-component\.xml Portal\data\portal-style\.xml
4	Rebuild and rearchive the new project
5	Create a new database in the test environment	For more information, see the chapter on deployment in Developing exteNd Director Applications.
6	Make the database available to the server in the test environment	For more information, see the chapter on deployment in Developing exteNd Director Applications.
7	Deploy the upgraded exteNd Director project in the test environment	For more information, see the chapter on deployment in Developing exteNd Director Applications.
8	Move the tested project and database into production