WebFOCUS Release 5 Migration

By Jim Thorstad, Emma Schwarz, Mona Baker, and Dimitris Poulos

WebFOCUS Release 5 is packed with new features. But a new architecture underlies many of these new features, so existing customers need to migrate their older installations to Release 5. With that in mind, we created utilities that simplify the migration process.

Before we get into the nuts and bolts of migration, let’s step back for a moment. Why do we have to migrate anyway, and what exactly does "migrate" mean? The need for migration arises because the required format for such things as Managed Reporting, ReportCaster repositories or the GFA metafiles that describe a Developer Studio project, may change over time. But whatever you as a customer create generally doesn’t require migration because the FOCUS language is upwardly compatible from one release to another.

The term "migration" is used in many ways, which is confusing. For example, someone might refer to migrating a FOCUS application to WebFOCUS. Features such as CRTFORM must be converted into HTML forms, and font, color, and styling issues arise for the first time. An "application conversion" more aptly describes this process, in which significant new benefits can be realized through the repurposing of a legacy reporting application.

"Migration" sometimes refers to the process of moving finished application components into production. This is an important aspect of the application lifecycle and you will hear us refer to this topic as "change management" instead of migration. We will use migration to refer to the one-time event of upgrading to a major new Information Builders release.

We encourage you to use this article in conjunction with the WebFOCUS installation guide, which has full instructions regarding migration.

We realize migration adds obstacles to the adoption of our new software, so we aim to minimize these issues. But technology changes and the demand for more advanced features can overcome our attempts to stay on a given architecture. Release 5 will surely not be our last architectural upgrade, but we are listening to you and strive to make our migration process more accommodating. So keep the feedback coming.

Managed Reporting Migration

We have made some minor changes to the repository in Release 5, such as adding the Public User and Group for Dashboard, which is now an integral feature of Managed Reporting. The migration utility (WebFOCUS52\utilities\mrmigrate.bat) is run once to extract your old repository information, published pages and templates, and any old ReportCaster prepared reports.

These files are written to a Java^TM zip file (the utility is written in Java), which is then loaded into the target installation. By breaking the migration into these two steps we can support migration between two machines more easily. In Release 5 the migration utility also can be used to convert a repository from Windows NT to Unix or from NT/Unix to OS/390. This can be helpful when up-sizing a smaller proof-of-concept installation.

One thing we don’t do for you is convert the static form actions in your published pages to use the new WFServlet, which is the default WebFOCUS configuration in Release 5. The 5.2.1 Release Notes will show some simple JavaScript that you can copy into these pages to dynamically determine the current WebFOCUS Client configuration (e.g., servlet, CGI, ISAPI). This was supposed to go into the installation manual but was inadvertently omitted.

One other change is that we no longer take your old publish templates (the files in WebFOCUSxx\ibi_html\template) and copy them over the top of our new ones in Release 5. Instead, we create a new folder for them under ibi_html and ask you to move any files you may have customized into our template directory. The reason for this is that in Release 5, we have added some important JavaScript to our templates and we don’t want you to miss out. See the note about Publish page migration in the 5.2.1 Release Notes for more information.

Dashboard Migration

Several new features in the Business Intelligence Dashboard enhance the product but also make migration a necessity. These features include group views, independent customizations for public views and multiple content pages.

The migration of Dashboard customizations and personalizations follows the same format as in previous releases. That is, the Dashboard folders are copied from the 4.3.6 directory into the 5.2 release directory. The migration procedure is invoked when the administrator brings up the View Builder.

The trigger for the migration is the presence of the new_worp_custom and new_worp_users directories. After the migration procedure is completed, these folders are automatically renamed to default_worp_custom and default_worp_users, and the worp_custom, worp_users and configuration directories are updated to Release 5 level. The migration procedure also creates a log file in the Dashboard directory.

Note that the migration must be staged before using the View Builder or the Dashboard in the 5.2 release, since the migration procedure will not merge changes to the Dashboard files made in 5.2 with the changes from Release 4.3.6.

ReportCaster Migration

In release 5, the architecture of ReportCaster has changed. Some features, most notably, the Report Library, have been added. To accommodate these changes, the ReportCaster Repository has changed dramatically.

Enhancements to the ReportCaster Repository consist of the following: Seven new tables were created and one table was removed (BOTEUSER). BOTEUSER was replaced with two new tables to support the new security paradigm in release 5: BOTTSKEX contains Execution IDs (valid operating system IDs) and BOTUPROF contains ReportCaster/Managed Reporting user IDs (owner IDs). Three tables have been created for the new Report Library (BOTLIB, BOTLIST, BOTACCES). To support distributing multiple tasks per schedule, two new tables were created (BOTPACK and BOTTASK).

Multiple options are available to bring your 4.3.X ReportCaster environment to the 5.2 level. We have expanded the migration utilities to not only migrate the data within the ReportCaster Repository, but to also synchronize users defined in Managed Reporting and ReportCaster, perform change management (selective migration) and globally update certain fields during the migration process.

We will first discuss the synchronization process between Managed Reporting and ReportCaster. Then we will discuss the ReportCaster Repository migration, which includes the ability to selectively migrate schedules and address books and perform, global update changes.

Synchronizing Users Between Managed Reporting and ReportCaster.

If ReportCaster is installed with Managed Reporting, there is a new synchronization program, rcusersync, which synchronizes the Managed Reporting Repository user file (user.htm), with the ReportCaster Repository user profile table (BOTUPROF). You should execute this utility before migrating the ReportCaster Repository.

The rcusersync command file must be edited before it can be executed. When editing this file, do not include any line feeds (i.e., do not hit the enter key). The line must flow as one consecutive input line. (Wrapping to the next line is acceptable but a line feed will cause an error.)

The information needed for the synchronization file includes the location of the basedir (for example, d:\ibi\WebFOCUS52\basedir\user.htm), the ReportCaster Administrator ID and password (for example, admin ""), and the ReportCaster Node and Port (for example, hostname:8200). Note that initially the admin user ID does not have a password, so the double quotes do not have a space between them, denoting no password.

If the Distribution Server and Web server are on different machines, rcusersync must be copied to the WebFOCUS52 directory on the Web server. The program will find the basedir directory on this machine and copy the information to the ReportCaster machine. This is a one-step process.

The rcusersync command file must be executed to synchronize the user information. The synchronization program needs to only be executed once. When new users are added to the system using the Managed Reporting User Administration tool, the user will be added to the ReportCaster Repository automatically if ReportCaster is installed.

ReportCaster Repository Migration

The migration of the ReportCaster Repository tables rely on one very important file – the configuration file rcmigrate.properties, which must be edited before executing the ReportCaster Repository migration programs. This file is used for both the extract and load procedures and needs to be edited only once.

The information required within the configuration files includes the target (new) ReportCaster 5.2 configuration file location (for example, d:\ibi\ReportCaster52\cfg). We also want to know what version we are migrating; the values for the source (old) version is 431, 435 or 436. The 5.2.1 release supports migrating from 5.2 to 5.2 also (for example, migrating data from a 5.2 test database to a 5.2 production database or migrating from a 5.2 FOCUS repository to a 5.2 DB2 repository).

It must also include the repository class and URL for general information for the source (old) repository. A helpful hint here is to view the old bkrsched.cfg file for this information. Also required is the location where the extract data files will be saved. If this field is not specified, output is sent to the user’s home directory. The trace file contains all tracing information. Uncomment and edit the trace file to add the correct drive if you want to activate the tracing option.

Now that the rcmigrate.properties file has all the pertinent information, the extract and load programs can be executed. Check the trace file to view exactly what is being extracted and loaded. XML files will be created during the extraction of the old repository. These XML files will then be used to load the information to the new repository. The XML files will be created with the names of the ReportCaster Repository tables (for example, BOTSCHED.XML).

Please note that in release 5.2.1, the migration will include Execution IDs, but the initial 5.2 release does not. For the 5.2 release, there are three different ways to add this information. You can edit the ReportCaster Configuration Tool and change the Run ID type to STATIC and include a valid operating system user ID and password for the SRV User. This ID will then be used to run all reports against the WebFOCUS Reporting Server. The second way would be to add Execution IDs using the ReportCaster Console. The third way is to edit a schedule and update with Execution user ID and password. This will add the Execution ID and password to the ReportCaster Repository.

New Control Management for ReportCaster

Within the rcmigrate.properties file, there are two new options: the ability to selectively move only certain information from one repository to another (rather than the entire repository), and the ability to globally update certain fields.

To selectively migrate schedules or address books, create one directory that contains one or more condition files. Inside this directory, all files will be searched. If the first line of the file contains FIELDNAME=fieldname$, the file will be read for the condition parameters. Blank lines are allowed in this file. Inside the condition file, specify the condition type: $INSERT, >$REPLACE$DELETE. Group the condition values. There can be a list of different condition values, each on a separate line. For example, here are the contents of the file sched.txt:

$FIELDNAME=SCHEDULEID
$INSERT
1234567890
234567890

$REPLACE
23456789w1

$DELETE
er456789w1

This condition file is requesting that two schedules be inserted, one schedule replaced and another deleted. You must uncomment the condition_path line in the rcmigrate.properties file if you are going to use this feature. Only the directory name is required. For example: condition_path=d:\ibi\ReportCaster52\temp. Within this directory, the files can be any name. Each file will be searched. For this reason, we recommend creating a new directory that contains only condition files.

Global Update During Migration

The Global Update feature is available from the ReportCaster Console as in past releases. In addition, global updates are now possible during migration. The following groups’ fields may be globally updated: MAILSERVER, FTPSERVER, PRINTER, EMAILADDRESS, MAILFROM, OWNER and EXECID. One text file needs to be created with the Global Update information. The text file for the Global Update must contain the following:

$ PARAMETER
The old value=old value
The new value=new value

For example:

$ MAILSERVER
old = ibismtp (Find this old value)
new = newsmtp (Replace it with this new value)
$ EMAILADDRESS
old = john@ibi.com
new = mike@ibi.com
old = smith@ibi.com
new = young@ibi.com

Uncomment the value global_update within the rcmigrate.properties file and add the directory and filename of the global update file (for example, d:\ibi\ReportCaster52\temp\update.txt). The changes will be made during the migration from the old to the new repository.

Check the trace files to view all activity associated with the migration. The ease and simplicity of the migration program is another must-have feature within the new Release 5 software.

The migration documentation is located in the installation manual for your environment.

Developer Studio Migration Utility

As with all other products in the new WebFOCUS suite, Developer Studio Release 5 underwent a major architecture change and gained a host of new and enhanced features. One enhancement is in the Projects area, previously known as the Local Applications.

Each project appears as a suitcase folder and, when expanded, a predefined set of virtual folders appears for organization purposes. Project resources are grouped in the subfolders HTML Forms, Maintain Files, Master Files, and Procedures by assigning filters for the different files that you want to display under each folder.

The default filters can be modified on a project-by-project basis, and filters can be added or removed.

It is also possible to rename, remove and create virtual folders. At the project level, you may specify the search path of shared resources you want to reuse.

All information for the Developer Studio projects is stored in a GFA file, which is the metadata file for the project. It has the same name as the project. For instance, a project called Financial Reports has an associated GFA file called Financial Reports.GFA.

The file format and location of the GFA files in Release 5 are different from previous releases. The new file is XML-based and it is now created inside the default project directory, which also contains the resources created for the given project. In previous releases, the GFA file was a binary file and it was created outside of the project/application directory.

Another change from previous releases is that the physical folder containing the resources of every project must be within a single top-level folder under the Application Directory location configured during installation of the product. Previous releases could use resources in subfolders and reside in various PC or LAN locations.

Developer Studio Release 5 provides an easy-to-use, flexible and intuitive graphical tool to assist in the migration of applications created in any previous release of the Developer Studio product line. This utility, the Project Migration Tool, migrates old applications based on user selection, convert GFA files to the new file format, migrate application resources in the new structure and location, and place the GFA file inside the required application directory.

The Migration Utility preserves old GFA files and original application directories. This allows developers to switch back to an earlier release of the product (not that you would want to do this after using Release 5) or rerun the migration if needed.

After installing Developer Studio 5, when you first launch the product a Project Migration prompt appears. You may migrate your applications before continuing with the Project Migration Tool.

If you have applications in a different directory, you may run the Project Migration Tool from the Developer Studio program group by selecting the option Project Migration Tool located in the WebFOCUS Developer Studio Utilities subfolder.

You may then specify and search for a location with old applications and select the application(s) you want to migrate. The tool also allows you to view properties for old applications, review and even modify the destination of the migration location, review search paths that were used, and alter the destination and origination paths.

At the end of the migration process, a report gets created with a log file that has detail information of the files that were migrated.

Conclusion

This article gives you an overview of the WebFOCUS product suite and the migration utilities. The installation manuals for each utility contain more detailed information.

The migration utilities in Release 5 have been designed to make your life easier.