Working with Change Packages

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

• Create a change project.

• Create a change package.

Note. Change Packager is only available for PeopleSoft application updates, not PeopleTools updates.

Understanding Change Packages

Once you have your change project completed, you create a change packages in Application Designer. 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. Only projects that contain physical files (such as SQR or Excel files) 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 for use 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 in Application Designer, by 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.

Using variables in the file reference definition eases the repackaging of a change package. When you create a change package with a variable file reference, the File Reference Path edit box in Create Change Package dialog expands the %FILEREFPATH% variable in the file reference definition. However, the file reference definition itself is not updated in the process.

This enable you to repackage change packages without having to modify the file reference definitions. The value in the File Reference Path field is stored in the registry and displays the last value.

When the change package is recreated, the update ID automatically expands the file reference paths according to the following construct:

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.

See Creating 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 Change Packages

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 in Application Designer.

To create a change package, select Tools, Create Change Package, which invokes the Create Change Package dialog box.

Export Directory	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.
File Reference Settings	These settings apply only if your change package contains file references, otherwise these settings are disabled. File Reference Path: Enter the path for the file reference. Update ID: Enter the associated update ID. See Variable File Reference Path.
Generate New Template	Select this option if you intend to generate a new Change Assistant template with your change package that does not incorporate any manual changes made to an existing template.
Merge Existing Template	Select this option if you intend to incorporate any manual changes you have made to an existing Change Assistant template. Enter the file path or navigate to the location of the existing Change Assistant template you want to merge with the updated template.
Backport IB to pre-8.48 PeopleTools	Select if your changes affect Integration Broker (IB) definitions and need to be applied to versions of PeopleTools before PeopleTools 8.48. In PeopleTools 8.48, the metadata surrounding Integration Broker changed significantly
Overwrite if already backported	Only appears if Backport IB to pre-8.48 PeopleTools is selected. Select this option to overwrite any Integration Broker changes that have already been backported.

The 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.

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.

Working With Change Package Automation

This section provides an overview, and discusses:

• Working with ReleaseAdaptor.

• Working with ProjectFilter.

• Working with ProjectInspector.

Understanding Change Package Automation

PeopleTools provides a set of standalone utilities that automate the manipulation of change packages, ensuring that only the appropriate changes get included in change packages and applied to your system. For the most part, these utilities improve the process of creating change packages within Oracle for distribution to customer sites. However, they can also be useful at customer sites, where development teams create custom change packages to apply to their implementations.

These utilities address situations in previous releases, where during upgrades, manual steps were required and multiple change packages need to be applied, such as in the cases where Integration Broker metadata needed to be applied to pre-PeopleTools 8.48 releases. In most cases, these utilities run in the background when you create change packages or perform an upgrade while using Change Assistant. To run these utilities manually, they can be invoked from the command line, or added to automation shell scripts, for example.

When these utilities are used within an upgrade process, the documentation in your Change Assistant job and your upgrade documentation will provide the necessary details.

See Your PeopleSoft application upgrade documentation

Working with ReleaseAdaptor

ReleaseAdaptor is invoked by Change Assistant to remove:

• contents from the project that are not consumable by the target PeopleTools release.

• unneeded steps from the change package template.

ReleaseAdaptor appears as a Change Packager step, and automatically examines the project to determine if it is applicable to the current PeopleTools release. For example, it determines whether a project contains Integration Broker content, and, if the PeopleSoft application release is pre-PeopleSoft 9.0. If the project meets these criteria it generates and includes the additional pre-PeopleTools 8.48 Integration Broker elements without any manual intervention. The resulting change package will contain all elements required for consumption by all applicable releases of PeopleTools.

A set of command-line transformation programs enables this processing. Which programs need to be run for a specific release is determined by the TRANSFORM_PROGRAMS.XML file. TRANSFORM_PROGRAMS.XML has two sections:

• a list of <release> tags that map various pillar and release identifiers into <InitialToolsRelease> elements

• and a list of <transform> tags that specify which transforms to apply for each <InitialToolsRelease> element

The TRANSFORM_PROGRAMS.XML file is located in PS_HOME\BIN\CLIENT\WINX86.

The final, consolidated project will contain all required elements for all release targets.

Working With ProjectFilter

ProjectFilter enables you to remove the specified project contents from the specified project.

Use the following syntax:

ProjectFilter [[-PRJ <projectFile> [-TY|-TX <type name[;type name*]>] 
[-N <instance name[;instance name*]>]] | [-TL]] [-LOG <log filepath>] [-?]

Example: ProjectFilter

Entering the following removes record and field type objects from the project C:\PRJ151141.xml, and writes a log file to C:\ProjectFilter151141.log.

ProjectFilter -PRJ C:\PRJ151141.xml -TY Record;Field
-LOG C:\ProjectFilter151141.log

Entering the following lists valid object types, and writes a log file to C:\ProjectFilterObjTypes.log

ProjectFilter -TL -LOG C:\ProjectFilterObjTypes.log
  

Working With ProjectInspector

ProjectInspector enables you to query the contents of projects. It does not require signon and it does not make a database connection. ProjectInspector is designed to be incorporated in automation shell scripts and for ad hoc queries. If can be run against projects created using previous releases of PeopleTools.

Use the following syntax: This has the command line:

ProjectInspector -PRJ <project file> [-TY <type name [‘;’ type name]* >]
[-N <instance name [‘;’ instance name]* >][-L N | C | T][-TL] [?]

Example: ProjectInspector

Entering the following lists the number of subscription PeopleCode and message channel definitions in the project, or a null string if there were none.

ProjectInspector -PRG PRJ8979874.XML -TY SubscriptionPPC ; MessageChannel -T T