Using the Upgrade Template

This chapter provides overviews of the upgrade template and process types and discusses how to:

Load the upgrade template.
(Optional) Edit templates.
(Optional) Create templates.
(Optional) Merge templates.
(Optional) Modify step properties.

Understanding the Upgrade Template

PeopleSoft Upgrade Assistant uses an upgrade template for each product line and release. The upgrade template contains the chapters, tasks, and steps for the upgrade and consists of SQL scripts, Data Mover scripts, SQR processes, Application Engine processes, and Application Designer procedures.

Note. The steps within the upgrade template contain delivered step properties. You do not need to modify these step properties unless you want to modify the step (for example, if you choose to run the step on a server).

Understanding Process Types

A process type must be assigned for each step in the upgrade process. The following table describes each process type contained in PeopleSoft Upgrade Assistant.

Process Type	Definition
Application Engine	Runs the Application Engine process indicated by the Script/Procedure value under Step Properties. You can run your Application Engine process on the client or the server. You may need to adjust these to reduce the amount of time needed for the actual Move to Production part of the upgrade.
Build Project	Builds the project specified in the Step Properties parameter as #Project= (for example, #Project=ALLTABS). The project is built through the PeopleTools command line. You can set the project build options by clicking Build Options in the Step Properties dialog.
Compare and Report	Runs the Upgrade Compare Process using the project specified in the Step Properties parameter as #Project= (for example, #Project=ALLTABS). You set the Upgrade Compare Options (for example, the Report Filters) by clicking Upgrade Options, Options in the Upgrade Assistant. PeopleSoft Upgrade Assistant uses the options, from the Upgrade Compare, when running the process.
Convert Application Engine	Converts Application Engine processes to the current PeopleSoft release format.
Convert Fieldnames	Converts FieldNames to the current PeopleSoft release format.
Convert PeopleCode	Converts PeopleCode programs to support the newly-supported Unicode format.
Convert Workflow	Converts Workflow objects to the current PeopleSoft release format.
Copy Database	Runs the Upgrade Copy Process using the project specified in the Step Properties parameter as #Project= (for example #Project=ALLTABS). You can modify the Upgrade Copy options (for example, Language options or Objects to Copy) through PeopleSoft Upgrade Assistant. PeopleSoft Upgrade Assistant uses the options, from the Upgrade Copy, when running the process.
Copy From File	Copies a project from a file. This is used in conjunction with the Copy To File. It uses the project specified in the Step Properties parameter as #Project= (for example #Project=ALLTABS). You can modify the Upgrade Copy options by clicking Upgrade Options, Options in the Step Properties dialog.
Copy To File	Copies a project to a file. This is used in conjunction with the Copy From File option. It uses the project specified in the Step Properties parameter as #Project= (for example #Project=ALLTABS).
Create Project	Enables you to select the type of records (#Type=) to insert into a project (#Project=). For example, #Project=ALLTABS #Type=Table).
Custom Defined Process	Enables you to include custom added processes, such as Batch files, that you can run through the Upgrade Assistant. You need to start this process with cmd /c for the process to run; for example: Cmd /c c:\backup.bat
Data Mover/Bootstrap	Runs Data Mover scripts as the Access ID specified in the Database Configuration (bootstrap mode).
Data Mover/User	Runs Data Mover scripts as the User ID specified in the Database Configuration (non-bootstrap mode).
DBTSFIX	Runs the DBTSFIX.sqr for database platforms that utilize tablespaces (DB2, Informix and Oracle. The SQR edits the rel8xx.sql scripts to sync the tablespace information in the scripts with the target database server. PeopleSoft Upgrade Assistant determines your source and target releases and decides which rel scripts need to be run for your upgrade.
Load Base Data	Runs scripts conforming to the PTXXXTLS.DMS naming convention that are greater than the target database’s current PeopleTools release. PeopleSoft Upgrade Assistant determines your source and target releases and decides which Base Data scripts need to be run for your upgrade.
Manual/Stop	Defines a task you must run manually. PeopleSoft Upgrade Assistant automatically sets the run status to Stop. After you have manually completed the step, you must change the Job Status to Complete.
SQL Command	Runs the SQL command defined in the Parameters value under the Step Properties. PeopleSoft Upgrade Assistant runs the command using the SQL Query tool specified in the Database Configuration dialog box. For most SQL Query Tools, PeopleSoft Upgrade Assistant stops on an error. Following is the list of query tools used for each platform: DB2: DB2CMD.EXE Informix: SQLEDITOR400.EXE Microsoft SQL Server: OSQL.EXE Oracle: SQLPLUS.EXE Sybase: ISQL.EXE
SQL Script	Runs the SQL script defined in the Script/Procedure value under the Step Properties. PeopleSoft Upgrade Assistant runs the script using the SQL Query tools specified on the Database Configuration. For most SQL Query Tools, PeopleSoft Upgrade Assistant stops on an error. Following is the list of query tools used for each platform: DB2: DB2CMD.EXE Informix: SQLEDITOR400.EXE Microsoft SQL Server: OSQL.EXE Oracle: SQLPLUS.EXE Sybase: ISQL.EXE
SQR Report	Runs SQRs using the pssqr command line. If parameters are included in the Parameters section of the step properties, Upgrade Assistant will obtain the SQR settings from Configuration Manager for the Profile selected in the Job Database Configuration.
Upgrade PeopleTools	PeopleSoft Upgrade Assistant determines your source and target releases and decides which release scripts and other miscellaneous scripts need to be run to upgrade your PeopleTools tables to the latest release level.

Loading the Upgrade Template

You can download the templates and documentation for your application from the upgrade documentation database on Customer Connection. You must download the upgrade template and the HTML upgrade documentation to the same machine on which the PeopleSoft Upgrade Assistant is installed. After the upgrade template file and documentation have been downloaded, detached, and unzipped, you can open the template in PeopleSoft Upgrade Assistant.

Note. The PeopleSoft Upgrade Assistant uses the HTML documentation. The PDF documentation is intended for print use and is the same documentation as the HTML file.

Loading a Template to the Upgrade Assistant

To load the upgrade template:

Start PeopleSoft Upgrade Assistant.
Select File, Open Upgrade Template.

The Open Upgrade Template dialog box appears.
Select the directory in which you stored the upgrade template that you downloaded from Customer Connection.
Select the template for your product and path.

PeopleSoft Upgrade Assistant loads the template for your upgrade product.

Setting the Documentation Directory

PeopleSoft Upgrade Assistant enables you to view the upgrade documentation relevant to the step you are viewing or performing.

To set the documentation directory:

Select Edit, Set Documentation Directory.

The Documentation Directory dialog box appears.
Enter or browse to the folder in which you placed your HTML documentation.
Click OK.

When you select a chapter, task, or step in the Upgrade Assistant template tree, PeopleSoft Upgrade Assistant displays the corresponding upgrade documentation in the documentation pane.

(Optional) Editing Templates

This section discusses how to:

Add steps.
Edit steps.
Delete chapters, tasks, or steps.
Rename chapters, tasks, or steps.

Note. When using PeopleSoft-delivered templates, adding custom steps, modifying existing steps, or deleting existing steps is optional.

Adding Custom Steps

You may need to add custom steps to the template—for example, steps for dropping and adding indexes or running a backup of the target database.

To add a step:

In the Upgrade Assistant template tree view, highlight the location where you want to add the step, then select Insert Step.

The Step Properties dialog box appears.
Enter a unique name in the Step Description field.
Enter the step properties for the new step.

See (Optional) Modifying Step Properties.
Click OK.
Save the template.

Editing Steps

You can modify the delivered settings by changing the step properties. Setting these properties determines the conditions that apply when you run the upgrade process.

To modify the step properties:

In the template tree view, highlight the step for which you want to modify the step properties, then select Edit, Step Properties.
Verify that the step description corresponds to the step you selected.
Modify the step properties as necessary.

See (Optional) Modifying Step Properties.
Click OK on the Step Properties dialog box.

The step properties you defined for the current step are displayed in the task details section of the Upgrade Assistant template view.
Save the template.

Deleting Chapters, Tasks, or Steps

To delete a chapter, task, or step:

Note. If you delete a chapter, PeopleSoft Upgrade Assistant deletes all the tasks and steps within the chapter. If you delete a task, PeopleSoft Upgrade Assistant deletes all the steps within the task.

Access PeopleSoft Upgrade Assistant.

Verify that the Upgrade Template view is selected.
Select File, Open to select your template.
Highlight the chapter, task, or step you want to delete.
Select from the following:
- If you want to delete a chapter, select Edit, Delete Chapter.
- If you want to delete a task, select Edit, Delete Task.
- If you want to delete a step, select Edit, Delete Step.
PeopleSoft Upgrade Assistant deletes the chapter, task, or step and updates the template.
Save the template.

Renaming Chapters, Tasks, or Steps

To rename a chapter, task, or step:

Note. If you rename an existing chapter, task, or step in a PeopleSoft-delivered Upgrade Template, you lose the link to the Documentation Window for that chapter, task, or step.

Access PeopleSoft Upgrade Assistant.

Verify that the Upgrade Template view is selected.
Select File, Open and select the template.
Highlight the chapter, task, or step you want to rename.
Select Edit, Rename.
Enter the new name.
Save the template.

(Optional) Creating Templates

This section discusses how to:

Create custom templates
Create new chapters.
Create new tasks.
Create new steps.

Creating Custom Templates

You can create a custom template for your upgrade. When you create a custom template, you also insert chapters, tasks, and steps. In addition, you specify step properties.

To create a custom template:

Access PeopleSoft Upgrade Assistant.
Select the upgrade template view.
Select File, New Upgrade Template.
Enter the name of the new template.
Click OK.

PeopleSoft Upgrade Assistant displays the name of your new template in the Template Tree. You can insert chapters, tasks, and steps, and assign step properties for the new template.

Creating New Chapters

You can add a chapter to a new or existing upgrade template. A chapter is a section heading for a group of tasks.

To insert a chapter:

In the template tree view, highlight the location where you want to add the chapter.

If this is the first chapter in the template, highlight the top node (template name) at the top of the template tree.
On the toolbar, select Edit, Insert Chapter.
Enter a unique name for your new chapter.

Note. Each chapter in the upgrade template must have a unique name.
Click OK.

Note. After you save the template, any job based on this template is automatically updated to reflect this change.

Creating New Tasks

You can add a task to a new or existing upgrade template. A task is a section heading for a group of steps.

To insert a task:

In the template tree view, highlight the location where you want to add the task.

If you are adding a task to an existing template, put your cursor where you want to insert the task.
On the toolbar, select Edit, Insert Task.
Enter a unique name for your new task.

Note. Each task in the upgrade template must have a unique name.
Click OK.

Note. After you save the template, any job based on this template is automatically updated to reflect this change.

Creating New Steps

You can add a step to a new or existing upgrade template. A step can be any process needed to perform the upgrade.

To insert steps:

In the template tree view, highlight the task or step where you want to add the new step.

If you are adding a step to an existing template, put your cursor where you want to insert the step.
From the toolbar, select Edit, Insert Step.
Enter a unique name for your new step.

Note. Each step in the upgrade template must have a unique name; also, ensure that each step name is different from its log file name.
Click OK.

PeopleSoft Upgrade Assistant displays the Step Properties dialog box.
Define the step properties for the new step.

See (Optional) Modifying Step Properties.
Continue creating steps until the template is complete.

Note. After you save the template, any job based on this template is automatically updated to reflect this change.

(Optional) Merging Templates

This option enables you to merge your existing template with a new template.

To merge templates:

Select Options, Merge Templates.
Enter the path and file name of the existing upgrade template.

This is the path you selected when you installed the upgrade template.
Enter the path and file name of the new upgrade template.
You can accept the default Log File Name or specify a different log file name.
Click Next.

PeopleSoft Upgrade Assistant merges the two templates. It then displays the new merged template for you to review.
Review the merged templates in the Upgrade Assistant - Merge Templates dialog box.
When satisfied, click Finish.

(Optional) Modifying Step Properties

This section describes fields and options on the Step Properties dialog box. You can modify step properties for a step when adding or editing steps in the upgrade template.

Note. When you have completed defining the properties for a step and click OK on the Step Properties dialog box, the template reappears with the modified step properties in the step details area of the template.

Access the Step Properties Dialog box.

Step Description	Displays your current step.
Script/Procedure	Enter the script or procedure name associated with this step. A script or procedure name is required for all process types except Manual Stop. For SQL scripts, Data Mover scripts, SQRs, and Application Engine programs, the script or procedure name should be the same name as the script, SQR or AE program to be run. For other step types, the script name is used to name the output log. For example, if you select SQL Command as the process type, you can enter any name for the script/procedure because the SQL command is included in the Parameters field. The name you enter for the script/procedure is used as the output log for the SQL command.
Type	Select a process type. This selection defines the type for the script or procedure you selected. Types of scripts and procedures are defined earlier in this chapter. See Understanding Process Types. Following is a list of the process types and the effects of selecting some of them: Application Engine Build Project: When you select this a Build Options button appears. Click the button to select options based on the instructions in the upgrade documentation for your product and path. Compare and Report: When you select this, the Upgrade Options button appears. Click the button to select options based on the instructions in the upgrade documentation for your product and path. Convert Application Engine Convert FieldNames Convert PeopleCode Convert Workflow Copy Database: When you select this, the Upgrade Options button appears. Click the button to select options based on the instructions in the upgrade documentation for your product and path. Copy From File: When you select this, the Upgrade Options button appears. Click the button to select options based on the instructions in the upgrade documentation for your product and path. Copy to File Create Project: If you select this, you must set the #Type= and #Project= parameters in the Parameter field. Custom Defined Process Data Mover - Bootstrap Data Mover - User DBTSFIX Load Base Data Manual - Stop SQL Command SQL Script SQR Report Upgrade PeopleTools
Parameters	Enter additional parameters you may need to run the step. For SQL commands, you enter the actual SQL command in this field.

The additional parameters are:

Parameter	Description
#Project=	Required for steps that refer to a project name; for example, Build Project, Upgrade Compare or Upgrade Copy.
#Directory=	Used when you need to run a script that is not located in the %PS_HOME%\scripts directory, for example, STOREPT. In this case, you could enter: #Directory=#PT_PSHOMEsrc\cbl\base\
#P1= through #P5=	Used to pass prepend parameters to SQR reports, for example, DBTSFIX.sqr. In this case, you would pass the necessary value, such as #P1=#OutputDirectory. You must group all #P1 through #P5 parameters together.
#A1= through #A5=	Used to pass append parameters to SQR reports. In this case, you would pass the necessary value, such as #A1=#OutputDirectory. You must group all #A1 through #A5 parameters together.
#Rename=	Used primarily for the Convert FieldNames step type. It automatically copies the CONVERT-XXXX.INF file from the %PS_HOME%\scripts directory into c:\temp\ and renames the file to CONVERT.INF.
#PTPS_HOME=	Used to specify the %PS_HOME% variable that is defined in the Database Configuration window.
#OutputDirectory=	Used to specify the Output Directory variable that is defined in the Database Configuration window.
#NT=	Used for DB2 Command Center, for Non-Terminated SQL Scripts.
#Type=	Enables you to specify the type of record to insert into the project. Select from the following record types: All Records, Table, View/Query View, Derived, SubRecord, Stored Procedure, Temporary Table, Dynamic View
#RCID=	Enables the user to override the Run Control ID used for Application Engine processes.

Run Location	Select Client or Server. This enables you to indicate whether to run the particular step, script, or procedure on the Client or a Process Scheduler server. If you select Server, PeopleSoft Upgrade Assistant checks the database configuration for the name of the process scheduler. You specify the process scheduler during the database configuration steps. Note. Selecting a Run Location applies to Application Engine processes only.
Database Orientation	Select Source or Target. This enables you to indicate whether to run the step, script, or procedure against the source or target database, as defined by the database configuration. Note. The default orientation is Target, but in certain steps, such as the Export and Copy or the Project Compare, you are required to log into the source first. In these cases, set the database orientation to Source.
Products	Click Products to display the Products dialog box. From the lists in the Products dialog box, select the product type (for example, FIN/SCM) and the products your step should be run against (for example Asset Management). After you select your products, the PeopleSoft Upgrade Assistant displays your selection on the Step Properties dialog box. Note. This feature is used primarily for data conversion processes.
Platforms	Click Platforms to select the platforms that you want to run against your upgrade step. After you select your platforms, the PeopleSoft Upgrade Assistant displays your selection on the Step Properties dialog box.
Language	Click Languages to select languages you have loaded in your database. The selections you make here work together with the selection you make in the Language Type group box. After you select your Languages, the PeopleSoft Upgrade Assistant displays your selection on the Step Properties dialog box.

Type of Upgrade Step

Indicate when to use the step, script, or procedure in the upgrade process.

Initial Upgrade	Indicates the initial upgrade part of the upgrade process.
Move to Production	Indicates the move to production part of the upgrade process.
Both	Indicates both the initial upgrade and the move to production parts of the upgrade process. This is the default selection.

Language Type

The language type works in conjunction with the languages selected for the step in the Language field.

Installed Language

If you select Installed Language, the step will be run if the you indicate in the Language tab of Database Configuration that one or more of these languages is installed on the target database. For example, if you select English, French and German in the Language field for the step properties and select Installed Language, the step will appear in a job if you indicate that English, French, or German is installed on the target database.

See Configuring the Database.

Base Language

If you select Base Language, the step will be run if you select a Target Base Language in Database Configuration that corresponds to the step properties Language selection. For example, if you select Spanish for the step properties and select Base Language, the step will appear in a job only if you select Spanish as the Target Base Language in Database Configuration.

See Configuring the Database.

Allow for Errors

In the Allow for Errors group box, select one of the following options:

Yes

Select to allow for errors in the step. If you select this option, PeopleSoft Upgrade Assistant continues the run the process if it encounters an error.

Select to allow for no errors in the step. If you select this option, PeopleSoft Upgrade Assistant stops the upgrade process if it encounters an error. You can configure PeopleSoft Upgrade Assistant to notify you, by email, if an error occurs.

See Specifying General and Email Settings.

Note. The default setting is No .

Run Concurrently

PeopleSoft Upgrade Assistant can run certain upgrade steps concurrently; for example, you can run several Application Engine, SQR, or SQL scripts simultaneously.

In the Run Concurrently group box, select one of the following options:

Yes

Select to run the step concurrently. If you select this option for two or more steps, PeopleSoft Upgrade Assistant starts those processes concurrently, until it reads a step that has been set to No or a step of type Manual-Stop.

Select to run the step individually.

Note. The default setting is No.