Upgrading with PeopleSoft Application Designer

This chapter provides an overview of a PeopleSoft application upgrade and discusses how to:

Use the upgrade workspace.
Prepare projects for an upgrade.
View upgrade messages.

Understanding a PeopleSoft Upgrade

This section discusses:

PeopleSoft Application Designer upgrade features.
Definition types that you can upgrade.

PeopleSoft Application Designer Upgrade Features

PeopleSoft Application Designer streamlines the migration of database definitions—such as records, pages, projects, and PeopleCode—from one PeopleSoft database to another. You can perform a complete database upgrade or you can upgrade only the definitions included in a particular project. This chapter focuses mainly on project upgrades, and the PeopleSoft upgrade documentation focuses on complete database upgrades, which are typically performed when upgrading from one version of a PeopleSoft application to another.

While this chapter does not discuss the specific procedures for an enterprise-wide upgrade for a specific platform, there are basic steps to perform in PeopleSoft Application Designer regardless of the type of upgrade, which include:

Updating your PeopleSoft software.
Identifying the source and target database. The source can be a file, a project, or an entire database.
Comparing the source and target database to determine changed definitions.
Copy any new or changed definitions into your database and adjust all your system components—such as application data, SQL tables, indexes, views, and so on—accordingly.

Updating the PeopleSoft software is covered in the installation documentation for Enterprise PeopleTools and Enterprise applications. This chapter focuses on comparing your source with your target and copying the definitions from the source to the target.

When comparing your source and target you can view results in the upgrade workspace, in reports, in your browser, and side-by-side (for pages and text definitions, such as PeopleCode). When copying definitions into the target database you can use the PeopleSoft Application Designer interface or a command line interface. For text definitions you can use the merge feature.

Note. The complexity of these tasks performed depends on the type of upgrade you are performing. For example, if you are copying brand new definitions from a small project into a source database this is a relatively uncomplicated task, as comparisons are not required and you can immediately begin a copy. However, if you are upgrading an entire database or a large project containing numerous changed definitions it is likely that the compare, merge, or copy process will require more analysis.

Note. To use the PeopleSoft Application Designer upgrade features, you must have full access to projects and upgrade access in the target database. To run a compare you only need read-only upgrade access.

Definition Types That You Can Upgrade

PeopleSoft Application Designer has the following levels of upgrade support for PeopleSoft definitions:

Upgrade Support	Description
Compare and copy	This is referred to as "Full support." You can compare this definition between source and target and copy it to the target.
Copy to and from file	You can copy the definition to the database and to a file.
Copy only	You can copy the definition to the target, but you can not compare definition versions between the source and target.

This table displays the upgrade support for each PeopleSoft definition for which upgrade is available.

Definition Type	Compare and Copy	Copy to and from File	Copy Only
Access Groups	No	No	Yes
Activities	Yes	Yes	No
Analytic Model	Yes	Yes	No
Application Engine Programs	Yes	Yes	No
Application Engine Sections	Yes	Yes	No
Application Packages	Yes	Yes	No
Approval Rule Sets	Yes	Yes	No
Archive Objects	Yes	Yes	No
Archive Templates	Yes	Yes	No
Business Interlink	Yes	Yes	No
Business Processes	Yes	Yes	No
Colors	Yes	Yes	No
Component Interfaces	Yes	Yes	No
Components	Yes	Yes	No
Cube Definitions	No	No	Yes
Cube Instance Definitions	No	No	Yes
Dimensions	No	No	Yes
Diagnostic Plug-Ins	Yes	Yes	No
Field Formats	Yes	Yes	No
Fields	Yes	Yes	No
File Layout Definitions	Yes	Yes	No
File References	Yes	Yes	No
File Type Codes	Yes	Yes	No
HTML	Yes	Yes	No
Images	Yes	Yes	No
Indexes	Yes	Yes	No
Java Portlet User Preferences	Yes	Yes	No
Job Definitions	Yes	Yes	No
Menus	Yes	Yes	No
Message Catalog Entries	No	No	Yes
Message Channels	Yes	Yes	No
Message Nodes	Yes	Yes	No
Messages	Yes	Yes	No
Mobile Pages	Yes	Yes	No
Optimization Models	Yes	Yes	No
Pages	Yes	Yes	No
PeopleCode—Application Engine	Yes	Yes	No
PeopleCode—Application Package	Yes	Yes	No
PeopleCode—Component	Yes	Yes	No
PeopleCode—Component Interface	Yes	Yes	No
PeopleCode—Component Interface Property	Yes	Yes	No
PeopleCode—Component Record	Yes	Yes	No
PeopleCode—Component Record Field	Yes	Yes	No
PeopleCode—Menu	Yes	Yes	No
PeopleCode—Message	Yes	Yes	No
PeopleCode—Page	Yes	Yes	No
PeopleCode—Page Field	Yes	Yes	No
PeopleCode—Record	Yes	Yes	No
PeopleCode—Subscription	Yes	Yes	No
Permission Lists	Yes	Yes	No
Portal Registry Definition	Yes	Yes	No
Portal Registry Structures	Yes	Yes	No
Portal Registry User Favorites	Yes	Yes	No
Portal Registry User Homepages	Yes	Yes	No
Problem Types	Yes	Yes	No
Process Definitions	Yes	Yes	No
Process Type Definitions	Yes	Yes	No
Queries	Yes	Yes	No
Records	Yes	Yes	No
Recurrence Definitions	Yes	Yes	No
Relationships	Yes	Yes	No
Roles	No	No	Yes
Server Definitions	Yes	Yes	No
SQL	Yes	Yes	No
Style Sheets	Yes	Yes	No
Styles	Yes	Yes	No
Translate Values	Yes	Yes	No
Tree Structures	Yes	Yes	No
Trees	No	No	Yes
URL Definitions	Yes	Yes	No
WSRP Cloned Portlet Handles	Yes	Yes	No
WSRP Remote Portlets	Yes	Yes	No
WSRP Remote Producers	Yes	Yes	No
XSLT	Yes	Yes	No

Note. Certain definition types that are specified as compare and copy or copy only (for example, Cube Dimensions) do not appear on the Development tab because you cannot edit them in PeopleSoft Application Designer.

Note. PeopleSoft delivered definition types (such as pages, Application Engine programs, iScript PeopleCode, and so on) cannot be copied across product lines. For example, you cannot copy a definition from PeopleSoft Human Capital Management to PeopleSoft Customer Relationship Management. License codes for these definitions are specific to the product line in which the definition is delivered. If a PeopleSoft delivered definition is copied to a different product line, it may be inaccessible on the target database.

Using the Upgrade Workspace

This section discusses:

Switching to the upgrade view.
Viewing upgrade attributes by definition type.
Working with upgrade definition columns.
Using the upgrade menu actions.
Setting upgrade options.

Switching to the Upgrade View

When you perform an upgrade with PeopleSoft Application Designer, select the Upgrade tab at the bottom of the project workspace to switch to the upgrade view.

The upgrade view of the project workspace shows all of the definition types in the project that are available for upgrade—not only those that PeopleSoft Application Designer can modify, as in the development view. The upgrade definition window displays the definitions in the project and their upgrade settings. One definition type appears at a time.

Displayed here are the upgrade attributes for all record definitions in the selected project:

Viewing Upgrade Attributes by Definition Type

To view the upgrade attributes by definition type in a project:

Open a project.
Select the Upgrade tab at the bottom of the project workspace.
Double-click a folder to open the upgrade definition window.

With the exception of PeopleCode, the folders in the upgrade view are not expandable. The upgrade definition window contains a grid with definitions in the project that are of the selected type. For example, if you double-click the Records folder in the upgrade view, the upgrade definition window displays the records in the project.

You can view only one upgrade definition window—and one definition type—at a time. When you double-click another definition type in the upgrade view, the upgrade definition window is refreshed with the new definitions of that type.

Note. You can filter which definitions are displayed in this window. By default, no filtering is applied.

Working with Upgrade Definition Columns

The columns in the upgrade definition window display various information about each definition.

Key	Displays the name of the definition, plus any other key values. The number and titles of the key columns vary, depending on the definition type.
Source	Displays the definition status in the source (current) database.
Target	Displays the definition target database status.
Action	Displays the action that is performed if the definition is copied into the target database.
Upgrade	Select to upgrade the definition during a copy.
Done	Is selected when the definition has been copied. You can't select Done check boxes yourself—PeopleSoft Application Designer does this after a copy—but you can clear them. Only definitions that have Upgrade selected and Done cleared are copied during an upgrade.
Execute	Only applies to file references and Application Engine definitions. Allows file references and Application Engine definitions to be executed when applying a change package.

The key columns on the left-hand side of the grid are frozen; they do not scroll horizontally. When you use the horizontal scroll bar, only the upgrade columns scroll, enabling you to see the key information about the definitions at all times. The various definition types have different numbers of key columns. For example, fields have only one column (Field Name), while translates have four (Field Name, Field Value, Language Code, and Effective Date).

When viewing definition types with a large nonscrolling region, the horizontal scroll bar is disabled unless at least one scrolling column is displayed.

To enlarge the window enough so that you can scroll through the upgrade columns:

Maximize the upgrade definition window.
Maximize PeopleSoft Application Designer.
Hide the project workspace.

To display all of the grid columns at one time when the preceding options don't enable you to see every column, use the zooming commands in the View menu. With each Zoom Out command, the grid size is reduced. To restore the normal view, select 100%.

You can also resize individual columns by dragging the column border to the appropriate size. If you resize the upgrade columns, save the sizing and use it for every project. Custom key column sizing is not preserved after you close a project; these columns reset to their default size.

Using Upgrade Menu Actions

To access the pop-up upgrade menu, right-click anywhere in the grid in the upgrade definition window.

This table describes the upgrade menu actions and the actions they perform:

Menu Item	Action
View Definition	Opens multiple definitions in the upgrade grid.
View PeopleCode	Opens the PeopleCode Editor. This is enabled for PeopleCode definition types.
Find Definition References	Finds all references to the selected definition.
Merge Definition	Enables you to compare and merge text definitions between two sources, either a file or another database. Text definitions are PeopleCode, SQL, XSLT, and HTML.
Diff / Merge Page	Enables you to compare (side-by-side) page definitions between two sources, either a file or another database, and merge the definitions.
Filtering	Opens a cascading menu with filtering options that you can apply to the upgrade grid. These same options are also in the View menu.
Refresh View	Updates the information in the upgrade definition window.
Set Action	Enables you to select and tag definitions for copying and deleting.
Set Action for Project	Enables you to select and tag all definitions in a project for copy or delete.
Tag for Upgrade	Enables you to tag a group of definitions for upgrade.
Untag for Upgrade	Enables you to remove the tag on a group of definitions for upgrade.
Reset Done Flag	Enables you to reset Done check boxes for a group of definitions.
Reset Project Done Flags	Enables you to reset all Done check boxes.
Insert Definitions into Project	Opens the Insert Definitions into Project dialog box.
Remove from Project	Removes the selected definitions from the current project. You can also use the Delete key.
Project Properties	Opens the Project Properties dialog box, in which you define properties for the project, like description.

Setting Upgrade Options

This section discusses how to:

Access the upgrade options.
Set general options.
Set compare options.
Set report options.
Set report filter options.
Set copy options.

Accessing the Upgrade Options

To access the upgrade options:

Select Tools, Compare and Report.
Sign in to an upgrade target database.
On the Compare and Report dialog box, click Options, and select the appropriate upgrade option tab.

Preserving Project Item Status

Access the Compare and Report dialog box and view the Project Item Status/Child Definitions group box.

Setting General Options

Access the Upgrade Options dialog box and select the General Options tab.

Use the Upgrade Options dialog box to set general options for the Compare or Copy process.

Commit Limit	Set the commit limit. Start with the default of 50. If the Copy process seems slow and there is sufficient log file space, try increasing the commit limit. You can modify the initial project default commit limit on the PeopleTools Options page. Very large commit limits, however, can cause more work if something goes wrong during the copy. For example, if the commit limit is set to 1,000 and the Copy process stalls on the 999th definition, none of the previous definitions are copied. The Copy process must be performed again.
Audit Flags on Records	Select one: Keep Target Audit Flags: Select to preserve all of the enabled target flags. This is the default. Audit flags that are enabled in the source are also retained. Differences between the source and target audit flags are not shown on the compare report. Set Target Audit Flags from Source: Select to copy audit flag settings from the source to the target database.
DDL on Records and Indexes	Select one: Keep Target DDL: Select to preserve the target DDLs. This is the default. Differences between the source and target DDL are not shown on the compare report. Take DDL from Source: Select to copy the DDL from the source to the target database.
Portal Structures Permission List	Select one: Keep Target References: Select to preserve the target portal structures permission list references. This is the default. Set References from Source: Select to copy the portal structures permission list references from the source to the target database.
Chartfield Options	Set the Display Size Page Property: Keep Target Display Size: Does not copy any display changes to a ChartField on the source database (the target values are saved). If this is set for a Compare process, no differences between the source and target in the named fields are displayed. If the only differences on the page are the ChartField display properties, then the page compares as the same for both. Set Display Size from Source: Copies the position, as well as the size and type attributes, from the source to the target database. Set the Database Field Format: Keep Target Field Format: Does not copy any changes to the field format values for a database field that is a ChartField on the source database, and preserves the target field format values. If this is set for a Compare process, any changes to the ChartField field format attributes are not displayed. If these attributes are the only changes for a field, then the definition compares as the same for both. Set Field Format from Source: Copies the ChartField field format attributes from the source to the target database.

Setting Compare Options

Access the Upgrade Options dialog box and select the Compare Options tab.

Compare Type

Select Project to compare only the definitions of the specified definition type in the current project. The contents of the project do not change.

Select Database to compare all definitions of the specified definition type. If you select Database, the contents of the current project are deleted and replaced with definitions that are found during the comparison.

Target Orientation

Determines how the Upgrade check boxes in the upgrade definition window are set for definitions that were last modified by the customer in one database and last modified by PeopleSoft in the other database.

Comparison

Select Release to compare databases by the highest release that the two databases have in common. Use the drop-down list box to select from lower common releases. The Compare process labels definitions as Changed or Custom/Changed if they have been changed since the date and time stamp for that release level. This is the default.

Select Date to have the Compare process label definitions as Changed or Custom/Changed if they have been modified since the date that you specify.

Compare Languages

Select the languages of definitions that you want to compare, and selectCOMMON, which specifies basic definition characteristics and parameters in the architecture that are not language-sensitive. Language options specify label-oriented characteristics of a definition, such as page names, labels, and messages. If you do not select COMMON, basic definition characteristics are omitted.

If you need specific languages and basic definition characteristics, also select COMMON. However, to copy only language attributes of a definition, you do not need COMMON.

Clicking Select All is the recommended default. Make sure that the languages in the source and target databases match. Press the Ctrl key and your mouse to clear unwanted languages.

Setting Report Options

Access the Upgrade Options dialog box and select the Report Options tab.

Report Output

Directory: Displays the compare report output directory. To change the output directory path, select Tools, Options from the PeopleSoft Application Designer toolbar, and select the General tab.

Font and Size: Displays the font type and size that will appear in the compare report output. Click Font to select a different font or to change the font size.

Generate Browser Reports: Select to generate HTML reports that you can view in a browser in addition to the reports that appear in the Application Designer workspace.

See Working with Browser Reports.

Generate Composite Reports: Select to generate a composite report, which is a subset of information showing only the definitions customized at your site that were also modified in the most recent PeopleSoft release.

Old Release Report Output Directory: Enter the directory containing the compare reports run on the database for your previous PeopleSoft installation: the database from which you are upgrading.

Old Release Source Database Name: Enter the source database name you specified when running the compare reports on your previous PeopleSoft installation. This enables the system to identify the appropriate database definitions listed within the compare reports.

See Working with Composite Reports.

PeopleCode Report

Specify the PeopleCode report options.

For PeopleCode compare reports, specify whether to show the entire program on the report (the default setting) or only the code differences between the source and target. If you select the latter, you can specify the number of code lines to show above and below the difference for context. The values for the number of lines to show are 0 to 99. A value of 0 shows only the difference line. A value greater than 0 shows that many lines above and below the difference line.

Note. The PeopleCode report options are global across all projects. Changing settings for one project changes all subsequent PeopleCode compares, regardless of project.

Report Data Color

Select the report data color.

Use the Browse button to display the standard color dialog box. Choose a color that is not included in the drop-down list box or create a custom color.

Additions: Select a color for additional data values on the source database. These are also source-only values. The default value is dark green.

Deletions: Select a color for data values that are deleted from the source database. These are target-only values. The default value is red.

Differences: Select a color for changed values, which are both source and target values. The default value is blue.

Setting Report Filter Options

Access the Upgrade Options dialog box and select the Report Filter tab.

When you perform a comparison, the system generates a report for each definition type compared. These reports provide detailed information about how each definition in the source differs from its counterpart in the target.

Before performing a comparison, you can select the definition status combinations with which you generate reports by using report filter options. For example, during an upgrade to a new PeopleSoft release, you might decide that if a definition that was last changed in the target by PeopleSoft is found in the source and it hasn’t changed since the last upgrade, you don’t need to see information about the definition differences (because you intend to accept the new PeopleSoft version). In this case, you want to filter the compare reports so that a report is not generated if:

The source is any status.
The target is unchanged.

Note. Filtering comparison reports does not affect which definitions are added to a project during a database comparison, only which definitions are reported. Definitions that are defined differently in the two databases are always added to the project.

Select the check boxes corresponding to the definition status combinations that you want to report.

Each row in the matrix corresponds to the definition status in the source database. Each column corresponds to the definition status in the target.

The default settings for report filtering show conflicting configured definitions only.

To reset your selections to the default setting, click the Default button.
To select all definition status combinations, click the Select All button.
If you don't want to generate any reports, click the Deselect All button to clear all of the check boxes.

Setting Copy Options

Access the Upgrade Options dialog box and select the Copy Options dialog box.

Copy Languages

Select a specific language and COMMON, which specifies basic definition characteristics and parameters in the architecture that are not language-sensitive. Language options specify label-oriented characteristics of a definition, such as page names, labels, and messages. If you do not select COMMON, basic definition characteristics are omitted. If you need specific languages and basic definition characteristics, also select COMMON.

Click Select All is the recommended default. Make sure that the languages in the source and target databases match. Otherwise, you might overwrite translations in the target. Use the Ctrl key and your mouse to clear unwanted languages.

When you save the project, the copy settings that you made are saved and remain set unless you change them again.

This table lists translation scenario examples:

Selection	Reason
COMMON and English	The source database does not include translations, but the target database has translations that you do not want to overwrite.
Languages (omit COMMON)	You sent the database out for translations and want to avoid copying inadvertent changes that were made by the translators to the definitions.
COMMON (omit languages)	You want to copy the source without translations to the target.

Preparing Projects for an Upgrade

This section provides an overview and discusses how to:

Search for definitions.
Print all definitions in a project.
Obtain access for upgrading.
Convert definitions.

Understanding Upgrade Projects

Before you can copy definitions from one database to another, you must insert them into a PeopleSoft Application Designer project. If you have a custom application, identify which definitions must be copied from the source into the target database. When you know which definitions you want to upgrade, specify and insert the definitions into the project.

However, when you are unfamiliar with one of the databases, you might want to populate a project by comparison—for example, when you upgrade to a new PeopleSoft application release. When you populate a project by comparison, the system compares the source and target databases and automatically populates the project with definitions that are defined differently in the two databases.

Populating Projects

To populate projects:

Select Insert, Definitions into Project from the PeopleSoft Application Designer menu.

PeopleSoft Application Designer designates certain definition types as related to a parent or controlling definition type. For example, a record's related definitions can include fields, indexes, and subrecords. When you insert definitions into a project for upgrading, it can be important for these related definitions to be included.
Select the definitions and click Insert.
Select Tools, Options.
On the Project tab, review the settings in Related Definitions Options and reset.

Searching for Definitions

To find a definition in the project select Edit, Find from the menu. This opens the Find dialog box where you can perform a search for a text string in an upgrade definition window.

Printing All Definitions in a Project

You can print a project definition for all of the definition types in the current project. This differs from the Print menu item, which prints only the currently selected definition type that is open in the upgrade grid. The data, however, is the same.

To print a project definition for all definitions in current project, select File, Print Project from the PeopleSoft Application Designer toolbar.

Obtaining Access for Upgrading

To use the PeopleSoft Application Designer upgrade features, you must have full access to projects and upgrade access in the target database.

Also, lock all PeopleSoft Application Designer definitions in the source and target databases before comparing and copying projects. To do this, you need supervisor-level access to Change Control (in the Tools menu). If your Change Control administrator performs this action for you, the administrator's user ID is the only one that is allowed to perform the copy while the target definitions are locked.

Viewing Upgrade Messages

This section discusses how to:

Determine whether errors were encountered.
View messages.
Print upgrade messages.
Clear messages.

Understanding Upgrade Messages

During the compare and copy processes discussed in this section, if the system encounters any errors you will be notified through system messages. These messages alert you to various areas that may need to be corrected for a successful upgrade compare and copy.

Determining Whether Errors Were Encountered

Select the Upgrade tab in the output window to determine whether any errors were encountered during the Compare or Copy process.

This view displays upgrade messages pertaining to the definition type that was most recently displayed in the upgrade definition window. In the preceding example, Access Groups was the last definition type that was viewed in the window.

Viewing Messages

To view messages:

Open the project.
Select the Upgrade tab in the project workspace.
Double-click the folder of the definition type for which you want to view messages, or click the project icon to view all messages.

Any upgrade messages for that definition type appear in the output window.

Printing Upgrade Messages

To print upgrade messages:

View the messages that you want to print.
Right-click the output window and select Print.

Clearing Messages

To clear messages:

View the messages that you want to clear.
Right-click the output window and select Clear.

Compare Type	Select Project to compare only the definitions of the specified definition type in the current project. The contents of the project do not change. Select Database to compare all definitions of the specified definition type. If you select Database, the contents of the current project are deleted and replaced with definitions that are found during the comparison.
Target Orientation	Determines how the Upgrade check boxes in the upgrade definition window are set for definitions that were last modified by the customer in one database and last modified by PeopleSoft in the other database.
Comparison	Select Release to compare databases by the highest release that the two databases have in common. Use the drop-down list box to select from lower common releases. The Compare process labels definitions as Changed or Custom/Changed if they have been changed since the date and time stamp for that release level. This is the default. Select Date to have the Compare process label definitions as Changed or Custom/Changed if they have been modified since the date that you specify.
Compare Languages	Select the languages of definitions that you want to compare, and selectCOMMON, which specifies basic definition characteristics and parameters in the architecture that are not language-sensitive. Language options specify label-oriented characteristics of a definition, such as page names, labels, and messages. If you do not select COMMON, basic definition characteristics are omitted. If you need specific languages and basic definition characteristics, also select COMMON. However, to copy only language attributes of a definition, you do not need COMMON. Clicking Select All is the recommended default. Make sure that the languages in the source and target databases match. Press the Ctrl key and your mouse to clear unwanted languages.