Configuring Change Assistant for Upgrades

This chapter discusses how to:

Click to jump to parent topicDownloading The Upgrade Template and Documentation

You can download the templates and documentation for your application from the upgrade documentation from Oracle.

Download the upgrade template and the HTML upgrade documentation to the same machine on which Change Assistant is installed. After the upgrade template file and documentation have been downloaded, detached, and unzipped, you can import the template to Change Assistant.

Note. Change Assistant uses HTML documentation. If you want to print the documentation, there is a .pdf file available that has the same information.

Click to jump to parent topicImporting and Opening a Template

To import and open the upgrade template:

  1. Start Change Assistant.

  2. Select File, Import Template.

    The Import Template dialog box appears.

  3. Select the directory where you stored the upgrade template that you downloaded from.

  4. Select the template for your product and path.

  5. Select File, Open Template..

    The Open Template dialog box appears, which lists all of the templates stored in Change Assistant.

    Note. If this menu option is disabled, make sure you have Create or Modify Templates selected as the mode in the Change Assistant Options dialog box.

    See Specifying Change Assistant Options.

  6. Select the template for your product and path.

    Change Assistant loads the template for your upgrade product.

Click to jump to parent topicConfirming The PATH Variable

When performing PeopleSoft application upgrades, you make a copy of your production database, and it is the Copy of Production database (not the New Release Demo database) against which you run many of the upgrade tasks. Unless instructed otherwise, any tasks run against the Copy of Production database during Chapter 1 of your PeopleSoft application upgrade need to use the previous installation of PeopleTools, not the new installation of PeopleTools supporting the new PeopleSoft release.

During the tasks in Chapter 1 of the application upgrade, make sure the PATH variable on the machine running Change Assistant references the PS_HOME of your previous PeopleTools installation instead of the PS_HOME of your new PeopleTools installation (OLD_PS_HOMEbinclientwinx86). When starting Chapter 2 of your application upgrade, edit your PATH variable to point to the new PS_HOME (NEW_PS_HOME\bin\client\winx86).

See Also

Confirming the Path Variable

Click to jump to parent topicSetting the Documentation Directory

To view the documentation associated with a template, you need to set the documentation directory first, so that Change Assistant can locate the files. Once set, you select a chapter, task, or step in the template or job tree, and Change Assistant displays the corresponding upgrade documentation in the documentation pane.

Note. Setting the documentation directory for a template requires that the template be saved.

To set the documentation directory:

  1. Select Edit, Set Documentation Directory.

  2. Enter or browse to the folder where you placed your upgrade documentation HTML files.

  3. Click OK.

See Working with Embedded Documentation.

Click to jump to parent topicConfiguring and Working With The Upgrade Environment

Before you begin performing an upgrade using Change Assistant, you must define your upgrade environment, which consists of all of the databases used to perform the upgrade and any Process Scheduler servers you intend to use. Change Assistant uses your configuration information to:

Click to jump to top of pageClick to jump to parent topicCreating An Upgrade Environment

To create an upgrade environment:

  1. Select File, New Environment.

  2. On the New Environment dialog box, enter a name for your upgrade environment, and click OK.

    This launches the Database Configuration Wizard.

  3. On the General Settings page, specify the high-level settings for your environment.

    Other settings within the environment are determined by selections on this page.

  4. Click Next to define databases and Process Scheduler servers as needed.

  5. On the Confirm Selections screen, make sure you have entered all the required information correctly.

Click to jump to top of pageClick to jump to parent topicSpecifying Upgrade Environment General Settings

The settings on the Database Configuration Wizard, General page are:


Select if you use a Unicode database. If not selected, the system assumes an ANSI database.


Browse and select all installed products affected by this upgrade.


Browse and select all languages that apply to this upgrade.

Database Type

Select a database platform from the list. Based on signon requirements for the database platform that you select in this field, other fields will be disabled or become available for entry.

SQL Query Executable

Select the correct executable for the database platform. Valid SQL query executables for each platform are:

  • DB2: db2cmd.exe

  • Informix: dbaccess.exe

  • Microsoft SQL Server: osql.exe

  • Oracle: sqlplus.exe

  • Sybase: isql.exe

Note. Change Assistant uses the command line version of the .exe, not the GUI version. For example, sqlplus.exe is used for an Oracle database, rather than sqlplusw.exe.

Important! Oracle Database Customers: For systems running on the Oracle database, by default, Change Assistant copies the generated SQL script files to the location specified as the TEMP User variable on the Environment Variables dialog box. So, on Oracle, the generated SQL script files will actually exist in two locations: the specified Change Assistant output directory, and the TEMP directory. This behavior is in place because some versions of Oracle SQL Plus do not support pathnames longer than 79 characters. It is recommended that you ensure that the value specified for the TEMP User variable is set to a path short enough so that the string comprising the path and generated SQL file will not exceed 79 characters.

Old Release PS_HOME

Enter the location of your previous PS_HOME.

Note. Oracle recommends using a mapped drive.

New Release PS_HOME

Enter the location of your current PS_HOME (the PS_HOME of the application to which you are upgrading).

Note. Oracle recommends using a mapped drive.

Enable Copy of Current Demo Database

Enables a third database, Copy of Current Demo, to be specified in the environment, in addition to Source and Target.

In some cases, during application upgrades only, templates contain steps to be run against the Copy of Current Demo database. The database orientation of Copy of Current Demo is available only for select step types, such as compare and Data Mover steps.

Note. This option is applicable for upgrades to PeopleSoft Financials and Supply Chain 8.9 and above and PeopleSoft applications 9.0 and above.

Note. This check box applies only to application upgrades.

Enable Production Database

Enable Production Database is not valid for any existing upgrade. It is reserved for future use. This option should normally be unselected.

Click to jump to top of pageClick to jump to parent topicSpecifying Upgrade Environment Database Settings

An upgrade environment includes these database types:

Which database types you specify in your environment depends on the type of upgrade you are performing and the types of steps that need to be run.

Database Type


Used in PeopleTools Upgrade?

Used in Application Upgrade?


Required (for Application Upgrades)







Copy of Current Demo








The Database Configuration Wizard provides a separate configuration page for each database type, containing these settings:

Database Name

Enter a name of up to 8 characters for the database.

User IDand Password

Enter the PeopleSoft user ID and password for the database that will be used to perform the upgrade. Examples of user IDs are VP1 and PS.

SQL Server Host Name

(Used for Microsoft SQL Server only). Enter the name of the host machine that runs the SQL Server database. It is used to run SQL commands and scripts in the command line.

Database Server Name

If applicable, enter a name of up to 256 characters for the database server name.

Access ID

The access ID has full access to all objects in the database.

Your access ID is not a PeopleSoft user ID, such as VP1 or PS. Examples of access IDs are sa or sysadm.

Note. The IDs and passwords are case-sensitive.

Note. The access ID is often the database owner. It is not normally the same value as the connect ID, which has limited access to the database.

See Access IDs.

Owner ID

(Used for DB2 z/OS only). Enter the owner ID used for the tables.

Test Connection

Click to confirm the database connection information you have entered.

Enable Process Scheduler

Select this option to define up to two Process Scheduler servers to run ProcessScheduler steps during the upgrade job run.

This option applies only to Source and Target databases in an application upgrade environment.

Click to jump to top of pageClick to jump to parent topicSpecifying Upgrade Environment Process Scheduler Settings

If you have selected the Enable Process Scheduler check box for an applicable database definition, you must enter the required information for the host machine and the Process Scheduler server definitions associated with that database that will be running the ProcessScheduler steps. You assign an existing Process Scheduler server to either the SERVER1 or SERVER2 slots. When defining a ProcessScheduler step type, you specify which server will run the step, SERVER1 or SERVER2.

Host Machine or IP

Enter the host name or the IP address of the application server where the appropriate Process Scheduler server domain is running (PSPRCSRV.EXE and so on).

JSL Port

Enter the domain's JSL port (listener port).

Server Name

Enter the name of the Process Scheduler server definition, such as PSUNIX.

Method of retrieving Process Scheduler logs

You can download view the Process Scheduler logs from within Change Assistant so that you don't need to monitor the processes separately using Process Scheduler monitoring and logging. Similar to other Change Assistant log files, the downloaded Process Scheduler log files are saved to the Change Assistant output directory.

  • None: Disables the ability to view Process Scheduler log information from within Change Assistant.

  • FTP: Select if Process Scheduler is running on a UNIX server.

  • File Copy: Select if Process Scheduler is running on a Windows server.

Note. If you have configured multiple Process Scheduler servers within your upgrade environment, and they each run processes within the job, as needed, note that the log information will reside in two locations, with each location containing the log information associated with the processes run on that server.

Machine Name or IP

(Applies only to FTP option). Enter the machine name or IP address of the FTP server where the Process Scheduler logs are located.

Log/output Directory

(Applies to File Copy and FTP option). Enter the path to where the Process Scheduler logs are located on the server.

  • For the FTP option, enter the absolute path on the FTP server.

  • For the File Copy option, this is the (mapped) path on the Change Assistant workstation.

User IDandUser Password

(Applies only to FTP option). Enter the user ID and password required for connecting to the UNIX server (as if an FTP client were connecting).

Click to jump to top of pageClick to jump to parent topicImporting and Exporting Upgrade Environments

To save time when creating other jobs or if you are accessing Change Assistant from multiple machines, you can export the environment configuration to a file after you’ve saved it. Change Assistant generates an XML file to store the upgrade environment information.

To export an environment:

  1. Select File, Export Environment.

  2. On the Environments screen, select the environment to export.

  3. On the Export Environments dialog box, navigate to the directory where you want to store the exported XML file.

    By default, the exported file assumes the name of the environment that you specified when you created it.

  4. Click Export.

To import an environment:

  1. Select File, Import Environment.

  2. On the Import Environments dialog box, navigate to and select the XML file storing an exported upgrade environment.

  3. Click Import.

Click to jump to top of pageClick to jump to parent topicDeleting Upgrade Environments

If you decide to delete an upgrade environment, consider that all the job instances associated with that environment that you created will also be deleted.

To delete an upgrade environment:

  1. Select File, Delete Environment.

  2. On the Delete Environment dialog box, select the name of the environment to delete, and click OK.

  3. Confirm that you are aware that all the jobs associated with the environment will also be deleted.

Click to jump to parent topicCreating Upgrade Jobs

You can create new upgrade jobs or use existing jobs.

To create a new upgrade job:

  1. Select File, New Upgrade Job.

  2. On the Use Template dialog box, select the template you want to use for the upgrade job, and click OK.

  3. On the Environments dialog box, select the environment you want to use for the upgrade job, and click OK.

  4. On the Type of Upgrade dialog box, select the type of upgrade to match the phase of your upgrade process.

    For example, if you are running a test upgrade against a Copy of Production database or a Demo database, select Initial Upgrade, but if this job is running against your Production database, select Move to Production. This filters steps based on the Type of Upgrade step property.

    See Specifying Change Assistant Options.

Note. You can create multiple upgrade jobs from each upgrade template.

Click to jump to parent topicConfiguring Remote Agent Processing

To improve performance and processing time for data intensive steps associated with, for example, data conversion, Build, and Alter scripts during the move to production upgrades, Change Assistant can run these step types through an EMF Agent running on a remote host:

Note. Remote agent processing applies only to upgrades.

In many cases, test runs against the Copy of Production database should provide reliable metrics with which you can determine which processes are candidates for remote processing. If a step appears to require a lot of time to complete, rather than running the process on the Windows workstation where Change Assistant is installed, you can elect to have the processes run on a high-powered server, where a PS_HOME (and thereby an EMF Agent) is also installed. For optimal results using this option, make sure that the EMF Agent resides on the same server machine as the database, or on a high-powered server on the same backbone network.

To configure remote agent processing:

  1. On the Change Assistant Options dialog box, select Enable Server Processing beneath Perform Application Upgrade.

  2. On the Change Assistant Options dialog box, set the Remote Agent options.

    The Remote Agent options are available only if you have selected both Perform Application Upgrade mode and Enable Server Processing.

    Host Name

    Name of the server machine where the agent to perform the remote processing is installed.

    Note. Use a fully-qualified machine name.

    Host PS_HOME (Complete Executable Path)

    The complete path to Data Mover (psdmtx) and Application Engine (psae) executeables.

    For example:

    Windows: c:\PT85\bin\client\winx86\

    UNIX: /ds1/pt85/bin/

    Host Output Directory

    Enter the directory in which you want the log files generated by the update process to reside.

    Host SQL Query Executable

    The complete path and filename of the SQL query executable.

    For example:

    Windows: c:\oracle10\bin\sqlplus.exe

    UNIX: /ds1/oracle/bin/sqlplus

    Host Maximum Concurrent Processes

    The maximum number of process that can be executed concurrently on the remote host.

  3. Set the PS_SERVER_CFG environment variable to point to the PSPRCS.CFG file of the user ID starting the agent, using a fully-qualified machine name.

  4. For the steps that you want to run on the remote host through the remote EMF Agent, in the Step Properties dialog, set Run Location to Remote Agent.