Using Change Packages

This chapter provides an overview of change packages and discusses how to:

• Create a change project.

• Create a change package.

Note. To take advantage of PeopleTools updates, see PeopleSoft Customer Connection. Change Packager is only available for PeopleSoft application updates, not PeopleTools updates.

Understanding Change Packages

Change packages are used to enable:

• PeopleSoft developers to package software updates and any prerequisites associated with PeopleSoft application updates

• You to package your own system customizations into a change project, which is then used by the Change Packager and Change Assistant when migrating from one release or one environment to the next.

The process of using a change package is to:

1. Create a new project adding all new items for the application changes to the database for the update, identifying the project as a change project and setting the appropriate update IDs and prerequisites, if applicable.

2. Define the file reference definition(s), if necessary, for the individual files that need to be packaged with the project and the file type code.

   Note. All projects need to include a file reference definition.

3. Generate the change package, which copies the project to a file, generates a Change Assistant template and documentation, creates the Data Mover scripts for non-managed objects, and packages the referenced files.

4. Manually update the Change Assistant template, if necessary, that is generated by the Change Packager.

5. Finalize the change package using the Finalize Change Package option, which performs validations on the package and produces the zip file.

   The zipped archive files contain the change project and all its associated files.

6. Test the newly created change package.

Creating a Change Project

In addition to identifying the project as a change project, if necessary, you will need to add a file reference definition to the project, which requires a file type code definition. A file reference is only necessary if there is a physical file that you want to execute or deploy or both when the change package is applied by Change Assistant.

This section discusses how to:

• Set project properties for a change package.

• Define the file type code.

• Create a file reference definition.

• Modify the upgrade definition type.

Setting Project Properties for a Change Package

Before beginning to work with the Change Packager, you must identify the project you want to use as a change project. You do this in the Project Properties dialog box.

To create a change project and set project properties:

1. Create a new project.

2. Open the Project Properties dialog box.

3. Enter a Project Description and any pertinent comments for your internal tracking system on the General tab.

   The system populates the information you enter here into the change log and the manifest.

4. Select Change Project on the General tab.

   This enables the Update IDs and the Pre-Requisites tabs. Here you identify the lead incidents from your incident tracking system, if applicable, that identify the updates to the database.

5. Select the Update IDs tab.

6. Enter the primary incident tracking ID associated with the update you want to implement in the Update ID field.

   This field may contain both numeric and alphanumeric characters. The system considers the first value in the list to be the primary ID for the project. When entering your own incidents:

   1. Enter the names of the fixes or the update IDs fixed in this project. The system logs them to the manifest and includes them when Change Packager copies the project.

   2. Click Add to add it to the list.

      Note. In order for Change Packager to create the change package successfully, you must enter a value in the Update ID field.

7. Select the Pre-Requisites tab.

   List any prerequisites that this project might have. Change Assistant checks those incidents that you enter here against those listed in the target environment's change log to verify whether the fix has been applied.

Defining the File Type Code

Each file reference definition that you create for the project must be associated with a file type code. The file type code stores generic information that is applicable to a group of files within the same target directory.

Access the file type code definition from Tools, Miscellaneous Definitions, File Type Codes.

To define the file type code for the file reference definition:

1. Click New to access the New File Type Code dialog box.

2. Enter a file type code and click OK.

   The file type code can be up to 30 characters in length. This action opens the File Type Code dialog box.

3. Enter the Path.

   This notifies Change Assistant where the file belonging to this type code should be deployed. The only supported environment variable at this time is %ps_home%.

4. Enter a description for the file type code.

   This field is required in order to save the definition.

Creating a File Reference Definition

If you have individual files that need to be packaged with the project, you can create file reference definitions to identify them. Create one file reference definition for each file. You create a file reference definition in the same manner as all other PeopleTools definitions: selecting File, New from the menu.

For each of the drop-down list boxes in this dialog box, you may select multiple entries by using the Shift/Ctrl keystroke combinations.

The file reference properties contain only the General tab where you can enter any comments about the file reference as well as select the Owner ID. This tab also tells you when the definition was last updated and by whom.

When you save the file reference definition, the definition name defaults to the file name you entered in the File Name and Path field. The Save As dialog box prompts you for the File Type Code, which is a requirement for every file reference definition.

Variable File Reference Path

You can use a variable path as a file reference. To do this, in addition to the steps for creating an absolute path:

• In the File Name and Path edit box, enter the name of the file and prepend the filename with %FILEREFPATH%.

  For example: %FILEREFPATH%\ExcelToCI.xls

• Add this file reference to a change project.

When you create a change package with a variable file reference, the Create Change Package dialog appears.

Note. If the project does not contain a file reference, the File Reference Settings group box is grayed out.

The file reference field in this dialog expands the %FILEREFPATH% variable in the file reference definition. The file reference definition will not be updated in this process. This will enable users who wish to repackage change packages without modifying the file reference definitions. The value in the File Reference Path field is stored in the registry and displays the last value.

Using variables in the file reference definition eases the repackaging of a change package.

When the change package is recreated, the update ID automatically expands the file reference paths.

When you enter an update ID, the file reference path expands to:

file reference path + upd + update ID + \ + upd + update ID + _batch\filereferences\ + file type code + filename.

For example:

c:\temp\upd999999\ upd999999_batch\filereferences\XLS\ExcelToCI.xls

c:\temp\upd999999\ upd999999_batch\filereferences\SQR\xrfwin.sqr

If the file does not exist in the directory, the system searches for the file reference path. If the file isn’t found in this directory, then an error will be displayed and the Change Packager fails to create a change package.

Modifying the Upgrade Definition Type

After creating the file reference definitions and inserting them into the change project, the next step is to modify the upgrade definition type to instruct whether Change Assistant should deploy or execute the file reference. Deploying the file copies it to the location specified in the File Type Code defined in the target environment. Executing the referenced file means it will be run on the Change Assistant machine.

Note. File references and application engine programs are the only definition types that can be executed.

To modify the upgrade definition type:

1. Open the change project.

2. Select the Upgrade tab in the project workspace.

3. Double-click the File References folder.

   This action opens the upgrade definition type listing all file reference definitions for that project.

4. Choose the appropriate upgrade attributes for each of the file references listed.

   Refer to this table to ensure the desired results:

   Desired Result	Execute Check Box	Upgrade Check Box	Action Option
   Deploy and Execute	Selected	Selected	Copy
   Deploy only	Cleared	Selected	Copy
   Execute only	Selected	Cleared	Copy
   No Step*	Cleared	Cleared	Copy
   No Action**	Either	Either	Delete

   * No step indicates that the generated Change Assistant template will not have a step corresponding to that file reference definition.

   ** No action means that the file is neither deployed or executed in the target machine.

   The default settings for the upgrade definition type are set for deploy only.

5. Save the project.

Creating a Change Package

This section discusses how to:

• Create a change package.

• Modify the Change Assistant template.

• Finalize the change package.

Creating a Change Package

Once you have created your change project you can build the change package using the Change Packager feature.

To create a change package:

1. Select Tools, Create Change Package from the menu.

2. Enter the Export Directory in the Create Change Package dialog box.

   The Change Packager feature copies the project into the directory you identify. Use the browse button to search for the desired directory. If you already created a change package for this project in the same directory, the system prompts you to delete the existing file.

   Progress dialog boxes indicate the definitions that the system is copying into the change package. The system then confirms that the change package was created successfully. The Results tab of the output window displays a list of the definitions in the project by definition type, as well as any errors encountered.

3. Open the staging directory to confirm the change package was created successfully.

   The destination directory now includes a new folder named after the project and appended with the word Package.

Change Packager Output

The Change Packager feature generates several folders and a manifest, placing them in the output directory you specified previously. The manifest from the change package is an XML document containing data that may need to be accessed quickly by Change Assistant. This manifest information includes:

• Update ID(s) from the project properties.

• Prerequisite ID(s) from the project properties.

• Update summary text from the project properties.

• The user who created the update.

  This is the user ID for the individual that last updated the project based on the By User field in the Project Properties dialog box.

• Post date.

  This date is generated from last updated Date/Time field from the Project Properties dialog box. Change Assistant uses this date to determine the order in which to apply a selection of change packages.

• The number of manual steps included in the Change Assistant template.

• A count of the definition types included in the project.

In addition to the manifest are six folders that include:

• The Change Assistant template

  The template contents for the update are tailored to the specific contents of the change project, including all relevant file deployment steps for each file reference definition given the file type code and the file reference attributes.

• Documentation

  The change package documentation is an HTML file. This document contains general information on the installation as well as instructions that are customized to your specific customizations. When you open the change package in Change Assistant, it displays the proper documentation for the current step in which you are currently working.

• File references

  The File References folder contains folders for each file type code associated with each file reference definition in the project. Each file type code folder contains a copy of the actual file referenced by the project's file reference definitions associated with this file type code.

• Project folder

  This folder contains an XML file of all project information.

• Pre 8.44 project folder

  This folder is applicable only to customers operating on a pre-8.44 PeopleTools release and are therefore not using Change Assistant to deploy change packages.

Modifying the Change Assistant Template

In most cases, the Change Assistant template generated by the Change Packager is exactly what you need to begin working with Change Assistant. However, in rare instances it may be necessary to manually add or update the steps in the Change Assistant template. The template is located in the Change Assistant package directory as an XML file.

Finalizing a Change Package

Once you create the change package and are satisfied with the Change Assistant template, finalize the change package. The finalization process validates the files to confirm that all of the necessary pieces to produce the change package are present and generates a zip file for the entire change package. The zip file enables you to easily migrate your change sets to multiple environments.

To finalize a change project:

1. Open the change project to finalize.

2. Select Tools, Finalize Change Package from the menu.

3. Enter the location of the staging directory that you would like zipped up for the change package and click OK.

   Use the browse button to search for the proper directory.

   Change Packager places the zip file in the "<project name>Package" file, using the project name for the file name.