Upgrading exteNd Director Applications

CHAPTER 3

Upgrading Version 4.x Projects

This chapter describes how to upgrade an exteNd Director application from Version 4.x to Version 5.2.1. It includes these sections:

• Overview

• Upgrading your Version 4.x project

• Migrating Version 4.x data

Overview

To upgrade an exteNd Director application from Version 4.x to 5.x, you'll need to perform these tasks:

Upgrading your Version 4.x project

To upgrade your 4.x project, follow these steps:

  Portal\data\portal-component\*.xml 
  Portal\data\portal-style\*.xml

About the Project Upgrade Wizard

The Project Upgrade Wizard:

• Converts all workflow process XML files to the 5.x format.

• Generates a report listing the differences in the config.xml and services.xml files between your 4.x project and the new format for these files. Some of these differences are the result of your customizations which you will need to manually modify the files in the 5.x project.

Running the Project Upgrade Wizard

To run the Project Upgrade wizard:

1. In the exteNd Director development environment, open your new 5.2.1 project with the 4.x customizations applied (from the task list outlined above).

2. Choose Project>Director>Upgrade.

   The Project Upgrade panel displays:

   

3. Complete the Project Upgrade panel as follows:

   Field	What to do
   Report differences for config and service	Check, if you want the wizard to generate a log file that lists the differences between your 4.x and 5.2.1 projects.
   Director 4.x project file	Select the original 4.x project file that you are upgrading.
   Log file	Specify a directory location and file name where the wizard should write the log file.
   View Report	Check, if you want to view the report as soon as it is generated.
   Migrate workflow process	Check, if your 4.x project contains workflow processes that you want upgraded.
   Source workflow-process directory	Specify the 4.x workflow process directory. This is typically ...\portal\data\workflow-processes
   Target workflow-process directory	Specify the 5.2.1 workflow process directory—the place where the updated files are written.

4. Click Run.

   The Project Upgrade Wizard generates a log like the following:

   

5. Click OK.

6. Complete the remaining upgrade steps listed in Upgrading your Version 4.x project.

Using the Project Upgrade Log

The Project Upgrade Log lists all of the differences between the 5.2.1 project and your original 4.x project. Some of these changes are a result of enhancements made to the 5.2.1 product; others are customizations that you made to the 4.x project. Review the file and make the identified updates to the new project.

For example, this log entry probably does not require an update:

  Entry with different value -- com.sssw.cm.search.queryport.Default
  ----> The value in 4.x = 2000
  ----> The value in 5.0 = 52000
  Entry with different value -- com.sssw.cm.search.indexport.Default
  ----> The value in 4.x = 2001
  ----> The value in 5.0 = 52001

It just means that between 4.x and 5.x the default ports for content management search changed from 2000 to 52000.

Project Upgrade Notes

This section contains:

• Changing the Portal WAR name (EAR projects only)

• WorkFlow Upgrade Notes

• Component Upgrade Notes

Changing the Portal WAR name (EAR projects only)

A Version 5.2.1 EAR project defaults the Portal WAR name to ProjectNamePortal. Project upgrade requires that the Version 4.x project and the Version 5.2.1 project have the same name. If your Version 4.x Portal WAR name does not follow this pattern, you'll have to change the Version 5.2.1 Portal WAR name to match the Version 4.x Portal WAR (or Custom Web App name) in these Version 5.2.1 project files:

• The EAR project file (.spf) (such as MyEAR.spf)

• ProjectPortal-resource.spf

• ProjectPortal.spf

in these Deployment plan files:

• ProjectPortal_DeplPlan.xml

• Project_DeplPlan.xml

in the config.xml files in these directories:

• PageFlowService-conf

• PortalService-conf

• RuleService-conf

• SecurityService-conf

• WorkflowService-conf

• WEB-INF/conf

in these XML files:

• application.xml

• web.xml

• resourceset.xml

For example   For example, if you created a Version 5.2.1 EAR project called myTest, the PortalWAR name created is MyTestPortal. If your version 4.x project PortalWAR name is MyWAR, you'd change the MyTestPortal-resource.spf to MyWAR-resource.spf, the MyTestPortal.spf to MyWAR.spf, and so on.

CAUTION:    Perform this procedure before deploying the new project for the first time so the exteNd Director tables are created with the correct names. If you deploy before changing the Portal WAR name, delete the exteNd Director tables and redeploy after making this change.

WorkFlow Upgrade Notes

The interface com.sssw.wf.api.EbiActivity was deprecated between 4.x and 5.x. If you used the invoke() method of this interface, follow these steps to update your code:

1. Change any automatic activities that implemented com.sssw.wf.api.EbiActivity to implement com.sssw.wf.api.EbiJavaActivity.

2. Change the invoke() method to invoke(EbiContext context)

3. Add an empty invoke() method so you can compile.

4. Remove any code that created a context. Instead, use the context that is passed to the invoke() method now.

5. Remove the forward call to the QueueDelegate. This is no longer necessary because it is now done for you.

Component Upgrade Notes

• If you upgrade a user or group page from 4.x to 5.2.1 and the page contains the stock quote component, you must repace it with the StockQuote portlet.

• The General component category is not used in 5.2.1. Version 4.x components migrated to 5.2.1 that are still listed in the General category will no longer be available in the Portlet list for page personalization. To make components in the General category visible, use the DAC to change the category from General to General Portlet (or some other 5.2.1 category that you find useful).

Migrating Version 4.x data

The exteNd Director database schema changed between Version 4.x and Version 5.x so you must migrate your existing data to the new schema structure. The Data Migration utility copies exteNd Director internal data (the data stored in the exteNd Director database) from 4.x and transforms it to the proper format for 5.x.

Running the Data Migration Utility

The Data Migration utility is run via a batch file (on Windows platforms) or shell script (on UNIX or Linux platforms).

Database driver requirements   The following table describes the database driver requirements for the Data Migration utility.

NOTE:   The application cannot be servicing requests when you run the Data Migration Utility.

To run the DataMigration utility:

1. Run the DataMigration utility file:

   Operating System	Description
   Windows	DataMigration.bat located at in the exteNd installation directory under: Director\migration\bin\
   UNIX/Linux	DataMigration.sh located in the exteNd installation directory under: Director\migration\bin\

   It looks like this:

   

   NOTE:   Disregard any error messages that appear in the command prompt window. They occur because the Data Migration Utility retrieves realm name constants. The resulting error messages include Unable to establish database connection and Need to specify class name in environment or system property. These messages do not pertain to the data migration process.

To specify the Source and Target database:

1. Select Settings>Configuration:

   

2. Complete the Source Database panel as follows:

   Field	What to do
   Database Name	Specify the name of the database containing the exteNd Director Version 4.0 tables that you want to migrate.
   User Name and Password	Specify the user name and password associated with the database.
   Database Driver	Choose the database driver from the dropdown. When you choose the database driver, the JDBC Driver and JDBC URL fields are filled in with default values—unless you choose Other.
   Database Server (Hostname)	The name of the machine hosting the database server.
   JDBC Driver	Accept the default value filled in when you chose the Database Driver.
   JDBC URL	Accept the default value provided when you chose the Database Driver and complete any variables (such as database name and port number).

3. Click Test Connection.

4. Review the message bar for status messages.

   If the migration utility was able to connect successfully to the source database, you'll see a message like:

     Test connection successful, Source connection parameters OK. 
   

   Otherwise, you'll have to review the error messages on the data utility console.

TIP:   If an error occurs and the test connection is not successful, you'll have to re-enter any JDBC URL values because these values are reinitialized when a test connection failure occurs.

1. Click OK to save the settings for the Source Database panel.

2. Choose the Target Database panel. Complete it as follows:

   Field	What to do
   Database Name	Specify the name of the exteNd Director Version 5.x database to which you want to migrate the Version 4.x data and services.
   User Name and Password	Specify the user name and password associated with the database.
   Database Driver	Choose the database driver for the target database. When you choose a database driver, the JDBC Driver and JDBC URL fields are automatically completed — unless you choose Other.
   Database Server (Hostname)	Specify the name of the machine hosting the database server.
   JDBC Driver	Accept the default value filled in when you chose the Database Driver
   JDBC URL	Accept the default value provided when you chose the Database Driver and complete any variables (such as database name and port number).

3. Click Test Connection.

4. Review the message bar for status messages.

   If the migration utility was able to connect successfully to the source database, you'll see a message like:

     Test connection successful, Source connection parameters OK. 
   

   Otherwise, you'll have to review the error messages on the data utility console.

   TIP:   If an error occurs and the test connection is not successful, you'll have to re-enter any JDBC URL values because it is reinitialized at a test connection failure.

5. You can click OK to save the settings for the Target Database panel, but you'll have to re-enter the tool to continue.

Choosing the services to migrate:

1. Open the Configuration section of the data migration utility.

2. Select the Migrate Services tab.

   

3. Complete the Migrate services panel as follows:

   Field	What to do
   User	Select if you want to migrate exteNd Director's user-related information (such as preferences).
   Include Security/Do not include Security	Select Include Security if you want to migrate the exteNd Director authorization information (such as ACLs). NOTE:   This is required if you are migrating the Content Management subsystem.
   Convert Group Pages to Containers	Select when your 4.x project includes Group Pages. Group pages are no longer supported and must be converted to Container pages. Deselect if your application does not include Group pages.
   Directory	Deselect if your 4.x project uses realm other than the exteNd Director default realm.
   Content Management	Select if your 4.x project includes the Content Management subsystem, otherwise, deselect.
   Portal	Select if your 4.x project includes the Portal subsystem, otherwise, deselect.

4. Select the Environment Settings tab:

   

5. Complete the Environment Settings tab as follows:

   Field	What to do
   Host Server Type	Choose the type of Directory service realm used in the 5.2.1 environment.
   Realm Name	If you select Other, you can specify the name of the realm. Otherwise, the name of the realm is the same as the Host Server Type.
   Project Path	The root of the exteNd Director 5.2.1 project.
   Custom Web App Name	Specify the Custom Web App Name for the 5.2.1 project. For EAR projects, this is the name of the WAR containing your exteNd Director application. It's name is not editable when you create your 5.2.1 project. It is always ProjectNamePortal. It is possible to change this name after creating the project as described in Changing the Portal WAR name (EAR projects only). For WAR projects, this is the context name for the WAR (which is also the project name).

To specify runtime parameters:

1. Select the menu options under Settings to specify runtime parameters for the migration process. They are:

   Menu option	Description
   Verbose	When selected (checked), the console output provides more detail.
   Line Wrap	When selected (checked), the console output is more readable.
   Halt on Error	When selected (checked), data migration terminates when an error is encountered.

To migrate your data:

1. Verify that you've completed the configuration tabs for

   • Source and Target Databases

   • Services to Migrate

   • Environment settings

2. Click the Start Data Migration (traffic light) icon to initiate the migration process:

   

   The main window displays the status of the data migration. When complete, the window reports the number of rows copied as well as the number of errors detected.

3. Review the utility console (command prompt window) log file to verify that no errors have been missed. In general, the utility console provides more detail for errors, such as stack traces.

Using console logging

Console output is written to a file named datamigrate.log in the same directory as the DataMigration.bat file. The log file is created every time the Data Migration Utility is run. If there are old log files in the same directory, they are backed up and renamed before the new log file is created.

To set up console logging:

1. Edit the migration properties file datamigration.properties, which is created in the same directory as the DataMigration.bat file the first time you run the Data Migration Utility.

2. Examine the log.lines setting. The default setting (0) prevents the Data Migration Utility from writing logging information to disk until the process is complete.

3. If you change the setting to something greater than zero (such as 100, for example), the application writes to the log file every time 100 lines (approximately) are written to the application window and clears the application window.

   This setting may be necessary when migrating large databases that create many messages in the window. Clearing the window frees some of the application's memory resources.

4. Shut down the Data Migration Utility and restart it to get the new buffer length.

Copyright © 2004-2005 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...