PeopleTools 8.55: Change Assistant and Update Manager

PeopleTools 8.55: Change Assistant
and Update Manager
November 2017
PeopleTools 8.55: Change Assistant and Update Manager
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and
disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement
or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute,
exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or
decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you
find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf
of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any
programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial
computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any
operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications. It is
not developed or intended for use in any inherently dangerous applications, including applications that may create a
risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible
to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation
and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous
applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their
respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used
under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD
logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a
registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and
services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an
applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any
loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as
set forth in an applicable agreement between you and Oracle.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://
www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/
topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Contents
Preface: Preface...........................................................................................................................................xi
Understanding the PeopleSoft Online Help and PeopleBooks............................................................. xi
PeopleSoft Hosted Online Help...................................................................................................... xi
Locally Installed Help..................................................................................................................... xi
Downloadable PeopleBook PDF Files............................................................................................xi
Common Help Documentation...................................................................................................... xii
Field and Control Definitions........................................................................................................ xii
Typographical Conventions............................................................................................................xii
ISO Country and Currency Codes................................................................................................xiii
Region and Industry Identifiers.................................................................................................... xiii
Translations and Embedded Help................................................................................................. xiv
Using and Managing the PeopleSoft Online Help.............................................................................. xiv
Change Assistant and Update Manager Related Links....................................................................... xiv
Contact Us.............................................................................................................................................xv
Follow Us.............................................................................................................................................. xv
Part I: Configuring and Working With Change Assistant................................17
Chapter 1: Getting Started with PeopleSoft Change Assistant......................................................19
PeopleSoft Change Assistant Overview.........................................................................................19
Change Assistant Actions........................................................................................................ 19
Installation.......................................................................................................................................20
Quick Start......................................................................................................................................20
PeopleSoft Update Manager (PUM) Enabled Updates........................................................... 21
Applying Individual PeopleSoft Release Patchset (PRP) to PeopleSoft Update Image.......... 22
Traditional (Non-PUM Enabled) Updates...............................................................................23
Application Upgrade................................................................................................................ 23
Other Sources of Information........................................................................................................ 24
Chapter 2: Understanding The Environment Management Framework and PeopleSoft
Change Assistant................................................................................................................................. 25
Environment Management Framework..........................................................................................25
Environment Management Hub...............................................................................................25
Agents.......................................................................................................................................26
Viewer.......................................................................................................................................27
EMF Terminology....................................................................................................................27
Change Assistant............................................................................................................................ 28
Understanding Change Assistant Versions.............................................................................. 29
Maintaining Change Assistant................................................................................................. 29
PeopleSoft Update Manager...........................................................................................................30
Software Update Process................................................................................................................30
PUM Enabled PeopleSoft Systems......................................................................................... 30
Non-PUM Enabled PeopleSoft Systems................................................................................. 33
Software Upgrade Process............................................................................................................. 34
Source and Target Databases......................................................................................................... 34
Change Assistant Databases and Terminology........................................................................35
Chapter 3: Configuring and Running Environment Management Components......................... 37
Configuring the Environment Management Hub...........................................................................37
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
iii
Contents
Running the Environment Management Hub................................................................................ 38
Running the Hub on a Single Server...................................................................................... 38
Running the Hub on Multiple Servers.................................................................................... 38
Configuring an Environment Management Agent.........................................................................40
Configuring Agents With a Secure PS_HOME.............................................................................42
Running an Environment Management Agent...............................................................................42
Running an Agent.................................................................................................................... 42
Starting an Agent in the Background on UNIX......................................................................46
Starting an Agent With PSEMAgent Windows Service..........................................................46
Running the Viewer........................................................................................................................48
Configuring and Starting an Environment Management Agent on z/OS...................................... 48
Integrating with Oracle Configuration Manager............................................................................49
Understanding Oracle Configuration Manager for PeopleSoft............................................... 49
Instrumenting PeopleTools for Configuration Data Collection...............................................49
Chapter 4: Configuring Change Assistant....................................................................................... 53
Setting Up Change Assistant......................................................................................................... 53
Removing PeopleSoft Change Assistant Installations from Previous Releases...................... 54
Removing PeopleSoft Change Assistant Instances in the Current Release.............................54
Installing a New Instance of Change Assistance.................................................................... 54
Updating Existing Instance of Change Assistant.................................................................... 55
Confirming the Path Variable.................................................................................................. 58
Define Environment Identification.......................................................................................... 59
Opening Change Assistant the First Time..................................................................................... 59
Specifying Change Assistant Options..................................................................................... 61
Defining Databases.........................................................................................................................62
Specifying Database Process Scheduler Settings.................................................................... 68
Specifying PeopleSoft Test Framework Settings.................................................................... 69
Chapter 5: Working With Change Assistant................................................................................... 71
Understanding The Change Assistant Interface.............................................................................71
Working With Change Assistant Menu Options............................................................................73
Exporting and Importing Change Assistant Settings..................................................................... 79
Exporting Change Assistant Setting in Change Assistant.......................................................81
Importing Change Assistant Setting in Change Assistant.......................................................82
Migrating PUM Data......................................................................................................................86
Using PUM Data Migration Page........................................................................................... 88
Working with Change Assistant Templates and Jobs.................................................................... 90
Creating New Template Elements........................................................................................... 91
Deleting Template Elements.................................................................................................... 92
Exporting Templates................................................................................................................ 92
Exporting Jobs to XML, HTML, or Microsoft Excel Format.................................................93
Working with Steps........................................................................................................................ 93
Setting Step Properties.............................................................................................................93
Setting Filter Queries...............................................................................................................99
Viewing Step Status.................................................................................................................99
Adding Filter Queries...................................................................................................................100
Creating Filter Query Step Type........................................................................................... 100
Defining Filter Queries.......................................................................................................... 102
Assigning Filter Query to a Step...........................................................................................104
Cutting and Pasting Filter Queries........................................................................................ 106
Creating and Executing Jobs that Include Filter Queries......................................................106
Working with Embedded Documentation.................................................................................... 107
iv
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Contents
Setting the Documentation Directory.................................................................................... 107
Viewing the Documentation.................................................................................................. 108
Creating and Editing Documentation.................................................................................... 108
Finalizing Documentation......................................................................................................108
Maintaining Change Assistant Directories...................................................................................108
Running Change Assistant Job from the Command Line........................................................... 109
Update Manager Mode.......................................................................................................... 109
Traditional Apply Updates Mode (non-PUM enabled)......................................................... 121
Using a Configuration File with Change Assistant.bat......................................................... 123
Part II: Using Change Assistant with PeopleSoft Update Manager...............125
Chapter 6: Understanding Update Manager Action..................................................................... 127
Update Manager Action Overview.............................................................................................. 127
Understanding Update Tools................................................................................................. 127
Understanding Update Manager Action................................................................................ 130
Chapter 7: Setting Up the Client, Source, and Target Environments......................................... 133
Installing PeopleSoft Update Image.............................................................................................133
Configuring the Microsoft Windows Client Running Change Assistant..................................... 133
Configuring the Microsoft Windows Client Configuration...................................................135
Understanding the Microsoft Windows Client Configuration...............................................136
Example Target Environment on Oracle Database PeopleTools Release 8.53...................... 139
Example Target Environment on Oracle Database PeopleTools Release 8.54...................... 140
Example Target Environment on Oracle Database................................................................141
Example Target Environment Not on Oracle Database........................................................ 142
Chapter 8: Using Update Manager Action.....................................................................................145
Selecting Update Manager Action............................................................................................... 145
Setting Up Target Environment............................................................................................. 145
Starting Change Assistant......................................................................................................146
Configuring Change Assistant for Update Manager............................................................. 146
Select Task............................................................................................................................. 153
Validating Change Assistant EMF Settings...........................................................................155
Defining Target Database............................................................................................................. 156
PS Home................................................................................................................................ 156
PS App Home........................................................................................................................ 157
PS Cust Home........................................................................................................................157
Uploading Target Database Information...................................................................................... 157
Defining a New Change Package................................................................................................ 159
Chapter 9: Using Update Manager Dashboard............................................................................. 161
Update Manager Dashboard Overview........................................................................................161
Using PeopleSoft Update Manager (PUM) Analytics................................................................. 162
BUGs by Target Database..................................................................................................... 163
BUG Status by Product......................................................................................................... 164
BUG Status by Tag................................................................................................................165
BUG Status by Image............................................................................................................166
Bug Detail Spreadsheet..........................................................................................................167
Modified Object List for a Bug.............................................................................................168
Defining Change Package............................................................................................................ 169
Using Update Manager Utilities.................................................................................................. 169
Reviewing Change Package...................................................................................................170
Deleting Change Packages.....................................................................................................172
About PeopleSoft Image........................................................................................................173
Chapter 10: Managing Customization Repository........................................................................ 175
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
v
Contents
Understanding Customization Repository....................................................................................175
Creating Customization Repository............................................................................................. 175
Uploading Customer Data to Image......................................................................................176
Using Customization Repository..................................................................................................177
Customization Repository......................................................................................................177
Manage Customized Objects................................................................................................. 178
Run Customization Calculation............................................................................................. 180
Chapter 11: Managing Test Repository.......................................................................................... 183
Understanding Test Repository.................................................................................................... 183
Creating Test Repository.............................................................................................................. 183
Uploading Customer Data to Image......................................................................................184
Using the Test Repository............................................................................................................ 185
Manage Tests..........................................................................................................................185
Managing Test Objects.......................................................................................................... 186
Running Test Coverage Report..............................................................................................188
Chapter 12: Using PeopleSoft Update Manager PIA Applications..............................................191
Defining Custom Change Packages............................................................................................. 191
Define Change Package Wizard Step 1 of 6.........................................................................192
Define Change Package Wizard Step 2 of 6.........................................................................193
Define Change Package Wizard Step 3 of 6.........................................................................195
Selecting All Other Search Criteria.......................................................................................196
Selecting Specific Updates.................................................................................................... 197
Selecting Updates by Prod/Severity/Image........................................................................... 198
Selecting Specific Objects..................................................................................................... 201
Selecting Tax Updates........................................................................................................... 202
Selecting New Features......................................................................................................... 203
Selecting Other Criteria......................................................................................................... 204
Using Advanced Options Page..............................................................................................205
Using the Selection Grid....................................................................................................... 206
Define Change Package Wizard Step 5 of 6.........................................................................207
Define Change Package Wizard Step 6 of 6.........................................................................211
Chapter 13: Applying Custom Change Packages.......................................................................... 213
Packaging Updates....................................................................................................................... 213
Applying Change Package........................................................................................................... 215
Understanding the Apply Update Process.............................................................................215
Applying the Change Package...............................................................................................216
Reviewing the Change Assistant Job...........................................................................................219
Understanding Job Naming Conventions.............................................................................. 219
Understanding Job Filtering...................................................................................................220
Running Change Assistant Job..............................................................................................220
Updating Package for Subsequent Passes............................................................................. 221
Moving to Production...................................................................................................................222
Chapter 14: Applying PeopleSoft Release Patchset to PeopleSoft Image................................... 225
Applying Downloaded PeopleSoft Release Patchset to PeopleSoft Image................................. 225
Discovering and Downloading the PRP................................................................................226
Applying the PRP to the PeopleSoft Image.......................................................................... 226
Applying the PRP to Target Database...................................................................................227
Chapter 15: Applying PeopleTools Patch....................................................................................... 229
Using Change Assistant to Apply PeopleTools Patch................................................................. 229
Understanding PeopleTools Patch......................................................................................... 229
Locating and Downloading PeopleTools Patch.....................................................................229
vi
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Contents
Locating and Downloading PeopleTools Patch VCD........................................................... 230
Installing the Patch................................................................................................................ 230
Installing a New PeopleTools Patch Version of Change Assistant........................................230
Configuring Change Assistant for Applying a PeopleTools Patch........................................231
Applying the PeopleTools Patch Change Package................................................................231
Chapter 16: Upgrading PeopleTools................................................................................................233
Using Change Assistant to Upgrade PeopleTools....................................................................... 233
Understanding PeopleTools Upgrade.................................................................................... 233
Configuring Change Assistant for PeopleTools Upgrade......................................................234
Configuring Change Assistant for Update Manager – Upgrade to a New Release of
PeopleTools............................................................................................................................ 235
Upgrading to a New Release of PeopleTools........................................................................240
Creating and Applying Tools Delta Package...............................................................................243
Defining the PUM Source and EM Hub............................................................................... 244
Creating the Tools Delta Package......................................................................................... 245
Applying Tools Delta Change Package.................................................................................246
Chapter 17: Defining and Applying Translations Fixes................................................................247
Understanding Translation Fix Packs.......................................................................................... 247
Defining Translations Delta Package........................................................................................... 247
Define Translations Delta Package Wizard Step 2 of 6........................................................ 248
Define Translations Delta Package Wizard Step 3 of 6........................................................ 249
Define Translations Delta Package Step 5 of 6.....................................................................249
Define Translations Delta Package Wizard Step 6 of 6........................................................ 250
Creating Translations Delta Package.....................................................................................251
Applying Translations Delta Package.......................................................................................... 252
Part III: Using Change Assistant with Non-PUM Enabled Systems..............257
Chapter 18: Using Apply Update Action........................................................................................259
Discovering Updates Using My Oracle Support......................................................................... 259
Downloading Updates From My Oracle Support........................................................................ 259
Downloading a Single Patch................................................................................................. 259
Downloading Multiple Patches From My Oracle Support....................................................259
Using WGET Options............................................................................................................260
Reviewing the Updates Change Log........................................................................................... 260
Configuring Change Assistant for Apply Updates Action.......................................................... 261
Selecting Apply Updates Action........................................................................................... 261
Validating Change Assistant Settings...........................................................................................267
Working with Templates.............................................................................................................. 268
Setting the Documentation Directory...........................................................................................269
Applying Updates To A Target Environment.............................................................................. 269
Apply Without Compare........................................................................................................271
Apply With Compare or Copy.............................................................................................. 274
Automatically Deploying Files to Different Servers.............................................................275
Resuming Running Jobs........................................................................................................ 275
Part IV: Working With Change Packages (Traditional Updates Only)......... 277
Chapter 19: Working with Change Packages (Traditional Update Only)...................................279
Understanding Change Packages................................................................................................. 279
Creating a Change Project........................................................................................................... 280
Setting Project Properties for a Change Package.................................................................. 280
Defining the File Type Code................................................................................................. 281
Creating a File Reference Definition.....................................................................................281
Modifying the Upgrade Definition Type...............................................................................283
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
vii
Contents
Creating Change Packages........................................................................................................... 284
Creating a Change Package................................................................................................... 285
Modifying the Change Assistant Template........................................................................... 287
Finalizing a Change Package.................................................................................................287
Working With Change Package Automation............................................................................... 288
Understanding Change Package Automation........................................................................ 288
Working with ReleaseAdaptor...............................................................................................288
Working With ProjectFilter....................................................................................................289
Working With ProjectInspector............................................................................................. 290
Part V: Using Change Assistant for Software Upgrades................................. 291
Chapter 20: Getting Started with Software Upgrades.................................................................. 293
Understanding Change Assistant For Upgrades.......................................................................... 293
Databases Used for Application Upgrade............................................................................. 293
Getting Started....................................................................................................................... 294
Chapter 21: Configuring Change Assistant for Upgrades............................................................295
Defining an Upgrade Package......................................................................................................295
Selecting the Target Database................................................................................................296
Define Upgrade Package Step 2 of 6.................................................................................... 296
Define Upgrade Package Step 3 of 6.................................................................................... 297
Define Upgrade Package Step 5 of 6.................................................................................... 298
Define Upgrade Package Step 6 of 6.................................................................................... 298
Creating Upgrade Package.....................................................................................................299
Configuring Change Assistant for Upgrade Application............................................................. 300
Setting Change Assistant Options......................................................................................... 301
Upgrading Application................................................................................................................. 304
Change Package Settings....................................................................................................... 305
Select Upgrade Target Database............................................................................................306
Select Upgrade Source Database...........................................................................................307
Select Application Upgrade................................................................................................... 308
Check Compatibility Page..................................................................................................... 309
Chapter 22: Running Upgrade Jobs with Change Assistant........................................................ 313
Running the Upgrade Job.............................................................................................................313
Viewing Upgrade Logs.................................................................................................................314
Viewing Scripts.............................................................................................................................315
Modifying Job Properties............................................................................................................. 315
Running Process Scheduler Steps................................................................................................ 315
Determining When to Run Process Scheduler Steps............................................................ 316
Preparing to Run Process Scheduler Steps............................................................................316
Working With Process Scheduler Steps................................................................................ 316
Ensuring Process Scheduler Security Authentication............................................................317
Chapter 23: Using Data Conversion Utilities................................................................................. 319
Understanding Data Conversion Utilities.................................................................................... 319
Using the PTIA Data Conversion Process............................................................................ 319
Understanding the PTIA Data Conversion Process...............................................................319
Reviewing PTIA Initial Analysis.......................................................................................... 320
Reviewing Dependency Analysis.......................................................................................... 334
Reviewing Runtime for PTIADATACONV.......................................................................... 335
Reviewing PTIA Reporting................................................................................................... 336
Using the Upgrade Driver Program............................................................................................. 339
Defining an Upgrade Path..................................................................................................... 339
Accessing the Define Data Conversion Page........................................................................340
viii
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Contents
Part VI: Comparing and Merging.....................................................................345
Chapter 24: Using Review Managed Object or Merge Select Object Types Action...................347
Comparing and Copying Managed Objects Overview................................................................ 347
Administering Projects................................................................................................................. 347
Viewing Managed Object Compare Reports......................................................................... 348
Viewing Projects.................................................................................................................... 350
Working With Project Administration Menu Options................................................................. 351
Comparing Definitions................................................................................................................. 352
Copying Definitions..................................................................................................................... 353
Validating Projects........................................................................................................................354
Understanding Merging PeopleCode, SQL, XSLT Programs......................................................354
Beginning a New Merge Session.................................................................................................354
Selecting Merge Databases.................................................................................................... 355
Defining Merge Rules............................................................................................................355
Using the Merge Interface............................................................................................................356
Appendix A: Working With Scripts...................................................................................................... 361
Understanding Process, Scripts, and Syntax...................................................................................... 361
Running Scripts Outside of Change Assistant................................................................................... 361
Appendix B: Modifying Step Properties and Parameters................................................................... 363
Step Types........................................................................................................................................... 363
Setting AE With Run Control Options for ADS Compare/Copy................................................ 369
Setting SQR Report Output Options............................................................................................371
Step Parameters...................................................................................................................................372
Variables for All Step Types that Use Path................................................................................. 375
Filter Query Variables.................................................................................................................. 376
Platform Used in Command Line................................................................................................ 376
Appendix C: Clearing Environment Management Framework Cache..............................................379
Clearing Environment Management Framework Cache Overview....................................................379
When to Clear Environment Management Framework Cache...........................................................379
Clearing EMF Cache.......................................................................................................................... 380
Appendix D: Troubleshooting Change Assistant and EMF................................................................ 383
Peer Cannot Connect to the Hub........................................................................................................383
Servlet Request Processor Exception................................................................................................. 385
Error Initializing Agent.......................................................................................................................385
Distributed Object Manager Errors.................................................................................................... 386
Cloned Databases Not Being Unique.................................................................................................386
Large SQL Scripts Fail on Microsoft SQL Server.............................................................................386
Process Scheduler Logs Retrieved Using FTP Losing Formatting.................................................... 386
Viewing Change Assistant Log Files................................................................................................. 386
Errors Found in Log Files.................................................................................................................. 390
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
ix
Contents
x
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Preface
Understanding the PeopleSoft Online Help and PeopleBooks
The PeopleSoft Online Help is a website that enables you to view all help content for PeopleSoft
Applications and PeopleTools. The help provides standard navigation and full-text searching, as well as
context-sensitive online help for PeopleSoft users.
PeopleSoft Hosted Online Help
You access the PeopleSoft Online Help on Oracle’s PeopleSoft Hosted Online Help website, which
enables you to access the full help website and context-sensitive help directly from an Oracle hosted
server. The hosted online help is updated on a regular schedule, ensuring that you have access to the
most current documentation. This reduces the need to view separate documentation posts for application
maintenance on My Oracle Support, because that documentation is now incorporated into the hosted
website content. The Hosted Online Help website is available in English only.
Note: Only the most current release of hosted online help is updated regularly. After a new release is
posted, previous releases remain available but are no longer updated.
Locally Installed Help
If your organization has firewall restrictions that prevent you from using the Hosted Online Help
website, you can install the PeopleSoft Online Help locally. If you install the help locally, you have more
control over which documents users can access and you can include links to your organization’s custom
documentation on help pages.
In addition, if you locally install the PeopleSoft Online Help, you can use any search engine for fulltext searching. Your installation documentation includes instructions about how to set up Oracle Secure
Enterprise Search for full-text searching. See PeopleTools Installation for your database platform,
“Installing PeopleSoft Online Help.” If you do not use Secure Enterprise Search, see the documentation
for your chosen search engine.
Note: Beginning with PeopleSoft PeopleTools 8.55.11, you can use Elasticsearch as the search engine for
locally installed PeopleSoft Online Help.
See Oracle Support Document 2189508.1 (PeopleTools 8.55.11 Elasticsearch Documentation Home
Page) for more information on using Elasticsearch with PeopleSoft.
Note: Before users can access the search engine on a locally installed help website, you must enable the
Search field. For instructions, select About This Help, Managing Locally Installed PeopleSoft Online
Help, Enabling the Search Button and Field in the Contents sidebar of the online help site.
Downloadable PeopleBook PDF Files
You can access downloadable PDF versions of the help content in the traditional PeopleBook format.
The content in the PeopleBook PDFs is the same as the content in the PeopleSoft Online Help, but it has
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
xi
Preface
a different structure and it does not include the interactive navigation features that are available in the
online help.
Common Help Documentation
Common help documentation contains information that applies to multiple applications. The two main
types of common help are:
•
Application Fundamentals
•
Using PeopleSoft Applications
Most product families provide a set of application fundamentals help topics that discuss essential
information about the setup and design of your system. This information applies to many or all
applications in the PeopleSoft product family. Whether you are implementing a single application, some
combination of applications within the product family, or the entire product family, you should be familiar
with the contents of the appropriate application fundamentals help. They provide the starting points for
fundamental implementation tasks.
In addition, the PeopleTools: Applications User's Guide introduces you to the various elements of the
PeopleSoft Pure Internet Architecture. It also explains how to use the navigational hierarchy, components,
and pages to perform basic functions as you navigate through the system. While your application or
implementation may differ, the topics in this user’s guide provide general information about using
PeopleSoft Applications.
Field and Control Definitions
PeopleSoft documentation includes definitions for most fields and controls that appear on application
pages. These definitions describe how to use a field or control, where populated values come from, the
effects of selecting certain values, and so on. If a field or control is not defined, then it either requires
no additional explanation or is documented in a common elements section earlier in the documentation.
For example, the Date field rarely requires additional explanation and may not be defined in the
documentation for some pages.
Typographical Conventions
The following table describes the typographical conventions that are used in the online help.
xii
Typographical Convention
Description
Key+Key
Indicates a key combination action. For example, a plus sign (
+) between keys means that you must hold down the first key
while you press the second key. For Alt+W, hold down the Alt
key while you press the W key.
. . . (ellipses)
Indicate that the preceding item or series can be repeated any
number of times in PeopleCode syntax.
{ } (curly braces)
Indicate a choice between two options in PeopleCode syntax.
Options are separated by a pipe ( | ).
[ ] (square brackets)
Indicate optional items in PeopleCode syntax.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Preface
Typographical Convention
Description
& (ampersand)
When placed before a parameter in PeopleCode syntax,
an ampersand indicates that the parameter is an already
instantiated object.
Ampersands also precede all PeopleCode variables.
⇒
This continuation character has been inserted at the end of a
line of code that has been wrapped at the page margin. The
code should be viewed or entered as a single, continuous line
of code without the continuation character.
ISO Country and Currency Codes
PeopleSoft Online Help topics use International Organization for Standardization (ISO) country and
currency codes to identify country-specific information and monetary amounts.
ISO country codes may appear as country identifiers, and ISO currency codes may appear as currency
identifiers in your PeopleSoft documentation. Reference to an ISO country code in your documentation
does not imply that your application includes every ISO country code. The following example is a
country-specific heading: "(FRA) Hiring an Employee."
The PeopleSoft Currency Code table (CURRENCY_CD_TBL) contains sample currency code data. The
Currency Code table is based on ISO Standard 4217, "Codes for the representation of currencies," and
also relies on ISO country codes in the Country table (COUNTRY_TBL). The navigation to the pages
where you maintain currency code and country information depends on which PeopleSoft applications
you are using. To access the pages for maintaining the Currency Code and Country tables, consult the
online help for your applications for more information.
Region and Industry Identifiers
Information that applies only to a specific region or industry is preceded by a standard identifier in
parentheses. This identifier typically appears at the beginning of a section heading, but it may also appear
at the beginning of a note or other text.
Example of a region-specific heading: "(Latin America) Setting Up Depreciation"
Region Identifiers
Regions are identified by the region name. The following region identifiers may appear in the PeopleSoft
Online Help:
•
Asia Pacific
•
Europe
•
Latin America
•
North America
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
xiii
Preface
Industry Identifiers
Industries are identified by the industry name or by an abbreviation for that industry. The following
industry identifiers may appear in the PeopleSoft Online Help:
•
USF (U.S. Federal)
•
E&G (Education and Government)
Translations and Embedded Help
PeopleSoft 9.2 software applications include translated embedded help. With the 9.2 release, PeopleSoft
aligns with the other Oracle applications by focusing our translation efforts on embedded help. We
are not planning to translate our traditional online help and PeopleBooks documentation. Instead we
offer very direct translated help at crucial spots within our application through our embedded help
widgets. Additionally, we have a one-to-one mapping of application and help translations, meaning that
the software and embedded help translation footprint is identical—something we were never able to
accomplish in the past.
Using and Managing the PeopleSoft Online Help
Click the Help link in the universal navigation header of any page in the PeopleSoft Online Help to see
information on the following topics:
•
What’s new in the PeopleSoft Online Help.
•
PeopleSoft Online Help accessibility.
•
Accessing, navigating, and searching the PeopleSoft Online Help.
•
Managing a locally installed PeopleSoft Online Help website.
Change Assistant and Update Manager Related Links
Hosted PeopleSoft Online Help
PeopleSoft Information Portal
My Oracle Support
Oracle University
PeopleSoft Video Feature Overviews
Patches&Updates
PeopleSoft Update Manager Home Page [ID 1641843.2]
Upgrading PeopleSoft? Start Here. [ID 1587686.2]
xiv
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Preface
Contact Us
Send your suggestions to PSOFT-INFODEV_US@ORACLE.COM. Please include release numbers for
the PeopleTools and applications that you are using.
Follow Us
Facebook.
YouTube
Twitter@PeopleSoft_Info.
PeopleSoft Blogs
LinkedIn
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
xv
Part I
Configuring and Working With Change
Assistant
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
17
Configuring and Working With Change Assistant
18
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 1
Getting Started with PeopleSoft Change
Assistant
PeopleSoft Change Assistant Overview
Oracle's PeopleSoft Change Assistant is a standalone, Windows based, Java program that orchestrates the
process of updating or upgrading your PeopleSoft system. Environment Management Framework is used
for non-PUM-enabled updates and for deploying files with Update Manager.
Change Assistant provides these main benefits:
•
Automates many of the steps in an upgrade or update process.
•
Provides a clear step-by-step definition of the process for applying maintenance or performing an
upgrade. Whether the process is automated or manual, as long as you complete each step, you will
successfully apply the application maintenance or perform the upgrade.
•
Provides in-line documentation for each of the steps in the process.
•
Is integrated with the PUM application and uses the change package definitions created in the
PeopleSoft Update Image.
The Environment Management Framework performs these key tasks:
•
Crawls local drives and directory paths to discover and validate the components associated with a
given PeopleSoft environment.
•
Deploys files to various components in the PeopleSoft environment.
Related Links
Environment Management Framework
Change Assistant Actions
Change Assistant supports the following actions:
Apply Updates
Any systems that are not Update Manager enabled will use the
Apply Updates to apply updates downloaded from My Oracle
Support.
Update Manager
Update Manager contains 3 sets of tasks:
•
Update Manager Tasks
Update Manager is used for application patching and
updates for PeopleSoft PUM-enabled applications(all 9.2
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
19
Getting Started with PeopleSoft Change Assistant
Chapter 1
applications and Interaction Hub 9.1). This option allows
you to select the updates from the PeopleSoft Update Image
and create a custom change package that includes only the
updates and any calculated requisites you want to apply to
your application.
•
Application Upgrade Tasks
Application Upgrade is used to perform an upgrade to 9.2
application release.
•
PeopleTools Tasks
PeopleTools tasks include applying the database changes
required with PeopleTools patches, PeopleTools upgrades
and PeopleTools delta packages.
Review Managed Object or Merge
Select Object Types
Provides the ability to copy and compare Managed Object
projects in Change Assistant. You also have the ability to view
and merge PeopleCode, SQL and XSLT.
Create or Modify Templates
Change Assistant templates are composites of all the possible
steps that apply to an update or upgrade. The templates are
delivered as part of the change package or upgrade. Once you
select a change package or upgrade, the template is loaded into
the Change Assistant internal storage. You can edit the template
or add additional chapters, tasks and steps, if needed.
Installation
Prior to using Change Assistant the following items must be in place:
Step
Reference
Install PeopleTools, database client software and any database
client connect information.
PeopleTools Installation for your platform
Install your PeopleSoft application
Your PeopleSoft application installation guide
Install Change Assistant
PeopleTools Installation for your platform : Installing
PeopleSoft Change Assistant
Quick Start
The following items provide a quick start reference for the main steps and concepts related to the
implementation and use of Change Assistant. This list is designed to help get you up and running with
Change Assistant as well as to help you to understand the main functions for which Change Assistant was
designed.
20
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 1
Getting Started with PeopleSoft Change Assistant
PeopleSoft Update Manager (PUM) Enabled Updates
The steps appear in the logical order that you would perform them, and the links point to the location
where the information for a specific task is provided. PUM enabled applications include all 9.2
applications and Interaction Hub 9.1
Image: PUM Environment
This diagram illustrates the PUM environment which includes the PeopleSoft Update Image, the target
environment and the windows client.
Note: If the target environment is Oracle database on PeopleTools 8.53 or 8.54, the configuration will be
the same as the target on a non-Oracle database.
Step
Reference
1. Use My Oracle Support (MOS) to find the current
PeopleSoft Update Image and download it.
See PeopleSoft Update Manager Home Page [ID 1641843.2]
2. Install the PeopleSoft Update Image.
See PeopleSoft Deployment Packages Installation (PeopleSoft
PeopleTools 8.55).
Note: The PeopleSoft Update Image may be at a different
release/patch level than your target environments.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
21
Getting Started with PeopleSoft Change Assistant
Chapter 1
Step
Reference
3. (Optional) Configure and start the PSEMAgent on every
server within your PeopleSoft target environment.
See Configuring an Environment Management Agent.
Note: EMF is only run on the target environments not on the
PeopleSoft Update Image.
EM Hub is only used for file deploy in PUM-enabled
applications.
4. Map your Windows client to the PeopleSoft Update Image
shared drives. Mapping can be done using the PeopleSoft
Update Image IP address.
See Configuring the Microsoft Windows Client Running
Change Assistant
Note: The IP address can be identified using the ifconfig Linux
command on the VirtualBox.
5. Configure Microsoft Windows client running Change
Assistant.
See Configuring the Microsoft Windows Client Running
Change Assistant
6. Install Change Assistant on Windows client from the PS
Home at the same release/patch level as the PeopleSoft Update
Image.
See Installing a New Instance of Change Assistance
7. Start Change Assistant. Click Next on Welcome page, then
select Update Manager action.
See Selecting Update Manager Action
8. In Change Assistant, select Update Manager > Define or
Create a New Change Package.
See Defining a New Change Package
The Change Assistant Wizard will lead you through the setup
pages.
14. Use PeopleSoft Update Manager PIA application in the
PeopleSoft Update Image environment to search for updates
you need, review the update impact, and define your custom
change package.
See Defining Custom Change Packages
15. Use Change Assistant to create the change package from
See Packaging Updates.
your custom change package definition created with PeopleSoft
Update Manager PIA application, analyze the change impact,
and apply the updates.
Note: Use the PeopleSoft Update Image Home Pages tab from the PeopleSoft Update Manager Home
Page [ID 1641843.2] to access the PeopleSoft Update Image for your application. The Update Image
Home page for your application will contain links to all the relevant information for the PeopleSoft
Update Image you are downloading. The Installation Documentation section on the page contains a link
to PeopleSoft Deployment Packages Installation (PeopleSoft PeopleTools 8.55).
Applying Individual PeopleSoft Release Patchset (PRP) to PeopleSoft
Update Image
The steps appear in the logical order that you would perform them, and the links point to the location
where the information for a specific item exists within this PeopleBook.
22
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 1
Getting Started with PeopleSoft Change Assistant
Step
Reference
1. Search MOS for the PRP.
See PeopleSoft Update Manager Home Page [ID 1641843.2]
2. Download the PRP to a local directory.
See Applying Downloaded PeopleSoft Release Patchset to
PeopleSoft Image
3. Apply the PRP to the PeopleSoft Update Image using
See Applying Downloaded PeopleSoft Release Patchset to
Update Manager action Apply Downloaded Individual Posting PeopleSoft Image
to PeopleSoft Update Image.
4. Use the Update Manager process to search for and apply the See PeopleSoft Update Manager (PUM) Enabled Updates
new individual fix to your target databases.
Traditional (Non-PUM Enabled) Updates
The steps appear in the logical order that you would perform them, and the links point to the location
where the information for a specific item exists within this PeopleBook.
Step
Reference
1. Configure and start the PSEMHUB within your PeopleSoft
environment.
See Configuring the Environment Management Hub.
2. Configure and start the PSEMAgent on every server within
your PeopleSoft environment.
See Configuring an Environment Management Agent.
3. Install and configure Change Assistant, specifying the proper See Setting Up Change Assistant.
directories for file download and storage, and ensuring it can
connect to the PSEMHUB.
4. Use My Oracle Support (MOS) to identify the bundles and
updates that need to be applied to your specific environment.
See Discovering Updates Using My Oracle Support.
5. Download the required bundles and updates.
See Downloading Updates From My Oracle Support.
6. Use Change Assistant to apply the bundles and updates.
See Applying Updates To A Target Environment.
Application Upgrade
Application Upgrade is only used to upgrade from a previous application release to application release
9.2. The steps appear in the logical order that you would perform them, and the links point to the location
where the information for a specific item exists within this PeopleBook.
Step
Reference
1. Install new PeopleTools release, if necessary.
See PeopleTools 8.55 Installation for your platform
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
23
Getting Started with PeopleSoft Change Assistant
Chapter 1
Step
Reference
2. Use My Oracle Support (MOS) to find the current
PeopleSoft Upgrade Source Image and download it.
See PeopleSoft Upgrade Source Image Home Page (ID:
1552580.1).
Note: Or install the Demo database for the Upgrade Certified
new release from the media pack or CD, available on Oracle
Software Delivery Cloud (classic method).
See PeopleSoft Deployment Packages Installation (PeopleSoft
PeopleTools 8.55).
3. Install the PeopleSoft Upgrade Source Image.
Note: The PeopleSoft Upgrade Source Image may be at a
different release/patch level than your target environments.
4. Use My Oracle Support (MOS) to find the current
PeopleSoft Update Image and download it.
See PeopleSoft Update Manager Home Page [ID 1641843.2]
5. Install the PeopleSoft Update Image.
See PeopleSoft Deployment Packages Installation (PeopleSoft
PeopleTools 8.55).
Note: The PeopleSoft Update Image may be at a different
release/patch level than your target environments.
6. Create an upgrade change package.
See Defining an Upgrade Package
7. Upgrade to new application release.
See Upgrading Application
Other Sources of Information
This section provides information to consider before you begin to use PeopleSoft Change Assistant. In
addition to implementation considerations presented in this section, take advantage of all PeopleSoft
sources of information, including the installation guides, release notes, PeopleBooks, and training courses
and your PeopleSoft application upgrade documentation.
Related Links
Application Designer Developer’s Guide
Lifecycle Management Guide
Change Impact Analyzer
24
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment
Management Framework and PeopleSoft
Change Assistant
Environment Management Framework
Environment Management Framework (EMF) is a collection of software elements that gathers and
publishes PeopleSoft installation, configuration, and update information. It enables you to identify and
view data about PeopleSoft environments. You can use EMF to obtain a snapshot of configuration and
setup information about the file servers, the web servers, the application servers, the individual hosts,
and the PeopleSoft Process Scheduler servers that comprise your PeopleSoft system. EMF also provides
a vehicle to carry out commands remotely on different machines on the network, directed by Change
Assistant, which uses EMF to apply updates to PeopleSoft installations and configurations.
EMF is used with Change Assistant to deploy files contained in an upgrade package. For traditional
updates (non PUM-enabled applications), EMF is required to identify PeopleSoft environments, for all
other Change Assistant actions configuring and running EMF is optional.
EMF consists of the following core elements:
•
The Environment Management hub (PSEMHUB)
•
Environment Management Agent (PSEMAgent)
•
The Environment Management viewer
Environment Management Hub
The Environment Management hub is a web application that is installed with the PeopleSoft Internet
Architecture and portal. It is started along with the rest of the web applications when the user boots the
web server. The hub is the broker for all communication between peers.
The Environment Management hub handles:
•
Peer registration.
The hub registers all of the information that is published by the agents. It also assigns a unique peer
ID for every peer that engages in a dialogue with the hub.
•
Maintenance of configuration information.
The hub handles updates to configuration information, the correlation of information, and the
grouping into environments based on the information that is published by the agents.
•
Agent health monitoring.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
25
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Chapter 2
The hub keeps track of the state or "health" information of the managed components. It shows
whether a peer is still running remotely or not.
•
Message brokering.
The hub services message service requests and responses from peers. The messages can be delivered
to the respective peers even if the peers are not currently running. They are picked up the next time
the peers “call in” to the hub. Typical messages include requests to deploy files to managed servers.
It's recommended that the managed server agents be left up and running at all times to listen for
messages from the hub. This is critical when applying software updates.
The Environment Management hub is installed as part of the standard PeopleSoft Internet Architecture
installation. It supports both single-server and multi-server installations. The Environment Management
hub is deployed in the J2EE containers as web application modules. They can be managed like any of the
standard web application modules.
The following Environment Management hub directories are created on the J2EE container for the hub:
•
With Oracle WebLogic:
PIA_HOME\webserv\domain\applications\peoplesoft\PSEMHUB
•
With IBM WebSphere:
PIA_HOME\webserv\server\installedApps\domainNodeCell/domain.ear\PSEMHUB.war
The required JAR files for the Environment Management hub are installed in the WEB-INF\lib
subdirectory.
Agents
An Environment Management agent is a Java executable installed on the servers in a PeopleSoft
environment, such as application servers, Process Scheduler servers, web servers, and so on. The
Environment Management agent initiates communication with the hub and is assigned a unique peer ID.
This ID persists and is reused for later connections by the agent.
The primary function of the agent is crawling the managed servers to identify manageable components.
The metadata of the search results of the crawling are saved to the local hard disk. On startup, if the agent
detects missing metadata, it recrawls the hard disk for manageable components. You can configure the
drives and directory paths used for crawling.
The agent also publishes managed server information to the hub. After detecting a manageable
component, the agent reads the non-sensitive information from configuration files of the component.
Some relevant information that is related to environment and patch levels is also fetched from the
database with which the application server or Process Scheduler communicates. The agent publishes this
information to the hub upon initial connection and upon a recrawl or revalidate.
The agent also determines heartbeat and command execution. On every heartbeat, the agent pings the
server to determine whether it has any pending messages. If there are pending messages for the agent, the
messages are retrieved from the hub and carried out locally on the agent machine.
26
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Note: You install the Environment Management agent by running the PeopleTools CD installation. The
Environment Management agent is installed in the PSEMAgent directory in your PS_HOME with the
server installation. If additional components are installed in the same PS_HOME location, the installer
warns you that existing software may be overwritten.
Note: Multiple EM Agents can be run, but they must be run using a different agentport.
See PeopleTools installation documentation for your database platform.
Viewer
The Environment Management viewer is a command-line tool enabling you to view data stored on the
Environment Management hub. This data is saved in an XML file that contains data that is specific to
individual customer sites—such as, information about environments, software updates, hosts, file servers,
application servers, PeopleSoft Process Scheduler servers, and web servers. Users can view this static data
in HTML.
The Environment Management viewer may only be executed on PeopleSoft web servers, from its
installed location in PS_HOME\PSEMViewer. You don't have to carry out any additional installation steps
to install the viewer.
EMF Terminology
The following terms relate to Environment Management:
Manageable component
A component that can be individually managed from the
Environment Management hub. A manageable component for
PeopleSoft is typically a file server, an application server, a
web server, individual hosts, or a PeopleSoft Process Scheduler
server.
Peer
A manageable component that is involved in a transaction with
one or more peers in the Environment Management by using
the hub as the intermediary. A peer may also be responsible
for delegation of management responsibility to a collection of
manageable components. Examples of peers are agents, Change
Assistant, and the Environment Management viewer.
Heartbeat
“I am alive messages” sent by every peer to the hub. The default
interval is configurable. On every heartbeat, the peer pings
the server to see if it has any pending messages. If it does, the
messages are taken and carried out.
Environment
All of the manageable components in the enterprise that share
the same globally unique identifier (GUID) in the database.
There can be more than one instances of a type of managed
component in an environment. For example, development
environments can contain several application servers, Process
Schedulers, and web servers.
GUID
Uniquely identifies a particular PeopleSoft system. PeopleSoft
assigns a unique value, referred to as a GUID, to each
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
27
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Chapter 2
PeopleSoft application installation. This value can't be
customized. When an Environment Management agent notifies
the hub that it has found a manageable component belonging
to an environment, if the GUID of the environment is not
recognized, the hub creates a new environment representation.
Crawling
The process of scanning the hard disk for known PeopleSoft
patterns for manageable components. The hub has a set of
configurable parameters by which the recrawl intervals can be
altered. Based on this, the hub can issue a recrawl command
to the agents to discover information about newly installed or
changed configurations.
Note: During crawling, the Environment Management
Framework uses the psserver property in the peopletools.
properties file within each PS_HOME installation to determine
the type of server(s) installed. For example, APP is application
server, BATCH is Process Scheduler, DB is database server,
WEB is web server, and FILE is file server.
Note: Recrawling includes revalidating.
Revalidate
The process of checking whether the last set of managed
components that have been discovered is still valid. The
agent iterates through the list of components that have been
discovered from the last recrawl. It then checks whether
the current set of configuration parameters for the managed
components have changed the management scope for the
component. If so, the information is updated. If the new set of
configuration options has made the component not usable, it is
removed from the list of managed components. This information
is updated in the hub the next time the agent communicates with
the hub.
Change Assistant
Change Assistant is a standalone application that enables you to assemble and organize the steps
necessary to apply updates and fixes for PeopleSoft application maintenance updates as well as
performing upgrades. Change Assistant automates many of the steps, but will prompt you and guide you
through any manual steps with embedded documentation.
You use Change Assistant for these situations:
28
•
Selecting and applying updates related to PeopleSoft application maintenance. Change packages are
automatically created based on the customers selection of the updates to apply.
•
Performing upgrades, which includes PeopleTools-only upgrades and PeopleSoft application-only
upgrades.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment Management Framework and PeopleSoft Change Assistant
•
Applying database changes for PeopleTools patches.
Note: You use Change Assistant to apply updates that have a .ZIP extension. You do not use Change
Assistant to apply updates that have an .EXE extension.
You can use PeopleSoft Update Manager for select applications releases to search for updates you may
need for your environment and to review the potential impact of the selected changes. PeopleSoft Update
Manager will automatically include requisite updates based on the items you select; it will show you what
has already been applied to your target environment; and, it will let you review the changes included
with each update before selecting it. You can then create a custom change package definition with your
selected updates.
Important! The change package definition created only guarantees the requisites for the specific target
selected. If the same change package is applied to a different target, you may encounter errors or warnings
if the environment is not at the same level as the target specified when the package definition was created.
Understanding Change Assistant Versions
You can use a newer version of Change Assistant than the version of PeopleTools you are using.
However, the environment management agents and hub must be at the same release level as Change
Assistant.
For PUM , your PeopleTools version could be at 8.54.03, but you can run Change Assistant at the 8.54.08
level since the environment management hub and agents are on the same release.
For non PUM-enabled environments, the environment management agents and hub must be at the same
release/patch level as Change Assistant, in order to apply updates. For example, your PeopleTools version
could be at 8.53.09, but you can run Change Assistant at the 8.53.14 level as long as the agents and hub
are also at the 8.53.14 level.
Maintaining Change Assistant
Periodically, Oracle provides patches for PeopleTools that supply fixes to critical defects. With each
PeopleTools patch version, Oracle provides the following updates in executable format:
Executable
Description
version.exe
Contains all current fixes to the entire PeopleTools product,
including those fixes to the software update technology, which
includes Change Assistant and all environment management
elements (agents, hub, and so on).
For example, 85014.exe
version-PSCA.exe
For example, 85014-PSCA.exe
Contains only the current fixes for Change Assistant and all
environment management elements (agents, hub, and so on).
The software update technology runs independently from the
rest of PeopleTools.
Important! This only applies to non PUM_enabled
applications.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
29
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Chapter 2
Note: If you install a complete PeopleTools patch, you do not need to apply the -PSCA patch individually.
Apply the -PSCA patch individually only if you are running non PUM-enabled applications and interested
in just the fixes for the software update tools and not the fixes for the entire PeopleTools product.
The -PSCA patch enables you to apply only the latest fixes to Change Assistant and the environment
management framework without applying the latest full PeopleTools patch. By doing so, you can avoid
the regression testing that typically occurs after applying a full PeopleTools patch.
PeopleSoft Update Manager
PeopleSoft Update Manager (PUM) is a tool which runs on the PeopleSoft Update Image database.
PeopleSoft Update Images (PI) are fully functioning instances of the PeopleSoft environment. There
is one PeopleSoft Update Image per product family (database instance) and they will be released
periodically according to the image schedule posted on the PeopleSoft Update Manager Home Page. The
PeopleSoft Update Image is the master source environment from which you will pull the updated objects,
create a custom change package, and apply updates to your environment. The PeopleSoft Update Image
for your application is cumulative so you will download the most current PeopleSoft Update Image and
get all of the updates that you need.
There are two types of downloads for your PeopleSoft Update Image:
•
VirtualBox: Use this download to deploy the PeopleSoft Update Image using a VirtualBox Virtual
Machine. This is similar to the installation process used with images using PeopleTools 8.53 and 8.54.
•
NativeOS: This download is for Linux and Windows customers. This download allows you to apply
your PeopleSoft Update Image directly to your OS or a virtualization platform without having to use
VirtualBox.
The PeopleSoft Update Manager PIA Application and the PeopleSoft Update Image work together; the
PeopleSoft Update Image contains the updates and the PeopleSoft Update Manager PIA Application
is the searching tool and custom change package definition generator. PeopleSoft Change Assistant
orchestrates the entire process flow. Change Assistant is the tool used to analyze and compare changes,
to apply the changed objects to your environment, to add in your customizations, and to generate custom
change packages.
Software Update Process
The software update process refers to applying updates to your PeopleSoft application. The procedure for
applying updates depends on whether the PeopleSoft application is PUM enabled.
PUM Enabled PeopleSoft Systems
All PeopleSoft updates for a product family are made available on a PeopleSoft Update Image. The
PeopleSoft Update Image is a VirtualBox image that contains the very latest PeopleSoft working
database, applications, managed objects, codeline, and the data and metadata required to use the
PeopleSoft Update Manager. The PeopleSoft Update Image is posted and downloaded from My Oracle
30
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Support (MOS). The schedule for images will be posted in advance on MOS for each PeopleSoft
application database instance.
Software update tools include:
•
Environment Management Framework
Used to collect environment information.
See Running the Environment Management Hub
•
Change Assistant
Used to upload target database information to the PeopleSoft Update Image, create change packages
from the change package definitions created using PeopleSoft Update Manager, and to the apply
change packages to target databases.
See Applying Updates To A Target Environment
•
PeopleSoft Update Manager PIA Application
The Update Manager Dashboard provides a central location for all update tasks including:
•
PUM Analytics
•
Defining Change Packages
Wizards are used to search for updates and create custom change package definitions.
•
Update Manager Utilities
•
Maintaining Customizations Repository
•
Maintaining Test Repository
See Update Manager Dashboard Overview
•
Change Packager
Creates the change package in Change Assistant based on the change package definition created in
PUM.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
31
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Chapter 2
Image: Software Update Process in Change Assistant
This diagram illustrates the Software Update process steps for the initial pass.
Steps Used in Software Update Process
This table lists the steps used to search for and apply updates to your development or target database.
32
Step
Description
1
Download latest PeopleSoft Update Image from MOS. Use Oracle VM VirtualBox Manager to startup
the PeopleSoft Update Image environment.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Step
Description
2
Configure your windows client to access the PeopleSoft Update Image (PI) database.
3
( Optional )Install and configure EMF on the target environment.
4
Install Change Assistant on the windows client.
5
(Optional) Start EMF Agent.
6
Start Change Assistant and configure for Update Manager. This includes defining the PUM Source.
Note: Update Manager action.
7
In Change Assistant, Select Tools, Upload Target Database Information to PUM Source.
8
In Change Assistant, Select Tools, Define or Create a New Change Packages to connect to the
PeopleSoft Update Image and create a change package definition.
Sign on to the PeopleSoft Update Image and use PUM PIA application to search for desired updates,
review potential update impacts and changes, and generate your custom change package definition.
9
In Change Assistant, Select Tools, Apply Change Packages to create the change package and apply it
to your target database.
Use the Initial Pass option to identify your customizations and adjust the project accordingly. Reapply
any customizations as necessary.
10
As part of the initial pass process, Change Assistant will create a new change package with all of your
customizations that can be applied to your other environments, using the Move to Production Pass
option.
Non-PUM Enabled PeopleSoft Systems
This software update process is only used for PeopleSoft systems that are not PeopleSoft Update Manager
enabled. For PUM enabled systems refer to the previous section.
This software update process refers to applying change packages, bundles, and maintenance packs to
your non-PUM enabled PeopleSoft application. For example, PeopleSoft application development teams
periodically post change packages containing fixes to various application elements, such as pages and
PeopleCode programs, that you can download and apply to your PeopleSoft system. You use Change
Assistant to apply software updates.
Step
Description
1
Install and configure Change Assistant and the Environment
Management components.
2
Use My Oracle Support (MOS) to search for updates.
3
Download the Change Packages from MOS.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
33
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Chapter 2
Step
Description
4
After you have downloaded the change packages, you can then
apply them in a batch or individually. If prerequisites or postrequisites are required, they will be included in the list as well.
Software Upgrade Process
The software upgrade process refers to moving from one release level to a newer release. This typically
involves installing a new version of PeopleTools and a new version of an existing PeopleSoft application.
This process uses Change Assistant, and the Environment Management Framework when running
remote upgrade processes. If you are upgrading from one release of a PeopleSoft application to another
application release, also consult your specific application's install and upgrade documentation.
Source and Target Databases
In various places within this PeopleBook, as well as any PeopleSoft documentation related to upgrades or
database compares, the terms source and target are used. Knowing the meanings of these terms helps you
to understand the context of a description or step.
During a PeopleSoft update or upgrade, in most cases, you copy application definitions (such as pages
and records) from a source database to a target database. The definitions of these terms are:
source database
The source database is the database from which the new changes
are coming.
target database
The target database is the database to which you are moving the
new changes.
Note: Depending on whether you are performing an upgrade or update, and the stage within the process
you are, these terms are relative and can refer to different databases.
For example, in a typical upgrade, you install the certified Upgrade Source database, referred to as Demo.
Then, you create a copy of your production database, referred to as Copy of Production. You then copy
the modified definitions from the Demo database into the Copy of Production. In this context, your Demo
database is your source and the Copy of Production is the target. Likewise, after you complete the initial
copy and perform the required compares and tests, you begin a Move to Production pass. In this pass
you take the Copy of Production database and incorporate the modified definitions into the Production
database. In this context, the Copy of Production is your source and the Production database is your
target.
When applying an update using the "Apply with Database Compare/Copy" option, the source database is
the Demo database where the update (change package) has already been applied.
34
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 2
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Change Assistant Databases and Terminology
The database definition will include:
•
Database name
•
Database type
•
Unicode
•
User Ids and passwords
•
SQL query executable
•
Products
Change Assistant will query the database for the products.
•
Languages
Change Assistant will query the database for the languages.
•
•
Paths to the current home directories.
•
PS_HOME
•
PS_APP_HOME
•
PS_CUST_HOME
For PeopleTools upgrades , the database will also include paths to the new home directories.
Paths to Home Directories
The order by which the PeopleTools runtime will pick up objects from the file system is as follows:
1. PS_CUST_HOME
2. PS_APP_HOME
3. PS_HOME
Change Assistant will loop through the paths in order of precedence until it finds the first instance of the
file object at which time it will execute the step.
Databases Used for Each Action
Action
Databases and Paths Used
Apply Update
Target database with path for current environment.
Update Manager
Target database with path for current environment.
Source database (PeopleSoft Update Image ) with path for
current environment.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
35
Understanding The Environment Management Framework and PeopleSoft Change Assistant
Action
Databases and Paths Used
Application Upgrade
PeopleSoft Update Image.
Chapter 2
Certified Upgrade Source Image.
Copy of Production.
Production database.
36
Upgrade PeopleTools
Target database with path for current environment.
Copy/Compare Managed Objects or Merge Selected Object
Types
Multiple databases can be copied, compared and merged.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment
Management Components
Configuring the Environment Management Hub
Before you can run the Environment Management hub, you must ensure that it's properly configured.
The hub issues automatic recrawl and revalidate commands to the agents, and it can be configured to
accept automatic updates from Change Assistant. You configure the hub by setting appropriate parameters
in its configuration file, which is located as follows:
•
WebLogic:
PIA_HOME\webserv\domain\applications\peoplesoft\PSEMHUB\envmetadata\config
\configuration.properties
•
WebSphere:
PIA_HOME\webserv\server\installedApps\domainNodeCell/domain.ear\PSEMHUB.war/
envmetadata/config\configuration.properties
The following table describes the primary configuration.properties parameters for the hub:
Configuration Parameter
Description
Default Value
recrawlinterval
The interval, in hours, between two
successive recrawl commands that have
been issued to a peer. The server issues
recrawl commands only to agents that
are connected to the hub and have no
pending messages in the queue. This
configuration parameter is ignored by the
agent.
24 hours
revalidateinterval
Note: A 0 value means that it will not
recrawl.
Recrawling includes a revalidating.
The maximum time, in hours, between
6 hours
two successive automatic revalidates that
the hub issues.
Note: A 0 value means that it will not
revalidate.
Hub Security Considerations
Environment Management framework does not support HTTPS connections. The agent and hub
communicate using standard HTTP only.
On WebSphere, or for a single server configuration on WebLogic, PSEMHUB is a web application
running within PIA. If PIA is configured to be accessed using HTTPS, you need to configure a separate
server instance for the hub to enable the HTTP connections between agents and hub.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
37
Configuring and Running Environment Management Components
Chapter 3
Configuring Hub Logging
The Environment Management hub logs are located as follows:
•
WebLogic: PIA_HOME\webserv\domain\applications\peoplesoft\PSEMHUB\envmetadata\logs
•
WebSphere: PIA_HOME\webserv\ps1\installedApps\<domain>NodeCell/<domain>.ear
\PSEMHUB.war/envmetadata/logs
Edit the .....\PSEMHUB\envmetadata\config\Logconfig.properties to configure logging for the hub. The
following two Logconfig.properties parameters, which determine the maximum size of each log file, and
the amount of log files rolled over, can be changed:
•
log4j.appender.R.MaxFileSize=1024KB
•
log4j.appender.R.MaxBackupIndex=1"
Running the Environment Management Hub
This section discusses how to:
•
Run the hub on a single server.
•
Run the hub on multiple servers.
Before you run the Environment Management agent, you must first ensure that it's properly configured in
the hub's configuration.properties file.
Running the Hub on a Single Server
On a single server, the PSEMHUB starts within PIA, so use the command you use for your web server to
start PIA.
Running the Hub on Multiple Servers
Environment Management also supports multi-server installs. However, the Environment Management
hub does not support clustering. The Environment Management hub persists metadata into the file system
on the J2EE container. This is not replicated in a clustered environment. You experience erroneous
behavior when you attempt to run the Environment Management hub in a clustered environment.
The Environment Management hub deals with large binary files that Change Assistant sends to the agents
by using the hub as the intermediary dispatcher. This can create significant overhead to a production
system that is running on a multi-server clustered environment. Therefore, PSEMHUB must always run
on separate servers dedicated to the Environment Management hub requests.
Starting PSEMHUB on Multiple Servers on WebLogic
In a multiple server configuration, the PSEMHUB server listens on port 8081, by default.
Use the following steps to start the WebLogic hub:
38
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
1. Configure the Environment Management hub to run on a server that is different from the PeopleSoft
Internet Architecture servers.
2. Configure the reverse proxy to redirect any network traffic with a uniform resource identifier (URI) of
PSEMHUB to the server running the Environment Management hub.
On the machine from which the RPS application runs, access the HttpProxyServlet folder.
Select PSEMHUBHttpProxyServlet and click the Init Params tab. Replace WebLogicHost ,
WebLogicPort with the host and port from which your PSEMHUB server listens.
Note: Save your new configuration.
Use the following commands in sequence to start the Environment Management hub in a multi-server
installation:
...\StartWebLogicAdmin.cmd (start the admin server)
...\StartManagedWebLogic.cmd RPS
...\StartManagedWebLogic.cmd PSEMHUB
Then use the following URL to access PSEMHUB: http://RPS host:RPS port/PSEMHUB/hub.
Note: For a single server install using a reverse proxy, this additional step needs to be performed
in order for the Environment Management hub to be able to process the PSEMHUB requests. You
need to edit: PIA_HOME\webserv\domain\applications\HttpProxyServlet\WEB-INF\web.xml. In the
PSEMHUBHttpProxyServlet section, change the default port from 8001 to 80.
The following is a sample configuration:
- <servlet>
<servlet-name>PSEMHUBHttpProxyServlet</servlet-name>
<servlet-class>weblogic.servlet.proxy.HttpProxyServlet</servlet-class>
- <init-param>
<param-name>WebLogicHost</param-name>
<param-value>localhost</param-value>
</init-param>
- <init-param>
<param-name>WebLogicPort</param-name>
<param-value>80</param-value>
</init-param>
</servlet>
Start the WebSphere Hub on Multiple Servers
If you are using multiple servers, then you need to dedicate one of them to handle PSEMHUB requests.
All PSEMHUB requests should be routed to the same server instance. The following steps show the
configuration changes that are required for this purpose:
1. Edit your reverse proxy's plug-in configuration file (plugin-cfg.xml) then make sure that only one
server is dedicated to PSEMHUB.
2. Remove this line from all other servers: <Uri AffinityCookie="JSESSIONID"
AffinityURLIdentifier="jsessionid" Name="/PSEMHUB/*" />. The server you chose for PSEMHUB
should only service PSEMHUB requests so that it can run independently and can be shut down
without affecting the rest of the system.
3. Restart the reverse proxy using : IBM_proxy_base_directory\bin\apachectl restart.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
39
Configuring and Running Environment Management Components
Chapter 3
4. Restart all the servers. For Windows, the directory is: WebSphere_Appserver_directory\bin
\startServer.bat serverX. For UNIX, the directory is: WebSphere_Appserver_directory/bin/
startServer.sh serverX.
5. Use the following URL to access PSEMHUB http://reverse_proxy_host:reverse_proxy_port/
PSEMHUB/hub.
The reverse proxy's listen port is defined in IBM_reverse_proxy_base_directory\conf\httpd.conf.
Stopping the PSEMHUB on Multiple Servers on WebLogic
In a multiple server environment, target the server which is dedicated to PSEMHUB then execute
PIA_HOME\webserv\domain\stopWebLogic.cmd PSEMHUB on Windows and PS_HOME/
webserv/domain/stopWebLogic.sh PSEMHUB on UNIX. This will only stop the server servicing
PSEMHUB requests. The other servers will still be up processing PIA requests.
The following is a sample XML configuration file for the WebLogic multi-server installation:
1.1 Sample XML configuration file for WebLogic Multiserver installation
<UriGroup Name="default_host_server1_st-lnx06_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSIGW/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSINTERLINKS/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSOL/*" />
</UriGroup>
- <UriGroup Name="default_host_server1_pt-lnx03_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSIGW/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSINTERLINKS/*" />
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSOL/*" />
</UriGroup>
- <UriGroup Name="default_host_server1_pt-ibm15_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/PSEMHUB/*" />
</UriGroup>
Stopping PSEMHUB on Multiple Servers on WebSphere
In a multiple server environment, target the server which is dedicated to PSEMHUB then
execute WebSphere_Appserver_directory\bin\stopServer.bat serverX on Windows and
WebSphere_Appserver_directory/bin/stopServer.sh serverX on UNIX. This will only stop the server
servicing PSEMHUB requests. The other servers will still be up processing PIA requests.
Configuring an Environment Management Agent
Before you can run an environment management agent, you must ensure that it's properly configured. You
configure the agent by making appropriate entries in its configuration.properties file, which is located
under:
PS_HOME\PSEMAgent\envmetadata\config
40
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
The following table describes the configuration.properties parameters for the Environment Management
agent:
Configuration Parameter
Description
Default Value
hubURL
The URL that contains the host name
http://hostname:port/PSEMHUB/hub.
and the port number of the machine on
which the Environment Management hub
is running (inside a J2EE container).
agentport
A port that the agent uses for internal life 5283.
cycle management.
pinginterval
The interval, in milliseconds, between
two successive attempts that the peer
makes to contact the hub. All peers that
access this configuration file have the
same ping interval.
10000 (in milliseconds for the heartbeat).
Note: The minimum required
pinginterval value is 1000.
windowsdrivestocrawl
On Microsoft Windows, the set of local
c: | d:
drives or directory paths where PS_
HOME, PS_CFG_HOME, PS_APP_
Note: Do not leave a trailing '/' or '\'
HOME , and PIA_HOME are located.
character at the end of the path.
Separate the drive letters or directory
paths with spaces and a pipe symbol ( | ).
unixdrivestocrawl
On UNIX, the set of local drives or
directory paths where PS_HOME, PS
_CFG_HOME, and PIA_HOME are
located.
$HOME
Note: Do not leave a trailing '/' or '\'
character at the end of the path.
Note: The environment variable for
PS_APP_HOME should be set in
the application server/batch server
configuration.
chunksize
Only applicable to large files, which may 1048576 (1 MB) (used for large file
be chunked when sent. The chunksize
transfers).
represents the maximum size in bytes of
each chunk.
Configuring Agent Logging
The Environment Management agent's logs are located under PS_HOME\PSEMAgent\envmetadata\logs.
Edit PS_HOME\PSEMAgent\envmetadata\config\Logconfig.properties to configure the logging for the
agent.
The following parameters determine the maximum size of each log file and the amount of log files rolled
over. You can change the values of these parameters.
•
log4j.appender.R.MaxFileSize=1024KB
•
log4j.appender.R.MaxBackupIndex=1"
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
41
Configuring and Running Environment Management Components
Chapter 3
Configuring PS Agent Home
If the environment variable PS_AGENT_HOME is not set, EMF writes to PS_HOME, which restricts
the ability to run multiple agents specific to each application simultaneously on a shared PS_HOME.
This also poses a security concern as users under which the EM Agent runs must have write access to
PS_HOME.
Set the environment variable PS_AGENT_HOME to the directory where you want to write the
environment management metadata. When you launch PSEMAgent, the system will check for the
PS_AGENT_HOME location and copy the necessary files to the PS_AGENT_HOME directory and log
all activity in that directory.
Note: If you are using a Portable PS_HOME, you must set the PS_AGENT_HOME variable to your
Portable PS Home location.
Configuring Agents With a Secure PS_HOME
Change Assistant deploys the updates to the PS_HOME using the agents running on the managed servers.
Therefore, the agent running on a server should have write access to the PS_HOME and its subdirectories.
Note: While specifying the crawl path in configuration.properties, make sure that the decoupled
configuration home (PS_CFG_HOME) is also included.
Related Links
"Working with the Default PS_CFG_HOME" (PeopleTools 8.55: System and Server Administration)
"Securing PS_HOME on UNIX" (PeopleTools 8.55: System and Server Administration)
"Securing PS_HOME on Windows" (PeopleTools 8.55: System and Server Administration)
Running an Environment Management Agent
This section discusses how to:
•
Run an agent.
•
Start an agent automatically in Windows.
Running an Agent
Before you run an Environment Management agent, you must ensure that it's properly configured in the
agent's configuration.properties file.
Starting the Agent
At a command prompt, navigate to PS_HOME\PSEMAgent.
Use one of these scripts to start the Environment Management agent:
•
42
On Microsoft Windows, run PS_HOME\PSEMAgent\StartAgent.bat.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
Note: If you want the agent to start automatically when the machine starts, use the Microsoft
Windows service that's delivered as part of PeopleTools. Or, you can add the script to the startup
applications.
•
On UNIX, run PS_HOME/PSEMAgent/StartAgent.sh.
Note: If you want the Environment Management agent to start automatically on UNIX when the
machine starts, add StartAgent.sh to the login/boot scripts.
The first time an agent starts, it crawls the machine to locate PeopleSoft elements on that machine.
The results of searching the hard disk are saved in the PS_AGENT_HOME\envmetadata\data\searchresults.xml file.
Note: When starting an agent manually from the command prompt or from a script, the command prompt
will continue to stay open, and it is normal to see the output of the periodic heartbeat events ("sending
pulse") in the command prompt as the agent communicates with the hub. By default these "pulses" are
every 10 seconds, except when environment information is being uploaded to the hub. You can configure
the agent to run in the background using the provided Windows service, and on UNIX by using the
nohup command. These options are documented in other sections of this PeopleBook.
Note: Only one Environment Management agent can be started per machine. If an agent is already
started, you may receive error messages indicating that the agent cannot be started because there is
already one running on the machine.
See Starting an Agent in the Background on UNIX.
See Starting an Agent With PSEMAgent Windows Service.
Starting the Agent on a Secure PS_HOME
On Microsoft Windows:
1. Create a new shortcut from the desktop (right-click, New, Shortcut).
2. In the Type the location of the item enter:
<PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>
For example:
c:\ptinstalls\pt851\PSEMAgent\StartAgent.bat -u :bigcompany.com\tsawyer
Where the user specified has write access to PS_HOME.
Note: When you run <PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>, the
%TEMP% directory is used. Both the user that runs the command and the "runas" user need write/
execute access to the %TEMP% directory.
3. Click Next, and enter a name for the shortcut.
4. Use this shortcut to start the agent.
On UNIX:
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
43
Configuring and Running Environment Management Components
Chapter 3
1. Log in as the user who has write access to the PS_HOME.
2. PS_HOME/PSEMAgent/StartAgent.sh.
See "Securing PS_HOME on UNIX" (PeopleTools 8.55: System and Server Administration).
Stopping the Agent
Use one of these scripts to stop the Environment Management agent:
•
On Microsoft Windows, run PS_HOME\PSEMAgent\StopAgent.bat.
•
On UNIX, run PS_HOME/PSEMAgent/StopAgent.sh.
Recrawl
If you install new software components, the running Environment Management agent doesn't
automatically detect them. This is because, to improve performance, the agent doesn't crawl every time it
starts up. Instead it crawls only if the search-results.xml file does not exist.
You can force a recrawl and make the new components manageable by reissuing the StartAgent command
with the recrawl option:
1. Open a new command line window.
2. Change directories to PS_HOME\PSEMAgent.
3. Issue the following command:
StartAgent recrawl
This forces a recrawl and creates a new search-results.xml file. If an agent is already running, it
publishes the results to the hub.
If the running Environment Management agent is connected to the hub constantly, the recrawl interval
occurs every 24 hours by default. If the agent has not been connected to the hub for a few days, the hub
requests the agent to recrawl when the agent contacts the hub the next time.
Note: Recrawling includes revalidating.
Note: The recrawl process assumes the Environment Management agent is running. If it is not running,
you may see error messages in the output. It is recommended that before running a recrawl, you make
sure the agent is running.
Revalidate
If the Environment Management agent does not recognize any of the installed components, the searchresults.xml file may not exist or may contain only an entry for Host. The problem may be that the agent
needs to have permission to read directories as well as execute programs. Grant these permission for the
agent. Also check whether the agent has permission to create a file on the local file system. Finally, check
whether the disk is full. The agent might have no disk space to create a search-results.xml file.
If the hub is not running, you may receive the following error messages in the agent log or console:
•
44
Broken connection - attempting to reconnect.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
•
RemoteException while connecting to server - retrying attempt 1.
•
RemoteException while connecting to server - retrying attempt 2.
•
RemoteException while connecting to server - retrying attempt 3.
Once the Environment Management hub is back up, the agent will successfully connect. There's no
need to stop and restart the agent.
Note: If you are performing a recrawl, you don't need to separately revalidate.
Command-Line Arguments for the Agent
You can run these command-line arguments with the startAgent.bat (or startAgent.sh) script.
Argument
Description
Sample Output
version
Returns the version of the agent.
Version:8.45 Build Number: 109
shutdown
Shuts down a previous instance of the
agent if it is running.
If the agent does not exist:
Shutting down Agent....
Unable to detect a
running agent...
Instance does not exist
If the agent exists:
Shutting down Agent....
Shut down normally
url
Prints the URL of the hub with which the http:// 216.131.222.227:80/PSEMHUB/
agent is configured to communicate.
hub
validate
Validates the current set of managed
components that have been discovered
from the last crawling by the agent.
Not applicable (NA)
recrawl
Recrawls the hard disk to detect new
configurations. Recrawls the detected
database environments to update
database information. The current
search-results.xml file is backed up.
NA
Note: Recrawling includes revalidating.
isrunning
Returns true if an agent is already
running and false if an agent is not
already running.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
NA
45
Configuring and Running Environment Management Components
Chapter 3
Argument
Description
Sample Output
remove
Removes the peer and all its registered
components from the hub.
Removal Completed- PeerID 2 has been
removed.
Removal Failed- PeerID 2 could not be
removed from the hub.
Starting an Agent in the Background on UNIX
Use the UNIX nohup command with the StartAgent.sh script to start an agent automatically and run
in the background. This enables you to avoid having a command prompt open at all times showing the
constant heartbeat of the agent. You can specify an output file to store heartbeat information.
For example,
nohup ./StartAgent.sh > agent_output.log &
Starting an Agent With PSEMAgent Windows Service
You can set an Environment Management agent to start automatically when your Environment
Management machine boots and run in the background. This enables you to avoid having a command
prompt open at all times showing the constant heartbeat of the agent.
For this option, use the PSEMAgent Windows service that's delivered as part of PeopleTools.
Installing the PSEMAgent Service
You install the PSEMAgent service from a command prompt. Copies of the install program are located in
two places:
PS_HOME\bin\client\winx86
PS_HOME\bin\server\winx86
To install the PSEMAgent service:
1. At a command prompt, change to either location of the install program.
2. Enter the following command:
PSEMAgentService /install PS_HOME\PSEMAgent
Where PS_HOME is the PeopleTools installed location.
The PSEMAgent service is now installed, but not started. It's configured by default to start
automatically when the system boots, and to log on using the local system account. You can start it
manually, or wait for the next reboot.
46
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
Note: The PSEMAgent service is configured to start as an automatic service, by default. However,
the Hub must be running prior to the PSEMAgent service attempting to start, or the PSEMAgent
service will not start successfully. It is recommended to set the PSEMAgent service to manual start
in the Windows Services interface. Then, to start the PSEMAgent service, start it manually from the
Services interface.
Starting the PSEMAgent Service
You can start the PSEMAgent service from a command prompt, or from the Windows Services control
panel. The name of the service follows this convention: PeopleSoft Environment Management Agent<release>.
•
To start the PSEMAgent service from a command prompt, use the NET START command. For
example:
NET START "PeopleSoft Environment Management Agent-8.50"
•
To start the PSEMAgent service from the Windows Services control panel:
1. Open the Windows Control Panel, then double-click Administrative Tools, then Services.
2. In the Services control panel, right-click the PeopleSoft Environment Management Agent entry
and select Start.
Stopping the PSEMAgent Service
You can stop the PSEMAgent service from a command prompt, or from the Windows Services control
panel.
•
To stop the PSEMAgent service from a command prompt, use the NET STOP command. For
example:
NET STOP "PeopleSoft Environment Management Agent-8.50"
•
To stop the PSEMAgent service from the Windows Services control panel:
1. Open the Windows control panel, then double-click Administrative Tools, then Services.
2. In the Services control panel, right-click the PeopleSoft Environment Management Agent entry
and select Stop.
Uninstalling the PSEMAgent Service
You uninstall the PSEMAgent service from a command prompt.
To uninstall the PSEMAgent service:
1. At a command prompt, change to either location of the uninstall program.
Copies of the uninstall program are located in two places:
PS_HOME\bin\client\winx86
PS_HOME\bin\server\winx86
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
47
Configuring and Running Environment Management Components
Chapter 3
2. Enter the following command:
PSEMAgentService /uninstall
PSEMAgentService determines if the service is currently started, and automatically stops it before
completing the uninstall operation. You'll see messages reporting on the status of the operation.
Note: If the service is currently stopped, you'll see an error message indicating that it can't be stopped.
Regardless of this, the uninstall operation completes normally.
Running the Viewer
To view data from the Environment Management hub:
1. Run a Java program to connect to the hub and retrieve the information in XML format.
Run the appropriate script for your environment in from PS_HOME\PSEMViewer. You will be
prompted for the web server's listening port.
•
UNIX: ./GetEnvInfo.sh
•
Windows: GetEnvInfo.bat
Note: For security reasons, the Java program connects only to the local host.
2. Open PS_HOME\PSEMViewer\envmetadata\data\viewer.html to view the information in the
generated XML file.
Configuring and Starting an Environment Management Agent on
z/OS
To run an agent on z/OS, you must have installed JRE delivered with PeopleTools on the z/OS machine.
To configure and start the agent on z/OS:
1. Edit the configuration.properties file (PS_HOME/PSEMAgent/envmetadata/config).
2. Edit hubURL and define the hub machine name and hub port.
3. Edit unixdrivestocrawl and set it to the set of directories that need to be crawled.
4. Edit StartAgent.sh.
On the first line, replace PS_HOME with your PS_HOME location.
Edit the last line to point to your JRE location.
5. Edit StopAgent.sh.
On the first line, replace PS_HOME with your PS_HOME location.
48
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
Edit the last line to point to your JRE location.
The default charset on z/OS is EBCDIC. If you wish to view the content of PS_HOME/PSEMAgent/
envmetadata/data/search-results.xml, you need to run the following commands:
cd PS_HOME/PSEMAgent/envmetatda/data
. PS_HOME/psconfig.sh
PS_HOME/bin/psuniconv utf-8 search-results.xml ccsid1047 result.txt
This comment is also true for PS_HOME/PSEMAgent/envmetadata/data/matchers.xml.
You can find a viewable version of the results in result.txt. You can also FTP (binary) these files to a
different machine running a different operating system and view them in any editor.
Integrating with Oracle Configuration Manager
This section contains an overview and discusses how to instrument PeopleTools for Oracle Configuration
Manager data collection.
Understanding Oracle Configuration Manager for PeopleSoft
Oracle Configuration Manager (OCM) is used to collect configuration data from customer environments
and upload that data to a Customer Configuration Repository (CCR) stored and managed by Oracle. OCM
works in tandem with PeopleSoft EMF for collecting configuration data from a PeopleSoft environment.
The OCM data collection agents collect configuration data using the feed provided by the PeopleSoft
EMF agents.
The PSEMAgent has to be running on the instance so that configuration data can be collected. After
crawling the environment, PSEMAgent writes the environment data in XML format (with a .psft
extension) to the PS_HOME/ccr/state directory.
OCM is installed and configured on a PeopleTools environment as part of the application server, Process
Scheduler server, and web server PeopleTools installation. You can also install and configure OCM by
directly downloading the standalone install kit from My Oracle Support.
See PeopleTools Installation for your platform, “Using the PeopleSoft Installer”
Instrumenting PeopleTools for Configuration Data Collection
This section provides an overview of the data collection and discusses:
•
Setting up Integration Broker for OCM.
•
Deploying Services for OCM.
•
Setting up security for OCM.
•
Publishing queries for OCM.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
49
Configuring and Running Environment Management Components
Chapter 3
Understanding PeopleTools Instrumentation for OCM
The optional configuration information collected from a PeopleSoft system for Oracle Configuration
Manager (OCM) are defined as queries and shipped with OCM collectors. The query definitions need
to be instrumented after the installation and configuration of OCM on a PeopleSoft environment. The
instrumentation step publishes the queries that are required to gather configuration information from
a PeopleSoft system using Integration Broker. The queries can be instrumented by a Java program
“psft_qrypub” and are part of the OCM collector. The publishing of queries is a one-time activity
performed after the configuration of CCR collectors.
The Integration Broker services and interfaces used by the publishing engine are:
Service Name
Operation Name
Description
QAS_QRY_SERVICE
QAS_EXECUTEQRYSYNC_OPER
Discovers application type.
QAS_LISTQUERY_OPER
Determines whether data already exists.
QAS_QUERY_DELETE_OPER
Deletes query for republishing.
QAS_SAVE_QUERY_OPER
Saves query definition.
CCR_TREE_ADD_REC
Adds participating records of a query to
QUERY_TREE_CCR.
PT_CCR_QUERY
Setting Up Integration Broker for OCM
Setting up Integration Broker is discussed in the Integration Broker documentation.
When setting up Integration Broker for OCM, make sure that:
•
Your gateway is configured and pointing to the appropriate gateway URL, such as http://
<webserver_machinename>:<httpport>/PSIGW/PeoplesoftListeningConnector.
•
All other connectors are loaded.
•
On the PeopleSoft Node Configuration page you specify the appropriate Gateway Default App.
Server values and PeopleSoft Nodes values.
•
You can ping the node successfully.
•
On the Service Configuration page (PeopleTools, Integration Broker, Service Configuration) that the
target location http://<webserver>:<httpport>/PSIGW/PeopleSoftServiceListeningConnector.
Deploying Services for OCM
To publish QAS services:
1. Select PeopleTools, Integration Broker, Web Services, Provide Web Service.
2. Search and select the QAS_QRY_SERVICE service, and click Next.
3. Select View All to see all operations in the grid.
50
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 3
Configuring and Running Environment Management Components
4. Choose the following operations:
•
QAS_EXECUTEQRYSYNC_OPER
•
QAS_LISTQUERY_OPER
•
QAS_QUERY_DELETE_OPER
•
QAS_SAVE_QUERY_OPER
5. Click Next until the final step and click Finish.
6. Make note of the WSDL URL generated, and open the wsdl in a new browser and make sure it was
generated successfully.
To publish CCR services:
1. Select PeopleTools, Integration Broker, Web Services, Provide Web Service.
2. Search for and select PT_CCR_QUERY, and click Next.
3. Choose the following operation. CCR_TREE_ADD_REC.v1.
4. Click Next until the final step and click Finish.
5. Make note of the WSDL URL generated, and pen the wsdl in a new browser and make sure it was
generated successfully.
To verify permissions for service PT_CCR_QUERY and operation CCR_TREE_ADD_REC:
1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.
2. For search criteria enter: for:
•
Service: PT_CCR_QUERY
•
Service Operation: CCR_TREE_ADD_REC
•
Operation Type: Synchronous
3. Click CCR_TREE_ADD_REC and select Service Operation Security.
4. Make sure that the permission list PTPT1000 has Full Access is set.
Setting Up Security for OCM
This section defines setting up of two user accounts.
User Account
Description
Publisher
Used by the client publisher Java program to publish queries
using Integration Broker.
To set up this user profile, add the CCR Publisher role to the
user profile.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
51
Configuring and Running Environment Management Components
Chapter 3
User Account
Description
PSEMAgent
Used for configuring your application server and Process
Scheduler. PEMAgent uses the same credentials to run the
queries for publishing the configuration information to OCM.
To set up this user profile, add the CCR Execution role to the
user profile.
See "Working With User Profiles" (PeopleTools 8.55: Security Administration).
Publishing Queries
The publisher program can be invoked by running psft_qrypub.bat in <PS_HOME>/ccr/sysman/admin/
util.
52
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Setting Up Change Assistant
Change Assistant runs only on supported Microsoft Windows workstations. Change Assistant is not
automatically installed when you install PeopleTools. You install Change Assistant by running a separate
setup.exe program in:
PS_HOME\setup\PsCA
After installing Change Assistant, you open it by selecting Start, Programs, PeopleSoft Change Assistant
8.5x.xx, Change Assistant.
Note: A new version of Change Assistant is delivered with each PeopleTools patch. After applying a
PeopleTools patch, you must run the setup program again.
Note: The user who runs Change Assistant needs to have Administrator privileges on the Windows
workstation. If you encounter the message “Another instance of Change Assistant is already running”
the first time you try to access Change Assistant, right-click the icon or menu item and select Run as
Administrator.
PeopleSoft Change Assistant installation includes the following features:
•
You can install multiple instances of PeopleSoft Change Assistant from the current release on one
physical machine.
Note: You cannot run more than one instance at a time. That is, you cannot run multiple instances in
parallel.
•
You must remove installations of PeopleSoft Change Assistant from PeopleSoft PeopleTools 8.54
or earlier before installing from the current release. PeopleSoft Change Assistant from PeopleSoft
PeopleTools 8.55 cannot co-exist with that from earlier releases.
•
You must install each PeopleSoft Change Assistant instance in a separate installation location.
•
You can remove or upgrade each PeopleSoft Change Assistant instance separately.
•
When you remove an installation instance, you have the option to save the existing configuration
information in a group of files gathered in a zip archive. You can configure Change Assistant at a later
time by importing the zip file.
Complete installation instructions for Change Assistant appear in your PeopleTools installation guide.
See PeopleTools Installation for your database platform: Installing PeopleSoft Change Assistant
For hardware and software requirements, consult My Oracle Support, Certifications.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
53
Configuring Change Assistant
Chapter 4
Removing PeopleSoft Change Assistant Installations from Previous
Releases
If there is a PeopleSoft Change Assistant installation from PeopleSoft PeopleTools 8.54 or earlier release
present when you begin the installation, the installer instructs you to remove it, and then exits. You must
remove the previous installation and then run the installer for the current release again.
See PeopleTools Installation: for your database platform: Installing PeopleSoft Change Assistant,
Removing or Upgrading PeopleSoft Change Assistant Installations
Removing PeopleSoft Change Assistant Instances in the Current Release
To remove a Change Assistant Instance in the current release:
1. From the PS_HOME\setup\PsCA directory, run setup.exe.
If there is an existing installation of PeopleSoft Change Assistant, the Existing Installed Instances
Detected window appears with a list of the instances present.
2. Select the option Maintain or update the instance of this application and highlight the instance that
you want to remove. Click Next.
3. Select the option Uninstall Selected Instance, and click Next.
4. On the Setup Type window, select Retain existing configuration, if you want to save a file with the
existing Change Assistant configuration.
Note: If there is no configuration information available, you see an error message.
5. Click Next.
If you selected the option to retain the existing configuration, you see a message that gives the name
of the backup log file, such as backupLogUninstall.log, and the installation location where you can
find it, for example C:\Program Files\PeopleSoft\Change Assistant. The log file is a text file that
includes the name and location of the configuration zip file.
The process also saves a zip file, changeassistantcfgbak.zip, in the same directory. The zip file
includes several XML files with configuration information. Click OK to close the message box.
Note: This backup configuration file can be used to import configuration settings into a new instance
of Change Assistant. See Importing Change Assistant Setting in Change Assistant.
You see another message asking if you want to proceed with removing the instance and saving the
existing configuration. Click OK to continue.
6. When the removal process is complete, click Finish on the window showing a completion message.
Installing a New Instance of Change Assistance
To install a new instance of Change Assistant:
1. From the PS_HOME\setup\PsCA directory, run setup.exe.
54
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Note: If you had existing instances of Change Assistant and selected to install a new instance the
same wizard is used.
2. The Welcome window appears, click Next.
3. Accept the default Destination Folder or click the Browse button to specify another Destination
Folder. The default destination folder is C:\Program Files\PeopleSoft\Change Assistant.
If the installer detects an existing installation in the destination folder that you specified, you see a
message telling you to change the installation location, or re-run the installation in upgrade mode.
4. Click Next.
5. If you are satisfied with your settings, click Next to begin copying files. PeopleSoft Change Assistant
copies files to the designated directory.
6. When the copy is complete, the "Setup has finished installing Change Assistant on your computer."
window is displayed. By default the Launch Change Assistant check box is selected. Click Finish to
complete the installation process.
Updating Existing Instance of Change Assistant
To update an existing instance of Change Assistant:
1. From the PS_HOME\setup\PsCA directory, run setup.exe.
If there is an existing installation of PeopleSoft Change Assistant, the Existing Installed Instances
Detected window appears with a list of the instances present.
2. Select the option Maintain or update the instance of this application selected below and click Next.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
55
Configuring Change Assistant
Chapter 4
Image: Existing Installed Instances Detected
This example illustrates the fields and controls on the Existing Installed Instances Detected, with
Maintain or update the instance of this application selected below selected.
3. Select Upgrade Selected Instance and click Next.
56
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Image: Welcome – Upgrade or remove the program window
This example illustrates the fields and controls on the Welcome – Upgrade or remove the program
window.
4. On the Setup Type window, select Retain existing configuration to save a file with the existing
Change Assistant configuration.
When you select the option to retain the configuration for an instance that does not include a
configuration zip file, the installer creates one. If you are upgrading an instance that does include a
configuration file, the installer deletes the previous configuration zip file and creates a new one.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
57
Configuring Change Assistant
Chapter 4
Image: Setup Type window
This example illustrates the fields and controls on the Setup Type window. You can find definitions
for the fields and controls later on this page.
5. When you click Next, you are prompted to confirm the upgrade. Click OK.
6. A message is displayed that gives the name of the backup log file, such as backupLogInstall.log, and
the installation location where you can find it. The log file is a text file that includes the name and
location of the configuration zip file. The process also saves a zip file, changeassistantcfgbak.zip, in
the same directory. The zip file includes several XML files with configuration information. Click OK
to close the message box.
Image: Backup created message
This example illustrates the fields and controls on the Backup created message.
7. When the upgrade process is complete, select the option Launch Change Assistant if you want to start
Change Assistant when you exit the installer, and then click Finish
Confirming the Path Variable
After installing Change Assistant, ensure that the PATH system variable has been set. The following
locations need to appear as the first entries in the PATH string.
58
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Example:
PS_HOME\bin\client\winx86
Where PS_HOME is the location where you installed PeopleTools.
To verify Path settings:
1. Select Start, Settings, Control Panel.
2. Double-click the System icon.
3. Select the Advanced tab on the System Properties dialog box.
4. Click Environment Variables.
5. Select the Path variable in the System Variables section, then click the Edit button.
The Edit System Variables screen appears.
6. On the Edit System Variables dialog box, ensure that in the Variable Value field, the following
directory locations appear as the first entries in the Path string:
C:\PS_HOME\bin\client\winx86;
7. If you've made any modifications, click OK to save your settings.
Define Environment Identification
In the browser, navigate to the PeopleTools Options page (PeopleTools, Utilities, Administration,
PeopleTools Options) and make sure that the Environment Long Name and Environment Short Name are
specified correctly.
The Environment Management Framework and Change Assistant use these values, along with the GUID,
to identify an environment and associate environment information with a particular named environment.
Likewise, it enables you to search for updates for a specific environment.
Related Links
Cloned Databases Not Being Unique
Opening Change Assistant the First Time
The first time you open Change Assistant after installing it, you will be presented with the Welcome
menu. You can select not to display this page again.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
59
Configuring Change Assistant
Chapter 4
Image: Change Assistant Welcome page
This example illustrates the fields and controls on the Change Assistant Welcome page.
Click Next to view the Change Assistant Options.
Image: Change Assistant Wizard – Select Action page
This example illustrates the fields and controls on the Change Assistant Wizard – Select Action page. You
can find definitions for the fields and controls later on this page.
60
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Depending on the action you select, the Change Assistant Wizard will guide you through the steps. Each
of these actions has a topic that will provide details.
Apply Updates
Any systems that are not PUM enabled, will use the Apply
Updates option to apply updates downloaded from My Oracle
Support.
Apply Updates can be used with any non-PUM change
packages.
See Applying Updates To A Target Environment
Update Manager
Update Manager is used to create and apply PUM Change
Packages and PUM PeopleSoft Release Patches (PRP).
PeopleSoft Update Images (PI) are fully functioning instances
of the PeopleSoft environment that contain the updates for a
PeopleSoft application. The PeopleSoft Update Manager PIA
application is used in the PeopleSoft Update Image to search for
updates, review potential change impact, and create a custom
change package definition that is based on the updates you
selected for your environment.
Starting in PeopleTools 8.54, the Update Manager action is also
used to apply PeopleTools patches and upgrade PeopleTools
release.
Note: Update Manager is only available for 9.2 and above
applications patching.
See Update Manager Action Overview
Review Managed Object or Merge
Select Object Types
Provides the ability to copy and compare Managed Object
projects in Change Assistant. You also have the ability to view
and merge PeopleCode, SQL and XSLT.
Create or Modify Templates
Change Assistant templates are composites of all the possible
steps that apply to an update or upgrade. The templates are
delivered as part of the change package. Once you select
a change package, the template is loaded into the Change
Assistant internal storage. You can edit the template or add
additional chapters, tasks and steps, if needed.
Specifying Change Assistant Options
When you first start change Assistant, you will need to define options necessary for the selected action.
Only the options related to the Change Assistant Action you selected will be displayed. Many of the
options apply to all actions. If you are using the Change Assistant Wizard, after you select an action and
click Next, the General Options page will be displayed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
61
Configuring Change Assistant
Chapter 4
Option
Description
General
The General Options define the Change Assistant PS Homes
and directory paths used with associated action.
Depending on the action selected, only the paths relating to
that action are displayed.
PUM Source Options
The PUM Source is only used with Update Manager, to define
the PeopleSoft Update Image that will be used for applying
application and PeopleTools updates.
For all other actions, PUM Source Options are skipped.
EM Hub Options
The Environment Management Hub is used to deploy files. If
you are deploying files manually, leave the Define EM Hub
checkbox deselected.
EM Hub is only required for traditional updates (Apply
Update action).
Additional Options
Additional options include email notifications and proxy
information. These options are optional and available with all
actions.
Note: Once the environment has been configured, you can use Tools, Options to make any changes to the
environment options.
Defining Databases
Each source or target database that is used with Change Assistant needs to be defined. When you create
the database definition, the system will query the database for details including:
•
If the database is Unicode
•
Products
•
Product Line
•
Industry
•
Languages
•
Base Language
•
PeopleTools Version
To create a new database:
1. Click the Create button, which will launch the Database Wizard.
2. On the Define Database page, enter the information for the database you are defining. Depending on
the action you selected and the database type, complete the fields necessary.
3. Click Next.
62
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Change Assistant will query the database and gather additional database information.
Note: Change Assistant will verify the connection to the database, including User ID/password,
Access ID/password, and Connect ID/password. You will need to correct any errors before continuing
to define the database.
4. The information is then displayed on the Additional Database Details page.
5. Click Next and the Confirm Settings page is displayed.
6. Click Finish.
Image: Database Wizard - Define Database top of page
This example illustrates the fields and controls on the Database Wizard - Define Database for the top of
the page. You can find definitions for the fields and controls later on this page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
63
Configuring Change Assistant
Chapter 4
Image: Database Wizard - Define Database bottom of page
This example illustrates the fields and controls on the Database Wizard - Define Database for the bottom
of the page. You can find definitions for the fields and controls later on this page.
The Database Configuration Wizard provides a separate configuration page for each database type,
containing these settings:
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.
Database Name
Enter a name of up to 8 characters for the database.
If EMF is configured and running, you can select a database
from Hub.
Database Server Name
Only applies to Informix, Microsoft SQL Server and Sybase.
If applicable, enter a name of up to 256 characters for the
database server name.
Owner ID
(Used for DB2 z/OS only). Enter the owner ID used for the
tables.
User ID and 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.
Access ID and Password
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.
64
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Note: For Microsoft SQL Server the access ID must also have
System Administrator privileges.
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" (PeopleTools 8.55: Security Administration).
Connect ID and Password
Enter the connect ID and password for the target database. The
default connect ID is people.
Set DB Owner Credentials
If this check box is select, then the DB Owner ID and DB
Owner Password Fields are required fields.
The DB Owner is only used with the step type SQLScript-DBO.
When the SQLScript-DBO step executes, the Set DB Owner
Credentials option is checked prior to issuing the commandline.
If the attribute is disabled, the job will exit with an error stating
the credentials are not set, rather than attempting to execute the
command and failing.
DB Owner ID and Password
Enter the Database Owner ID and password for the target
database.
SQL Client Tool
Select the correct executable for the database platform. Valid
SQL query executables for each platform are:
•
DB2: db2cmd.exe
•
Microsoft SQL Server: sqlcmd.exe
•
Oracle: sqlplus.exe
•
Informix: dbaccess.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.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
65
Configuring Change Assistant
Chapter 4
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.
Current HomesPS Home
Enter the location of your current PS_HOME.
Note: Oracle recommends using a mapped drive.
Current Homes PS App Home
Enter the location of your current PS_APP_HOME.
Note: Oracle recommends using a mapped drive.
Current Homes PS Cust Home
Enter the location of your current PS_CUST_HOME.
Note: Oracle recommends using a mapped drive.
SQR SettingsSQR Executables
(SQRBIN)
The SQRBIN value is read only and derived from the PS Home
and platform setting.
SQR Settings SQR Flags
(PSSQRFLAGS)
By default , the -ZIF parameter is to set the full path and name
of the SQR initialization file, SQR.INI. Make any necessary
changes or add additional SQL parameters if needed.
SQR Setting PSSQR Path
This field is read-only and will contain the path that is used in
Change Assistant:
1. StagingDirectory\SQR
2. PS_CUST_HOME\SQR
3. PS_APP_HOME\SQR
4. PS_HOME\SQR
Each path is separated by a “;” (semi-colon).
The static display is: “<StagingDir>\SQR;<Cust_Home>
\SQR;<App_Home>\SQR;PS_Home>\
66
New Homes Set path information
Select this check box if you are performing an upgrade. This
check box only applies to upgrades, it does not apply to updates.
Connect to Database using New PS
Home
When performing a PeopleTools upgrade, initially you will
connect to your target database using your current PS Home.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
Once the target database is updated to the new release, the rest
of the steps will require you to connect using the New PS Home.
Select this checkbox if you need to edit the database after the
database has been upgraded to the new PeopleTools release.
New Homes PS Home
Enter the location of new PS_HOME.
Note: Oracle recommends using a mapped drive.
New Homes PS App Home
Enter the location of your new PS_APP_HOME.
Note: Oracle recommends using a mapped drive.
New Homes PS Cust Home
Enter the location of your new PS_CUST_HOME.
Note: Oracle recommends using a mapped drive.
SQR Executables (SQRBIN)
The SQRBIN value is read only and derived from the PS Home
and platform setting.
SQR Flags (PSSQRFLAGS)
By default , the -ZIF parameter is to set the full path and name
of the SQR initialization file, SQR.INI. Make any necessary
changes or add additional SQL parameters if needed.
PSSQR Path
This field is read-only and will contain the path that is used in
Change Assistant:
1. StagingDirectory\SQR
2. PS_CUST_HOME\SQR
3. PS_APP_HOME\SQR
4. PS_HOME\SQR
Each path is separated by a “;” (semi-colon).
The static display is: “<StagingDir>\SQR;<Cust_Home>
\SQR;<App_Home>\SQR;PS_Home>\.
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 database.
See Specifying Database Process Scheduler Settings
Enable PeopleSoft Test Framework
Select this option if the upgrade contains PTF steps or if you
want to incorporate PTF scripts into your template.
See Specifying PeopleSoft Test Framework Settings
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
67
Configuring Change Assistant
Chapter 4
Specifying Database 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.
Machine name 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).
Domain Connection Password
Enter the domain connection password for the application
server.
Server Name
Enter the name of the Process Scheduler server definition, such
as PSUNIX.
Method of retrieving Process
Scheduler logs
You can download and 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.
•
68
For the FTP option, enter the absolute path on the FTP
server.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 4
Configuring Change Assistant
•
User IDandUser Password
For the File Copy option, this is the (mapped) path on the
Change Assistant workstation.
(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).
Specifying PeopleSoft Test Framework Settings
If you selected the Enable PeopleSoft Test Framework option, you will need to supply PTF connection
settings.
Server:Port
Enter the server name and port for the environment. Contact
your Integration Broker administrator or system administrator
for the correct values.
The format for the Server:Port field is:
<machine_name>:<https_port>
For example:
rtdc79614.us.oracle.com:443
If the https port is the default 443 the port is optional.
You can also enter a complete https URL in this format:
https://<machine_name>:<https_port>/PSIGW/HttpListeningConnector
For example:
https://rtdc79614vmc.dsi-inet.peoplesoft.com:443/PSIGW/HttpListe
Node ID
This field is required if more than one database is connected to
the server. Enter the name of the PeopleSoft node with which
the integration gateway is to communicate.
Contact your Integration Broker administrator or system
administrator for the correct values.
Execution Options
Specify the name of the Execution Options configuration to use.
Path to PTF Client
Specify the path to the PTF client executable.
The default location is C:\Program Files\PeopleSoft
\PeopleSoft Test Framework.
Use Proxy Options
Select this option to enter details for the proxy server. When you
select this option, the proxy information fields are enabled.
Proxy Information
Enter the following information for the proxy server:
•
Server: Enter the server name.
•
Port: Enter the server port.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
69
Configuring Change Assistant
Chapter 4
•
User: Enter the user ID for the proxy server.
If you use network authentication, use the DOMAIN\USER
format.
•
70
Password: Enter the password.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Understanding The Change Assistant Interface
Change Assistant enables you to run, view, and modify Change Assistant templates. You open Change
Assistant on a Windows workstation by selecting Start, Programs, PeopleSoft Change Assistant 8.5x.xx,
Change Assistant.
Change Assistant enables you to:
•
View, modify, and create Change Assistant templates or jobs.
•
Run PeopleSoft update and upgrade jobs.
Select and configure the action and task to perform. A Change Assistant job is created from the change
package selected.
Note: Before starting and running Change Assistant, application servers, Process Scheduler servers, and
web servers should be running. If you are planning to use EM Hub for file deploy or using the Apply
Updates (non-PUM) action, then ensure all agents running on the servers are running and sending pulses.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
71
Working With Change Assistant
Chapter 5
Image: Job open in Change Assistant
This example illustrates the fields and controls on the Change Assistant interface. You can find definitions
for the fields and controls later on this page.
When you have a Change Assistant template or job open, you use these areas in the project workspace:
Interface Area
Description
Template tree
The template tree section displays distinct nodes for the
chapters, tasks, and steps within a template.
•
Chapters are section dividers that group and display the
tasks.
•
Tasks are section levels that contain one or more steps.
•
Steps are the actual update actions that complete the
processing of your update job.
Note: Properties are assigned at the step level in the template,
not the task or chapter level.
72
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Interface Area
Description
Properties box
Depending on what is selected in the template tree, the
properties box displays the properties associated with that
node.
For the Create or Modify Templates action, the properties
box displays the properties assigned to the step when it was
defined.
For a job, the properties box displays information related
to the progress of a step, such as start time, end time, total
duration, and so on.
Documentation box
Each template contains its own built-in documentation
to provide guidance for a chapter, task, or step. The
documentation exists in separate HTML files, but it appears in
this box for each selected node on the template tree.
Activity box
The Activity box displays the processing and status messages
associated with a step, when a job is running in Change
Assistant. This is similar to the Output window in the
Application Designer workspace.
Working With Change Assistant Menu Options
This section describes the menu options available when using Change Assistant.
Note: Some menu options are enabled only during a specific Change Assistant action, which is
determined in the Change Assistant Actions dialog box.
File Menu
The File menu contains some generic Windows options, plus these specific Change Assistant options:
Menu Option
Description
New Template
Creates a new Change Assistant template.
Open Template
Opens a template from the Change Assistant storage (internal
database).
Save Template
Saves the template into the Change Assistant storage (internal
database).
Save Template As
Saves the new template with the name you specify.
New Job
Creates a new Change Assistant job.
Open Job
Opens a job from the Change Assistant storage (internal
database).
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
73
Working With Change Assistant
Chapter 5
Menu Option
Description
Save Job
Saves the job into the Change Assistant storage (internal
database).
Save Job As
Saves the job with the name you specify.
Close
Closes the current template or job.
Import Template
Imports an existing template into Change Assistant.
Note: Any modifications to the current template will not affect
the original template that you imported. If you want others to
obtain a copy of your modified template, you need to export it
out of Change Assistant.
Delete Template
Removes the template from Change Assistant. When you
delete a template, you also delete all the jobs associated with
the template.
Note: Press and hold the CTRL key to select multiple
templates for deletion.
Export Template
Exports a copy of the template out of Change Assistant so
others can use it.
Export Job
Exports a copy of the job out of Change Assistant so others
can use it.
Delete Job
Removes a job associated with the current template.
New Database
Launches the Database wizard for creating a new database.
Change Assistant uses these settings to locate PS_HOME
directories, connect to the Target database, and so on.
Open Database
Opens a defined database.
Import Database
Imports an existing database.
Delete Database
Deletes an existing database.
Exit
Exits Change Assistant.
Note: This option is disabled when a Change Assistant step is
running. To exit Change Assistant while a process is running,
you must first kill the process (select Run, Kill). When you
relaunch Change Assistant you can resume at the point where
you killed the process.
74
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Edit Menu
The Edit menu contains some generic Windows options, plus these specific Change Assistant options:
Menu Option
Description
Insert Chapter
Inserts a new chapter. A chapter serves as a section head for
multiple tasks.
Insert Task
Inserts a new task within a chapter. A task serves as a section
head for one or more steps.
Insert Step
Inserts a new step within a task.
Step Properties
When a step is selected, launches the Step Properties dialog.
Rename
Renames an existing chapter, task, or step.
Run
Runs the selected step.
Stop
Stops the selected step.
Restart
Restarts certain types of steps that you have stopped or have
failed. Restart is supported for these step types:
•
Application Engine
•
SQL
Application Engine programs can keep track of the state of
a program run, and when restarted, they can pick up where a
previous run stopped.
When restarting SQL steps, Change Assistant generates
a separate log file and numbers them incrementally, as in
logfile_2, logfile 3, and so on.
Complete
Marks the selected step as complete. Often used when setting
a manual step to complete, indicating that the manual work is
done.
View Log
Opens the current job processing log.
View Script
Opens the script associated with the selected step.
Job Properties
Enables you to set properties for the job.
Set Documentation Directory
Specifies the directory into which your upgrade documentation
is saved. Change Assistant loads the documentation for
viewing when you open a template or job.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
75
Working With Change Assistant
Chapter 5
Menu Option
Description
Edit Documentation
Enables you to modify the documentation associated with the
selected chapter, task, or step.
Finalize Documentation
Generates the HTML files.
View Menu
The View menu contains these specific Change Assistant options:
Menu Option
Description
Step Details
Displays the step properties box in the Change Assistant
workspace.
Documentation
Displays the documentation box in the Change Assistant
workspace.
Activity
Displays the Activity box in the Change Assistant workspace.
Expand All
Expands all chapters, tasks, and steps.
Collapse All
Collapses all chapters, tasks, and steps.
Steps Not Yet Completed
Filters steps to show steps not yet completed.
Steps Completed by System
Filters to show steps completed by the system.
Deselect this option if you want to hide all the steps that have
been completed.
Steps Completed Manually
Filters to show the steps that were manually completed.
Deselect this option if you want to hide all the steps that have
been manually completed.
Steps Filtered By Filter Query
Filters to show the steps that were filtered using a query filter.
Deselect this option if you want to hide all the steps that have
been filtered by a filter query.
Steps Filtered at the Job Level
Filters to show the steps that were filtered at the job level.
Deselect this option if you want to hide all the steps that have
been filtered at the job level.
Run Menu
The Run menu contains these specific Change Assistant options:
76
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Menu Option
Description
Run
Begins the execution of a Change Assistant job.
Cancel
Stops the processing of a Change Assistant job after the
currently running process completes.
Kill
Stops the processing of a Change Assistant job completely and
immediately, including the step that's currently running.
Tools Menu
The Tools menu contains these specific Change Assistant options:
Note: If the menu option does not apply to the action selected, it will be grayed out.
Menu Option
Description
Upload Target Database Information to PUM
Enabled when action type is Update Manager.
Uploads the target database information to the PUM source.
Upload Customer Data to Image
Enabled when action type is Update Manager.
Allows you to upload customer data (customization project) to
the PUM source.
See Using Customization Repository
Define or Create a New Change Package
Enabled when action type is Update Manager.
Opens Change Assistant Wizard to select your database
information and leads you through the process to create a
change package.
See Defining a New Change Package
Apply Change Package
Enabled when action type is Update Manager.
Opens Change Assistant Wizard to lead you through the
process to apply a change package.
See Applying Change Package
Apply Tools Delta Package
Enabled when action type is Update Manager.
Opens Change Assistant Wizard to lead you through the
process to apply a delta change package.
See Creating and Applying Tools Delta Package
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
77
Working With Change Assistant
Chapter 5
Menu Option
Description
Apply Translation Delta Package
Enabled when action type is Update Manager.
Opens Change Assistant Wizard to lead you through the
process to apply a translation delta change package.
See Applying Translations Delta Package
Apply PeopleSoft Release Patchset
Enabled when action type is Update Manager.
Opens Change Assistant Wizard to guide you through applying
PeopleSoft release patchset to the PeopleSoft Update Image.
See Applying Downloaded PeopleSoft Release Patchset to
PeopleSoft Image
Apply PeopleTools Patch
Enabled when action type is Update Manager.
Open Change Assistant wizard to guide you through applying
a PeopleTools patch.
See Using Change Assistant to Apply PeopleTools Patch
Upgrade PeopleTools
Enabled when action type is Update Manager.
Open Change Assistant wizard to guide you through upgrading
your database for the new PeopleTools release.
See Using Change Assistant to Upgrade PeopleTools
Upgrade Application
Enabled when action type is Update Manager.
Open Change Assistant wizard to guide you through upgrading
your application for the new application release.
See Upgrading Application
Validate
Validates the Change Assistant settings for EM Hub to ensure
that the required elements are up and running, and that Change
Assistant can connect to them.
Export &Import Settings
Allows you to export Change Assistant settings to a file and
import Change Assistant settings either from another Change
Assistant directory or from a backup configuration.
See Exporting and Importing Change Assistant Settings
78
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Menu Option
Description
Migrate PUM Data
Enabled when action type is Update Manager.
Allows you to migrate user metadata (PUM customization
Information, test information and package definition
information from one PUM Image to a new PUM Image.
See Migrating PUM Data
Merge PeopleCode/SQL/XSLT
Enabled when action type is Review Managed Object or
Merge Select Object Types.
Allows you to start a new merge session or open an existing
session.
Default Merge Rules
Enabled when action type is Review Managed Object or
Merge Select Object Types.
Opens the Default merge Rules dialog box.
Project Administration
Enabled when action type is Review Managed Object or
Merge Select Object Types.
Opens Project Administration page.
Scan Configuration
Searches the Change Assistant workstation for tools and
utilities required to perform updates and upgrades. For
example, this process locates the local SQL tool, Data Mover,
Application Designer, and so on.
Change Actions
Opens Change Assistant Wizard Select Action page.
See Opening Change Assistant the First Time
Options
Opens the Change Assistant Options dialog box, enabling you
to select Change Assistant configuration options.
Exporting and Importing Change Assistant Settings
Change Assistant settings can be exported and imported using one of the following processes:
•
Exporting Configuration
1. Change Assistant Installer exports configuration when Retain existing configuration is selected
during the install.
See Removing PeopleSoft Change Assistant Instances in the Current Release
2. User exports configuration manually in Change Assistant GUI.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
79
Working With Change Assistant
Chapter 5
See Exporting Change Assistant Setting in Change Assistant
3. User exports configurations using Change Assistant command line.
See PeopleTools Installation for your database platform: Installing PeopleSoft Change Assistant,
Installing PeopleSoft Change Assistant in Silent Mode
•
Importing Configuration
1. Change Assistant Installer imports configuration when an existing Change Assistant instance is
upgraded and Retain existing configuration is selected.
See Updating Existing Instance of Change Assistant
2. User imports configuration using Change Assistant GUI through menu item.
See Importing Change Assistant Setting in Change Assistant
3. User imports configuration to Change Assistant using command line.
See PeopleTools Installation for your database platform: Installing PeopleSoft Change Assistant,
Installing PeopleSoft Change Assistant in Silent Mode
Change Assistant settings are exported to configuration backup files. A configuration backup is a zip file.
It consists of the following XML files:
•
Configuration backup property file (cfgbak_prop.xml)
•
Options file (settings.xml)
•
Database definitions backup file (cfgbak_dblist)
Configuration Backup Property File
Configuration backup property file (cfgbak_prop.xml) contains the following content:
•
ToolsVersionCA
The value is the Tools version of Change Assistant which is used to generated this backup file.
•
Creator
The value is Installer or CA.
•
ImportType
The value is Auto, Confirm, or Manual.
•
OptionsIncluded
The value is true or false.
•
DBDefnNum
The value is the number of database definitions included in the export file.
80
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
•
DB definition list
The database list will be used as a pre-check to determine if the database definition already exists in
Change Assistant when user imports the configuration.
Exporting Change Assistant Setting in Change Assistant
Use the Export/Import Change Assistant Setting option to export or import settings.
Navigation
In Change Assistant, select Tools, Export/Import Change Assistant Settings
Image: Export&Import Settings Wizard – Export/Import page
This example illustrates the fields and controls on the Export&Import Settings Wizard – Export/Import
page with the Export radio button selected.
Exporting Change Assistant Settings
To export Change Assistant Settings:
1. In Change Assistant, select Tools, Export/Import Change Assistant Settings.
2. Select the Export radio button.
3. Enter the destination directory and file name.
4. Click Next.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
81
Working With Change Assistant
Chapter 5
5. On the Select Details page, select if you want to export the settings, as well as the databases.
Image: Export&Import Settings Wizard – Select Details page
This example illustrates the fields and controls on the Export&Import Settings Wizard – Select Details
page. You can find definitions for the fields and controls later on this page.
Export existing settings(option,
layout, merge color and font,etc)
Select this option to export CA settings.
Database Definitions
Select this option to export database definitions. When this
option is selected, the databased defined in CA will be listed
and you can choose which databases to export.
6. Click Next. The status is displayed with the path to the configuration backup file.
Image: Export&Import Settings Wizard – Export/Import Status page
This example illustrates the fields and controls on the Export&Import Settings Wizard – Export/
Import Status page.
7. Click Finish.
Importing Change Assistant Setting in Change Assistant
Use the Export/Import Change Assistant Setting option to export or import settings.
Navigation
In Change Assistant, select Tools, Export/Import Change Assistant Settings
82
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Image: Export&Import Settings Wizard – Export/Import page
This example illustrates the fields and controls on the Export&Import Settings Wizard – Export/Import
page with the Import radio button selected.
Importing Change Assistant Settings
You can import Change Assistant Settings from either another instance of Change Assistant or from a
configuration backup file.
To import Change Assistant settings:
1. In Change Assistant, select Tools, Export/Import Change Assistant Settings.
2. Select the Import radio button.
3. Select the import option to use:
•
Import from other Change Assistant Installation
Select the Change Assistant directory for the instance.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
83
Working With Change Assistant
Chapter 5
Image: Import from other Change Assistant Installation
This example illustrates the fields and controls on the Import from other Change Assistant
Installation option.
•
Import from configuration backup
Select the directory and file.
Image: Import from configuration backup
This example illustrates the fields and controls on the Import from configuration backup option.
4. Click Next. A progress bar is displayed as Change Assistant retrieves the information.
84
•
If Import from other Change Assistant installation is selected, Change Assistant will check the
Tools version of the selected Change Assistant instance. If the Tools version is available, it will
call the selected Change Assistant instance to export the configuration to a temporary folder. The
configuration is then retrieved from the temporary configuration backup file.
•
If Import from configuration backup is checked, Change Assistant will retrieve the configuration
from the selected configuration backup file.
•
If there is a problem with retrieving the configuration, a warning message is displayed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
5. Click Next. On the Select Details page, select if you want to import the options and which databases
you want to import.
•
If settings have already been configured on this instance of Change Assistant, the Overwrite
existing settings check box will be cleared.
•
If this instance of Change Assistant has not been configured, the Overwrite existing settings check
box is selected.
•
If a database definition already exists in Change Assistant, the check box for the database is
cleared.
•
If a database definition does not exists in Change Assistant, the check box for the database is
selected.
•
If a database definition is being used in a job, the check box for the database is cleared.
Image: Example Select Details page for option Import from configuration backup
This example illustrates the fields and controls on the Export&Import Settings Wizard- Select Details
page where the new instance of Change Assistant does not contain any settings.
6. Click Next. Change Assistant will validate the settings and display the status.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
85
Working With Change Assistant
Chapter 5
Image: Export/Import Status showing import complete
This example illustrates the fields and controls on the Export/Import Status showing import complete.
7. Click Finish.
If the validation showed any issues with the options settings, Change Assistant will launch the
Options window automatically when you click Finish, in order to make the corrections.
Migrating PUM Data
Change Assistant provides the ability to migrate metadata from the current PUM Source to the new PUM
Source. The following data types can be migrated:
•
PUM Customization Information
See Using Customization Repository
•
Test Information
See Using the Test Repository
•
Package Definition Information
Package definition information refers to all of the metadata for Change Packages that were created on
the PUM Source. Only Created change packages are migrated.
86
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Importing the Change Package definitions into the new PUM Source provides change package
history. The change package definitions can be viewed in the new PUM Source, but can not be used to
directly create a change package.
Exporting PUM Data from Current PUM Source
To export PUM data on the current PUM source:
1. In Change Assistant, select the task Migrate Customer Data from the Tools menu.
2. Select Export PUM(User) Metadata From Existing PUM Source.
3. Select the current PUM database.
4. Select the metadata to export.
See Using PUM Data Migration Page
5. Select the export directory in the Export To field.
The export file is a data mover DAT file. By default the name is customerdata.DAT.
6. Deselect Import PUM(User) Metadata to New PUM Source.
7. Click Import/Export.
Change Assistant will check that the database is a PUM Source, if it is not, you will receive an error
message.
8. A message is displayed that the export was successful.
Importing PUM Data into New PUM Source
To import PUM Data from a DAT file into a new PUM Source:
1. Install a new Change Assistant instance for the new Update Image.
2. In the new Change Assistant instance, select the task Migrate Customer Data from the Tools menu.
3. Deselect Export PUM(User) Metadata From Existing PUM Source.
4. Select Import PUM(User) Metadata to New PUM Source.
5. Either select the new PUM Source database or click the Create button to open the Define Database
Wizard and define the database.
6. Select the metadata to export.
See Using PUM Data Migration Page
7. Select whether to overwrite existing data or ignore duplicates.
8. Select Specify.
9. In the Import From field select the path and file for the DAT file exported from the old PUM Source.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
87
Working With Change Assistant
Chapter 5
10. Click Import/Export.
Migrating PUM Data
If both your old PUM source and new PUM source are available, you can export and import at the same
time.
To migrate PUM data:
1. Download and deploy new Update Image.
2. Install Change Assistant from the PS Home that matches the new PUM Source.
Note: Change Assistant Settings can be retained from the existing instance of Change Assistant. See
Setting Up Change Assistant
3. In Change Assistant, configure database definitions for the old PUM source database and the new
PUM source database.
4. Select the task Migrate Customer Data from the Tools menu.
5. Select the metadata to import and export.
See Using PUM Data Migration Page
6. Click Import/Export.
7. Change Assistant performs a compatibility check.
8. If the compatibility check passes, a Migration Summary report is displayed.
9. Click Finish.
Using PUM Data Migration Page
In Change Assistant, select Tools, Migrate Customer Data.
88
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Image: PUM Data Migration page
This example illustrates the fields and controls on the PUM Data Migration page. You can find definitions
for the fields and controls later on this page.
Export PUM(User) Metadata From
Existing PUM Source
Select to enable the export.
Database
Select the old PUM source database.
If the database has not been defined in this instance of Change
Assistant, use the Create button to launch the Define Database
wizard.
PUM Customization Information
Select to export the customization repository.
Test Information
Select to export the test repository.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
89
Working With Change Assistant
Chapter 5
Package Definition Information
Select to export change package definitions.
Export To
Enter the path and file name for the export.
Import PUM(User) Metadata to New Select to enable import.
PUM Source
Database
Select the new PUM source database.
If the database has not been defined in this instance of Change
Assistant, use the Create button to launch the Define Database
wizard.
PUM Customization Information
Select to import customization repository.
Test Information
Select to import test repository.
Package Definition Information
Select to import change package definitions.
Overwrite if exists
Select to overwrite data if the data already exists.
Ignore duplicate
Select to ignore duplicate data.
Same as Export
The file specified in the Export To field is used.
Specify
Select if you have an existing file to import.
Import From
Enter the path and file name for the import.
Compatibility Checks
When PUM Source data is exported, the only check performed is Check 1: Check if the old PUM source
is a real source database.
When PUM source data is imported, the following checks are performed:
1. Check 1: Check if the old PUM source is a real source database.
2. Check 2: Check if there are duplicate definitions in the PUM source database.
3. Check 3: Product line of PUM Source.
4. Check 4: Image Version of PUM Source. New PUM source must be greater than or equal the old
PUM saource.
Working with Change Assistant Templates and Jobs
Whether you are performing an update or an upgrade, you work with Change Assistant templates and
jobs. The templates are composites of all possible steps that apply to an update or upgrade, whether they
apply to your environment or not.
The source of the template is dependant on the action you are performing in Change Assistant. This table
lists the template source for each Change Assistant action.
90
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Change Assistant Action
Template
Apply Update
Change Assistant template comes in the change package
downloaded from MOS.
For change packages created in Application Designer,
the template is generated when you select Generate New
Template.
Update Manager
Change Assistant template is either generated from the custom
change package when you select to apply the change package
or delivered from PeopleSoft if you are applying a PeopleSoft
Release Patchset (PRP).
For PeopleTools patches and PeopleTools upgrades, the
change package is downloaded from MOS.
Upgrade
Change Assistant template for your upgrade path is
downloaded from MOS.
After you specify the required settings in Change Assistant regarding your environment, you use Change
Assistant to build a job tailored to your environment. When building the job, Change Assistant filters the
steps so that the job contains only the steps applicable to your implementation. For example, the resulting
Change Assistant job will have only steps that apply to your database type, your installed applications,
your languages, and so on.
When you apply updates or run an upgrade, Change Assistant automatically loads the template into
the Change Assistant internal storage system. You can add additional chapters, tasks, and steps to the
template, if needed. To edit a template, you must be in the Create or Modify Templates mode, specified on
the Change Assistant Options dialog box.
Examples of custom steps that might be added include, dropping indexes, adding indexes, backing up a
database, adding PTF steps, and so on.
Note: In most cases, it is not necessary (or recommended) to modify a delivered template. Any changes
that you make to the imported template won't affect the original template that you downloaded. However,
if you choose to edit a template, keep a backup of the original.
Creating New Template Elements
You can add chapters, tasks and steps to an existing template.
To insert a template element:
1. Highlight the location where you want to add the element.
If you want to add a chapter above the existing first chapter in the template, highlight the template
root node (template name) at the top of the template tree.
2. From the Edit menu (or toolbar) select the appropriate option: Insert Chapter, Insert Task, Insert Step.
3. Enter a unique name for your new element.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
91
Working With Change Assistant
Chapter 5
Note: Each chapter in the update template must have a unique name, each task within a chapter must
have a unique name, and each step within a task must have a unique name.
4. Click OK.
When creating new steps, Change Assistant displays the Step Properties dialog box for specifying step
options.
Deleting Template Elements
To delete a chapter, task, or step:
1. Highlight the chapter, task, or step that you want to delete.
Note: Press and hold the CTRL key to select multiple steps for deletion.
Warning! If you delete a chapter, Change Assistant deletes all the tasks and steps within the chapter.
If you delete a task, Change Assistant deletes all the steps within the task.
2. Select from the following:
a. If you want to delete a chapter, select Edit, Delete Chapter.
b. If you want to delete a task, select Edit, Delete Task.
c. If you want to delete a step, select Edit, Delete Step.
3. Change Assistant deletes the chapter, task, or step and updates the template.
4. Save the template.
Exporting Templates
In order for others to use the template that you create or modify, you need to export it from Change
Assistant. If you want to overwrite an existing template file, enter the name of the original template.
To export a template:
1. Open the template in Change Assistant by selecting File, Open Template.
2. Select File, Export Template.
The Export Template dialog box appears.
3. Navigate to the folder in which you want to save the template.
4. Enter the name of the template.
Note: If you want to overwrite the original template that you downloaded, enter the original name of
the template.
92
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
5. Click Save.
Exporting Jobs to XML, HTML, or Microsoft Excel Format
Change Assistant allows you to export jobs to XML, HTML, or Microsoft Excel file formats.
To export a job:
1. Select File, Export Job.
2. Enter the desired exported filename and the select the desired file type format.
You can use this option to enable other implementation team members, who do not have access to the
machine on which Change Assistant is running, to view the job. Exporting the job to Microsoft Excel
enables you to view the timings in a spreadsheet format.
Note: You can not export a Change Assistant job and either import it or open it on another machine with
Change Assistant installed and then run or modify the job on that other machine.
Working with Steps
This section discusses how to:
•
Set step properties.
•
Set filter queries.
•
View step status.
Setting Step Properties
PeopleSoft delivers update templates with default settings and steps to perform updates. If needed, you
can modify the steps, or create new steps, based on the conditions that apply when you run the update
process.
To modify the step properties, highlight the step for which you want to modify the step properties, then
double-click on the step or select Edit, Step Properties. After making any changes to step properties, click
OK, and save your template.
Note: Depending on what mode you are in, some of the fields may be disabled.
Note: Under normal circumstances, it is recommended that you do not modify or edit the step properties
in your delivered template.
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 template.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
93
Working With Change Assistant
Chapter 5
Image: Step Properties dialog box
This example illustrates the fields and controls on the Step Properties dialog box. You can find definitions
for the fields and controls later on this page.
Step Description
This field displays the current step.
Script/Procedure
Enter the name of the script, procedure, project, or program
name to which you want to assign the properties of the step. For
example, enter SYSAUDIT.
This field is required for all step types except manual stop.
Type
Select a step type. This selection defines the type of action to
be performed by the step. For example, if you are running the
SYSAUDIT SQR report, select SQRReport.
Detailed information related to each step type appears elsewhere
in this PeopleBook.
See Step Types
Parameters
94
Enter additional parameters that you may need to run the step.
For example, for SQL commands, you enter the actual SQL
command in this field. In other cases, you use this edit box to
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
override various environment settings or other parameters so
that the step completes successfully.
Detailed information related to the parameter options for each
step type appears elsewhere in this PeopleBook.
See Step Parameters
From Tools Release
Specify the PeopleTools releases to which a step applies. Use
the associated operator dropdown list to indicate ranges of
releases. The default values are All with the = operator.
The operator dropdown list enables you to express greater than,
less than, equal to, and 'in' relationships.
The in operator enables you to specify more specific ranges,
such as 'in' 8.48 and 8.49, as opposed to 'greater than' 8.48.
When adding multiple release numbers, separate the values with
a comma (,). For example:
8.48,8.49
Note: If you enter more than one From Tools Release value, the
system assumes the 'in' operator.
Change Assistant uses these values to filter the steps when
creating the upgrade job so that only the steps necessary for a
particular environment remain.
Run Location
Select one of these run location options:
•
Local: runs a step's process on the local machine: the
Windows workstation where Change Assistant is running.
For Application updates and PeopleTools-only upgrades,
steps run locally. However, for full upgrades, steps can run
locally or remotely.
•
Remote Agent: runs the step on a remote server. During
a full upgrade, some steps are data intensive and, for
performance reasons, can be run on a remote server. If
you select Remote Agent, before running the step you need
to configure the Remote Agent options on the Change
Assistant Options dialog.
See Specifying Database Process Scheduler Settings.
Orientation
Specify which database the step needs to be run against. Options
will vary based on the action selected, but may include:
•
Source
•
Target
•
Copy of Current Demo
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
95
Working With Change Assistant
Chapter 5
•
Production
•
Not Applicable
Note: This orientation is used for Manual Stops or a task
that does not use an orientation.
Step type and type of upgrade determine valid orientation
settings.
See Source and Target Databases.
Products
Click the Products icon. Change Assistant displays the Select
Products dialog box, which enables you to select the product
line, the industry, and the products to which your step should
be run against (for example, FIN/SCM, Commercial, Asset
Management).
Note: You must select at least one product.
Apply Type
Specify the type of upgrade to which this step applies:
•
Initial Pass: refers to the initial application of a change
package or new release to your Copy of Production
database.
•
Move to Production: refers to the upgrade between your
Copy of Production database and your test or production
system.
•
Both: refers to steps that need to be run in both apply types.
Note: When the job is created, the system filters the template
steps to be executed by the apply type specified. For example,
if Move to Production is specified as the apply type, only steps
in the template specified as Move to Production or Both will be
included in the job.
Allow for Errors
Indicates how the system should react to any errors that may
arise during a step run. If set to Yes, if the step encounters errors
the system does not perform any error handling and continues
on to the next step.
Default is set to No.
Run Concurrently
Enables you to set multiple steps (programs, processes, and so
on) to run simultaneously.
If you select this option for two or more consecutive steps,
Change Assistant starts those processes concurrently, until the
job reaches:
•
96
a step with Run Concurrently set to No.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
•
a step type of Manual Stop.
•
the Maximum Concurrent Processes value, as set on the
Change Assistant Options dialog box.
By setting Run Concurrently to Yes, you are indicating to
Change Assistant that this step can run concurrently with
the following step. The total number of processes that can
run concurrently is determined by the Maximum Concurrent
Processes setting on the Change Assistant Options dialog box.
Some examples are shown here, these examples use 3 AE steps
and CA concurrency set to 2:
•
Example 1
Steps:
•
AE1 Concurrent=Yes
•
AE2 Concurrent=Yes
•
AE3 Concurrent=No
•
Manual Stop
In this example, AE1 and AE2 will run in parallel. When
both finished, AE3 will then run.Job will stop when
ManualStop is encountered.
•
Example 2:
Steps:
•
AE1 Concurrent=Yes
•
AE2 Concurrent=Yes
•
AE3 Concurrent=Yes
•
Manual Stop
In this example, AE1 and AE2 will run in parallel, when
either AE1 or AE2 finish, AE3 will run. Job will stop when
ManualStop is encountered.
•
Example 3
Steps:
•
AE1 Concurrent=Yes
•
AE2 Concurrent=Yes
•
Manual Stop
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
97
Working With Change Assistant
Chapter 5
•
AE3 Concurrent=No
In this example, AE1 and AE2 will run in parallel, the job
will stop when ManualStop is encountered. AE3 will run
after the user completes the ManualStop.
•
Example 3
Steps:
•
AE1 Concurrent=Yes
•
AE2 Concurrent=No
•
AE3 Concurrent=Yes
•
Manual Stop
In this example, AE1 will run, when AE1 finishes, AE2 will
run, when AE2 finishes AE3 will run. Job will stop when
ManualStop is encountered.
Running steps concurrently is a strategy reserved for application
upgrades to save time when running the following step types
on a remote host through a remote EMF agent or Process
Scheduler:
•
Application Engine
•
SQL
•
Data Mover
Concurrent processing is not enabled in any circumstances for
these step types:
•
DBTSFIX
•
Load Base Data
•
Upgrade PeopleTools
•
Manual Stop
Note: If a step is dependent on a previous step, it is not
recommended to set it to run concurrently with that step.
Note: Steps set to run concurrently can span across multiple
consecutive tasks or chapters, and can be of different step types.
Note: In an application upgrade, do not run the "Update
PeopleTools System Tables" step concurrently, and, unless
specifically instructed to do so, do not run any of the steps in the
"Apply PeopleTools Changes" chapter concurrently.
98
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
See the upgrade documentation for your specific upgrade for
recommendations on specific steps within that upgrade that can
be run concurrently.
Setting Filter Queries
Filter queries provide the ability to add ad-hoc step filtering criteria to a template to further improve
applicability of job to the customer and where possible remove unnecessary manual steps.
See Adding Filter Queries
Viewing Step Status
When working with templates and jobs, you see these status icons to the left of steps:
Run
Indicates that Change Assistant runs this step or process
automatically without manual intervention.
Stop
Indicates that Change Assistant stops on this process. It also
indicates that there may be manual steps to perform for this step.
Review the documentation window for further instructions.
After completing the work described in a manual step, you must
set the status to Complete.
Restart
Processing
Failure
Warning
Complete
Manually Complete
Filter
Indicates a restart process. If a step failed and you corrected the
problem, you can set the step to restart from the point of failure.
Indicates that the process is running.
Indicates a failure has occurred that needs immediate attention.
This appears if a Data Mover script, SQL script , or project copy
step fails. Resolve the error before continuing with processing.
Indicates a warning for this step which does not need immediate
attention. The job continues processing with no adverse affects.
After the job completes, review the steps in a warning state and
evaluate for further action.
Indicates that the step was completed by the system.
Indicates this step was completed manually.
Indicates this step is filtered at the job level.
Steps filtered at the job level will not execute and are equivalent
to Complete. To hide these steps, select View, and deselect Steps
Filtered at the Job Level.
Filter Query
Indicates this step is filtered by a filter query.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
99
Working With Change Assistant
Chapter 5
Steps filtered by filter query will not execute and are equivalent
to Complete. To hide these steps, select View, and deselect Steps
Filtered by Filter Query.
Adding Filter Queries
Filter queries provide the user with the ability to add ad-hoc step filtering criteria to a template in order to
improve the applicability of a job to the customer and where possible remove unnecessary manual steps.
This section discusses how to:
•
Create Filter Query Step type.
•
Assign Filter Query to a step.
•
Cut and Paste filter queries
•
Create and execute jobs that include filter queries.
Creating Filter Query Step Type
A template can have 0–n Filter Query steps defined and they can be defined at any position in the
template. The location of the filter query step will determine when the filter queries associated to that step
will be executed.
100
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Image: Step Properties for Type FilterQuery
This example illustrates the fields and controls on the Step Properties dialog box . You can find
definitions for the fields and controls later on this page.
Script/Procedure
The Script/Procedure is defaulted to Filter<n+1> where n is set
to 0 for a new template and incremented by 1 each time a Filter
Query step type is added and saved.
The first Filter Query step created in a template will be named
Filter0001, the second will be named Filter0002, and so on.
These values must be unique, deletion of a filter query step, will
not change the n value. When a filter query step is deleted, the
value is never reused.
Define Filter Query
Use this button to access the Define Filter Queries dialog box.
The following step attributes can be set for Filter Query step type:
•
From Tools release
•
Orientation
•
Products
•
Platforms
•
Languages
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
101
Working With Change Assistant
•
Chapter 5
Apply Type
Setting Step Properties
The following step attributes cannot be changed and will be greyed out.
•
Parameters — not required for Query Filter step type
•
Run Location (Default = Local)
•
Allow for Errors (Default = No)
•
Run Concurrently (Default = No)
Note: A filter query step cannot be filtered by it’s own query. A filter query step can not be filtered by a
filter query defined in another step.
Defining Filter Queries
The Define Filter Queries page is used to define the actual filter queries. The grid is displayed in readonly mode and always contains a minimum of one row in the view.
•
To add a new filter query, right-click and select Add New Filter Query.
•
To delete an existing filter query, right-click on the row and select Delete Selected Filter Query.
•
To update an existing filter query either:
•
Right-click on the row and select Edit Selected Filter Query.
•
Double click on the row.
Defining Filter
Use the Filter Definition dialog box to define the filter.
102
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Image: Filter Definition dialog box
This example illustrates the fields and controls on the Filter Definition dialog box. You can find
definitions for the fields and controls later on this page.
Filter ID
The Filter ID must be unique within the Filter Query step. The
Filter ID value in conjunction with the Script/Procedure name
is used to ensure uniqueness within the template. For example:
Filter1–AP Check.
Description
Enter a description for the filter query.
System Query
Select this radio button to use a system queries. System queries
include:
•
Source Platform = Target Platform
•
Source Platform != Target Platform
•
Database EM Hub Enabled = Yes
•
Database EM Hub Enabled = No
•
Scripts File Exists
•
Scripts File Does not Exist
•
SQR File Exists
•
SQR files Does not Exist
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
103
Working With Change Assistant
Chapter 5
•
MO Project Exists
•
MO Project Does not Exist
•
ADS Project Exists
•
ADS Project Does not Exist
User Defined
Select this radio button to type your own query definition.
Query Definition
Enter the SQL statement for the query.
Special filter queries are also available as described in the next
section.
Note: The SQL statement is not validated.
Filter if True Value
The Filter if True Value can be a numeric or a string. Valid
operator are:
•
Numeric
=, <, >, >=, <=, <>
•
String
Contains, Does Not Contain
For a single filter query, when the Filter if True Value is True
then the associated step will be filtered.
Assigning Filter Query to a Step
To use a filter query, the filter query must be assigned to a step. The following rules apply:
•
The drop down list of filter queries will be restricted to filter queries that are defined in the template at
a position ahead or above the step being updated.
•
Steps can only be associated to Filter Queries that would execute prior to the step being executed.
•
Steps cannot be associated to the same Filter Query twice.
Adding a Query Filter to a Step
To add a query filter to a step:
1. Double-click on the step to open the Step properties.
2. Select the Filter Queries tab.
104
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Image: Filter Queries dialog box
This example illustrates the fields and controls on the Filter Queries dialog box. You can find definitions
for the fields and controls later on this page.
Step will be filtered if:
Select when filtering will be done.
•
All Filter Queries listed Return True Values
AND condition
•
One Filter Query listed returns True value
OR condition
Filter Name
Select the Filter name from the drop down list.
To add additional filter queries, right-click and select Insert
Query.
Filter Identifier
Select the Filter Identifier from the drop down list.
Note: The drop down list will contain all of the Filter IDs for
the selected Filter Name. This field will be grayed out if a Filter
name has not been specified.
To add additional Filter Queries, right-click on a row and select Insert Query.
Deleting a Query Filter from a Step
To delete a query filter:
1. Double-click on the step to open the Step properties.
2. Select the Filter Queries tab.
3. Right-click on the row with the filter and select Delete Query.
4. Click OK.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
105
Working With Change Assistant
Chapter 5
Cutting and Pasting Filter Queries
Once Filter Query Step types have been defined and used as filters for additional steps, you must take care
in deleting or moving the steps in the template. Keep in mind the following points:
•
Deleting a Filter Query Step
If you delete a Filter Query step from the template, you will receive a warning that the deletion will
result in all references to all filters defined in that step will be deleted. If you choose to continue, the
process will remove all step references to the deleted Script/Procedure + Filter ID values.
•
Cutting and pasting a Filter Query Step to another location in the template
•
Pasting to a position above or ahead of the original position has no impact.
•
Pasting to a position below the original position will result in a warning message indicating that
moving step will result in removal of references to the current filter query step above it’s new
position.
If you choose to continue, the process will remove all step references to the moved Script/
Procedure + Filter ID values in steps that precede it in the revised template.
•
Cutting and pasting a non-filter query step
•
Pasting to a position below the original position has no impact.
•
Pasting to a position above the original position will result in a warning message indicating that
moving the step will result in removal of references to filter queries below it’s new position.
If you choose to continue, the process will remove all step references to the impacted Script/
Procedure + Filter ID values within the relocated step.
Creating and Executing Jobs that Include Filter Queries
This section discusses how filter queries affect:
•
Job Creation
•
Job Execution
Job Creation
At the time of job creation, Filter Query steps can be filtered by any of the standard attributes (such as
Platforms) as is the case for any other Step type. The filtering of a Filter Query step in this manner does
not invalidate or cause steps that reference the filter query to filtered.
At job creation all Filter Queries defined within the template will be set to a default value of Null or No
Value. No Step will be filtered by an Ad-Hoc Filter Query at job creation, because no Filter queries have
been run at that time. The earliest these Filter Queries can be executed is in the first step of the template/
job.
A step can be filtered by a System Filter Query at job creation, assuming that the associated step does not
also have any ad-hoc Filter Queries associated to it.
106
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Job Execution
On Filter Query step execution, results are retrieved for all filter query ID’ s defined within that specific
Filter Query step. These results are written to the Change Assistant database.
•
The execution accounts for the orientation of the Filter Query step.
•
The return values for each Filter Query are noted in the CA log listing the Filter Identifier, Filter ID,
the Hide if True Condition, the return value and whether the Hide if True Condition was met.
•
In the event of a SQL error, an error message is written to the CA log and the step is marked as
Failed.
•
In the event that the SQL returns a value of the wrong type (numeric as string) ,an error message is
written to the CA log and the step is marked as Failed.
Upon completion of this execution, the template is refreshed and as part of this action filtering of steps
will occur. Filtering of steps by filter query can only occur where all associated Filter Identifier’ s have
been resolved and are not in the Null or no value state. This is true even when only a single FALSE is
required to filter a step.
When a Job is opened or refreshed – the filter query filtering will execute to ensure that all required
filtering has occurred.
Working with Embedded Documentation
Each delivered Change Assistant template comes with embedded documentation to help guide you
through an update or upgrade job, especially for manual steps. Typically, full upgrades have significantly
more documentation than updates.
The documentation for any chapter, task, or step resides in a separate HTM file with the same name as the
template element. A master HTML file stores the compilation of the separate HTM files displayed in an
order matching the template.
When working with Change Assistant documentation, you:
•
Set the documentation directory.
•
View documentation.
•
Create and edit documentation.
•
Finalize documentation.
Setting the Documentation Directory
You set the documentation directory before an upgrade and prior to customizing documentation. The
documentation directory contains the documentation HTM files.
To set the documentation directory:
1. Select Edit, Set Documentation Directory.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
107
Working With Change Assistant
Chapter 5
2. Navigate to the directory where you want to store the documentation.
3. Click Open.
Viewing the Documentation
To view the embedded documentation associated with a particular template element:
1. Select the template node.
2. View the documentation in the documentation box.
To view the compiled documentation:
1. Navigate to the documentation directory.
2. Open the template_name.HTM file.
Creating and Editing Documentation
To create or edit documentation:
1. Select the desired element node.
2. Select Edit, Edit Documentation.
3. In the edit box on the Edit Documentation dialog box, insert your cursor, and add new content or
modify existing content.
Click Attach to incorporate additional files, such as graphics or additional text files. Attaching
files moves that file into the documentation directory and inserts a link to that file in the embedded
documentation.
4. Click OK.
Finalizing Documentation
After modifying any documentation for individual template elements, select Edit, Finalize
Documentation to compile the individual documentation changes into the master HTM file.
Maintaining Change Assistant Directories
After you download and apply change packages, it's not uncommon for there to be a number of files left
in the local Change Assistant directories. This section describes when it's safe to remove the files and
what to consider if you want to remove any of the files.
108
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Directory
Maintenance Consideration
Download
Location where the system stores your downloaded bundles
and change packages. After the updates have been applied
to all environments, you may delete the updates from this
directory.
This can be advantageous when applying change packages
by keeping the list of change packages on the Select Change
Packages page of the Apply Change Packages wizard at a
manageable length.
However, keep in mind that if you delete the updates, and then
you need to recreate another environment, you will need to
download the update again.
Staging
A temporary holding place for files needed during the
application of a change package. It is safe to delete files in this
directory after a change package has been successfully applied
to all target databases.
Output
Contains all the logs related to the processing of a change
package. The files in this directory should be kept as long as it
is feasible in case problems are detected later. The logs contain
valuable information for troubleshooting.
PeopleSoft Update Manager Directory
This is a network share that maps to the PI_HOME share of
the image. Do not delete these files.
PS_HOME\Maint
Contains script files and other files that are only required
during the application of the change package. It is safe to
delete files in this directory after a change package has been
successfully applied.
Running Change Assistant Job from the Command Line
Change Assistant jobs can be run from the command line to automate applying updates to multiple
environments. There are 2 modes available AU and UM.
This section discusses command line parameters based on mode:
•
Update Manager Mode (UM)
•
Traditional Apply Updates Mode (AU)
Update Manager Mode
Update Manager mode supports the following actions:
•
ENVIMP = Import Environment
•
ENVCREATE = Create Environment
•
ENVUPDATE = Update Environment
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
109
Working With Change Assistant
Chapter 5
•
PRPAPPLY = Apply PRP
•
CPAPPLY = Apply Previously Created (non-PRP) Change Package
•
CPCREATE = Create Change Package
•
EMFVAL = Validate EMF Settings
•
OPTIONS = Set General Options
•
PTPAPPLY =Apply a patch to your Current PeopleTools Release
•
PTUAPPLY =Upgrade to a New Release of PeopleTools
Command Line for Running PUM Updates 9.2 and Higher
The action CPAPPLY is used to apply a change package that was created using PUM.
When you run the command line, the error codes are as follows:
•
0 = Success
•
1 = Failure
•
2 = Manual Stop encountered
Command line format:
Changeassistant.exe -MODE UM -ACTION CPAPPLY -TGTENV <target database> –UPD <change⇒
package> -TYPE <initial pass or move to production> -SYNCTYPE <y OR n> -OUT <log f⇒
ile directory> -WARNINGSOK <Y or N> -EXONERR <launch GUI Y or N> -RESETJOB <Y or N>
Example command line:
Changeassistant.exe -MODE UM -ACTION CPAPPLY
-TGTENV HC920001 – UPD PKG1
In this example the target database is named HC920001and the change package to apply is PKG1. All of
the other parameters will use the default.
Parameter
Description
-MODE
Change Assistant mode (Required)
UM
-ACTION
Change Assistant action (Required)
CPAPPLY = Apply Previously Created (non-PRP) Change
Package
-TGTENV
110
Target database
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-UPD
The Change Package to apply. (Required)
Specify either all , a single or multiple Change Packages to
apply to the specified environment.
For example:
-TYPE
-SYNCTYPE
-OUT
•
-UPD all
•
-UPD PKG1
•
-UPD PKG1,PKG2
Apply Type. (Optional)
•
IP = Initial Pass (All steps) (default)
•
MTP = Move to production
•
IPSRC = Source only initial pass
•
IPTGT = Target only initial pass
Synchronize target metadata. (Optional)
•
Y = Yes (default if type is IP)
•
N = No (default if type is not IP)
Path of log file (Optional)
If the log directory is not specified it uses the default defined
under General Options.
-WARNINGSOK
-EXONERR
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Proceed with apply even if warnings are found. (Optional)
•
Y = Proceed with apply even if warnings are found. (
default)
•
N = Stop apply when warnings are encountered.
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
111
Working With Change Assistant
Chapter 5
Parameter
Description
-RESETJOB
Specify whether or not to reset the job if the job fails the first
time it is run.
•
Y = Delete existing job and create a new job
•
N = Do NOT delete existing job and continue running the
existing job. (default)
Command Line for Applying Downloaded PRP to PeopleSoft Update Image
The action PRPAPPLY is used to apply a previously downloaded PRP to the PeopleSoft Update Image.
In order to apply a PRP from the command line, you must run 2 commands, first identify the PUM source
using the Options action and then apply the PRP.
1. This is an example of the command line to set the PUM environment.
Changeassistant.bat -MODE UM -ACTION OPTIONS -SRCYN Y -SRCENV HR92U016 -PUH D:⇒
\psft\pt\pi_home\ -PIA http://edddr32p1.us.oracle.com:8000/ps/signon.html -OUT⇒
d:\temp\PRP.LOG -EXONERR Y
In this example, Configure PUM Source (SRCYN) is set to Y, the PUM Source database (-SRCENV)
is HR92U016 , the PI home directory (-PUH) is set to D:\psft\pt\pi_home\, the PIA URL (-PIA) is set
to http://edddr32p1.us.oracle.com:8000/ps/signon.html.
See the section on Command Line for Setting Options for additional details on setting General
Options.
2. This is an example for applying the PRP.
changeassistant.bat
-MODE UM -ACTION PRPAPPLY -UPD PRJ22534037
In this example the change package to apply isPRJ22534037 (name of the downloaded PRP change
package). All of the other parameters will use the default.
Command line format:
Changeassistant.exe -MODE UM -ACTION PRPAPPLY –UPD <change package> -OUT <log file⇒
directory> -WARNINGSOK <Y or N> -REPLACE <Y or N> -EXONERR <launch GUI Y or N> -RE⇒
SETJOB <Y or N>
Parameter
Description
-MODE
Change Assistant mode (Required)
UM = Update Manager
-ACTION
Action name (Required)
PRPAPPLY = Apply PRP
-UPD
112
Update ID of Change Package to apply. (Required)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-OUT
Path of log file (Optional)
If the log directory is not specified it uses the default defined
under General Options.
-WARNINGSOK
-REPLACE
-EXONERR
-RESETJOB
Proceed with apply even if warnings are found. (Optional)
•
Y = Proceed with apply even if warnings are found. (
default)
•
N = Stop apply when warnings are encountered.
Replace existing data if it exists (Optional)
•
Y = Replace existing values if they exist. (default)
•
N = Do not replace values if they exist
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Specify whether or not to reset the job if the job fails the first
time it is run.
•
Y = Delete existing job and create a new job
•
N = Do NOT delete existing job and continue running the
existing job. (default)
Command Line for Uploading Change Assistant Environments that were
Previously Exported
The action ENVIMP is used to import an environment that was previously exported.
Command line format:
changeassistant -MODE UM -ACTION ENVIMP -FILEPATH <location of xml file> -FILE <xml⇒
file name> -REPLACE <Y or N>
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
ENVIMP = Import Environment
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
113
Working With Change Assistant
Chapter 5
Parameter
Description
-FILEPATH
Location of xml file to be uploaded. (Required)
Example: -FILEPATH C:\pt8.53
-FILE
Name of xml file to be uploaded. (Required)]
Example: -FILE PT903R1.xml
-REPLACE
Replace existing data if it exists (Optional)
•
Y = Replace existing values if they exist. (default)
•
N = Do not replace values if they exist.
Command Line for Creating Environment
The action ENVCREATE is used to create an environment using the command line.
Command line format:
changeassistant -MODE UM -ACTION ENVCREATE -TGTENV <target database> -OUT <log path⇒
> -REPLACE <Y or N> -EXONERR <Y or N> -CT <database type> -CS <database server name⇒
> -OID <owner ID> -UNI <unicode> -CA <access id> -CAP <access id password> -CO <use⇒
r id> -CP <user password> -CI <connect id> -CW <connect id password> -CZYN <Y or N>⇒
-CZ <DB owner> -CZP <DB owner password> -SQH <path to SQL Query tool> -INP <produc⇒
ts> -PL <product line> -IND <industry> -INL <languages> -PSH <path to PS Home> -PAH⇒
<path to PS App Home> -PCH <path to PS Cust Home> -NPYN <Y or N> -NPSH <path to ne⇒
w PS Home> -NPAH <path to new PS App Home> -NPCH <path to new PS Cust Home>
The parameters for ENVCREATE action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
ENVCREATE = Create Environment
-TGTENV
Name of target database. (Required)
-OUT
Path of log file (Optional)
If the log directory is not specified it uses the default defined
under General Options.
114
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-REPLACE
Replace existing data if it exists (Optional)
-EXONERR
•
Y = Replace existing values if they exist. (default)
•
N = Do not replace values if they exist.
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
-CT
Database Type (Required)
-CS
Database Server Name (Optional)
-OID
Owner ID (Optional)
-UDI
Unicode (Required)
•
Y = Yes
•
N = No
-CO
User ID (Required)
-CP
User Password (Required)
-CA
Access ID (Required)
-CAP
Access Password (Required)
-CI
Connect ID (Required)
-CW
Connect Password (Required)
-CZYN
Set DB Owner Credentials (Optional)
•
Y = Yes
•
N = No (default)
-CZ
DBOwner ID (Required if –CZYN is Y)
-CZP
DBOwner Password (Required if –CZYN is Y)
-SQH
SQL Query Tool (Required)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
115
Working With Change Assistant
Chapter 5
Parameter
Description
-INP
Installed Products (Required)
Specify either all , a single or multiple products.
For example:
•
-INP all
•
-INP FMA
•
-INP FMA.REA,SMA
-PL
Product Line (Required)
-IND
Industry (Required)
Specify either all , or a specific industry.
For example:
-INL
•
-IND all
•
-IND Commercial
Languages (Required)
Specify either all , or a specific languages.
For example:
116
•
-INL all
•
-INL ENG,FRA
-PSH
PS Home (Required)
-PAH
PS App Home (Required)
-PCH
PS Cust Home (Required)
-NPYN
Enable new PS Home (Optional)
•
Y = Yes
•
N = No (default)
-NPSH
New PS Home (Required if –NPSH is Y)
-NPAH
New PS App Home (Required if –NPSH is Y)
-NPCH
New PS Cust Home (Required if –NPSH is Y)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Command Line for Updating Environment
The action ENVUPDATE is used to set options using the command line.
The command line for updating the environment uses the same parameters as creating an environment
(ENVCREATE), except -REPLACE is not included.
Command Line for Setting Options
The action OPTIONS is used to set options using the command line.
Command line options are available for the General Options, EM Hub Options, and PUM Source
Options. Additional options are not supported via command line.
Command line format:
changeassistant -MODE UM -ACTION OPTIONS -OUT <path to output log> -REPLACE <Y or N⇒
> -EXONERR <Y or N> -SWP <True or False> -MCP <maximum concurrect processes> -PSH <⇒
path to PS Home> -STG <staging directory> -OD <output directory> -DL <download dire⇒
ctory> -SQH <path to SQL Query tool> -EMYN <Y or N) -EMH <server host name> -EMP <s⇒
erver host port> -EMC <chunck size> -EMPING <ping interval> -EMDRV <drives to crawl⇒
> -SRCYN <Y or N> -SRCENV <PUMsource database name> -PUH <PUM PS Home> -PIA <PUM PI⇒
A URL>
The parameters for OPTIONS action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
OPTIONS = Set General Options
-OUT
Path of log file (Optional)
If the log directory is not specified it uses the default defined
under General Options.
-REPLACE
-EXONERR
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Replace existing data if it exists (Optional)
•
Y = Replace existing values if they exist. (default)
•
N = Do not replace values if they exist.
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
117
Working With Change Assistant
118
Chapter 5
Parameter
Description
-SWP
Show Welcome Menu (Optional)
•
True = Show welcome page
•
False = Do not show welcome page
-MCP
Maximum Concurrent Processes (Optional)
-PCH
PS Home (Optional)
-PAF
PS App Home (Optional)
-PCH
PS Cust Home (Optional)
-STG
Staging Directory (Optional)
-OD
Output Directory (Optional)
-DL
Download Directory (Optional)
-PUH
PeopleSoft Update Directory (Optional)
-SQH
SQL Query Tools (Optional)
-EMYN
Configure EM Hub for file deploy (Optional)
•
Y = Yes
•
N = No (default)
-EMH
Server Host Name (Required if –EMYN is Y)
-EMP
Server Host Port (Required if –EMYN is Y)
-EMC
Chunk Size (Required if –EMYN is Y)
-EMPING
Ping Interval (Required if –EMYN is Y)
-EMDRV
Drives to Crawl (Required if –EMYN is Y)
-SRCYN
Configure PUM Source (Optional)
•
Y = Yes
•
N = No (default)
-SRCENV
PUM Source Database Name (Required if –SRCYN is Y)
-PUH
PUM PS HomDirectory (Required if –SRCYN is Y)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-PIA
PUM Source PIA URL (Required if –SRCYN is Y)
Command Line for Applying PeopleTools Patch
The action PTPAPPLY is used to apply a PeopleTools Patch using the command line.
Command line format:
Changeassistant.exe -MODE UM -ACTION PTPAPPLY -TGTENV <target database> -UPD <chang⇒
e package>
The parameters for applying a PeopleTools patch are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
PTPAPPLY =Apply PTP
-TGTENV
Target environment (Required)
-UPD
Update ID of change package. (Required)]
Example: -UPD PTP85401
-OUT
Path to log file. (Optional)
-WARNINGSOK
Proceed with apply even if warnings are found. (Optional)
-EXONERR
•
Y = Proceed with apply even if warnings are found. (
default)
•
N = Stop apply when warnings are encountered.
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Command Line for Running PeopleTools Upgrade
The action PTUAPPLY is used to upgrade to a new PeopleTools release using the command line.
Command line format:
changeassistant -MODE UM -ACTION PTUAPPLY -TGTENV <target database> -UPD <change pa⇒
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
119
Working With Change Assistant
Chapter 5
ckage> -OUT <path to log file> -WARNINGOK <Y or N> -EXONERR <Y or N>
The parameters for PTUAPPLY action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
PTUAPPLY=Apply PTU
-TGTENV
Target environment (Required)
-UPD
Update ID of change package. (Required)]
Example: -UPD PTU854
-OUT
Path to log file. (Optional)
-WARNINGSOK
Proceed with apply even if warnings are found. (Optional)
-EXONERR
•
Y = Proceed with apply even if warnings are found. (
default)
•
N = Stop apply when warnings are encountered.
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Command Line for Creating Change Package
The action CPCREATE is used to upgrade to a new PeopleTools release using the command line.
Command line format:
changeassistant -MODE UM -ACTION CPCREATE
file> -EXONERR <Y or N>
-UPD <change package> -OUT <path to log ⇒
The parameters for CPCREATE action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
120
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-ACTION
Action name (Required)
CPCREATE =Create Change Package
-UPD
Update ID of change package. (Required)]
Example: -UPD PTU854
-OUT
Path to log file. (Optional)
-EXONERR
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Command Line to Validate EMF Settings
The action EMFVAL is used to upgrade to a new PeopleTools release using the command line.
Command line format:
changeassistant -MODE UM -ACTION EMFVAL -OUT <path to log file>
-EXONERR <Y or N>
The parameters for EMFVAL action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
UM = Update Manager
-ACTION
Action name (Required)
EMFVAL = Validate environment
-OUT
Path to log file. (Optional)
-EXONERR
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Traditional Apply Updates Mode (non-PUM enabled)
CPAPPLY (Apply Change Package) is the only action available for the mode AU (Apply Updates).
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
121
Working With Change Assistant
Chapter 5
Command Line for Non PUM-Enabled Environments
For Non PUM-enabled environments (PeopleSoft Update Image is not available), use the following
command line format:
Changeassistant.exe -MODE AU -ACTION CPAPPLY -ENV <target database> – UPD <change ⇒
package> -FS <file server> -CA <access id> -CAP <access password> -CO <user id> -CP⇒
<user password> -DL <download directory> -BLD <manual or auto> -OUT <log file dire⇒
ctory> -EXONERR <launch GUI Y or N>
Note: EMF Agent must be running.
The parameters for CPAPPLY action are:
Parameter
Description
-MODE
Change Assistant Action (Required)
AU = Apply Updates
-ACTION
Action name (Required)
CPAPPLY = Apply Change Package
-ENV
Target database. (Required)
-UPD
The Change Package to apply. (Required)
Specify either all , a single or multiple Change Packages to
apply to the specified environment.
For example:
-FS
•
-UPD all
•
-UPD PKG1
•
-UPD PKG1,upd222222
File Server path to apply the Change Package to the specific
environment. (Required)
Select either all or list a specific file server configuration path
in order.
For example:
•
-FS all
•
-FS c:\pt8.53
-FS c:\pt8.53,c:\pt8.53–903
-CA
122
Access id for the environment. (Required)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 5
Working With Change Assistant
Parameter
Description
-CAP
Access password for the environment. (Required)
-CO
User id for the environment. (Required)
-CP
User password for the environment. (Required)
-DL
Download directory for the environment. (Optional)
If the directory is not specified it uses the default defined
under General Options.
-BLD
Specify whether to create the Build scripts and execute them
automatically or have the DBA run the scripts automatically. (
Optional)
•
0 = Manual
•
1 = Automatically (default)
-OUT
Path of log file (Optional)
-EXONERR
Specify whether or not to launch GUI if an error or manual
stop is encountered. (Optional)
•
Y = Do not Launch
•
N= Launch (default)
Using a Configuration File with Change Assistant.bat
You can create a configuration file that contains the parameters and then run the command line using
—INI parameter which contains the path to the ini file. For example, if you created an ini file named
config.ini in the C:\temp folder, you would run the following command.
changeassistant.bat -INI C:\temp\config.ini
The ini file needs to contain the General parameters and the parameters specific to the action.
Example ini File for Creating an Environment
[GENERAL]
MODE=UM
ACTION=ENVCREATE
OUT=d:\aaa.log
EXONERR=Y
[ENVCREATE]
TGTENV=T2D85501
CT=2
UNI=Y
CA=emdbo
CAP=emdbo123
CO=PTTRN
CP=PTTRN
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
123
Working With Change Assistant
Chapter 5
CI=people
CW=peop1e
CZYN=N
SQH=D:\psft\db\oracle-server\12.1.0.2\BIN\sqlplus.exe
INP=All
PL=PEOPLETOOLS
IND=ALL
INL=All
INBL=ENG
PSH=D:\PT8.55.04_Client_ORA
PAH=D:\PT8.55.04_Client_ORA
PCH=D:\PT8.55.04_Client_ORA
REPLACE=N
Example ini File for Creating a Change Package
[GENERAL]
MODE=UM
ACTION=CPCREATE
OUT=d:\CREATEPKG4.log
EXONERR=N
[CPCREATE]
UPD=PKG4
124
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Part II
Using Change Assistant with PeopleSoft
Update Manager
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
125
Using Change Assistant with PeopleSoft Update Manager
126
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 6
Understanding Update Manager Action
Update Manager Action Overview
This section provides an overview of the Update Manager action.
Understanding Update Tools
This section describes the tools used in applying updates with the PeopleSoft Update Manager (PUM). In
a typical update process, you will use these tools to:
1. Locate, download, and install the PeopleSoft Update Image for your PeopleSoft application. This is
the PUM Source environment.
2. Set up a Microsoft Windows client with Change Assistant, PeopleTools client and database client
utilities for your environment.
3. Enable the Environment Management Framework on the target environment.
4. Configure Change Assistant with information about the source and target environments, and define a
new change package.
5. Use the PeopleSoft Update Manager PIA Application to search for updates and create a custom
change package.
See Quick Start for a list of steps and links.
PeopleSoft Update Image
PeopleSoft Update Images (PI) are fully functioning instances of the PeopleSoft environment made up of
PeopleSoft deployment packages (DPKs). They can be deployed using Oracle VM VirtualBox to host the
PeopleSoft (DPKS). Alternatively, you can install and configure PeopleSoft environments on Microsoft
Windows or Linux hardware or virtualization platforms using the DPKs. The DPKs that are deployed
using Oracle VM VirtualBox are referred to as "VirtualBox DPK," and those that are deployed directly
onto Microsoft Windows and Linux operating systems are referred to as "Native OS DPK."
Oracle delivers a complete and current PeopleSoft Update Image on a regular schedule for each
PeopleSoft application database instance, for example: FSCM, HCM. The delivery schedules and the PI
will be posted on My Oracle Support (MOS). Customers must download the image and deploy the image
locally before they can run Update Manager or create a custom change package.
The most current PeopleSoft Update Image will be delivered on the most current PeopleTools release. It
is not necessary to upgrade PeopleTools on your target environment in order to use the current Image. The
PeopleSoft Update Image supports multiple releases.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
127
Understanding Update Manager Action
Chapter 6
Note: It is recommended that customers download PeopleSoft Update Images when they are available,
this will avoid the need to do a large download when a current image is needed to resolve a critical
production issue.
The PeopleSoft Update Manager Home Page( My Oracle Support, Document 1641843.2) is the central
location for all things related to PeopleSoft Update Manager (PUM) and PeopleSoft Update Images (PIs).
•
Hardware and Software Requirements are available from the left-hand side of the PeopleSoft Update
Manager Home Page.
•
The PeopleSoft Update Image Home Pages tab provides links for you to locate the PeopleSoft Image
and additional information for your application.
The Update Image Homepage for your application will contain links to all the relevant information
for the PI you are downloading. The Installation Documentation section on the page contains a link to
PeopleSoft Deployment Packages Installation (PeopleSoft PeopleTools 8.55).
•
The Best Practices provides information to help you plan for and determine the maintenance strategy
and best practices your organization.
See Installing PeopleSoft Update Imageand Configuring the Microsoft Windows Client Running Change
Assistant.
Change Assistant
Install Change Assistant on the Microsoft Windows client machine. The Update Manager action in
Change Assistant is used to:
•
Upload Target Database information to the PeopleSoft Update Image, including products and
maintenance logs. Once the database information is uploaded, the database will be available in
PeopleSoft Update Manager as a target database.
•
Create a custom change package based on the change package definition created in PUM. Since
Change Assistant has all of the target database information, this custom change package is
automatically filtered for database platform and installed products.
•
Apply updates to the target database.
•
Create the reconciled or modified change package that can then be applied without compare into all
other customized environments, assuming these customized environments are at the same release/
patch level.
•
Deploy updates to additional target environments using the reconciled change package.
•
Update PeopleSoft Update Image with PeopleSoft Release Patchsets (PRP).
•
Apply change package for PeopleTools patch.
•
Apply change package for new PeopleTools release.
•
Apply application upgrade.
See Opening Change Assistant the First Time
128
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 6
Understanding Update Manager Action
Environment Management Framework (Optional)
Environment Management Framework (EMF) gathers and publishes configuration and setup information
about the file servers, the web servers, the application servers, the individual hosts, and the PeopleSoft
Process Scheduler servers that comprise your PeopleSoft system. Change Assistant uses the information
gathered by EMF to identify the available target databases when applying updates.
Configuring and running EMF is optional, EMF is only required to automate the file deploy process. If
EMF is not configured and running, you will need to deploy files manually when you apply an application
update.
See Configuring the Environment Management Hub
PeopleSoft Update Manager PIA Application
The PeopleSoft Update Manager PIA application runs on the PeopleSoft Update Image (PI) virtual
machine. The Update Manager Dashboard provides pivot grids to determine the current status of your
target databases and also provides folders with links to the Update Manger pages. The Define Change
Package folder contains links to wizards that will lead you through the process of selecting updates and
defining custom change packages for your environment. It provides a wide array of search options for
selecting the updates to apply to your environment. It lets you review the details of the changes for each
update before creating the change package definition, shows you what has already been applied to your
environment, and automatically includes requisite updates based on what you selected and what is already
applied to your environment.
Once the Target information has been uploaded to the PI, you can directly signon to the PI at any time to
search for updates and create change package definitions without using Change Assistant. However, when
you access Update Manager PIA application directly, the maintenance log details of that target will not be
updated. Target database details are updated when:
•
The task Upload Target Database Information to PUM Source is run.
•
The step SyncDatabaseInfoToPUMSource in the change package template is executed.
Note: This step is included in the change package if the option Synchronize Target Metadata
(Requires Source) is selected on the Change Package Settings page when apply the update.
Change Assistant is updated when:
•
The database is defined.
•
The step SyncDatabaseInfoToCA in the change package template is executed.
When you are ready to create and apply the change package, the change package definition will be
available from Change Assistant.
Change Packager
Change Packager is the software update tool that will automatically create your change package based
on the change package definition. For change packages defined using PeopleSoft Update Manager PIA
application, the change packager is invoked automatically by Change Assistant when you select to apply
the change package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
129
Understanding Update Manager Action
Chapter 6
Understanding Update Manager Action
Update Manager Action includes the following sections:
•
Update Manager Tasks
These are the tasks associated with defining and applying application updates from the PeopleSoft
Update Image. The tasks include:
•
•
Validate Change Assistant EMF Settings
•
Upload Target Database Information to PUM Source
•
Define or Create New Change Package
•
Apply Change Package
•
Apply Translation Delta Package
•
Apply Downloaded PeopleSoft Release Patchset to PeopleSoft Update Image
Application Upgrade Tasks
Upgrade to New Application Release
•
PeopleTools Tasks
These are the tasks associated with applying PeopleTools patches and upgrades. The tasks include:
•
Apply a Patch to Your Current PeopleTools Release
•
Upgrade to a New Release of PeopleTools
•
Apply Tools Delta Package
Validate Change Assistant EMF Settings
EMF is used with the Update Manager action to identify the file servers for your target environment. If
you configured the EM Hub option for your environment, use this to validate the EMF settings.
Upload Target Database Information to PUM Source
The Upload Target Database Information to PUM Source is used to upload the target database information
to the PeopleSoft Update Image, including products and maintenance logs. Once the database information
is uploaded, the database will be available in PeopleSoft Update Manager as a target database.
Note: In previous releases of Change Assistant, the target information was uploaded to the
PUM source when you were creating a new change package in Change Assistant or when the
PUMMaintenanceLogSync step was executed in Change Assistant. The PUMMaintenanceLogSync step
has been replaced by the steps SyncDatabaseInfoToPUMSource and SyncDatabaseInfoToCA.
Define or Create a New Change Package
The Define or Create a New Change Package option is used to:
130
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 6
Understanding Update Manager Action
•
Define your target databases in Change Assistant and open a browser session to the PeopleSoft
Update Image database (PUM source).
•
Define change package definition using PeopleSoft Update Manager PIA application on the
PeopleSoft Update Image.
•
Create the change package in Change Assistant.
•
Apply the change package to the target database.
See Defining a New Change Package,
Apply Change Package
The Apply Change Package option is used to:
•
Apply the custom change package to a target environment.
•
Apply custom change package to additional target environments.
See Applying Change Package
Apply Translation Delta Package
The Apply Translation Delta Package option is used to:
•
Apply translation delta package to a target environment.
•
Apply translation delta package to additional target environments.
Apply Downloaded PeopleSoft Release Patchset to PeopleSoft Image
The Apply Downloaded PeopleSoft Release Patchset to PeopleSoft Update Image is used to apply
PeopleSoft Release Patches (PRP) to the PeopleSoft Update Image.
See Applying Downloaded PeopleSoft Release Patchset to PeopleSoft Image
Upgrade to New Application Release
The Upgrade to New Application Release is used to upgrade to application 9.2.
Apply a Patch to Your Current PeopleTools Release
PeopleTools patches deliver fixes between PeopleTools minor releases. PeopleTools patches are posted to
My Oracle Support, as they become available. PeopleTools patches are cumulative. They include all fixes
from all previous patches for the specified release.
A PeopleTools patch contains the PeopleTools binaries and database changes. The database changes
are delivered in a change package located in the PS_HOME\PTP directory. The Apply a Patch to Your
Current PeopleTools Release option is used to apply this change package.
Upgrade to a New Release of PeopleTools
A PeopleTools upgrade consists of the new PeopleTools release and PeopleTools upgrade change package
that contains all the database changes. After installing the new release and downloading the upgrade
change package, this option is used to apply the upgrade change package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
131
Understanding Update Manager Action
Chapter 6
Apply Tools Delta Package
The Apply Tools Delta Package option is used to:
•
Apply the tools delta package to a target environment.
•
Apply the tools delta package to additional target environments.
See Creating and Applying Tools Delta Package
132
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target
Environments
Installing PeopleSoft Update Image
To prepare your environment, you must install the PeopleSoft Update Image and configure the client
machine that runs PeopleSoft Change Assistant to communicate with the PI.
To install the PeopleSoft Update Image see PeopleSoft Deployment Packages Installation (PeopleSoft
PeopleTools 8.55).
Configuring the Microsoft Windows Client Running Change
Assistant
Change Assistant needs to be run from a Microsoft Windows client. It is highly recommended that you
dedicate a Microsoft Windows client machine that is not used for other PeopleSoft purposes for each
PeopleSoft Update Image (PI). It is necessary to configure this Microsoft Windows client machine
to access your target environment, as well as the PI. This setup is necessary for Change Assistant to
communicate with the PI and target databases in 2-tier mode in order to correctly install updates.
In setting up the Microsoft Windows client, be sure to review the software versions listed on the My
Oracle Support home page for the PI you are using, as these will impact your setup.
Note: This documentation uses "release/patch" to refer to the PeopleSoft PeopleTools release, for
example, 8.54, and patch number, for example 06. This release/patch example is written as 8.54.06.
The Microsoft Windows client needs to include:
•
Oracle Database Client at a version level that is certified for the PeopleSoft PeopleTools release
included on the PI.
See My Oracle Support, Certifications
•
Database Client for target database platform (if the target RDBMS is not Oracle).
•
For a target database that is not Oracle, you must always install the database client for your
database platform.
•
For a target database that is Oracle, it may be necessary to install a second Oracle Database Client
if the target database is not at the same PeopleTools release level as the PI.
For example, PeopleTools 8.53 uses a 32–bit client and PeopleTools 8.54 requires a 64–bit client.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
133
Setting Up the Client, Source, and Target Environments
•
Chapter 7
PeopleTools Client for Oracle database platform at the same version level of the PI.
Note: The PeopleTools client will work with all your target databases that are on the same
PeopleTools release as the PI in carrying out PUM-enabled maintenance as long as the PeopleTools
client is installed from the tools_client shared drive. If your target database is on a different
PeopleTools release, you will need to install a second PeopleTools Client for that PeopleTools release.
•
PeopleTools Client for target database platform at a version level supported by the PI.
Note: The supported PeopleTools client installer is available in the tools_client share. It is not
necessary to upgrade the target database to the supported PeopleTools release patch level. The target
database will work with the PeopleTools client.
•
Change Assistant installed from the PS_HOME directory for the PeopleSoft Update Image on the
Microsoft Windows client.
Note: This use of PS_HOME refers to the location created by the client installation. You may need
more than one client PS_HOME location, when you configure the Microsoft Windows Client. This
documentation also uses "PS Home" in some cases to match the syntax on the Change Assistant UI.
After you install and initialize the PI, you access a shared drive which makes the folders from the image
accessible to the host (Microsoft Window OS).
From Windows Explorer access the virtual appliance file system from your Microsoft Windows host by
selecting Start, Run, and entering the Microsoft Windows UNC path containing your virtual machine IP
address.
Image: Microsoft Windows Run dialog box with IP address
This example illustrates the fields and controls on the Microsoft Windows Run dialog box with IP
address.
The shared drive includes 2 folders:
134
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target Environments
Image: Shared Drive Folders
This example illustrates the fields and controls on the Shared Drive Folders. You can find definitions for
the fields and controls later on this page.
The pi_home folder contains all files needed for patching.
The tools-client folder includes the following:
•
client-853
The client-853 folder includes a Readme file, a manifest with version information, archives, and
scripts for deployment of the PeopleSoft PeopleTools 8.53 client home folder.
•
client-854
The client-854 folder includes a Readme file, a manifest with version information, archives, and
scripts for deployment of the PeopleSoft PeopleTools 8.54 client home folder.
•
client-855
The client-855 folder includes a Readme file, a manifest with version information, archives, and
scripts for deployment of the PeopleSoft PeopleTools 8.55 client home folder.
•
oracle-client
The oracle-client folder includes a Readme file, a manifest with version information, archives, and
scripts for deployment of the Oracle 12c database client home folder.
•
SetupPTClient.bat — Interactive script that installs the PeopleSoft PeopleTools components such as
Application Designer and Change Assistant.
You supply information such as the PeopleSoft PeopleTools release and the RDBMS platform.
•
source.properties — A text file that includes information required for the setup. Do not edit this file.
The information is supplied by the setup scripts.
•
tnsnames.ora — Oracle database connectivity file. The file includes the information for the source
(PI) database.
Configuring the Microsoft Windows Client Configuration
You will use the SetupPTClient.bat file to configure the client. When you run the setup script, you will be
prompted for information about your environment.
For detailed information on the setting up the client see PeopleSoft Deployment Packages Installation
(PeopleSoft PeopleTools 8.55).
The script uses the information you supplied and carries out the following validations and deployments:
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
135
Setting Up the Client, Source, and Target Environments
Chapter 7
•
Oracle 12c database client for the Update Image source database (PI). The setup process determines
whether a 64-bit Oracle 12c database client is present on the Microsoft Windows client machine for
connectivity to the source database. If not, the setup process installs it.
•
Oracle 12c database client for the target database. If the target is an Oracle database, the setup process
determines whether the correct Oracle database client is present. PeopleSoft PeopleTools 8.55 and
8.54 require a 64-bit Oracle 12c database client installation. PeopleSoft PeopleTools 8.53 requires the
32-bit Oracle 12c database client. If the correct Oracle database client is not present, the setup process
installs it.
•
PeopleSoft PeopleTools Client for the source (PI). The source client tools are installed in C:
\Peoplesoft\PSHOME\Client<release_number>, where <release_number> refers to the PeopleSoft
PeopleTools release and patch, such as 8.55.02.
•
PeopleSoft PeopleTools Client for the target. The target client tools are installed in C:\Peoplesoft
\PSHOME\Client<release_number>, .where <release_number> refers to the PeopleSoft PeopleTools
release and patch, such as 8.54.14.
•
Change Assistant installation Change Assistant is installed in C:\Program Files\Peoplesoft\Change
Assistant. If there is an earlier Change Assistant installation on the machine, the setup script removes
it.
Understanding the Microsoft Windows Client Configuration
After running the SetupPTClient, you will need to update the tnsnames.ora file located in your
oracle_home directory with the tnsname entry from the tools_client folder. If your target database is also
Oracle, you will also need to add the target databases tnsnames entry. To update the tnsnames.ora file:
1. Open the tnsnames.ora file in the tools_client directory.
2. Copy the entry in the tnsnames.ora file to the tnsnames.ora file located in your oracle_home directory.
Depending on your installation, the location of the tnsname.ora file in the oracle_home directory
will vary. If you installed the oracle client using SetupPTClient, the tnsnames.ora file is located in
oracle_home\network\admin\tnsnames.ora; for example: C:\oracle\product\12.1.0\client_1\network
\admin\tnsnames.ora:
3. If your target database is on Oracle, copy the tnsnames entry for your target database into the
tnsnames.ora file
The location of the tnsnames.ora file will vary depending on the Windows client installation. If
SetupPTClient detects an existing Oracle DB Client 12c with 64-bit installation, it will use that
version of Oracle Database, if SetupPTClient needs to install the DB Client 12c , the default location
is: C:\oracle\product\12.1.0\client_1.
The tnsnames entry for your target databases must use the SERVICE_NAME in order for your
PeopleTools or Change Assistant clients to connect to the PUM source database within the 12c
database server. This is an example of the entry:
PT855GA1 =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = hostname.domain)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = PT855GA1)
)
136
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target Environments
)
4. Save the file.
This table describes the Windows client configuration based on the database client and PeopleTools
release of the target environment.
Target Environment
Microsoft Windows client machine
install
PS Homes on Microsoft Windows
Client Machine
Oracle database on PeopleTools
8.53
1.
Oracle database 32-bit client
2.
Oracle database 64-bit client.
For this scenario you will have two client PS
Homes — one on PeopleTools 8.53 and one
on PeopleTools 8.55.
3.
PeopleTools 8.53.xx client.
4.
PeopleTools 8.55 client
5.
Enter the tnsnames entry into the
tnsnames.ora file.
See Example Target Environment on Oracle
Database PeopleTools Release 8.53
Oracle database on PeopleTools
8.54
1.
Oracle database 64-bit client
2.
PeopleTools 8.54 client
3.
PeopleTools 8.55 client
4.
Enter the tnsnames entry into the
tnsnames.ora file.
For this scenario you will have two client PS
Homes — one on PeopleTools 8.54 and one
on PeopleTools 8.55.
See Example Target Environment on Oracle
Database PeopleTools Release 8.54
Oracle database on PeopleTools
8.55
1.
Oracle database 64-bit client
2.
PeopleTools 8.55 client
3.
Enter the tnsnames entry into the
tnsnames.ora file.
For this scenario you will have one client PS
Home that is used by both the source and the
target.
See Example Target Environment on Oracle
Database
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
137
Setting Up the Client, Source, and Target Environments
Chapter 7
Target Environment
Microsoft Windows client machine
install
PS Homes on Microsoft Windows
Client Machine
Non-Oracle database on
PeopleTools 8.53
1.
Oracle database 64-bit client
2.
Install target database client from the
target environment and set up database
connectivity.
For this scenario you will have two PS
Homes—one for the source (Oracle
RDBMS) at PeopleTools release 8.55
and one for the target (non-Oracle) at
PeopleTools release 8.53.
3.
PeopleTools 8.55 client
Note: The PeopleTools install is for
Oracle database platform.
4.
PeopleTools 8.53 client
Note: The PeopleTools install is for your
target database platform.
5.
Enter the tnsnames entry into the
tnsnames.ora file.
See Example Target Environment Not on
Oracle Database
Non-Oracle database on
PeopleTools 8.54
1.
Oracle database 64-bit client
2.
Install target database client from the
target environment and set up database
connectivity.
3.
PeopleTools8.55 client
For this scenario you will have two PS
Homes—one for the source (Oracle
RDBMS) at PeopleTools release 8.55
and one for the target (non-Oracle) at
PeopleTools release 8.54.
Note: The PeopleTools install is for
Oracle database platform.
4.
PeopleTools8.54 client
Note: The PeopleTools install is for your
target database platform.
5.
Enter the tnsnames entry into the
tnsnames.ora file.
See Example Target Environment Not on
Oracle Database
138
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target Environments
Target Environment
Microsoft Windows client machine
install
PS Homes on Microsoft Windows
Client Machine
Non-Oracle database on
PeopleTools 8.55
1.
Oracle database 64-bit client
2.
Install target database client from the
target environment and set up database
connectivity.
For this scenario you will have two PS
Homes — one for the source (Oracle
RDBMS) and one for the target (nonOracle).
3.
PeopleTools 8.55 client
Note: The PeopleTools install is for
Oracle database platform.
4.
PeopleTools8.55 client
Note: The PeopleTools install is for your
target database platform.
5.
Enter the tnsnames entry into the
tnsnames.ora file.
See Example Target Environment Not on
Oracle Database
Example Target Environment on Oracle Database PeopleTools Release 8.53
If your target database is on Oracle database and PeopleTools 8.53, you will have 2 PS Homes and 2
Oracle clients.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
139
Setting Up the Client, Source, and Target Environments
Chapter 7
Image: Target Database on PeopleTools 8.53 and database platform is Oracle
This diagram illustrates the relationship between the Microsoft Windows client running Change Assistant
and the PI when your target database is on PeopleTools 8.53 and the database platform is Oracle.
Example Target Environment on Oracle Database PeopleTools Release 8.54
If your target database is on Oracle database and PeopleTools 8.54, you will have 2 PS Homes and 1
Oracle client.
140
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target Environments
Image: Target Database on PeopleTools 8.53 and database platform is Oracle
This diagram illustrates the relationship between the Microsoft Windows client running Change Assistant
and the PI when your target database is on PeopleTools 8.54 and the database platform is Oracle.
Example Target Environment on Oracle Database
If your target database is on Oracle database and PeopleTools 8.55, you will have 1 PS Home and 1
Oracle client.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
141
Setting Up the Client, Source, and Target Environments
Chapter 7
Image: Target Environment on Oracle Database
This diagram illustrates the relationship between the Microsoft Windows client running Change Assistant
and the PI when your target database platform is Oracle.
Example Target Environment Not on Oracle Database
When the target environment is not on Oracle database, you will always have 2 PS Homes and 2 database
clients (one for Oracle and one for the target database platform). The PS Home for the PUM Source
database will be on PeopleTools 8.55 and the Target PS Home will be on the same release as the target
database.
142
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 7
Setting Up the Client, Source, and Target Environments
Image: Target Environment Not on Oracle Database
This diagram illustrates the relationship between the Microsoft Windows client running Change Assistant
and the PI when your target database is not Oracle.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
143
Setting Up the Client, Source, and Target Environments
144
Chapter 7
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
Selecting Update Manager Action
The Update Manager action is used to selectively apply updates (bug fixes, patches, enhancements or new
features) to your system. Before you can select this action, the following prerequisites must be configured
and installed.
1. Download the latest PeopleSoft Update Image (PI) from My Oracle Support and install it locally.
See
2. Configure the Microsoft Windows Client running Change Assistant.
See Installing PeopleSoft Update Image and Configuring the Microsoft Windows Client Running
Change Assistant
Setting Up Target Environment
To set up the target environment:
•
Configure the Environment Management Framework (EMF) for your environment.
EMF is required for the file deploy feature. This feature will automatically deploy files in change
packages to different servers.
Note: If Environment Management Framework is not configured, the file deploy steps will be
excluded from the change package and any files included in the change package will require manual
deployment.
Change Assistant 8.55 is compatible with EMF on all releases.
See Configuring an Environment Management Agent
•
Start the EMF Agent on the target environment.
To verify that the EMF Agent is running, enter the hubURL into a browser. You should see a window
with a message similar to this: "Sending pulse from 'com.peoplsoft.emf.peer: id 1'"
See Running an Environment Management Agent
•
Set user ID access.
In Change Assistant, the user ID for the target database needs to have Full data admin access
defined for Build/Data Admin on the Tools Permissions page for PeopleTools on one of the assigned
permission lists. With the Full data admin access permission assigned, Change Assistant has access to
all the build and copy options. Application Data Set (ADS) objects represent another security issue,
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
145
Using Update Manager Action
Chapter 8
because they contain actual rows of application data and there may be instances where this data is not
suitable for compare or copy. In order to compare and copy ADS definitions, the user ID must have
Full Access to compare and copy defined on the Copy Compare Permissions page for Data Migration
on one of the assigned permission lists.
See "Setting PeopleTools Permissions" (PeopleTools 8.55: Security Administration), "Setting Data
Migration Permissions" (PeopleTools 8.55: Lifecycle Management Guide), and Administering
Projects
Starting Change Assistant
To start Change Assistant:
1. Select Start, Programs, PeopleSoft Change Assistant 8.55.xx, where xx refers to the release/patch
number.
2. Depending on your preferences, you may or may not see a Welcome dialog box. If the Welcome
dialog box is displayed, click Next.
The Select Action page is displayed.
Image: Change Assistant Wizard - Select Action page
This example illustrates the fields and controls on the Change Assistant Wizard - Select Action page.
3. Select Update Manager and click Next.
Note: You must select Update Manager for PUM-enabled maintenance.
Configuring Change Assistant for Update Manager
If this is the first time you are selecting Update Manager, the Wizard will guide you through the
environment setup. As you click Next you will complete the following pages:
1. General Options
2. PUM Source Options
3. EM Hub Options
146
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
4. Additional Options
5. Select Task
Note: After the environment has been configured, you can use Tools, Options to make any changes to the
environment options.
Change Assistant settings can be exported and imported, therefore the options only need to be set once.
See Exporting and Importing Change Assistant Settings.
General Options
Image: Change Assistant – General Options page
This example illustrates the fields and controls on the Change Assistant – General Options page. You can
find definitions for the fields and controls later on this page.
Maximum Concurrent Processes
Specifies the maximum number of processes that can be
executed concurrently on the local machine. The default is 1.
PS Home Server Starting Port
Specify the port number for the first PS Home server.
Change Assistant uses this port number to communicate with
Change Assistant PS Home servers. The default starting port
number is 6151. If you enter a port number that is already
in use, you see an error message. You must change to a port
number that is not in use, and then restart Change Assistant for
the change to take effect.
PS Home Server Maximum Instances Enter a number between 1 and 10 for the maximum number of
PS Home servers.
Use this value for environments with more than one PS_HOME.
For each server instance, Change Assistant increments the PS
Home Server Starting Port number by 1 up to the maximum
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
147
Using Update Manager Action
Chapter 8
number of instances. For example, with a PS Home Server
Starting Port value of 6151 and a PS Home Server Maximum
Instances value of five, the port numbers would be 6151, 6152,
6153, 6154, and 6155. The default is 5.
If you change this value, you must restart Change Assistant for
the change to take effect.
PS Home
Enter the full path in which you installed PeopleTools client on
the Windows Client machine.
Note: Specify the PS_HOME location you used to install
Change Assistant.
Staging Directory
Enter the directory in which you would like to stage all the
Change Assistant update files. This is the location that Change
Assistant will store files to be used during the apply update
process.
Output Directory
Enter the directory in which you want the log files generated by
the update process to reside.
Download Directory
Enter the full path of the location to which you want to
download your change packages.
SQL Query Tool
Select the correct executable for the database platform that
matches the PS_HOME defined for CA.
Note: The SQL Query tool must align with the installed Change
Assistant version..
This value is used as the default when creating databases. Each
database contains separate settings and therefore, you can
change this executable for a specific database.
Valid SQL query executables for each platform are:
•
DB2: db2cmd.exe
•
Microsoft SQL Server: sqlcmd.exe
•
Oracle: sqlplus.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.
148
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
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.
PUM Source Options
Image: Change Assistant - PUM Source Options page
This example illustrates the fields and controls on the Change Assistant - PUM Source Options page. You
can find definitions for the fields and controls later on this page.
Define PUM Source
Select this checkbox to define the PUM Source.
Note: Not all Change Assistant actions require a PUM Source.
PUM Source Database
If the database has already been defined, it will be available
from the drop-down list. After you select a database that has
already been configured, the database information on the
remainder of the page will be displayed in read-only mode.
If the database has not been defined yet, click Create which will
launch the Database Wizard.
When defining the PUM Source database, keep the following
points in mind:
•
PS Home for the PUM Source database is the PeopleTools
client installed from the tools_client share for Oracle
database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
149
Using Update Manager Action
Chapter 8
•
PUM Source does not use PS App Home or PS Cust Home,
however you must include the path, use the same path as PS
Home.
•
The SQL Client Tool for the PUM Source is the SQL PLUS
executable that aligns with the installed Change Assistant
version. For example, Change Assistant on PeopleTools 8.
55, uses the 64–bit version of sqlplus.exe.
See Defining Databases
PUM(PI_HOME) Directory
Enter the path to the pi_home share on the PI. The pi_home
share contains all files needed for patching.
Note: The drive is a path mapped to the pi_home share folder.
PUM Source PIA URL
Enter the URL to sign on to the PUM Source.
When you click OK, Change Assistant will validate the connection to the PUM Source database.
EM Hub Options
Use this page to configure the EM Hub options for the target database.
Image: Change Assistant - EM Hub Options page
This example illustrates the fields and controls on the Change Assistant - EM Hub Options page. You can
find definitions for the fields and controls later on this page.
Configure EMHub For Deploy File
Select this checkbox if you want to use EMHub for file deploy.
Note: In order to use this option EMF must be configured and
running.
Server Host Name
150
The hostname of the server in which the Environment
Management HUB resides.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
Server Host Port
Indicates the port in which to connect to the Environment
Management hub.
Chunk Size
Used for deploying files during a software update. Default is
1024 * 1024 bytes. Typically this does not need to be changed
unless there are a significant number of files greater that
1024KB in a software update.
Ping Interval
Ping interval is in milliseconds for Change Assistant to contact
the hub for new messages.
Drives to Crawl
Setting of drives to crawl to identify the configuration of the
Change Assistant machine. Windows directories need to use
the forward slash (/) character. Include your local drive in this
setting so that Change Assistant can locate the SQL Query tool
used for automating steps. Also include the path of the SQL
Query tool.
Note: For PUM-enabled applications Change Assistant EM
Hub is only used to deploy files. Change Assistant uses the SQL
Client Tools path defined for the database definition. If you
receive a validation error when applying changes packages that
EMF did not find any SQL Query Tools, you can ignore it.
Ping
Click to verify a valid server URL. If you see Service is off to
the right of this button, then you must correct the server URL
and ping again until you see Service is on.
Note: This button is visible only if your display is set to
Windows Classic style. To change the Windows display,
select Programs, Control Panel, Display. Select the change
the Windows display, select Programs, Control Panel, Display.
Select the Appearance tab and choose Windows Classic style
from the Windows and buttons drop-down list.
View
Click to display the list of all PeopleSoft components discovered
and registered in the Environment Management Hub.
Note: This button is visible only if your display is set to
Windows Classic style.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
151
Using Update Manager Action
Chapter 8
Additional Options
Image: Change Assistant - Additional Options page
This example illustrates the fields and controls on the Change Assistant - Additional Options page. You
can find definitions for the fields and controls later on this page.
Notification Settings Section
152
Send Email Notifications
Select this check box to receive email notifications if there are
errors in the update process. Change Assistant also sends you
a completion message when it encounters a Stop in the update
process.
SMTP Server
Enter the SMTP mail server from which you receive the error or
completion messages.
Port
Enter the port from which you want to access the email.
Send To
Enter the address to which you want the email sent.
Return Address
Enter the email address of the sender. Use this to identify who
sent the notification.
Test
Validates that email is sent to the designated recipients and is
working correctly.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
Note: Ensure that your SMTP server is installed and configured
correctly.
Proxy Section
Host
(Optional) Enter the name of the proxy server if you want to run
Change Assistant behind the firewall using a proxy server.
Port
(Optional) Enter the port number for the proxy server.
Anonymous Proxy
Indicates that you are using a proxy server that does not require
authenticated connections.
Microsoft Proxy Server
Indicates that you are using a proxy server with Windows
authentication.
Windows Domain
The network domain in which the system runs.
Other Proxy Servers
Indicates you are using non-Microsoft proxy servers.
Select Task
Image: Change Assistant Wizard - Select Task page
This example illustrates the fields and controls on the Change Assistant Wizard - Select Task page. You
can find definitions for the fields and controls later on this page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
153
Using Update Manager Action
Chapter 8
Depending on the options configured, some tasks may be not be enabled. For example if EM Hub is not
defined, Validate Change Assistant EM Settings will be grayed out.
Validate Change Assistant EMF
Settings
Select to validate the settings. Change Assistant validates
settings by:
•
Locating valid SQL query tools required to run SQL scripts.
•
Testing the Environment hub and ensuring Change Assistant
can communicate with it.
Upload Target Database Information Select to upload the target database information to the PUM
to PUM Source
source database.
Once the database information is uploaded, the database will be
available in PeopleSoft Update Manager as a target database.
Define or Create a New Change
Package
Select to open the Wizard that will guide you through the
process of creating a custom change package with the updates
you select.
See Defining a New Change Package
Apply Change Package
Select after the custom change package has been created to
apply the change package to your target database.
See Applying Change Package
Apply Downloaded PeopleSoft
Select to apply a PRP to the PeopleSoft Update Image.
Release Patchset to PeopleSoft Image
See Applying Downloaded PeopleSoft Release Patchset to
PeopleSoft Image
Upgrade to New Application Release Select to upgrade your target database to a new application
release.
See Upgrading Application
Apply a Patch to Your Current
PeopleTools Release
Select to apply a PeopleTools patch change package.
Upgrade to a New Release of
PeopleTools
Select to apply a new release of PeopleTools change package.
Export/Import Change Assistant
Settings
Select to export or import Change Assistant Settings.
See Using Change Assistant to Apply PeopleTools Patch
See Using Change Assistant to Upgrade PeopleTools
See Exporting and Importing Change Assistant Settings
From this page, you also have the ability to go directly to other pages by selecting the radio button on the
left:
154
Welcome Page
Select to go to the Welcome page.
Select Action
Select to go to the Select Actions page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
General
Select to go to the General Options page.
PUM Source
Select to go to the PUM Source Options page.
EM Hub Options
Select to go to the EM Hub Options page.
Additional
Select to go to the Additional Options page.
Select Task
This radio button is selected by default to lead you through the
wizard for the option selected on the right.
Validating Change Assistant EMF Settings
After you have set up and configured Change Assistant and the Environment Management components,
you should validate your Change Assistant and environment settings. To validate your environment:
1. Select the Validate Settings radio button.
2. Click Finish.
3. Click Start Validation.
When the validation is complete, a completion message appears. To view the log, click the View Log
button. The log will contain information about any steps that were not successful.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
155
Using Update Manager Action
Chapter 8
Image: Validating Change Assistant Settings in Your Environment dialog box
This example illustrates the fields and controls on the Validating Change Assistant Settings in Your
Environment dialog box.
Note: SQL Query Tool discovered by EM Hub is only used for traditional (non-PUM enabled) updates. If
you receive a validation error for the SQL Query Tool, you can ignore it.
Defining Target Database
The Define Database page is used to define all databases. See Defining Databases.
When defining the target database to use with PUM, make sure that the various PS homes are properly
configured based on your database platform and release.
Important! You only need to define the database once. When you install a new instance of Change
Assistant the existing settings can be maintained. See Exporting and Importing Change Assistant Settings.
PS Home
Ps Home needs to be set to the PeopleTools release/patch for your target database.
When you set up your windows environment, you may have installed 2 PS Homes. One for Oracle on the
PUM image release/patch, which is used for the PUM Source PS Home and one for your target database
156
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
platform at the supported release/patch level for your target environment. Make sure you select the PS
Home for your target environment.
PS App Home
PS App Home is the location where you installed your PeopleSoft application files for your target
environment. If you needed to install a new PS Home to use with the PUM image, it will not contain your
application files. Make sure you select the path where your application files reside.
PS Cust Home
If you are using PS_CUST_HOME (PeopleSoft Customization Home) to identify and store your site's
customized files, you need to specify the path PS Cust Home.
Uploading Target Database Information
In order to use the Update Manager actions, the PUM Source must contain all of the information about
your target database. The upload may take several minutes. This information includes:
•
Database name
•
Database user defined in Change Assistant for this database.
Note: Change Packages are associated with both database and user ID. The user ID on the target
database must match the user ID used to signon to the PUM source in PIA when you create a define a
change package.
•
Products
•
Languages
Note: If you have multiple target databases with different languages, you will need to install separate
PeopleSoft Update Images for each language combination.
To upload the target database information:
1. In Change Assistant, select Tools, Change Actions.
2. Select Update Manager and click Next.
3. Select Upload Target Database Information to PUM Source and click Finish.
Note: The PUM Source must be defined before this option is available to select.
4. Select or Create the target database to upload.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
157
Using Update Manager Action
Chapter 8
Image: Upload Target Database Information to PUM Source page
This example illustrates the fields and controls on the Upload Target Database Information to PUM
Source page. You can find definitions for the fields and controls later on this page.
Target Database
Select an existing target database or create a new target database
using the Create button.
See Defining Databases
Upload Target Database Information This check box is always selected and read only. This option
to PUM source
upload the target database information to the PUM Source.
Update Target Database Information This check box is always selected and read only. This option
in Change Assistant Environment
updates Change Assistant with the target database information.
Proceed to Define or Create a New
Select this check box to open the Define or Create a New
Change Package Wizard after Target Change Package Wizard after target information is uploaded.
Information Upload
Note: After upgrading the target database tools release, it is necessary to update the target database in
Change Assistant and upload the upgraded target database information to the PeopleSoft Update Image
database. In Change Assistant, select File, Open Database and update the target database. After updating
the target database, select Tools, Upload Target Database Information to PUM Source.
158
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 8
Using Update Manager Action
Defining a New Change Package
In order to define a new change package, the following steps must be completed:
•
PUM Source Database defined.
•
Target Database defined.
•
Target Database uploaded to the PUM Source.
See Selecting Update Manager Action
Use the Define or Create a New Change Package action to create the custom change package definition.
To define a new change package:
1. In Change Assistant, select the Update Manager action.
The Update Manager action is available from:
•
The menu by selecting Tools, Change Actions.
•
Clicking Next on the Welcome page.
2. Select Define or Create a New Change Package and click Finish.
3. Click the Click Here to Open Browser and Connect to PUM Source Database.
Use the PeopleSoft PIA application to create the change package definition. See Defining Custom
Change Packages
4. After you create the change package definition in the PUM PIA application, return to this page in
Change Assistant and the package will be available from the drop down.
5. Select the package to create the change package and click Finish.
The Change Package Wizard will generate the change package. When the package is created you will
receive a message indicating the change package was successfully created.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
159
Using Update Manager Action
Chapter 8
Image: Define or Create a New Change Package page
This example illustrates the fields and controls on the Define or Create a New Change Package page. You
can find definitions for the fields and controls later on this page.
Click Here to Open Browser
and Connect to the PUM Source
Database
Click to open the browser and sign on to the PeopleSoft Update
Image database.
Download Directory
When the change package definition is defined on the PUM
Source, it will be downloaded to the directory indicated here. By
default the download directory defined for Change Assistant is
used.
Change Package
All change package definitions that have been created with the
PUM process will be available in the drop down list. Select the
change package to work with.
Note: Change package definitions that were not created with the
PUM process are not included in this list.
Proceed to Apply Change Package
Wizard after Package Creation
Select this check box to proceed to the apply the apply Change
Package Wizard when the change package is created.
If you want to review the change package or make some
changes to the template, leave this check box deselected.
160
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
Update Manager Dashboard Overview
The Update Manager Dashboard provides a central location for all update tasks. The dashboard provides
analytics for PUM (PeopleSoft Update Manager) that assist in determining your current level of
maintenance. The various pivot grids provided on the dashboard, provide access into the maintenance
logs and bug information for each database uploaded to the PeopleSoft Update Image.
Image: Update Manager Dashboard
This example illustrates the fields and controls on the Update Manager Dashboard. You can find
definitions for the fields and controls later on this page.
By default the Update Manager Dashboard has four tiles:
1. Bug by Target Database pivot grid
2. Bug Status by Product pivot grid
3. Bug Status by Image pivot grid
4. Bug Status by Tag pivot grid
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
161
Using Update Manager Dashboard
Chapter 9
The left navigation pane of the Update Manager Dashboard provides links to Update Manager features
and pages. When you select a link from the left navigation pane, the corresponding page appears in the
target content area. The following folders make up the Update Manager Dashboard.
Folders
Description
Select Target Database
This folder contains a list of all the target database that have
been uploaded to the PUM Source. When you select a database
Push Notifications is used to refresh the four Pivot Grid tiles in
the dashboard.
See Using PeopleSoft Update Manager (PUM) Analytics
Define Change Package
This folder contains links to the various types of change
packages.
See Defining Change Package
Update Manager Utilities
This folder contains links to Update Manager utilities.
See Using Update Manager Utilities
Customization Repository
This folder contains links to the tasks necessary to manage the
customization repository.
See Understanding Customization Repository
Test Repository
This folder contains links to the tasks necessary for managing
test repository.
See Understanding Test Repository
Information for working with and customizing Dashboards is provided elsewhere in PeopleTools product
documentation. See the product documentation for PeopleTools 8.55: Using PeopleSoft Applications
Using PeopleSoft Update Manager (PUM) Analytics
The Update Manager Dashboard provides analytics for PUM (PeopleSoft Update Manager) that assist
in determining your current level of maintenance. The Update Manager Dashboard is available on the
PeopleSoft Update Image. The various pivot grids provided on the dashboard, provide access into the
maintenance logs and bug information for each database uploaded to the PeopleSoft Update Image.
By default the Update Manager Dashboard has four tiles:
1. Bugs by Target Database pivot grid
2. Bug Status by Product pivot grid
3. Bug Status by Image pivot grid
4. Bug Status by Tag pivot grid
Bugs are categorized by into four distinct groups:
•
162
Applied Bug Fixes for installed products
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
All bug fixes that have been applied to the target database for installed products.
•
Applied Bug Fixes for non-installed products
All bug fixes that have been applied to the target database for non-installed products.
•
Unapplied Bug Fixes for installed products
Use the unapplied bug fixes for installed products to determine how far behind the target database is
compared to the current PeopleSoft Update Image. If there are no unapplied bug fixes for installed
products, the target database is current.
•
Unapplied Bug Fixes for non-installed products
Unapplied bug fixes for non-installed products will not have any effect on target database.
To display analytics for a specific target database:
1. Expand the Select Target Database folder and click the link for the database to display.
2. Click on one of the pivot grid tiles to open Pivot Grid Viewer.
3. Use the Show Filters icon to display the available filters on the left-hand side of the pivot grid.
4. Click the Percent column in the grid to view the bug detail. The bug detail is presented in a
spreadsheet that can be downloaded or used to cut and paste.
Note: If no bugs have been delivered for a given product code, the percentage applied will be 100%
on the grid, however the bug detail spreadsheet will not show any bugs.
BUGs by Target Database
This pivot grid displays the status of all installed products. Use the filters to determine what bugs need to
be applied.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
163
Using Update Manager Dashboard
Chapter 9
Image: BUG Status by Target Database
This example illustrates the fields and controls on the BUGs by Target Database pivot grid. In this
example, the pivot grid is filtered to show the status of all installed products for database CUSTPI06.
BUG Status by Product
This pivot grid displays the status of all installed products. Use the filters to determine what bugs need to
be applied.
164
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
Image: BUG Status by Product
This example illustrates the fields and controls on the BUG Status by Product pivot grid. In this example
the filter was changed to show unapplied bugs.
BUG Status by Tag
This pivot grid displays bug status by tag. Tag types will vary depending on the application. Use the
filters to narrow down the search.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
165
Using Update Manager Dashboard
Chapter 9
Image: BUG Status by Tag
This example illustrates the fields and controls on the BUG Status by Tag pivot grid. This example
displays all applied bugs by tag.
BUG Status by Image
This pivot grid displays the bug status by Image, which can be used to track your maintenance strategy.
166
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
Image: BUG Status by Image
This example illustrates the fields and controls on the BUG Status by Image pivot grid. This example
shows a database that went live on image 6.
Note: When filtering the Bug Status by Image pivot grid, select only one Product Status at a time.
Bug Detail Spreadsheet
When you click the link in the Percent column for a product, the list of bugs meeting the criteria will be
displayed in a spreadsheet.
Note: If no bugs have been delivered for a given product code, the percentage applied will be 100% on
the grid, however the bug detail spreadsheet will not show any bugs.
You can download the spreadsheet to Excel, as a CSV text file or as an XML file to assist in identifying
the bugs to apply to your target database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
167
Using Update Manager Dashboard
Chapter 9
Image: PTIA_BUG_PRODUCT_DETAIL- BUGS by Product Details
This example illustrates the fields and controls on the PTIA_BUG_PRODUCT_DETAIL- BUGS by
Product Details. This is an example of the spreadsheet displayed for unapplied bugs for product HCM
Human Resources.
Modified Object List for a Bug
To drill down to the modified objects list for a bug, click the bug number link in the BUG column.
Image: PTIA_BUG_MOL_DETAIL- BUG MOL Details
This example illustrates the fields and controls on the PTIA_BUG_MOL_DETAIL- BUG MOL Details.
168
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
Defining Change Package
There are 4 types of change packages that can be created:
1. Change Package
The Define Change Package component is a wizard that will lead you through the process of selecting
updates and defining a custom change package for your environment. It provides a wide array of
search options for selecting the updates to apply to your environment. It lets you review the details
of the changes for each update before creating the change package definition, shows you what has
already been applied to your environment, and automatically includes requisite updates based on what
you selected and what is already applied to your environment.
Note: Required for Upgrade (RFU) bugs are included in the Upgrade package.
See Defining Custom Change Packages
2. Upgrade Package
The Define Upgrade Package component is a wizard that will create an upgrade package based on
the upgrade path specified. When you select this option 2 change package definitions are created the
upgrade package (UPG) and the Required for Upgrade package (RFU).
3. Tools Delta Package
The Define Tools Delta Package component is a wizard that is used after a PeopleTools upgrade to
create a Tools delta change package that contains attributes or objects that were stripped away when
the updates were applied in the old release.
See Creating and Applying Tools Delta Package
4. Translation Delta Package
The Define Translations Delta Package component is a wizard that will lead you through the process
of selecting the languages and translation fixes and create a translation delta package.
Using Update Manager Utilities
Update Manager Utilities include:
•
Review Change Package
•
Delete Change Package
•
About PeopleSoft Image
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
169
Using Update Manager Dashboard
Chapter 9
Reviewing Change Package
Navigation
Select PeopleTools, Lifecycle Tools, Update Manager Dashboard, Update Manager Utilities, Review
Change Packages
You can also select the Review Package Definition link on the Define Change Package Step 6 of 6 page.
Image: Review Change Packages page
This example illustrates the fields and controls on the Review Change Packages page. You can find
definitions for the fields and controls later on this page.
The Review Change Package page is display only to provide information on the change package.
Incomplete packages will not display all of the fields.
Package Status
Search Scope
170
Indicates the current status of the package.
•
Incomplete - the change package has not been created in
Change Assistant.
•
Complete - the change package has been created in Change
Assistant.
Indicates the scope used to create the change package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
Depending on the scope selected, additional information is
displayed.
Dependency Calculation
Indicates which type of dependency calculation used to create
the change package (Standard or PostReq's Included).
Show Template
For change packages that are complete, use this link to view the
steps in the change package template.
Bugs in this Package
For change packages that are complete, you see a grid
displaying the bug in the change package, with a flag indicating
the selected bugs.
Modified Objects in this Package
For change packages that are complete, you see a grid listing the
modified objects.
Customizations
Expand this section to view the names of the customizations
included in this package.
Tests
Expand this section to view the test names included in this
package.
Components
Expand this section to view the components to test for this
package.
Show Template
Click Show Template on the Review Change Packages page to open the Change Package Template
window listing the chapters, tasks, steps, and step scripts in the change package template.
Image: Change Package Template
This example illustrates the fields and controls on the Change Package Template.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
171
Using Update Manager Dashboard
Chapter 9
Deleting Change Packages
Navigation
Select PeopleTools, Lifecycle Tools, Update Manager Dashboard, Update Manager Utilities, Delete
Change Packages
Image: Delete Package Definition page
This example illustrates the fields and controls on the Delete Package Definition page. You can find
definitions for the fields and controls later on this page.
Package Name
Search by package name.
Database Name
Search by database name.
Package Status
Search by package status. Package statuses are:
Package Type
172
•
Complete
•
Imported
•
Incomplete
•
Package Created
Search by package type. Package types are:
•
Application Upgrade
•
Tools Delta Package
•
Required for Upgrade
•
Translations Delta Package
•
Updates
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 9
Using Update Manager Dashboard
The Select Package Definitions to Delete grid will list all the change packages that meet the selection
criteria. Select the change packages to delete and click the Delete Selected button.
About PeopleSoft Image
Use the About PeopleSoft Image page to display information about the PeopleSoft Image.
Navigation
Select PeopleTools, Lifecycle Tools, Update Manager Dashboard, Update Manager Utilities, About
PeopleSoft Image
Image: About PeopleSoft Image page
This example illustrates the fields and controls on the About PeopleSoft Image page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
173
Using Update Manager Dashboard
174
Chapter 9
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 10
Managing Customization Repository
Understanding Customization Repository
The customization repository provides a way to assist customers in managing customizations when
selecting updates in the PUM Search. The customization repository includes:
•
Customization repository in the PUM Image.
•
Visualization of customization impact in the PUM Search.
•
Ability to take action based on identified customization impacts.
•
Customization Repository persistence mechanism.
See Migrating PUM Data
Creating Customization Repository
The customization repository resides on the PUM Source. In order to create the repository, you must
first identify all of the customizations that you want to track in the target databases and then upload
the customization projects to the PUM Source. The customization projects apply across all your target
databases.
1. Create a project on the customer database that includes your customizations.
Note: You can create as many customization projects as required.
The following methods are available to create the customization projects:
•
In Application Designer create a project by manually adding the managed objects you have
identified as customizations.
You can use the UPGCUST project from your last upgrade.
Note: This method can be used for target databases on PeopleTools release 8.53, 8.54 and 8.55.
•
Create the project using PJRCUST, using one of theses options:
•
In Change Assistant use the step Create Customization Project to create the project.
See Step Types
•
Create the project using the command line PJRCUST.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
175
Managing Customization Repository
Chapter 10
See "Creating Customization Project Using the Command Line" (PeopleTools 8.55: Lifecycle
Management Guide)
Important! Your target database must be on PeopleTools 8.55 to use PJRCUST.
2. Copy the customization project to file.
3. Use Change Assistant to upload the customer data to PUM Source.
4. Review the upload on the PUM Source.
5. Run the Test Coverage Calculation on the PUM Source.
See Run Customization Calculation
Uploading Customer Data to Image
To upload custom project to Image:
1. In Change Assistant, select Tools, Upload Customer Data to Image.
Image: Upload Customer Data to Image page
This example illustrates the fields and controls on the Upload Customer Data to Image page. You can
find definitions for the fields and controls later on this page.
2. By default the Import Customer Metadata into PUM Source checkbox is selected.
3. Select your PUM Source database.
Use the Create button to define the PUM Source database if it has not been defined in Change
Assistant yet.
4. By default, the Managed Object Project(s) is selected.
176
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 10
Managing Customization Repository
5. Click Add Project.
6. Select the Project Content. For the customization repository, the project content must be
Customization Impact - All Objects.
7. Select the directory and project, then click Open.
Add as many projects as required.
8. Click Import.
Using Customization Repository
Once customizations have been uploaded to the PUM Source, the Update Manager Dashboard provides
the following components to manage the customizations:
1. Manage Customizations
2. Manage Customized Objects
3. Run Customization Calculation
Customization Repository
The Customization Repository is used to identify the relationships to customized objects before the
change package is created. The Customization Repository is delivered empty on the PUM Source and
must be populated using Change Assistant to upload the customer data.
To access the Customization Repository page, select PeopleTools, Lifecycle Tools, Update Manager
Dashboard, Customization Repository, Manage Customizations .
Image: Manage Customizations page
This example illustrates the fields and controls on the Manage Customizations page. You can find
definitions for the fields and controls later on this page.
Customization Name
By default, this the name of the customization project that was
uploaded to the PUM Source using Change Assistant. You can
have 0–n customizations defined. Each defined customization
must have a unique customization name.
Description
Use this field to provide a more detailed description of the
customization.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
177
Managing Customization Repository
Include in Package
Chapter 10
Specify whether bug fixes which impact the specified
customization should be, by default, included or excluded from
change package creation.
•
No – exclude from package creation
•
Yes (default) – include in package creation
Note: This value can be overridden in the PUM Search.
Adding Customizations
To manually add customizations, use the + action in the grid. When this method is used, a new row is
added, however no objects will be associated with the new row. Use the Customized Objects page to add
the objects. See Manage Customized Objects
Rows can also be added by uploading customer data through Change Assistant. See Creating
Customization Repository
Deleting Customizations
To delete a customization, use the – (delete row) action in the grid, you will be prompted that the delete
will also delete all references at the object level to this customization.
If a customization is deleted, the customization calculation must be re-run to ensure that the correct
metadata exists in the database.
Manage Customized Objects
The Managed Customized Objects page contains a list of the customized objects. The same object may
exist in more than one customization.
Navigation
To access the Manage Customized Objects page, select PeopleTools, Lifecycle Tools, Update Manager
Dashboard, Customization Repository, Manage Customized Objects .
178
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 10
Managing Customization Repository
Image: Managed Customized Objects page
This example illustrates the fields and controls on the Managed Customized Objects page. You can find
definitions for the fields and controls later on this page.
Filter By
Use the Filter By editbox to display customizations for a
specific customization name.
Object Type
Specifies the managed object type.
Object Value 1–4
These 4 columns are the same 4 key columns used to identify a
managed object in PUM and managed object projects.
Customizations
Displays the customization count. Click the count link to open
the Add/Delete Customization References page.
Deleting Objects
To delete an object or objects, select one or more objects from the grid and click the Delete Selected
button. This will delete all customization references for that object.
Adding and Deleting Customization References
To add or delete customization references, click the count link.. This will open the Add/Delete
Customization Reference page. The list of customizations to add to an object is limited to the list of
customizations defined in the Customization Repository.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
179
Managing Customization Repository
Chapter 10
Image: Add/Delete Customization References page
This example illustrates the fields and controls on the Add/Delete Customization References page.
To add a reference:
1. Click the Add a row icon (+).
2. Select an existing Customization Name using the Lookup icon.
Note: Customization Names are defined in the Customization Repository.
3. Click OK.
Note: If a customization reference is added, the Customization Calculation must be rerun.
To delete a reference:
1. Click the Delete a row icon (+).
2. Click OK to delete the row.
3. Click OK.
If only one row exists in the Add/Delete Customization References page, the reference cannot be deleted
from this page, it would need to be deleted from the Managed Customized Objects page.
Note: If a customization reference is deleted, the Customization Calculation must be rerun.
Run Customization Calculation
In order to manage and display the customization impact in the PUM Search UI, a customization
calculation must be generated for each bug fix in the Image. The Customization Calculation page is used
to run the calculation for the customizations identified in the Customization Repository.
180
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 10
Managing Customization Repository
Navigation
To access the Run Customization Calculation page, select PeopleTools, Lifecycle Tools, Update Manager
Dashboard, Customization Repository, Run Customization Calculation .
Image: Run Customization Calculation page
This example illustrates the fields and controls on the Run Customization Calculation page.
Click the Run Customization Calculation button to update the bug calculations.
Note: If no data exists in the Customization Repository, then there is no customization impact and the
Run Customization Calculation button will be grayed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
181
Managing Customization Repository
182
Chapter 10
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 11
Managing Test Repository
Understanding Test Repository
The test repository provides awareness for mapping tests to bug fixes when selecting updates in the PUM
search. The test repository includes:
•
Test repository in the PUM Source.
•
Visualization of test impact in the PUM Search.
•
Ability to take action based on identified test impacts.
•
Test Repository persistence mechanism.
See Migrating PUM Data
Creating Test Repository
The test repository resides on the PUM Source. In order to create the repository, you must first identify
the components or tests that you want to track in the target databases in a project and then upload the
metadata to the PUM Source. The test projects apply across all your target databases.
Test information is uploaded to the PUM Source in Change Assistant. Depending on the type of test
project uploaded the following occurs:
•
PTF Tests
Change Assistant will read the test metadata and determine all of the components associated with
the test. The test information metadata is uploaded to the test repository by test name. The test object
reference will display the all the tests associated with the component.
•
Components
For customer who do not use PTF, you can create projects that contains components. The test
information (component names) is uploaded to the test repository using the project name. The test
name will be the same as the project name.
Note: It is not necessary to use PTF in order to use the test repository. Test impact is calculated based on
components.
1. Create a project on the customer database that includes your components or tests.
Note: You can create as many test projects as required.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
183
Managing Test Repository
Chapter 11
2. Copy the test project to file.
3. Use Change Assistant to upload the customer data to PUM Source.
4. Review the upload on the PUM Source.
5. Run the Test Coverage Calculation on the PUM Source.
Uploading Customer Data to Image
To upload test project to Image:
1. In Change Assistant, select Tools, Upload Customer Data to Image.
Image: Upload Customer Data to Image page
This example illustrates the fields and controls on the Upload Customer Data to Image page. You can
find definitions for the fields and controls later on this page.
2. By default the Import Customer Metadata into PUM Source checkbox is selected.
3. Select your PUM Source database.
Use the Create button to define the PUM Source database if it has not been defined in Change
Assistant yet.
4. By default, the Managed Object Project(s) is selected.
5. Click Add Project.
6. Select the directory and project, then click Open.
Add as many projects as required.
7. Select the Project Content. For the test repository, the project must be either Test Impact – Test
Objects or Test Impact — Component Objects.
184
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 11
Managing Test Repository
8. Click Import.
Using the Test Repository
Once test projects have been uploaded to the PUM Source, the Update Manager Dashboard provides the
following components to manage the test repository:
1. Manage Tests
2. Manage Test Objects
3. Run Test Coverage Calculation
Manage Tests
The Test Repository is used to identify the relationship between tests and components before the change
package is created. For PTF customers, this would be the same as the Test Coverage Report, however it is
available when selecting updates in the PUM Search. The Test Repository is delivered empty on the PUM
Source and must be populated using Change Assistant to upload the customer data.
To access the Manage Tests page, select PeopleTools, Lifecycle Tools, Update Manager Dashboard, Test
Repository, Manage Tests .
Image: Manage Tests page
This example illustrates the fields and controls on the Manage Tests page. You can find definitions for the
fields and controls later on this page.
Test Name
For PTF tests, this is the name of the test. For component
projects, this is the name of the project.
You can have 0–n test defined. Each defined test must have a
unique test name.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
185
Managing Test Repository
Chapter 11
Description
Use this field to provide a more detailed description of the test.
Include in Package
Specify whether bug fixes which impact the specified test
should be, by default, included or excluded from change
package creation.
•
No – exclude from package creation
•
Yes (default) – include in package creation
Note: This value can be overridden in the PUM Search.
Include Bugs that Reference
Components Without Associated
Tests in Package
Select Yes to include the bugs in the change package even if the
component does not have an associated test.
Select No if you want 100% test coverage for the package.
Adding Tests
To manually add tests, use the + action in the grid. When this method is used, a new row is added,
however no objects will be associated with the new row. Use the Define Test Object Reference page to
add the objects. See Managing Test Objects.
Rows can also be added by uploading customer data through Change Assistant. See Creating Test
Repository.
Deleting Tests
To delete a tests, use the – (delete row) action in the grid.
If a test is deleted, the test coverage calculation must be re-run to ensure that the correct metadata exists in
the database.
Managing Test Objects
The Manage Test Objects page contains a list of the test objects. The same object may exist in more than
one test.
Navigation
To access the Manage Tests Objects page, select PeopleTools, Lifecycle Tools, Update Manager
Dashboard, Test Repository, Manage Test Objects.
186
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 11
Managing Test Repository
Image: Manage Test Objects page
This example illustrates the fields and controls on the Manage Test Objects page. You can find definitions
for the fields and controls later on this page.
Filter By Name
Use the Filter By editbox to select a test name and display all
the components associated with that test.
Object Type
The object type is Component.
Object Value 1–4
These 4 columns are the same 4 key columns used to identify a
managed object in PUM and managed object projects.
Tests
Displays the test count. Click the count link to open the Add/
Delete Test Coverage page, which displays the test names
associated with the component.
To delete a component, select the component on the grid and click Delete Selected.
Adding and Deleting Tests
To add or delete test coverage, click the count link. This will open the Add/Delete Test Coverage page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
187
Managing Test Repository
Chapter 11
Image: Add/Delete Test Coverage References page
This example illustrates the fields and controls on the Add/Delete Test Coverage References page. You
can find definitions for the fields and controls later on this page.
Use the + (add row) icon to add a test. The list of tests to add to a component is limited to the list of tests
defined in the Test Repository.
Use the – (delete row) icon to delete a test from the component.
Running Test Coverage Report
In order to manage and display the test impact in the PUM Search UI, a test coverage calculation must be
generated for each bug fix in the Image. The Test Coverage Calculation page is used to run the calculation
for the components identified in the Test Repository.
Navigation
To access the Run Test Coverage page, select PeopleTools, Lifecycle Tools, Update Manager Dashboard,
Test Repository, Run Test Coverage Calculation
188
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 11
Managing Test Repository
Image: Test Coverage Calculation page
This example illustrates the fields and controls on the Test Coverage Calculation page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
189
Managing Test Repository
190
Chapter 11
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA
Applications
Defining Custom Change Packages
The latest PeopleSoft Update Image downloaded from MOS includes the PeopleSoft working database,
PeopleTools, applications, managed objects, codeline, and the data and metadata required to use the
PeopleSoft Update Manager. The Update Manager PIA interface is used to identify required and desired
updates for the change package definition.
The Define Change Package wizard will guide you through the steps to create a change package
definition. There are 6 steps:
1. Select Target Database
Note: The target database is selected from the Select Target Database folder on the Update Manager
Dashboard. This page is only displayed when no target databases have been up loaded.
2. Enter Change Package Name
3. Select Scope
4. Select the updates, objects or criteria
Based on the scope selected in step 3, appropriate page will open to select your updates. If you select
All Updates Not Yet Installed in step 3, this step is skipped.
5. Review Bugs
6. Done Identifying Bugs
Dependency Calculator
When the user transitions from Step 4 to Step 5 the dependency calculator is automatically executed.
•
The calculator is a PeopleCode Program.
•
If you selected to select by Specific Updates, Updates by Criteria, or Updates by Object Name, the
dependency tree is calculated such that bugs that are Already Applied, and the post-requisites of
those same bugs are excluded from the package during the calculation process. Un-applied prerequisites of applied bugs will, however, be included in the calculated result.
•
If you selected All Updates Not Yet Installed, the calculator will insert all updates that have not been
applied in the selected target environment into the results table.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
191
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Note: All requisite updates are specific to and calculated based on the target database. If the change
package is reused for another database, Change Assistant will perform a check to ensure all requisites
exist. If requisites are missing, you will get an error message.
Languages
If your target database contains multiple languages, the first time you select to create a change package
the system will prompt to install the languages on the PeopleSoft Image.
Image: Install Languages page
This example illustrates the fields and controls on the Install Languages page. You can find definitions for
the fields and controls later on this page.
This example shows 3 languages that need to be installed for the target database. Enter the Access ID and
Access Password and click OK. A status bar is displayed as the languages are installed. When the install
is complete, click OK.
Define Change Package Wizard Step 1 of 6
Custom change packages are created on to your PUM Source Database.
Navigation
On to your PUM Source Database, select PeopleTools, Lifecycle Tools, Update Manager, Update
Manager Dashboard, Select Target Database
192
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
All environments that were selected as target databases in Change Assistant Wizard and uploaded to the
PUM Source will be displayed in the list. This list is also filtered by UserID.
Image: Select Target Database
This example illustrates the fields and controls on the Select Target Database.
Note: The target database information is uploaded to the PUM source database when you select the
Upload Target Database Information to PUM Source. See Uploading Target Database Information
If you only have one database, it is selected by default..
Define Change Package Wizard Step 2 of 6
Navigation
Open the Define Change Package folder and select Define Change Package.
The second step is to enter a change package name.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
193
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Image: Define Change Package Step 2 of 6
This example illustrates the fields and controls on the Define Change Package Step 2 of 6. You can find
definitions for the fields and controls later on this page.
Package Name
Package Description
Enter a name for your custom change package. To edit an
existing change package, select the Lookup button. The list of
change packages that can be edited is restricted as follows:
•
Packages created by the current user.
•
Packages created for the currently selected target database.
•
Packages which have been defined but have not been
created.
Enter a description for the change package.
Click Next.
If the package name already exists, the Change Package Options page will be displayed.
Change Package Options
On the Change Package Options page, you can select whether to edit or replace the change package.
194
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
Image: Change Package Options page
This example illustrates the fields and controls on the Change Package Options page. You can find
definitions for the fields and controls later on this page.
Edit
Select this option to edit the existing change package. The
search results previously entered are retained.
Replace
Select this option to replace the existing change package.
Cancel
Select this option to cancel and select a new name for the
change package.
Define Change Package Wizard Step 3 of 6
The third step is to select the scope to use for searching for updates.
Image: Define Change Package Step 3 of 6
This example illustrates the fields and controls on the Define Change Package Step 3 of 6. You can find
definitions for the fields and controls later on this page.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
195
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Note: Regardless of the option you choose, all available and not yet applied requisite updates for the bugs
selected will be included in the change package.
All Other Search Criteria
Select this option to perform a selective search.
All Updates Not Installed
Select this option to take all of the available updates and get
current.
Selecting All Other Search Criteria
Select the All Other Search Criteria radio button and click Next.
Image: Define Change Package Step 4 of 6
This example illustrates the fields and controls on the Define Change Package Step 4 of 6. You can find
definitions for the fields and controls later on this page.
The search process is iterative. Once you have selected bugs into the search results gird, you can select
another search option and add additional bugs to the search result grid. Search and selection can be
performed in any order, the results are recalculated with each search.
True Requisites
When you select this option, the Search by True Post Requisites
page is displayed. Users can use the Search button to display the
post requisite bugs. Users have the option to select or deselect
the bugs in the grid.
If there are no unapplied true requisites for the target database,
this option will be grayed out and not selectable.
196
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
New Features
Using PeopleSoft Update Manager PIA Applications
Select this option to search for new features.
Note: This option is equivalent to using the Advanced Search
option in PeopleTools 8.54 and selecting the tracking group
Enhancement with the value Enhancement.
Translations Only
When you select this option you see a field that allows you to
select a language.
If the target database is English Only, this link will be greyed
out and not selectable.
Tax Updates
Select this option to search for tax updates.
If there are no unapplied tax updates for the target database, this
link will be greyed out and not selectable.
Specific Updates
Select this option to search for updates related to specific Bug
IDs.
Specific Objects
Select this option to search for updates related to specific
PeopleSoft managed objects.
Prod/Severity/Image
Select this option to search for updates by various criteria such
as Product, Severity, or Image.
Other Criteria
Other criteria covers any tracking groups for the application that
are not covered in another search, such Legislative/Regulatory,
Multi-instance, or PeopleTools Compatibility.
Tracking groups will differ by product.
If there are no unapplied other criteria for the target database,
this link will be greyed out and not selectable.
Advanced Options
Select this link to set the dependency calculation.
See Using Advanced Options Page
Selecting Specific Updates
Select the Specific Updates link.
Note: Specific updates can be combined with bugs using any of the other search criteria options.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
197
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Image: Search by Updates page
This example illustrates the fields and controls on the Search by Updates page. You can find definitions
for the fields and controls later on this page.
Enter Multiple Bug Numbers
Use this link to open a model window where you can enter the
specific bugs. Use a comma or space to separate Bug numbers.
Bug Number
Use the lookup icon to select specific bugs. Add additional rows
as needed.
Product
The product from the bug will be displayed as read only.
Subject
The subject from the bug will be displayed as read only.
Image: Find these specific Bugs page that opens when Enter Multiple Bug Numbers is selected
This example illustrates the fields and controls on the Find these specific Bugs page that opens when
Enter Multiple Bug Numbers is selected.
Once you have selected the updates, click Next.
Selecting Updates by Prod/Severity/Image
Select the Prod/Severity/Image link.
198
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
Image: Product/Severity/Image Search page
This example illustrates the fields and controls on the Product/Severity/Image Search page. You can find
definitions for the fields and controls later on this page.
The Product/Severity/Image Search page, enables you to search for updates by:
•
Product Family
Allows you to select one or more values.
A Product Family is a grouping of products. This grouping is defined by PeopleSoft, and is intended
to align with the “Bundle” groupings in non-PUM enabled application updates.
Note: Product Family = PNA will select all fixes for Payroll North America (equivalent to a PNA Tax
Update in prior releases),
Product Family = Global Payroll will select all fixes for Global Payroll products (equivalent to a GP
Update Bundle in prior releases).
•
Installed Products
You can select if you want to include related components and subcomponents and then select the
installed products to search. A related component or subcomponent is a defined relationship between
products. This relationship is defined by PeopleSoft, and is intended to assist the search experience
by including the related products automatically when a given product is selected.
•
Severity
Select the severity:
•
1 - Complete loss of service
•
2 - Severe loss of service
•
3 - Minimal loss of service
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
199
Using PeopleSoft Update Manager PIA Applications
•
Chapter 12
Image Number
When you select this option you see drop-down lists for From PI and To PI. Enter a range of image
numbers to include in the search.
The minimum allowed value is image 1.
Image: Example Search by Severity
This example illustrates the fields and controls on the Product/Severity/image Search page, where the
severity of Complete Loss of Service was selected.
200
Show Already Applied Updates
Select this check box to include already applied updates in the
result set. If this check box is selected, a visual indicator will
appear in the Applied column.
Bug Number
Lists the bug numbers returned by the search.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
Subject
Displays the subject for the bug.
Applied
A visual indicator will be displayed, if the Show Already
Applied check box is selected and the bug has already be
applied to the target database.
This bug is not included in the change package definition.
True Post Req
True post-requisite updates will be sorted to the top of the bug
list. A visual indicator is displayed to identify the bug as true
post requisite.
All bugs discovered based on the Post Requisites for (Select)
Previously Applied bugs will be listed as suggested.
Custom Impact
A visual indicator will be displayed if the bug has an impact on
an object stored in the Customization Repository.
See Using Customization Repository
Test Exists
A visual indicator will be displayed if the bug has an impact on
tests defining in the Test Repository.
See Using the Test Repository
Details
Click this icon to display the bug details.
Selecting Specific Objects
The Specific Objects link, enables you to search for updates related to specific PeopleSoft objects. Select
an object type and enter an object name. For example, you can search for the PERSONNEL record and
see all of that record’s related fixes.
To search for updates related to specific PeopleSoft objects:
1. Select an object type from the drop-down list.
2. Enter an object name.
For example, you can search for the records that start with JOB and see all of that records that start
with JOB.
3. Optionally, deselect the Hide Objects of Applied Bugs if you want to see objects matching your
criteria that have already been applied.
4. Click Find.
After clicking the Find button, the grid displays your query output; in this instance, the specific
PeopleSoft objects related to your search criteria.
5. Select the check box next to each object in the result grid that you want to search for.
6. Click the Search for Bugs button.
7. By default all bugs returned in the grid will be selected.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
201
Using PeopleSoft Update Manager PIA Applications
Chapter 12
You can manually deselect a bug or use the Clear All button to clear all the selections and then
manually select the bugs to include.
8. Optionally, select the Show Already Applied Updates check box to include bugs that have already
been applied to the target database or environment.
Image: Search by Objects page
This example illustrates the fields and controls on the Search by Objects page. You can find definitions
for the fields and controls later on this page.
Selecting Tax Updates
Select the Tax Updates link.
202
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
Image: Tax Updates Search page
This example illustrates the fields and controls on the Tax Updates Search page. You can find definitions
for the fields and controls later on this page.
Tax or Regulatory Update
When you select this option you see a drop-down list for Tax or
Regulatory updates available.
Image Number
When you select this option you see drop-down lists for From
PI and To PI. Enter a range of image numbers to include in the
search.
Selecting New Features
Select the New Features link.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
203
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Image: New Features Search page
This example illustrates the fields and controls on the New Features Search page. You can find definitions
for the fields and controls later on this page.
There are 2 filter options to assist in the search for new features, Installed products and Image Number.
These filters are optional and if you click Search for Bugs with no filters, all matching rows will be
returned.
Installed Products
When you select this checkbox, the installed products are
displayed and available to select.
Image Number
When you select this option you see drop-down lists for From
PI and To PI. Enter a range of image numbers to include in the
search.
Selecting Other Criteria
Other Criteria allows you to search by tracking group and image. Tracking Groups are defined by
PeopleSoft on an as required basis in order to facilitate the search for fixes of a specific, often functional,
type. Tracking groups will differ by product.
Select the Other Criteria link.
204
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Using PeopleSoft Update Manager PIA Applications
Image: Search by Criteria
This example illustrates the fields and controls on the Search by Criteria. You can find definitions for the
fields and controls later on this page.
Tracking Group
Select the Tracking Group name and value.
Image Number
Select the Image Numbers to search.
Using Advanced Options Page
Use this page to set the dependency calculation. The package dependency calculation can optionally
include or exclude the post requisites of fixes that have previously been applied to your target database
Image: Advanced Options page
This example illustrates the fields and controls on the Advanced Options page. You can find definitions
for the fields and controls later on this page.
Yes
Include Post Requisites of Already Applied Bug Fixes
The full Dependency Tree is calculated prior to checking
whether bug fixes included in the calculation have previously
been applied to your target. The resulting package will include
the Post Requisites of Already Applied bug fixes, but not the
Already Applied bug fixes or their pre-requisites. Selecting this
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
205
Using PeopleSoft Update Manager PIA Applications
Chapter 12
option will generally result in a larger change package being
created, but this may reduce the chances of missing a fix.
No
Exclude Post Requisites of Already Applied Bug Fixes (default)
The Dependency Tree is calculated such that bugs that are
Already Applied are removed during the calculation process,
and as a result the resulting package will not include the Post
Requisites of the Already Applied bug fixes, nor the Already
Applied bug fixes or their prerequisites. Selecting this option
will generally result in a smaller change package being created,
but this may increase the chances of missing a required fix.
Using the Selection Grid
Regardless of the search option selected, the search results will always be displayed in the selection grid
at the bottom of the search page.
Image: Select Bugs Grid
This example illustrates the fields and controls on the Select Bugs Grid. You can find definitions for the
fields and controls later on this page.
Show Already Applied Updates
Select this check box to include already applied updates in the
result set. If this check box is selected, a visual indicator will
appear in the Applied column.
Bug Number
Lists the bug numbers returned by the search.
Subject
Displays the subject for the bug.
Applied
A visual indicator will be displayed, if the Show Already
Applied check box is selected and the bug has already be
applied to the target database.
This bug is not included in the change package definition.
206
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
True Post Req
Using PeopleSoft Update Manager PIA Applications
True post-requisite updates will be sorted to the top of the bug
list. A visual indicator is displayed to identify the bug as true
post requisite.
All bugs discovered based on the Post Requisites for (Select)
Previously Applied bugs will be listed as suggested.
Custom Impact
A visual indicator will be displayed if the bug has an impact on
an object stored in the Customization Repository.
See Using Customization Repository
Test Exists
A visual indicator will be displayed if there is a test name in the
Test Repository corresponding to an object in the bug.
See Using the Test Repository
Details
Click this icon to display the bug details.
Define Change Package Wizard Step 5 of 6
The fifth step is to review the results of the dependency calculation. This page will display all of
the updates selected, as well as all dependent updates. Any updates that include PeopleTools hard
dependencies will be excluded from the change package and listed in the Excluded Tools Dependent Bug
grid.
Note: This page is read-only. In order to modify the results, the user must click Previous to return to the
previous page in the Wizard.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
207
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Image: Define Change Package Step 5 of 6
This example illustrates the fields and controls on the Define Change Package Step 5 of 6. You can find
definitions for the fields and controls later on this page.
Bug Number
All of the bug numbers that will be included in the change
package are listed.
Product
The PeopleSoft product impacted.
Subject
Displays the subject for the bug.
User Selected
If the bug number was selected in Step 4, this column will
contain a check. Updates that do not have a check are required
for the selected updates.
Applied
If the bug has already been applied to your database, this
column be checked.
Note: Applied bugs are not included in the change package
definition.
208
True Post Req
Icon is displayed to indicate the bug type.
Subject
Bug subject is displayed
Image Number
Displays the image in which the bug was made available.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Custom Impact
Using PeopleSoft Update Manager PIA Applications
A visual indicator will be displayed if the bug has an impact on
an object stored in the Customization Repository.
See Using Customization Repository
Test Exists
A visual indicator will be displayed if the bug has an impact on
a referenced component stored in the Test Repository.
See Using the Test Repository
Click the Bug Details icon to display the Bug information.
Excluded Bug Fixes Section
Expand this section to view bugs that are excluded from the
package, excluded bug will include bugs that have already
been applied, bugs the user excluded, bugs that fail to meet the
minimum tools level, and bugs that are required for upgrade.
Overlapping Packages Section
This section will appear if any of the bugs selected have already
been included in another change package definition that has not
been applied to the database.
Note: If overlapping packages are listed, you will be prompted
to either click OK to ignore the overlapping packages, or click
Cancel to return to the previous page and review the change
package.
Bug Details
When you click the bug details icon, a modal window is displayed:
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
209
Using PeopleSoft Update Manager PIA Applications
Chapter 12
Image: Example Bug details page
This example illustrates the fields and controls on the Example Bug details page. You can find definitions
for the fields and controls later on this page.
Show Compare Report
The compare report is stored in the PUM metadata. This delta
compare report is intended to show the specific changes made in
order to fix the bug.
Important! Keep in mind that you will need to run a compare
on the change package once it has been created, as the results
may be different based on requisite changes to the same object
or objects in your target database.
210
Tags Defined by Bug
The tag name and value represent the tracking group and value.
A bug can have 0-n Tracking Groups defined.
Objects Contained in Bug
List of objects included in the change package. The object
columns list the records, fields and so on, that are part of the
fixes in the bug.
Pre-requisite Bugs
List of pre-requisite bugs, their subjects and image numbers.
Click the Details icon to open a window with the bug details.
Post-requisite Bugs
List of post-requisite bugs, their subjects and image numbers.
Click the Details icon to open a window with the bug details.
Customizations
Expand this section to view the names of the customizations
included in this package.
Tests
Expand this section to view the test names included in this
package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 12
Components to Test
Using PeopleSoft Update Manager PIA Applications
Expand this section to view the components to test for this
package.
Define Change Package Wizard Step 6 of 6
When you transition to step 6 , the Change Package Aggregator will execute. The Change Package
Aggregator is an engine that aggregates the steps from one or more BUG step apply structures into one
single list of steps. This list of steps is then passed to the Change Packager API so that a Change Assistant
template can be generated. The Change Package Aggregator will also remove any duplicate steps.
Image: Define Change Package Step 6 of 6
This example illustrates the fields and controls on the Define Change Package Step 6 of 6. You can find
definitions for the fields and controls later on this page.
A summary is displayed for the Change Package. A link is provided to Review Change Package.
See Reviewing Change Package
This step indicates that you are done identifying the updates and you need to return to Change Assistant to
begin packaging.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
211
Using PeopleSoft Update Manager PIA Applications
212
Chapter 12
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
Packaging Updates
After defining the Change Package, you must return to Change Assistant to create the package.
1. Select Tools, Define or Create a New Change Package.
2. Select the new change package from the drop down list.
3. Optionally select the Apply Change Package check box.
If selected the Apply Change Package Wizard will launch when the package is created.
4. Click Finish.
The progress dialog box will open to indicate the change package is being created.
The change package is created as upd<change package definition name>.zip. For example
updPKG1.zip.
5. Click OK on the message Change Package <package name> has been successfully Created in the
Download Directory.
Change Packager is also aware of the target environment, including the platform and all installed
products. The Change Package will include platform and product filters.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
213
Applying Custom Change Packages
Chapter 13
Image: Create a New Change Package
This example illustrates the fields and controls on the Define or Create a New Change Package page that
are used to create the change package. You can find definitions for the fields and controls later on this
page.
Download Directory
When the change package definition is defined on the PUM
Source, it will be downloaded to the directory indicated here. By
default the download directory defined for Change Assistant is
used.
Change Package
Select the change package definition from the drop down list.
Create Selected Change Package
Definition
This check box is selected and read-only. After selecting the
change package definition when you click Finish, Change
Assistant will create the change package in the download
directory.
Proceed to Apply Change Package
Wizard after Package Creation
Select this option if you want to apply the change package as
soon as it’s created. If you leave this check box cleared, you can
review the Change Package before applying it.
Change Package Contents in the Download Directory
The download directory will contain the following:
•
Zip file for the change package name upd<changepackage_name>.zip
•
Project Directory named upd<changepackage_name>
Depending on the updates selected, the project directory contains the following folders:
214
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
changeassistanttemplate
Contains the Change Assistant template for the update job
DATA
Contains any data files required for the selected updates.
Documentation
Contains the documentation for the Change Assistant job.
Projects
Contains the Managed Objects project.
Scripts
Contains any scripts files required for the selected updates
SQR
Contains any SQRs included in the selected updates.
Applying Change Package
The Apply Change Package wizard will guide you through the configuration based on the Apply Type
that is selected.
•
•
Initial Pass — the initial pass is used to compare the updates to your target system. There are 3
choices:
•
All Steps
•
Target Steps Only
•
Source Steps Only
Move to Production
Used to apply the updated custom change package to your other environments, including production.
Understanding the Apply Update Process
When the custom change package containing your selected updates is created not all files are included in
the change package for 2 major reasons:
1. Reduces the time it takes to create the initial package.
2. Leverages Change Assistant job filtering to eliminate the creation of files not required by your target
environment.
The update job is filtered based on the target environment and only the files required for the target
environment are created from the PUM source. Depending on where the PeopleSoft Update Image (PUM
Source) is installed the process may be very time-consuming, to alleviate this issue customers have the
option to run the source and target steps in separate jobs.
The initial pass to apply updates has the following options:
•
Source Steps Only
The Source Steps Only option provides the ability to run the initial pass to create all files that are
contained in the change package. This job can be run on the same machine where the PUM Source is
installed. Once the initial pass has completed, a modified change package is created that contains all
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
215
Applying Custom Change Packages
Chapter 13
the files. The modified update change package can then be copied to the machine where you will run
the Apply Update on your target database.
•
Target Steps Only
Using the new change package created from the Source Steps Only job, you can apply the change
package to your target database without requiring a connection to the source database. When the job is
created for the target environment, all unnecessary files are filtered out.
•
All Steps
All steps requires a connection to both the target database and the PUM source. When this option is
selected, the source steps will create the necessary files needed for the target system.
Applying the Change Package
To apply the change package:
1. Start EMF if it is not already started and you selected Configure EMHub For File Deploy on the
EMHub Options page in Change Assistant.
Note: EMHub is only required for file deploy. If you plan to manually deploy file, skip this step.
2. In Change Assistant, select Tools, Change Actions.
3. Select Update Manager and Click Next.
Note: If you are already in the Update Manager action, select Tools, Apply Change Package.
4. Select Apply Change Packages and click Finish.
5. Select the download directory where the change package was created.
6. Select the change package that was created for your custom change package definition.
7. Select Initial Pass.
By default All Steps is selected. Change this value if you choose to decouple the source and target
steps.
8. Click Next.
9. Select the target database.
Note: Use the Create button to create the target database if it has not been previously created. See
Defining Databases and Defining Target Database
10. If you are using EMHub, select the file server.
216
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
Image: Select Target Database page
This example illustrates the fields and controls on the Select Target Database page. You can find
definitions for the fields and controls later on this page.
11. Click Next.
12. Change Assistant will connect to the target database and check compatibility. The Compatibility
Check page will then be displayed.
13. Click Next.
14. The Apply Summary is displayed, click Finish.
Change Assistant will begin building the Change Assistant job.
15. The Update job will be created and open in Change Assistant.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
217
Applying Custom Change Packages
Chapter 13
Image: Change Package Settings
This example illustrates the fields and controls on the Change Package Settings. You can find definitions
for the fields and controls later on this page.
Download Directory
When the change package definition is defined on the PUM
Source, it will be downloaded to the directory indicated here. By
default the download directory defined for Change Assistant is
used.
Change Package
The change package name will include the change package
definition. upd<your change package name>.zip.
Apply Type
•
Initial Pass
You will first apply the update to your development
environment which is an Initial Pass.
In the Initial Pass you will perform compares to retrofit your
customizations and repackage the update to include all your
customizations.
Important! Development environment must have the
same maintenance level as any additional targets where
you intend to subsequently reuse this package (after
incorporating customizations) and apply them using the
Move to Production apply type.
In the initial pass, you can select which steps to perform.
See Understanding the Apply Update Process
•
218
Subsequent Pass
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
Reserved for future use. This option will be grayed and
unavailable.
•
Move to Production
Use the Move to Production to apply the updated custom
change package to your other environments, including
production.
See PUM Best Practices and Maintenance Strategy document
post on the PUM Homepage.Change Assistant and Update
Manager Related Links
Synchronize Target Metadata
(Requires Source)
Select Yes to upload the target database information to the PUM
Source when the update is applied.
The default is Yes, however if you are applying the update to
a database that is not used for defining and creating change
packages in PUM, there is no need to upload the database
information to the PUM Source and you would select No.
Note: If the PUM source is not defined, this option will not be
enabled.
Reviewing the Change Assistant Job
After you apply a change package, the Change Assistant job is created using the selected change package
and options.
Understanding Job Naming Conventions
The Update job name reflects the criteria selected for the job.
Softwareupdate.<PACKAGE NAME>.{<PUM SOURCE DATABASE>-<TARGET-DATABASE}<IP or MTP>
For example:
Softwareupdate.SELECTIVE.{HR92U016-HC920001}IP
In this example, the package name is SELECTIVE, the PUM source database is HR92U016, the target
database is HC920001, and the apply type is Initial Pass.
Staging and Output Directories
When the Change Assistant job is created, a folder for the job is created in both the Staging and Output
directory. The folder will have the same name as the Change Assistant job. In the example above the
folder would be named softwareupdateSELECTIVE{HR92U016-HC920001}IP.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
219
Applying Custom Change Packages
Chapter 13
When Change Assistant is creating a new job, if an existing output and staging folder is found, Change
Assistant will add a number to the folder, for example, softwareupdateSELECTIVE{HR92U016HC920001}IP.1.
Understanding Job Filtering
Change Assistant will filter the job to only include the steps that apply to your environment. The job is
filtered by step attribute criteria, including:
•
Platform
•
Language
•
Products
•
PeopleTools Release
•
Orientation
•
EM Hub
If the EM Hub is defined and the target database is defined to the hub, the file deploy steps will be
included in the job, if it is not defined, the file deploy steps will be set to Filtered at the Job Level.
•
Synchronize Target Metadata
If the Synchronize Target Metadata option is set to No , the step Re-Synching Target Details with PI
Image will be set to Filtered at the Job Level.
Creating Filtered Documentation
The Change Assistant template is delivered with embedded documentation to help guide you through
the change package jobs, especially the manual steps. You can create a single HTM file that is filtered
to contain only the documentation for the chapters, tasks, and steps relevant to your job. This section
assumes that you have created a Change Assistant job from a PUM change package. To create the filtered
documentation:
1. In Change Assistant, in Update Manager mode, highlight the root node of the template.
2. Right-click, and select Finalize Documentation.
This produces a single consolidated HTM file named for the update job. The file is saved on your
client machine in the following location, where <staging_directory> is the directory you specified on
the General Settings page:
<staging_directory>\<change assistant job name>\Documentation\<package_name>.h⇒
tm
For example: D:\PUM\Staging\softwareupdateSELECTIVE{HR92U016-HC920001}IP
\Documentation\SELECTIVE.htm.
Running Change Assistant Job
Change Assistant will execute each step in the job until completion, unless a manual step or error is
encountered.
220
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
When you encounter manual steps you will need to take some action, such as review compare reports. If
you make any changes while the job is executing, you will want these same changes applied to additional
targets.
Running SQRReport Steps
For Change Assistant jobs created from PUM change packages only, you can edit the SQRReport step
type to add a user-defined Run Control ID, as follows:
1. Highlight the step and select Edit, Step Properties.
2. Select the Step Definition tab.
3. Click Additional Settings.
4. Add the Run Control ID, and specify any other settings needed.
If no value is entered for Run Control ID, the default value ADHOC is used.
5. Click OK twice and restart the Change Assistant job.
Updating Package for Subsequent Passes
The last steps in the template are used to prepare your change package for the Move to Production.
Step
Type
Description
Copying Customized Codeline Objects
Manual Stop
Manually copy your customized codeline
objects (located in PSHOME / PS_APP
_HOME / PS_CFG_HOME or such
similar locations to the staging directory.
Merging CP and CP Invalid View
Projects
Merge Project
Merges the additional invalid views
project (if one was created during the
initial pass) into the existing project
resulting in a single project. The merged
project is used in all subsequent applies
using the updated change package.
Exporting Modified Package-MO Project CopyToFile
Copies the managed object project to a
file.
Exporting Modified ADS-MO Project
AEWithRunControl
Consolidates multiple ADS projects into
one project and copies it to a file.
AEWithRunControl
Copies individual ADS project (by bug)
to a file.
Only if Required
Exporting Modified ADS Project [ADSProjectName]
Only if Required
Create Modified Change Package
Note: There will be a step created for
each ADS project included in the change
package.
UpdateChangePackage
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
The change package is zipped to the
staging directory and ready for the Move
to production.
221
Applying Custom Change Packages
Chapter 13
Moving to Production
In the Initial Pass, you applied the custom change package to your development database. In the process
of applying the change package, you completed all compares and adjusted the change package to retrofit
any customizations to your system. Once you have tested the updates, you are ready to deploy the updates
to your other target environments, including production.
When you select the Apply Type Move to Production, the Patching Source Database will be your
Development database where the patch has already been applied.
To apply the updates to your target databases:
1. (Optional) Start EMF if it is not already started and you selected Configure EMHub For File Deploy
on the EMHub Options page in Change Assistant.
Note: EMHub is only required for file deploy. If you plan to manually deploy file, skip this step.
2. In Change Assistant, select Tools, Change Actions.
3. Select Update Manager and Click Next.
Note: If you are already in the Update Manager action, select Tools, Apply Change Package.
4. Select Apply Change Packages and click Finish.
5. Select the download directory where the change package was created.
6. Select the change package that was created for your custom change package definition.
7. Select Move to Production.
8. Click Next.
9. Select the target database.
Note: Use the Create button to create the target database if it has not been previously created. See
Defining Databases
10. If you are using EMHub, select the file server.
11. Click Next.
12. Change Assistant will connect to the target database and check compatibility. The Compatibility
Check page will then be displayed.
13. Click Next.
14. The Apply Summary is displayed, click Finish.
Change Assistant will begin building the Change Assistant job.
15. The Update job will be created and run until it completes or encounters an error.
222
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 13
Applying Custom Change Packages
Note: There are no manual stops in the Move to Production.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
223
Applying Custom Change Packages
224
Chapter 13
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 14
Applying PeopleSoft Release Patchset to
PeopleSoft Image
Applying Downloaded PeopleSoft Release Patchset to PeopleSoft
Image
The PeopleSoft Update Image will be available on a regular schedule and is the source of all updates to
your application, however there may be times when a critical fix is necessary and you can not wait for the
next PeopleSoft Image. When this circumstance occurs, it will be necessary to download the PeopleSoft
Release Patch from My Oracle Support (MOS).
You will apply the PRP to the current PeopleSoft Image so that you can continue to take advantage of the
powerful PeopleSoft Update Manager PIA application to generate a custom change package including
requisite updates that may have already been posted. The PRP change package includes the metadata
required to keep your current PeopleSoft Image up to date. Every PRP will be included in the next
scheduled release of the PeopleSoft Image which is cumulative of all updates.
Important! The pi_home directory requires read and write access to apply PeopleSoft Release Patchsets
(PRPs). To apply PeopleSoft Release Patchsets (PRPs), use the instructions in the PeopleSoft Deployment
Packages for Update Images Installation (PeopleSoft PeopleTools 8.55), “Using and Maintaining the
PeopleSoft Environment”, Changing the Access for PI_HOME to change the access to read/write and
disable guest login.
Warning! Because PRPs are created for specific PIs, the PRP can only be applied to the specific PI for
which it was created. Change Assistant will not allow you to apply a PRP directly to your PeopleSoft
environment.
To download and apply an individual fix:
1. Discover and download the PRP from MOS.
2. Use Change Assistant to apply the PRP to the PeopleSoft Image database.
3. Create a new custom change package definition using Define Change Package option in the Update
Manager Action.
See Defining a New Change Package
4. Apply the new custom change package the same as any other update from the PeopleSoft Image.
See Applying Change Package
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
225
Applying PeopleSoft Release Patchset to PeopleSoft Image
Chapter 14
Discovering and Downloading the PRP
Before you download the change package for the PRP, make sure that you have set up a download
directory on your local machine.
To discover and download the PRP:
1. Create a download directory on your local machine.
2. Log onto My Oracle Support and Select the Patch and Updates tab.
3. Search for PeopleSoft Release Patchsets (PRP) by Bug Number, Product, or Product Family.
4. Search for PRPs.
Use the Patches and Updates tab in My Oracle Support to search for PRPs. PRPs have a classification
of Critical.
5. Open the fix details to review the fix.
6. From the Patch Details page, click Download.
7. Select the Include Prerequisites checkbox to list all the prerequisite change packages.
8. In the file download window, click on the change package name and select Save.
9. Select your download directory.
Applying the PRP to the PeopleSoft Image
To apply the PRP to the PeopleSoft Image:
1. In Change Assistant, select Tools, Change Actions.
Note: If you are already in the Update Manager Action, select Tools, Apply Downloaded PeopleSoft
Release Patchset to PeopleSoft Image then go to step 4.
2. Select Update Manager and click Next.
3. Select Apply Downloaded PeopleSoft Release Patchset to PeopleSoft Image and click Finish.
4. Select the download directory where you downloaded the PRP change package and click Next.
5. Select the PRP change package or packages from the list displayed and click Next.
6. Change Assistant will verify that the package is compatible with the PI version. If it is not compatible,
you will receive a message to Cancel.
7. The Change Assistant job will start running.
Note: Use the instructions in the PeopleSoft Deployment Packages for (PeopleSoft PeopleTools 8.55) ,
“Using and Maintaining the PeopleSoft Environment”, Changing the Access for PI_HOME to change the
access to read/write and disable guest login for the pi_home share.
226
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 14
Applying PeopleSoft Release Patchset to PeopleSoft Image
Applying the PRP to Target Database
After the PRP has been applied to the PeopleSoft Image database, it is now available for you to apply
to your target environments using the Update Manager action. Apply the PRP as you would any other
update.
See Defining a New Change Package
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
227
Applying PeopleSoft Release Patchset to PeopleSoft Image
228
Chapter 14
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 15
Applying PeopleTools Patch
Using Change Assistant to Apply PeopleTools Patch
Understanding PeopleTools Patch
PeopleTools patches deliver fixes between PeopleTools minor releases. PeopleTools patches are posted to
My Oracle Support, as they become available. PeopleTools patches are cumulative. They include all fixes
from all previous patches for the specified release. For example, patch .03 contains all the fixes contained
in the .02 patch as well as all of those contained in the .01 patch.
The patch contains the PeopleSoft Installer which is used to update the binaries in your PS Home
directory.
The PeopleTools patch location is always the PTP directory in your target PS home.
Important! In PeopleSoft PeopleTools 8.55, Oracle recommends that you use the PeopleSoft
Deployment Packages (DPKs) to install and configure your PeopleSoft environment. DPKs offer outof-the-box functionality that greatly enhances the installation and configuration of your PeopleSoft
environment, which is not available via the standard VCD installation.
Locating and Downloading PeopleTools Patch
PeopleTools Patch DPKs are available for Windows and Linux.
To locate and download the DPKs:
1. Go to the PeopleSoft PeopleTools Patches Home Pages, My Oracle Support, Doc ID 2062712.2, to
find the information on locating and downloading the latest PeopleSoft PeopleTools patch.
The PeopleTools Patches Home Pages contain links to the patch, as well as the links to the installation
documentation.
2. Download the DPK zip files into a single directory, referred to in this documentation as
DPK_INSTALL
Be sure that the DPK_INSTALL directory has adequate available space for all the zip files. When
you download, there will probably be multiple zip files. The multiple files are needed due to size
limitations.
The files names are comprised of the following parts:
•
<Operating_System> is LNX for Oracle Linux, or WIN for Microsoft Windows.
•
<Release> is the release and patch number for the product, such as 8.55.02.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
229
Applying PeopleTools Patch
•
Chapter 15
n represents the total number of zip files
The zip files have the following format:
PEOPLETOOLS-<Operating_System>-<Release>-#ofn.zip
For example:
PEOPLETOOLS-LNX-8.55.02-1of4.zip
PEOPLETOOLS-LNX-8.55.02-2of4.zip
PEOPLETOOLS-LNX-8.55.02-3of4.zip
PEOPLETOOLS-LNX-8.55.02-4of4.zip
Locating and Downloading PeopleTools Patch VCD
The traditional VCD PeopleTools patch is also available. For customers on operating systems other than
Windows or Linux, the VCD install is used to apply PeopleTools patches.
To locate and download a PeopleTools patch:
1. Go to the PeopleSoft PeopleTools Patches Home Pages, My Oracle Support, Doc ID 2062712.2, to
find the information on locating and downloading the latest PeopleSoft PeopleTools patch.
2. Select PeopleTools Patches on Other Operating Systems.
3. Download the patchset.
4. The readme file downloaded with the patch provides the instructions for installing the PeopleTools
binaries.
Note: Once the binaries are installed, you can use Change Assistant to apply the database changes for
the patch. If you prefer to load database changes manually, follow the instructions in the readme file
downloaded with the PeopleTools patch.
Installing the Patch
Refer to the installation documentation PeopleSoft PeopleTools 8.55 Deployment Packages Installation
for instructions on installing the PeopleTools DPK. This documentation is available on the PeopleSoft
PeopleTools Patches Home Page 2062712.2
For the traditional VCD install see the Readme information posted with the patch.
Installing a New PeopleTools Patch Version of Change Assistant
Most PeopleTools patches will instruct you to install the new PeopleTools patch version of Change
Assistant. To install Change Assistant:
See Installing a New Instance of Change Assistance
230
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 15
Applying PeopleTools Patch
Configuring Change Assistant for Applying a PeopleTools Patch
To apply a PeopleTools Patch, the following configurations is required:
•
General Options
If the general options have not been previously defined, the Change Assistant Wizard will open this
page when you select an action. See Opening Change Assistant the First Time
Alternatively, you can populate the General options using the command line. See the section
Command Line for Setting Options in Update Manager Mode
•
Database Definition
Each target database will need to be defined. You can define a database by selecting File, New
Database or clicking the Create button on the Select Target Database page. See Defining Databases
Alternatively, you can define the target database using the command line. See the section Command
Line for Creating Environments in Update Manager Mode
Applying the PeopleTools Patch Change Package
To apply the PeopleTools patch in Change Assistant:
1. In Change Assistant, select Tools, Change Actions.
2. Select Update Manager and click Next.
3. Select Apply a Patch to your Current PeopleTools Release and click Finish.
4. Review the Change Package Settings page and click Next.
PeopleTools patches do not use the PUM Source, so it will indicate Not Set.
The download directory is always the PTP directory in your target home.
PeopleTools patches are always applied to the target database.
5. Select the target database, if the database has not been defined yet use the Create button to create the
database.
See Defining Databases
6. Click Next.
7. Select the Change Package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
231
Applying PeopleTools Patch
Chapter 15
Image: Select PeopleTools Patch to Apply
This example illustrates the fields and controls on the Select PeopleTools Patch to Apply.
8. Click Next.
9. Change Assistant performs a PeopleTools patch version check. Review the messages and click Next.
A warning is displayed if the selected patch is at the same or a lower level than the installed
PeopleTools patch. It is not recommended to re-apply or downgrade PeopleTools patches.
10. The Apply Summary page is displayed, review the summary and click Finish.
11. Change Assistant will load the change package and run the PeopleTools patch job.
12. All steps will run unattended and when the last step is complete you will receive a message that there
are no more steps to run.
PeopleTools Patch Level
In PeopleTools 8.54, a new field PTPATCHREL was added to the PSSTATUS table. When you apply a
PeopleTools patch, the PTPATCHREL field is updated with the new PeopleTools patch level.
Using Command line to Apply PeopleTools Patch
Alternatively, If you have configured a target database and general options in Change Assistant, you can
apply the PTP via the command line by using an updated version of the following syntax: For example:
Changeassistant.bat -MODE UM -ACTION PTPAPPLY -TGTENV <YOUR_TARGET_DB_ENV_NAME_LIKE⇒
_PT854TST> -UPD PTP85401
See the section Command Line for Applying PeopleTools Patch in Update Manager Mode
232
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
Using Change Assistant to Upgrade PeopleTools
Understanding PeopleTools Upgrade
PeopleTools upgrades involve two major components:
•
New PeopleTools release.
•
Change Package containing databases changes for the new PeopleTools Release.
The PeopleSoft PeopleTools 8.55 Upgrade Home Page (Doc ID ) provides links to the information and
resources for your PeopleTools upgrade.
Your documentation and template files are delivered differently depending on which of the following
installation methods you are using:
•
PeopleTools DPK
The PeopleTools DPKs also contain the upgrade documentation, upgrade template, and files.
•
Software downloaded from the Oracle Software Delivery Cloud (OSDC)
Download the Change Package from the upgrade home page to get your template and HTML
documentation.
Upgrading Oracle's PeopleSoft PeopleTools software requires planning, resources, testing, and training.
The PeopleSoft PeopleTools upgrade documentation provides information to help you get started
planning for your upgrade and installing the new release.
Important! The PeopleSoft PeopleTools upgrade documentation provides all of the steps necessary to
prepare for and upgrade PeopleTools.
The PeopleSoft PeopleTools Upgrade involves the following steps:
1. Installing the New Release
Refer to the documentation for installing either the PeopleTools DPK or the PeopleTools installation
guide for your database platform if you downloaded the software from OSDC.
2. Applying a PeopleTools Patch
If you installed the new release using OSDC, you will need to download the latest PeopleTools patch
from My Oracle Support.
See Using Change Assistant to Apply PeopleTools Patch
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
233
Upgrading PeopleTools
Chapter 16
3. Installing PeopleSoft Change Assistant
See Installing a New Instance of Change Assistance
Note: If Change Assistant was installed on a previous release, you will be prompted to remove the
existing Change Assistant. For some release/patch levels, the installation may perform an update and
all your configurations settings can be retained.
4. Applying the PeopleTools Upgrade Change Package
a. Downloading the PeopleTools Upgrade Change Package
Note: If you used DPK to deploy PeopleSoft PeopleTools on Windows or Linux, you do not need
to perform this step.
b. Setting Up Change Assistant
See Configuring Change Assistant for PeopleTools Upgrade and Configuring Change Assistant
for Update Manager – Upgrade to a New Release of PeopleTools
c. Upgrading PeopleTools
See Upgrading to a New Release of PeopleTools
d. Reviewing Upgrade Step Properties
Configuring Change Assistant for PeopleTools Upgrade
When performing a PeopleTools Upgrade, you will always be using a newly installed version of Change
Assistant at the new PeopleTools release/patch level.
To configure Change Assistant for PeopleTools upgrade:
1. Launch Change Assistant.
2. At the Welcome menu, click Next.
De-select the Always show this page if you want to bypass the Welcome menu next time you launch
Change Assistant.
3. On the Select Action page, select Update Manager and click Next.
4. If this is the first time you are selecting Update Manager, the Wizard will guide you through the
Change Assistant setup.
See Configuring Change Assistant for Update Manager – Upgrade to a New Release of PeopleTools
5. On the Select Task page, select Upgrade to a New Release of PeopleTools and click Finish.
6. To apply the PeopleTools upgrade, the Wizard will guide you through the environment setup.
See Upgrading to a New Release of PeopleTools
234
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
Configuring Change Assistant for Update Manager – Upgrade to a New
Release of PeopleTools
If this is the first time you are selecting Update Manager, the Wizard will guide you through the Change
Assistant setup. As you click Next you will complete the following pages:
1. General Options
2. PUM Source Options
Note: PUM Source is not used with PeopleTools upgrades. You will click Next to skip this page.
3. EM Hub Options
Note: EM Hub is not used with PeopleTools upgrades. You will click Next to skip this page.
4. Additional Options
5. Select Task
Note: Once the environment has been configured, you can use Tools, Options to make any changes to the
environment options.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
235
Upgrading PeopleTools
Chapter 16
General Options
Image: General Options
This example illustrates the fields and controls on the General Options. You can find definitions for the
fields and controls later on this page.
Maximum Concurrent Processes
Specifies the maximum number of processes that can be
executed concurrently on the local machine. The default is 1.
PS Home Server Starting Port
Specify the port number for the first PS Home server.
Change Assistant uses this port number to communicate with
Change Assistant PS Home servers. The default starting port
number is 6151. If you enter a port number that is already
in use, you see an error message. You must change to a port
number that is not in use, and then restart Change Assistant for
the change to take effect.
PS Home Server Maximum Instances Enter a number between 1 and 10 for the maximum number of
PS Home servers.
Use this value for environments with more than one PS_HOME.
For each server instance, Change Assistant increments the PS
Home Server Starting Port number by 1 up to the maximum
number of instances. For example, with a PS Home Server
Starting Port value of 6151 and a PS Home Server Maximum
Instances value of five, the port numbers would be 6151, 6152,
6153, 6154, and 6155. The default is 5.
236
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
If you change this value, you must restart Change Assistant for
the change to take effect.
PS Home
Enter the full path to the new PeopleTools release PS_HOME.
Note: This is the same PS_HOME used to install Change
Assistant.
Staging Directory
Enter the directory in which you would like to stage all the
Change Assistant upgrade files. This is the location that Change
Assistant will store files to be used during the upgrade to new
PeopleTools process.
Output Directory
Enter the directory in which you want the log files generated by
the upgrade process to reside.
Download Directory
Enter the full path of the location to which you want to
download your change packages.
SQL Query Tool
Select the correct executable for the database platform that
matches the PS_HOME defined for CA. This value is used as
the default when creating environments. Each environment
contains separate settings and therefore, you can change this
executable for a specific database.
Valid SQL query executables for each platform are:
•
DB2: db2cmd.exe
•
Microsoft SQL Server: sqlcmd.exe
•
Oracle: sqlplus.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.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
237
Upgrading PeopleTools
Chapter 16
Additional Options
Image: Change Assistant - Additional Options page
This example illustrates the fields and controls on the Change Assistant - Additional Options page. You
can find definitions for the fields and controls later on this page.
Notification Settings Section
238
Send Email Notifications
Select this check box to receive email notifications if there are
errors in the upgrade process. Change Assistant also sends you
a completion message when it encounters a Stop in the update
process.
SMTP Server
Enter the SMTP mail server from which you receive the error or
completion messages.
Port
Enter the port from which you want to access the email.
Send To
Enter the address to which you want the email sent.
Return Address
Enter the email address of the sender. Use this to identify who
sent the notification.
Test
Validates that email is sent to the designated recipients and is
working correctly.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
Note: Ensure that your SMTP server is installed and configured
correctly.
Proxy Section
Host
(Optional) Enter the name of the proxy server if you want to run
Change Assistant behind the firewall using a proxy server.
Port
(Optional) Enter the port number for the proxy server.
Anonymous Proxy
Indicates that you are using a proxy server that does not require
authenticated connections.
Microsoft Proxy Server
Indicates that you are using a proxy server with Windows
authentication.
Windows Domain
The network domain in which the system runs.
Other Proxy Servers
Indicates you are using non-Microsoft proxy servers.
Select Task
Select Upgrade to a New Release of PeopleTools.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
239
Upgrading PeopleTools
Chapter 16
Image: Select Task – Upgrade to a New PeopleTools Release
This example illustrates the task Upgrade to a New PeopleTools Release selected.
Upgrading to a New Release of PeopleTools
To apply the PeopleTools upgrade, the Wizard will guide you through the environment setup. As you
click Next you will complete the following pages:
1. Change Package Settings
2. Select Target Database
3. Select PeopleTools Upgrade
4. Check Compatibility
5. Apply Summary
240
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
Change Package Settings
Image: Change Package Settings for a PeopleTools Upgrade
This example illustrates the fields and controls on the Change Package Settings for a PeopleTools
Upgrade. You can find definitions for the fields and controls later on this page.
For a PeopleTools upgrade, the apply type is Initial Pass and Target Steps Only.
Select Target Database
On the Select Target Database page, select your target database if the databases were imported to the new
instance of Change Assistant.
To create a new database or add the New Homes to an existing database:
1. Click the Create button, which will launch the Database Wizard.
2. On the Define Database page, enter the information for the database you are defining.
Note: For PeopleTools Upgrade, you must set the path information for the new PS home locations.
See Defining Databases
3. Click Next.
Change Assistant will query the database and gather additional database.
Note: Change Assistant will verify the connection to the database, including User ID/password,
Access ID/password, and Connect ID/password. You will need to correct any errors before continuing
to define the database.
4. The information is then displayed on the Additional Database Details page.
5. Click Next and the Confirm Settings page is displayed.
6. Click Finish.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
241
Upgrading PeopleTools
Chapter 16
Select PeopleTools Upgrade
The select PeopleTools Upgrade page will display the target database information, as well as the
change package to install and any PeopleTools patches that Required at Upgrade and downloaded to the
download directory.
Image: Select PeopleTools Upgrade
This example illustrates the fields and controls on the Select PeopleTools Upgrade page.
Check Compatibility
Change Assistant will perform a compatibility check to the upgrade version and upgrade patch.
242
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
Image: Check Compatibility
This example illustrates the fields and controls on the Check Compatibility.
PeopleTools Upgrade Job
When you click Finish on the Summary page, the PeopleTools upgrade job is created and opens. The first
step is usually a manual stop.
For more information on running Change Assistant Jobs, see Running the Upgrade Job
Creating and Applying Tools Delta Package
Since PUM supports multiple PeopleTools releases it is necessary for PUM to handle shape differences
that may exist between different PeopleTools releases. There are 2 types of Tools dependencies:
•
Hard Dependencies - The object will not work on a lower release and is therefore stripped from the
change package definition.
•
Soft Dependencies - Some of the attributes of the object are stripped in order to work on the lower
release.
When the customer does upgrade to the newer PeopleTools release, any previously applied updates that
contained soft dependencies need to be re-applied with the associated post-requisites to add back the
attributes or objects that were stripped away when the updates were applied in the old release. The Tools
Delta Package option in the PeopleSoft PIA application is used to create this change package.
Prerequisites
You will use the Change Assistant Update Manager > Define or Create a New Change Package action to
create and apply the change package. Before you can select this action, the following prerequisites must
be configured and installed:
1. Download the latest PeopleSoft Update Image (PI) from My Oracle Support and install it locally.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
243
Upgrading PeopleTools
Chapter 16
See Installing PeopleSoft Update Image
2. Configure the Microsoft Windows client running Change Assistant.
See Configuring the Microsoft Windows Client Running Change Assistant
3. (Optional) Configure Environment Management Framework for your target environment, if you want
to use the file deploy feature.
See Configuring the Environment Management Hub
4. (Optional) Start EMF if you plan to use the file deploy feature.
See Running the Environment Management Hub
5. Define the PUM Source and EM Hub.
Note: For the PeopleTools Upgrade these options were skipped when the original configuration for
Change Assistant was completed. Depending on the PeopleSoft Image downloaded and installed, you
may need to remove Change Assistant and install the version delivered with the PeopleSoft Image.
After installing a new version of Change Assistant, you will need to set up Change Assistant.
Defining the PUM Source and EM Hub
If you are using the same version of Change Assistant that was used for the PeopleTools upgrade, follow
these instructions. If you installed a different version of Change Assistant, follow the instructions in
Configuring Change Assistant for Update Manager.
To configure Change Assistant options:
1. In Change Assistant, select Change Actions.
2. Select Update Manager and click Finish.
3. Select Tools, Options.
4. Verify that the information on the General page is correct.
Note: PS_HOME will be the new release of PeopleTools.
5. Select the PUM Source tab.
a. Select Define PUM Source.
b. Click Create and define the PUM source database.
See Defining Databases
c. Select the drive that you mapped to the pi_home directory when you configured the Microsoft
Windows client.
d. Enter the PUM Source PIA URL.
6. (Optional) Select the EM Hub tab.
244
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 16
Upgrading PeopleTools
You must have EMF configured and running before defining the EM Hub.
a. Select Configure EMHub For File Deploy.
b. Enter the Server Host Name.
c. Enter the Server Host Port.
d. Enter the Chunk Size.
e. Enter the Ping Interval.
f. Enter the Drives to Crawl.
g. Click Ping.
A successful ping will return Packets: Sent = 3, Received = 3, Lost = 0.
h. Click the View button to display the Environment Management Hub Summary.
Select the Additional tab.
Verify that the information on the Additional page is correct.
7. Click OK.
Creating the Tools Delta Package
To create the tools delta package:
1. Select Tools, Define or Create a Change Package.
2. Click the button Click Here to Open a Browser and Connect to the PUM Source Database.
3. Sign on.
4. Select PeopleTools, Lifecycle Tools, Update Manager Dashboard, Select Target Database.
5. If you only have one target database defined, the target database is selected by default.
6. Select Define Change Package, Define Tools Delta Package.
7. On step 2, enter a Package name and description, then click Next.
8. On step 3, enter the From Tools Release value in the format <release>.<patch> for example 8.53.12
(PeopleTools release 8.53 patch 12). The new PeopleTools release/patch number for the target
database is displayed in the To Tools Release field.
9. Click Next. For tools delta packages step 4 is skipped.
10. Step 5 in the Define Change Package wizard is displayed showing all the bugs that will be included in
the change package.
Note: This package may also contain additional bugs that you have not applied to the target database.
11. Click Next.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
245
Upgrading PeopleTools
Chapter 16
The change package definition is created and you can return to Change Assistant to apply the change
package.
12. Sign off and close the browser.
13. Return to Change Assistant and click the drop-down for Change Package on the Define or Create
New Change Package page. The package you just created on the PUM source should be at the top of
the list. Select the change package.
Note: If you closed Change Assistant, launch Change Assistant and select Tools, Define or Create a
Change Package.
14. If you would like to apply the package when it is created, select the Proceed to Apply Change
Package Wizard after Package Creation checkbox.
15. Click Finish.
Applying Tools Delta Change Package
To apply the tools delta package:
1. In Change Assistant, select Tools, Apply Tools Delta Package.
2. Select the change package using the drop down. Only tools delta change packages are available.
3. Select Initial Pass.
By default All Steps is selected.
4. Click Next.
5. Select the target database.
Note: Use the Create button to create the target database if it has not been previously created. See
Defining Databases and Defining Target Database
6. Click Next.
7. Change Assistant will connect to the target database and check compatibility. The Compatibility
Check page will then be displayed.
8. Click Next.
9. The Apply Summary is displayed, click Finish.
Change Assistant will begin building the Change Assistant job.
10. The Update job will be created and open in Change Assistant.
246
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 17
Defining and Applying Translations Fixes
Understanding Translation Fix Packs
The Translations organization, from time to time, will review existing/ previously defined and delivered
translations, and determine that a revision to that translation is required. This is a standalone review
process that:
•
is not directly linked to fixes or features being delivered by the applications.
•
may include changes to objects that have not changed since Product GA.
•
is language specific, in that each language is reviewed separately and the content of each language
deliverable can and is likely to be unique.
The result and content of this translations process is referred to as a Translations Fix Pack (TFP).
The Define Translation Delta Package component is used to select the Translations Fix Pack(s) to include
in a Translations Delta Package (TDP).
Note: The Define Translation Delta Package component replaces Translations Only option that was
included as Additional Search Criteria when creating a Change Package definition.
Defining Translations Delta Package
To define a translation delta package:
1. Select PeopleTools, Lifecycle Tools, Update Manager, Update Manager Dashboard.
2. Expand the Select Target Database folder and click on the database name.
3. Expand the Define Change Package folder and select Define Translation Delta Package.
4. This launches the Define Translations Delta Package Wizard starting at step 2. Enter a name and
description for the package.
Note: Step 1 is only displayed when no target databases have been uploaded. The database name you
selected in step 2 above is used.
5. Click Next.
6. On step 3, select the languages.
7. Click Next. Step 4 is skipped for translation delta packages.
8. Step 5 will display all bugs meeting the language criteria.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
247
Defining and Applying Translations Fixes
Chapter 17
9. Click Next.
10. When you transition into Step 6 the change package definition is complete.
11. Return to Change Assistant to create the package.
Define Translations Delta Package Wizard Step 2 of 6
Navigation
After selecting the target database in the Update Manager Dashboard, expand the Define Change folder
and select Define Translation Delta Package.
The second step is to enter the package name and description.
Image: Define Translations Delta Package Wizard step 2 of 6.
This example illustrates the fields and controls on the Define Translations Delta Package Wizard step 2 of
6. You can find definitions for the fields and controls later on this page.
Package Name
Package Description
248
Enter a name for your translation delta change package. To edit
an existing change package, select the Lookup button. The list
of change packages that can be edited is restricted as follows:
•
Packages created by the current user.
•
Packages created for the currently selected target database.
•
Packages which have been defined but have not been
created.
Enter a description for the change package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 17
Defining and Applying Translations Fixes
Define Translations Delta Package Wizard Step 3 of 6
Use the Select Search Method page to select the language or languages to update.
Note: If the target database is English only, nothing is displayed since you do not need a translation fix
pack.
Image: Define Translation Delta Package Wizard Step 3 of 6
This example illustrates the fields and controls on the Define Translation Delta Package Wizard Step 3 of
6.
Define Translations Delta Package Step 5 of 6
Step 5 will display the bugs to be included in the translation delta package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
249
Defining and Applying Translations Fixes
Chapter 17
Image: Define Translation Delta Package Step 5 of 6
This example illustrates the fields and controls on the Define Translation Delta Package Step 5 of 6. You
can find definitions for the fields and controls later on this page.
For details on the grid columns see Define Change Package Wizard Step 5 of 6
Define Translations Delta Package Wizard Step 6 of 6
When you transition into Step 6 the change package definition is complete.
250
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 17
Defining and Applying Translations Fixes
Image: Define Translation Delta Package Wizard Step 6 of 6
This example illustrates the fields and controls on the Define Translation Delta Package Wizard Step 6 of
6. In this example there were 2 languages selected, therefore
Each language is processed separately. A project definition is created for language, with suffix indication
the language. The projects will be combined into a single change package with separate steps by
language. The Change Package Type is TDP.
Creating Translations Delta Package
After defining the translations delta package, return to Change Assistant to create the package.
Select the package name and click Finish.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
251
Defining and Applying Translations Fixes
Chapter 17
Image: Create a New Change Package
This example illustrates the fields and controls on the Define or Create a New Change Package . Use the
Create a New Change Package section to create the change package.
If you select the Proceed to Apply Change Package Wizard after Package Creation, Change Assistant will
launch the wizard. See Applying Translations Delta Package
Applying Translations Delta Package
To apply the translation delta package:
1. In Change Assistant, select Tools, Change Actions.
2. Select Update Manager and Click Next.
Note: If you are already in the Update Manager action, select Tools, Apply Translation Delta
Package.
3. Select Apply Translation Delta Package and click Finish.
4. Select the download directory where the change package was created.
252
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 17
Defining and Applying Translations Fixes
Image: Change Package Settings
This example illustrates the fields and controls on the Change Package Settings.
5. Select the translation delta change package to apply. Only translation delta packages are available in
the drop down. The package name will end with TDP.
6. Select Initial Pass.
By default All Steps is selected. Change this value if you choose to decouple the source and target
steps.
Note: For information on Apply Type see Understanding the Apply Update Process
7. Click Next.
8. Select the target database.
Note: Use the Create button to create the target database if it has not been previously created. See
Defining Databases and Defining Target Database
9. Change Assistant will connect to the target database and check compatibility. The Compatibility
Check page will then be displayed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
253
Defining and Applying Translations Fixes
Chapter 17
Image: Check Compatibility page
This example illustrates the fields and controls on the Check Compatibility page.
10. Click Next.
11. The Apply Summary is displayed, click Finish.
254
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 17
Defining and Applying Translations Fixes
Image: Apply Summary page
This example illustrates the fields and controls on the Apply Summary page.
12. Change Assistant will begin building the Change Assistant job.
13. The Update job will be created and open in Change Assistant.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
255
Defining and Applying Translations Fixes
Chapter 17
Image: Example Translations Delta Project Job
This example illustrates a Translation Delta Project Job.
256
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Part III
Using Change Assistant with Non-PUM
Enabled Systems
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
257
Using Change Assistant with Non-PUM Enabled Systems
258
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
Discovering Updates Using My Oracle Support
If the current application level of PeopleSoft product is not PUM-enabled, it is necessary to use My
Oracle Support to discover updates and then download them to your local system.
1. Log onto My Oracle Support (MOS).
2. Select Patch and Updates tab.
For detailed instructions on using MOS for patches and updates, refer to
My Oracle Support Patches and Updates for PeopleSoft Products [ID 1465172.1]
Downloading Updates From My Oracle Support
When you select an update to download, you will be downloading the change package. You will need
to set up a download directory on your local machine to store all of your downloaded change packages.
When you are ready to apply the change packages, you will reference this directory from Change
Assistant.
Downloading a Single Patch
To download a patch from the Patch Details page:
1. In the Patch Search Results table, click the patch name link to view the patch details page.
2. Click Download.
3. Select the Include Prerequisites check box to list all the prerequisite change packages.
4. In the File Download window, click the patch file name link and select Save.
The context bar for each patch provides a download option. Note that you can select multiple patches
from a list by using Ctrl or Shift.
Downloading Multiple Patches From My Oracle Support
To download more than one patch:
•
From the patch search results, click anywhere in the row except a link to select that row. Use Ctrl or
Shift to select multiple rows.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
259
Using Apply Update Action
Chapter 18
•
Choose the Download button from the context bar.
•
Click each file and save it.
Using WGET Options
WGET is a UNIX download utility. The WGET options enable you to create a WGET download script
that you can save as a file or copy to the clipboard.
Note: The WGET download script is intended for advanced users. In most cases, there are no messages to
indicate that an error has occurred. Before using the WGET script, you should be familiar with the WGET
command and WGET log files. You should also be familiar with UNIX file management, know how to
edit, delete, and copy UNIX files, create and edit shell scripts, change execute privileges in UNIX, and
understand HTTP error codes. Alternatively, use a download manager to download multiple patches. If
you do this, you must maintain an active My Oracle Support session while you download the patches.
For details on using the WGET options refer to
Patches and Updates
Reviewing the Updates Change Log
Using the Environment Management hub, Change Assistant evaluates the change log status of the
available environments to identify if prerequisites have already been applied before allowing you to apply
a new change package.
To review the change log for an environment, or to confirm whether particular update has been applied,
you use the following PeopleTools utilities:
Utility
Navigation
Updates - View All
PeopleTools, Utilities, Administration, Updates - View All
Updates by Release Label
PeopleTools, Utilities, Administration, Updates by Release
Label
Updates by Update ID
PeopleTools, Utilities, Administration, Updates by Update
ID
Only those application releases in which all of their application updates were delivered in change
packages are considered to have reliable change log data. Application updates that you applied that were
not delivered as change packages are probably not included in your change log. Therefore it's possible
that your change log does not match your actual maintenance history. In these cases, you should apply
change packages individually—select only one change package in the Update Wizard. Then, you can
verify whether the list of missing prerequisites reported by Change Assistant accurately reflects your
maintenance history.
260
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
If your target environment is at an application release level that is not considered to have reliable change
log data, Change Assistant may falsely report that a prerequisite is missing from this environment. If this
is the case, do not add the supposed missing update to your current apply list, as this would reinstall the
update (not recommended).
Therefore, if your target environment may have unreliable change log data, review the list of missing
prerequisites found by Change Assistant and if any of these updates are known to have been previously
applied to your target environment, manually enter these updates to your change log first so that Change
Assistant can accurately determine that these prerequisites have been satisfied. If you need to add entries
to your change log, you will have to restart the apply change packages process.
Configuring Change Assistant for Apply Updates Action
Before you can apply an update, you need the following:
1. Change package in your download directory.
For non-PUM enabled applications, this is the change package downloaded from MOS. See
Downloading Updates From My Oracle Support
For change packages created for your own customizations, place the change package in the download
directory. See Creating a Change Project
2. Environment Management Framework must be configured and running.
See Configuring the Environment Management Hub
Selecting Apply Updates Action
To start Change Assistant: and apply updates:
1. Select Start, Programs, PeopleSoft Change Assistant 8.54.xx, where xx refers to the release/patch
number.
2. Depending on your preferences, you may or may not see a Welcome dialog box. If the Welcome
dialog box is displayed, click Next.
The Select Action page is displayed.
3. Select Apply Updates and click Next.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
261
Using Apply Update Action
Chapter 18
Image: Apply Updates Tasks
This example illustrates the fields and controls on the Select Task page for Apply Updates. You can
find definitions for the fields and controls later on this page.
4. The options required for Apply Updates are shown on the left side of the page. If the options have not
been defined, Change Assistant will guide you through the set up pages. Click each option to ensure it
is properly configured for this action.
General Options
Image: General Options for Apply Updates
This example illustrates the fields and controls on the General Options page. You can find definitions for
the fields and controls later on this page.
Maximum Concurrent Processes
262
Specifies the maximum number of processes that can be
executed concurrently on the local machine. The default is 1.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
PS Home Server Starting Port
Using Apply Update Action
Specify the port number for the first PS Home server.
Change Assistant uses this port number to communicate with
Change Assistant PS Home servers. The default starting port
number is 6151. If you enter a port number that is already
in use, you see an error message. You must change to a port
number that is not in use, and then restart Change Assistant for
the change to take effect.
PS Home Server Maximum Instances Enter a number between 1 and 10 for the maximum number of
PS Home servers.
Use this value for environments with more than one PS_HOME.
For each server instance, Change Assistant increments the PS
Home Server Starting Port number by 1 up to the maximum
number of instances. For example, with a PS Home Server
Starting Port value of 6151 and a PS Home Server Maximum
Instances value of five, the port numbers would be 6151, 6152,
6153, 6154, and 6155. The default is 5.
If you change this value, you must restart Change Assistant for
the change to take effect.
PS Home, PS App Home, and PS
Cust Home
Enter the full path for your PS home directories.
Staging Directory
Enter the directory in which you would like to stage all the
Change Assistant update files. This is the location that Change
Assistant will store files to be used during the apply update
process.
Output Directory
Enter the directory in which you want the log files generated by
the update process to reside.
Download Directory
Enter the full path of the location to where you downloaded the
update change packages.
Note: Specify the PS_HOME location you used to install
Change Assistant.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
263
Using Apply Update Action
Chapter 18
EM Hub Options
Image: EM Hub Options for Apply Updates
This example illustrates the fields and controls on the EM Hub Options page. You can find definitions for
the fields and controls later on this page.
Configure EMHub For Deploy File
Select this checkbox if you want to use EMHub for file deploy.
Note: In order to apply traditional updates (non PUM-enabled)
EMF must be configured and running.
264
Server Host Name
The hostname of the server in which the Environment
Management HUB resides.
Server Host Port
Indicates the port in which to connect to the Environment
Management hub.
Chunk Size
Used for deploying files during a software update. Default is
1024 * 1024 bytes. Typically this does not need to be changed
unless there are a significant number of files greater that
1024KB in a software update.
Ping Interval
Ping interval is in milliseconds for Change Assistant to contact
the hub for new messages.
Drives to Crawl
Setting of drives to crawl to identify the configuration of the
Change Assistant machine. Windows directories need to use
the forward slash (/) character. Include your local drive in this
setting so that Change Assistant can locate the SQL Query tool
used for automating steps. Also include the path of the SQL
Query tool.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
Note: For traditional updates, Change Assistant discovers the
SQL Client Tool using EM Hub. There is a directory path limit
of 5 when EM hub crawls the drives, therefore if your SQL
Client Tool is more than 5 directories deep, you must provide
partial path. For example: D:/|D:/Oracle/app/Administrator
where the full path to the query tool is path is D:\Oracle\app
\client\Administrator\product\12.1.0\client_1\BIN\sqlplus.exe.
Ping
Click to verify a valid server URL. If you see Service is off to
the right of this button, then you must correct the server URL
and ping again until you see Service is on.
Note: This button is visible only if your display is set to
Windows Classic style. To change the Windows display,
select Programs, Control Panel, Display. Select the change
the Windows display, select Programs, Control Panel, Display.
Select the Appearance tab and choose Windows Classic style
from the Windows and buttons drop-down list.
View
Click to display the list of all PeopleSoft components discovered
and registered in the Environment Management hub.
Note: This button is visible only if your display is set to
Windows Classic style.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
265
Using Apply Update Action
Chapter 18
Additional Options
Image: Additional Options for Apply Updates
This example illustrates the fields and controls on the Additional Options page. You can find definitions
for the fields and controls later on this page.
Notification Settings Section
266
Send Email Notifications
Select this check box to receive email notifications if there are
errors in the update process. Change Assistant also sends you
a completion message when it encounters a Stop in the update
process.
SMTP Server
Enter the SMTP mail server from which you receive the error or
completion messages.
Port
Enter the port from which you want to access the email.
Send To
Enter the address to which you want the email sent.
Return Address
Enter the email address of the sender. Use this to identify who
sent the notification.
Test
Validates that email is sent to the designated recipients and is
working correctly.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
Note: Ensure that your SMTP server is installed and configured
correctly.
Proxy Section
Host
(Optional) Enter the name of the proxy server if you want to run
Change Assistant behind the firewall using a proxy server.
Port
(Optional) Enter the port number for the proxy server.
Anonymous Proxy
Indicates that you are using a proxy server that does not require
authenticated connections.
Microsoft Proxy Server
Indicates that you are using a proxy server with Windows
authentication.
Windows Domain
The network domain in which the system runs.
Other Proxy Servers
Indicates you are using non-Microsoft proxy servers.
Validating Change Assistant Settings
Before applying non-PUM updates, you should validate your settings.
Change Assistant validates settings by:
•
Locating valid SQL query tools required to run SQL scripts.
•
Testing the Environment Management hub and ensuring that Change Assistant can communicate with
it.
You can also print a summary of your environment, which can facilitates the diagnosis of problems by
Oracle Global Customer Support.
To validate your environment:
1. From the Select Task page, select Change Assistant Validate EMF Setting and click Finish or from the
menu bar, select Tools, Validate.
2. Click Start Validation.
3. When the validation process has completed, a completion message appears.
4. If any of the steps were unable to complete successfully, open the log file to determine the cause.
Click View Log in the lower part of the screen to see more details regarding individual steps of the
validation.
You can also select the Validate Change Assistant EMF Settings radio button from the Change Assistant
Wizard when the action Apply Updates is selected.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
267
Using Apply Update Action
Chapter 18
Image: Validating Change Assistant Settings in Your Environment
This example illustrates validation results.
Note: If you use proxy servers, the system will ping those and prompt for proxy server user ID and
password.
Working with Templates
When applying a change package, Change Assistant uses the update template embedded in the
PeopleSoft-provided change package. You can use the update template to automate the majority of the job
steps. The primary difference between a template and a job is that a template is a composite of the update
process, whereas a job is a set of filtered steps for a given target environment within a template.
When you apply updates by using the Apply Update action with the Apply Change Packages option,
Change Assistant automatically loads the template into the Change Assistant internal storage system. You
can add additional chapters, tasks, and steps to the template.
Note: Any changes that you make to the imported template won't affect the original template that you
downloaded with the change package. If you want to overwrite the original template with your changes,
save the template and select File, Export to export it to the directory from which you downloaded it. You
can also use the export function to make this modified template available to others.
In order for others to use the template that you create or modify, you need to export it from Change
Assistant.
To export a template:
1. Select File, Open Template.
2. Select File, Export Template.
The Export Template dialog box appears.
3. Navigate to the folder in which you want to save the template.
268
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
4. Enter the name of the template.
Note: If you want to overwrite the original template that you downloaded, enter the original name of
the template.
5. Click Save.
Note: To ensure consistency with shared templates, the system includes all template and step
properties in the exported XML file, regardless of whether the property value differs from the default
value.
Setting 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.
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.
4. Save the template.
Note: The saved template will include the documentation path information.
See Working with Embedded Documentation.
Applying Updates To A Target Environment
The apply process enables you to apply one or more change packages to the target environment. A typical
change package apply process, would be as follows:
1. Apply the change package without compare to your demonstration environment.
Since the demonstration environment does not contain any customizations, there is no need to
compare. This brings the demonstration environment current on the specific maintenance, overwriting
the new maintenance into the demonstration environment.
2. Apply the change package to the first customized environment by using the 'Apply with Database
Compare/Copy' option.
This uses your demonstration database as the source and this customized environment as the target.
This process augments the normal Change Assistant template/job in order to compare the change
project from the demonstration database to the target database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
269
Using Apply Update Action
Chapter 18
3. Use the PeopleTools database compare and copy utilities to reconcile the new changes from
PeopleSoft with your customizations, just as you do during an upgrade.
4. Once the reconciled or modified change package is created, it can then be applied without compare
into all other customized environments, assuming these customized environments are the same.
To apply change packages to the target environment:
1. The Environment Management Hub must be up and running.
2. In Change Assistant, select Tools, Change Actions.
3. Select Apply Updates.
4. Select Apply Change Packages and click Finish.
5. Apply Change Packages Wizard starts.
You use the Apply Change Packages wizard to select the appropriate settings for a change package.
Image: Apply Updates to Target Environment
This example illustrates the fields and controls on the Apply Updates to Target Environment page. You
can find definitions for the fields and controls later on this page.
Apply Automatically Without
Compare
Applies the change package to the target environment and
copies the project without initiating any compare reports or
analysis.
Select this option if you are:
•
Applying a PeopleSoft-delivered change package to a
PeopleSoft demo environment.
Because you have not made any customizations to a
demonstration environment, there is no need to compare
objects.
270
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
•
Applying a modified change package to your own
environments, as in development, test, or production
environments.
The "modified change package" refers to a new change
package created using the Apply with Database Compare/
Copy option. This modified change package is the result of
the Change Management process where you have reconciled
changes made in the PeopleSoft maintenance with your
customizations. Once the modified change package has been
created for the first customized environment, there is no
need to compare additional environments. This assumes
that the additional environments contain the same metadata.
Once you have created this modified change package, it can
be applied without compare to the remaining customized
environments.
See Apply Without Compare
Apply With Database Compare/
Copy
Select this if you are beginning the process of migrating a
PeopleSoft-delivered change package to your customized
environments. In this case, you are applying to a customized
environment, and this will require the use of PeopleTools'
change management tools, such as compare and copy.
See Apply With Compare or Copy
Note: When applying multiple updates, a job set may not move on to the next update if there are steps in
the current update with a status of Warning rather than Success. In this situation, review the logs for the
steps with warnings and take any corrective measures, as needed. Then change the status of these steps
from Warning to Complete to proceed to the next change package in the job set.
Apply Without Compare
This section describes the apply process after you have selected the Apply Automatically without
Compare option.
To apply a change package without compare:
1. On the Apply Updates Using the Change Impact Analyzer screen indicate whether you want to
include Change Impact Analyzer analysis.
Typically, system administrators use Change Impact Analyzer to help devise a test plan based on the
impact of changes.
2. On the Select a product line release screen indicate product line associated with the target
environment.
3. On the Select Target Environment screen, select the database name associated with the target
environment.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
271
Using Apply Update Action
Chapter 18
All PeopleSoft web servers, application servers, Process Scheduler servers, and so on, are associated
with one, and only one, environment, which is determined by the database. Change Assistant will revalidate the environment.
4. On the Environment Preparation screen acknowledge that you have performed the recommended preupdate procedures.
5. On the Select File Servers screen, select the file servers that are used in conjunction with the target
environment.
Note: The system uses this file server selection only as a destination to deploy files during the apply
process. The file server specified is not used for execution purposes. The executables used to run
steps during the apply process are those specified in the PS_HOME edit box on the Change Assistant
Options page.
File server installations are not necessarily tied to any one environment, unlike application servers,
web servers, Process Scheduler servers and database servers, which are associated with one, and
only one, database environment. On the other hand, a single file server could be used for multiple
databases, and likewise, there could be multiple file servers in your PeopleSoft implementation all
supporting different application versions. So, it is necessary to prompt you to select the appropriate
file server installation.
6. On the Enter user name and password screen, enter the user credentials required for Change Assistant
to be authenticated.
Note: For the Apply without compare, only the target database is required. For the Apply with
compare, credentials for both the target and source are required.
7. On the Select Download Directory screen, confirm the location of the change packages you intend to
apply.
8. On the Select Change Packages screen, select change packages to install.
You can use Select All to select all the available change packages listed on the screen.
9. Click Next after you've selected your change packages.
At this time, Change Assistant examines all the selected change packages to determine if any of them
have previously been applied.
Note: If an Unable to read change package error appears because of an unsupported change package
version number, then you must install the latest release of Change Assistant.
10. If the change package has already been installed, you will be prompted to select one of the following
options:
•
Do not reapply the change package.
•
Review each change package individually, with option to apply.
If you choose to review each change package individually, you will be prompted either not to
reapply the change package or to reapply the change package (not recommended).
272
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
Using Apply Update Action
11. Select the options, then click Next.
If none of the translated languages included in a change package applies to the languages installed in
the target environment, you will be prompted to select one of the following options:
•
Remove these change packages from my installation list.
•
Review each of these change packages individually, with option to apply.
If you elect to review each change package individually, you will be prompted either not to apply
the change package or to apply the change package (not recommended).
12. After you've made your selection, Change Assistant searches for post-requisites. If there are postrequisites that are not listed in the apply list, you will be prompted to select one of the following
options:
•
Apply these additional change packages.
The additional change packages are added to the list of selected change packages.
Note: This option is enabled only if the additional change packages are already present in your
apply directory.
•
Remove the change packages that require post-requisites from my installation list.
13. Click Next.
Change Assistant searches for any missing prerequisites required by the selected change packages,
and you will be prompted to make the same selections as in the previous step.
Note: If your target environment is at an application release level that is not considered to have
reliable change log data, Change Assistant may falsely report that a prerequisite is missing from this
environment. If this is the case, it is very important that you not elect to add the supposed missing
update to your current apply list, because this would reinstall the update, which is not recommended.
Therefore, if your target environment is considered to have unreliable change log data, it is very
important that you review the list of missing prerequisites found by Change Assistant. If any of
these updates are known to have been previously applied to your target environment, you must first
manually enter these updates to your change log so that Change Assistant can accurately determine
that these prerequisites have been satisfied. If you need to add entries to your change log, you will
have to restart the Apply Change Packages process.
14. After you have selected your option, click Next.
If one or more of the change packages you are applying includes the Build and Alter template steps,
you will be prompted to select one of the following methods to apply the database changes.
•
Automatically: Enables build scripts to be run as an automated template step.
•
Manually: Enables the build script to be run as a manual template step.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
273
Using Apply Update Action
Chapter 18
15. If one of your selected changes packages will be executing a script that includes embedded question
syntax that is supported by Change Assistant, you will be prompted to enter a runtime value for the
script variables.
16. Click Next to display a screen where you confirm your selections–target environment and change
packages to apply and number of manual steps, if any, for each change package.
17. On the Apply Now screen, consider the options presented before applying the change project.
Validate Now
Note: Before you initiate the apply update process, you
can validate your environment connections to ensure all
components are active.
Review and Apply
Enables you to review the entire job to make sure it is
correct before running it against an environment.
Note: If there are steps you don't want run or have already
completed manually, you could set them to Complete
while reviewing the job. For example, if you have already
deployed some files manually to a certain PS_HOME,
you could set that step to Complete to save time and avoid
overwriting any custom settings.
Begin Apply
Starts the update job.
Apply With Compare or Copy
The interface of the Apply Change Packages wizard is similar to what you see with the Apply Without
Compare option, however, the following steps are included.
•
Compare project from the demo database to the development or copy of production database.
Change Assistant will compare this project between the source database and the currently selected
environment (target database).
•
Examine the compare report step (a manual step).
You must examine the compare reports generated to determine the appropriate action (for example,
whether or not to copy the object from the source database to the target database).
•
Copy project from the source database.
Change Assistant copies the objects from the source database to the target database, based on the
actions chosen.
•
Extract the files from the delivered change package.
Change Assistant will extract the current change package to a temporary location (<<staging
directory>>/~ExtractedCP).
•
Re-apply customizations.
This is a manual step.
274
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 18
•
Using Apply Update Action
Compare and merge files.
This is a manual step.
•
Export the project from the target database.
Change Assistant will export (from the target database) the project containing customize objects to a
temporary location (<<staging directory>>/~ExportedProject).
•
Change Assistant creates a new change package in the download directory. The original change
package is renamed to xxxxx.zip_datetimestamp.
Automatically Deploying Files to Different Servers
Change Assistant can automatically deploy files in a change package to different servers within an
environment. If the job that is running while applying the change package includes a Deploy Files chapter
and contains tasks and steps, that indicates to Change Assistant to deploy the files to the agents that are
running in the environment.
While Change Assistant runs deploy file steps within the job, it will query the hub for the location to
deploy the files. The query is based on the server, operating system, and database platform. If the query
returned from the hub matches what was defined for the file reference in the change package, Change
Assistant attempts to deploy the files to the agent running on the host machine.
Change packages provided by PeopleSoft applications, are configured to deploy multiple files of the
same type within one step. This can improve performance, especially when a change package contains
hundreds of updated files.
When files are deployed, the step's log file lists the host name and the type of server that match the file
reference and the target path on the remote host.
If the Environment Management agent is not running at the time when Change Assistant is trying to
deploy files, a warning message appears stating the inability to deploy the files. Other types of problems
that may occur, such as lack of disk storage space, will result in step failure.
Resuming Running Jobs
If there is a current apply job set, the Resume Running Jobs dialog box appears automatically when you
start Change Assistant, run a job, or apply change packages (start a new apply).
Select Cancel to:
•
Remove all jobs associated with the current apply job set that have not been run.
•
If a job definition is open in Change Assistant and it does not belong in the current apply job set, the
job definition remains open.
•
If a template definition is open in the Change Assistant, regardless of whether or not it's used in the
current job set, it will remain open.
Select No to keep the current apply job set and its associated jobs as they are, so that you can resume this
apply job set later.
Select Delete Job Set to delete the current apply job set.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
275
Using Apply Update Action
276
Chapter 18
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Part IV
Working With Change Packages (Traditional
Updates Only)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
277
Working With Change Packages (Traditional Updates Only)
278
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
Working with Change Packages (Traditional
Update Only)
Understanding Change Packages
Once you have your change project completed, you create a change package 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.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
279
Working with Change Packages (Traditional Update Only)
Chapter 19
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 is numeric. The system considers the first value in the list to be the primary ID for the
project. When entering your own incidents:
a. 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.
b. 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.
280
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
Working with Change Packages (Traditional Update Only)
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.
File Name and Path
Enter the path and file name for the file you want to reference.
Use the browse button to search the proper path. This is the
source location and file from which Change Packager selects
the definition for packaging. This field supports the use of
environment variables.
If you want to create a file reference with a variable path,
prepend %FILEREFPATH% to the filename.
Change Assistant Template Text
Enter the text you want to display in the Change Assistant
template for this change package. This field has a 20 character
limit.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
281
Working with Change Packages (Traditional Update Only)
Chapter 19
Binary
Check if the file is a binary file. This information is necessary to
properly transfer the file to the target platform.
Database Platform
Select the database platform for the target database.
Operating System
Select the operating system for the target database.
PeopleSoft Server
Select the applicable server for your system.
Unix Target Directory Security
Specify the file permissions the file should have once it is
copied if operating on a UNIX system.
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
•
282
Add this file reference to a change project.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
Working with Change Packages (Traditional Update Only)
Image: Example of Variable Path File Reference
This example illustrates the fields and controls on the Example of Variable Path File Reference. You can
find definitions for the fields and controls later on this page.
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 enables 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
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
283
Working with Change Packages (Traditional Update Only)
Chapter 19
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:
284
•
Create a change package.
•
Modify the Change Assistant template.
•
Finalize the change package.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
Working with Change Packages (Traditional Update Only)
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.
Image: Create Change Package dialog box
This example illustrates the fields and controls on the Create Change Package dialog box. You can find
definitions for the fields and controls later on this page.
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 Creating a File Reference Definition.
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
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
285
Working with Change Packages (Traditional Update Only)
Chapter 19
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.
286
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
•
Working with Change Packages (Traditional Update Only)
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.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
287
Working with Change Packages (Traditional Update Only)
Chapter 19
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:
•
288
a list of <release> tags that map various pillar and release identifiers into <InitialToolsRelease>
elements
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 19
•
Working with Change Packages (Traditional Update Only)
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>] [-?]
Parameter
Description
-PRJ
Specify the project file to be scanned. No default value
assumed.
-TY | -TX
-TY specifies one or more object type names to be removed,
delimited by a semicolon character (;).
-TX specifies one or more type names to be retained, delimited
by a semicolon character (;).
-TY and -TX are mutually exclusive. If neither TY nor TX are
specified, all types are removed.
-N
A list of names of instances to be removed or retained in the
form type:name0.name1.name2.name3 where each name is
delimited by a semicolon (;) character. If not specified, all
instances are removed or retained consistent with any -TY or TX specification.
-TL
Lists the valid type identifiers, names, and descriptions.
-LOG
Absolute path to log file.
-?
Shows usage details.
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
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
289
Working with Change Packages (Traditional Update Only)
Chapter 19
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] [?]
Parameter
Description
-PRJ
Path name of the project file to be scanned. There is no
default. If just a name is specified, the program checks in the
current directory.
-TY
One or more object type names to be listed, delimited by a
semicolon character (;).
If not specified, all types are removed.
-N
A list of names of instances to be removed or retained in the
form type:name0.name1.name2.name3 where each name is
delimited by a semicolon (;) character. If not specified, all
instances are removed or retained consistent with any -TY
value.
-L
Specifies the listing format and can be either N, T or C.
•
N means list the types and names of all objects with one
object per line.
•
T means list the types and counts of all objects with one
type per line.
•
(Default) C means list just the number of objects as a
single integer.
The –N and –T arguments can be used in the same command
provided the types do not overlap. Specifying the same types
in an –N name argument as in a –T argument causes an error.
-TL
Lists the valid type names, numeric identifiers, and
descriptions.
-?
Shows usage details.
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
290
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Part V
Using Change Assistant for Software
Upgrades
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
291
Using Change Assistant for Software Upgrades
292
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 20
Getting Started with Software Upgrades
Understanding Change Assistant For Upgrades
Application upgrade only applies to upgrading an older application release to application release 9.2.
Once your application is on 9.2, PUM is used to apply maintenance and new features. You use Change
Assistant to help automate and customize the PeopleSoft upgrade process. A PeopleSoft upgrade typically
includes a PeopleTools and a PeopleSoft application upgrade.
Depending on your upgrade path, the application upgrade may be combined with the tools upgrade. If
they are not combined, you will need to perform the tools upgrade before the application upgrade.
The following list describes the major steps within an upgrade when using Change Assistant.
•
Deploy the Certified Upgrade Source Image as your New Release Demo database. The Upgrade
Source Image is available for download from My Oracle Support. Or install the Demo database for
the Upgrade Certified new release from the media pack or CD, available on Oracle Software Delivery
Cloud (classic method).
See PeopleSoft Upgrade Source Image Home Page (ID: 1552580.1).
•
Deploy the PeopleSoft Update Image.
See Installing PeopleSoft Update Image
•
Configure Change Assistant for Upgrade.
See Configuring Change Assistant for Upgrade Application
•
Define Upgrade Package.
See Defining an Upgrade Package
•
Use the Upgrade Application action to create an upgrade job tailored to your specific environment,
defining all the steps required to perform the upgrade.
See Upgrading Application
•
Use Change Assistant to guide you step-by-step through the upgrade processes. Change Assistant
shows you documentation for each step, automates many of the steps, and keeps track of the upgrade
progress.
Databases Used for Application Upgrade
The following Databases are used in an Application Upgrade:
•
Production
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
293
Getting Started with Software Upgrades
Chapter 20
•
Copy of Production
•
New Release Demo (certified Upgrade Source database)
•
Update Image
As you progress through the application upgrade process, the source and target databases
Image: Application Upgrade Process
This diagram illustrates the source and target databases used during the upgrade process.
Getting Started
Download documentation for the specific upgrade process that you will be performing from the Upgrade
home page in My Oracle Support. You must read the documentation Getting Started on Your PeopleSoft
Upgrade before you continue with your upgrade. This getting started guide explains the upgrade process,
terminology, and setup tasks that must be performed prior to starting your upgrade.
Before continuing with the upgrade, you must complete all of the tasks in Getting Started on Your
PeopleSoft Upgrade, "Starting Your Upgrade."
294
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Defining an Upgrade Package
The Define Upgrade Package component in the PUM PIA application will create 2 change package
definitions:
•
Upgrade package (UPG)
This package contains the Application Upgrade template from your current release to 9.2.
•
Required for Upgrade package (RFU)
This package contains all of the bugs required for upgrade.
To define an Upgrade Package:
1. In Change Assistant configure the General Options and PUM Source.
See Configuring Change Assistant for Update Manager
2. Upload the Upgrade Source Database to the PUM Source database.
See Uploading Target Database Information
3. Select Tools, Define or Create a New Change Package.
4. Click the Click Here to Open Browser and Connect to the PUM Source Database.
5. Sign on to the PUM Source Database.
6. Select PeopleTools, Lifecycle Tools, Update Manager, Update Manager Dashboard.
7. Expand the folder Select Target Database.
8. Click on the Upgrade Source database name.
9. Expand the Define Change Package folder and select Define Upgrade Package.
10. The Define Upgrade Package wizard will guide you through the steps to create a change package
definition.
•
Step 2 of 6 - Enter Change Package Name
See Define Upgrade Package Step 2 of 6
•
Step 3 of 6 – Select Scope
•
Step 4 of 6 – this step does not apply to upgrade packages and therefore is skipped.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
295
Configuring Change Assistant for Upgrades
Chapter 21
•
Step 5 of 6 - Review Bugs
•
Step 6 of 6 - Done Identifying Bugs
11. Return to Change Assistant and create the Upgrade Change package.
Selecting the Target Database
The target database for an Upgrade package is the Upgrade Source database (New Release Demo).
Define Upgrade Package Step 2 of 6
Enter a name and description for the Upgrade Package.
Image: Define Upgrade Package Step 2 of 6
This example illustrates the fields and controls on the Define Upgrade Package Step 2 of 6. You can find
definitions for the fields and controls later on this page.
Package Name
296
Enter a name for your upgrade package. To edit an existing
change package, select the Lookup button. The list of change
packages that can be edited is restricted as follows:
•
Packages created by the current user.
•
Packages created for the currently selected target database.
•
Packages which have been defined but have not been
created.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
If the package name already exists, the Change Package Options
page will be displayed. See Define Change Package Wizard
Step 2 of 6
Package Description
Enter a description for the upgrade package.
Define Upgrade Package Step 3 of 6
Select which App Upgrade Option to use. By default Application Upgrades to 9.2 is selected.
Image: Define Upgrade Package Step 3 of 6
This example illustrates the fields and controls on the Define Upgrade Package Step 3 of 6.
App Upgrade Options
Application Upgrades to 9.2
Select this radio button to create an application upgrade package
(UPG).
Select the From release from the drop down list.
Select the Select the To path which will align with the Upgrade
Certified Image, for example 9.2 Image 10 from the drop down
list.
By default Required for Upgrade Fixes will be included in the
package.
Note: When you select this option 2 change package definitions
are created UPG and RFU.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
297
Configuring Change Assistant for Upgrades
Required for Upgrade Fixes
Chapter 21
Select this radio button to create a Required for Upgrade (RFU)
package.
Note: When you select this option only 1 change package is
created RFU.
Define Upgrade Package Step 5 of 6
When you transition to step 5, the upgrade path is displayed.
Image: Define Upgrade Package Step 5of 6
This example illustrates the fields and controls on the Define Upgrade Package Step 5 of 6.
Define Upgrade Package Step 6 of 6
When you transition to Step 6 the project definitions for the upgrade (UPG) and the required for
upgrade( (RFU) are created, as well as the Change Assistant template.
You will return to Change Assistant to create the Change Packages.
298
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Image: Define Upgrade Package Step 6 of 6
This example illustrates the fields and controls on the Define Upgrade Package Step 6 of 6.
Creating Upgrade Package
To create the upgrade package in Change Assistant:
1. Navigate to the Define or Create a New Change Package if you are not already on that page.
Select Tools, Define or Create a New Change Package
2. Select the upgrade change package for the drop down. There will be 2 packages for upgrade (UPG
and RFU). Select one of these.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
299
Configuring Change Assistant for Upgrades
Chapter 21
Image: Create a New Change Package
This example illustrates the fields and controls on the Create a New Change Package. You can find
definitions for the fields and controls later on this page.
3. Click Next. You will receive a message Do you need to create the corresponding UPG CP? or
Do you need to create the corresponding RFU CP?, depending on your selection. Click OK.
4. The change packages will be created.
Configuring Change Assistant for Upgrade Application
Before you begin performing an application upgrade using Change Assistant, you configure Change
Assistant settings.
•
General Options
•
PUM Source is not used with Upgrade Application
•
EM Hub is not used with Upgrade Application
•
Additional Options is optional.
Depending on the upgrade pass, the source and target databases will change.
300
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Pass
Source
Target
Initial
New Release Demo database
Copy of Production
Note: This is either the certified Upgrade
Source Image or Demo database for the
Upgrade Certified new release installed
from the media pack or CD.
Test Move to Production
Upgraded Copy of Production
New Copy of Production
Move to Production
Upgraded Copy of Production
Production
Setting Change Assistant Options
To set Change Assistant Options:
1. In Change Assistant, select Tools, Options.
2. Select Application Upgrade and click Next.
3. On the General Options page, specify the high-level settings for your current environment. and click
Next.
4. On the Additional Options page, enter your optional email notifications settings.
5. Click Finish.
General Options
The values entered on the General Options page are used as the default values for all of the various
databases in the upgrade process.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
301
Configuring Change Assistant for Upgrades
Chapter 21
Image: General Options page
This example illustrates the fields and controls on the General Options page. You can find definitions for
the fields and controls later on this page.
Maximum Concurrent Processes
Specifies the maximum number of processes that can be
executed concurrently on the local machine. The default is 1.
PS Home Starting Port
Specify the port number for the first PS Home server.
Change Assistant uses this port number to communicate with
Change Assistant PS Home servers. The default starting port
number is 6151. If you enter a port number that is already
in use, you see an error message. You must change to a port
number that is not in use, and then restart Change Assistant for
the change to take effect.
PS Home Server Maximum Instances Enter a number between 1 and 10 for the maximum number of
PS Home servers.
Use this value for environments with more than one PS_HOME.
For each server instance, Change Assistant increments the PS
Home Server Starting Port number by 1 up to the maximum
number of instances. For example, with a PS Home Server
Starting Port value of 6151 and a PS Home Server Maximum
Instances value of five, the port numbers would be 6151, 6152,
6153, 6154, and 6155. The default is 5.
302
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
If you change this value, you must restart Change Assistant for
the change to take effect.
PS Home
Enter the full path in which you installed PeopleTools client on
the Windows Client machine.
Note: Specify the PS_HOME location you used to install
Change Assistant.
Staging Directory
Enter the directory in which you would like to stage all the
Change Assistant upgrade files. This is the location that Change
Assistant will store files to be used during the upgrade job.
Output Directory
Enter the directory in which you want the log files generated by
the upgrade job.
Download Directory
Enter the download directory where you created the Upgrade
Change Package.
Additional Options
Image: Additional Options page
This example illustrates the fields and controls on the Additional Options page. You can find definitions
for the fields and controls later on this page.
Send Email Notifications
Select this check box to receive email notifications if there are
errors in the update process. Change Assistant also sends you
a completion message when it encounters a Stop in the update
process.
SMTP Server
Enter the SMTP mail server from which you receive the error or
completion messages.
Port
Enter the port from which you want to access the email.
Send To
Enter the address to which you want the email sent.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
303
Configuring Change Assistant for Upgrades
Chapter 21
Return Address
Enter the email address of the sender. Use this to identify who
sent the notification.
Test
Validates that email is sent to the designated recipients and is
working correctly.
Note: Ensure that your SMTP server is installed and configured
correctly.
Upgrading Application
Before using the Upgrade Application task, the following must have been completed:
•
Define Upgrade Package
•
Configure Change Assistant Settings.
To use the Upgrade Application
1. In Change Assistant, select Tools, Upgrade Application.
Note: You must be in the Update Manager action.
2. The Change Package Wizard will guide you through the creating the upgrade job.
3. On the Change Package Settings page, select the download directory and apply type and click Next.
4. On the Select Upgrade Target Database page , select the target database and click Next.
5. On the Select Upgrade Source Database page, select the source database and click Next.
6. On the Application Upgrade page, select the packages to apply and click Next.
7. Change Assistant will check the compatibility and display the status. Review the checks and click
Next.
8. The Apply Summary page is displayed. Click Finish.
9. Change Assistant will create the Application Upgrade job and open it.
304
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Image: Application Upgrade Job
This example illustrates the fields and controls on the Application Upgrade Job.
Change Package Settings
On the Change Package setting page, you will select the download directory and apply type.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
305
Configuring Change Assistant for Upgrades
Chapter 21
Image: Upgrade Application - Change Package Settings
This example illustrates the fields and controls on the Upgrade Application - Change Package Settings.
You can find definitions for the fields and controls later on this page.
Download Directory
Select the directory where you created the Upgrade Package.
See Creating Upgrade Package
Apply Type
Select the Apply Type. By default Initial Pass is selected.
•
Initial Pass (default)
Initial upgrade pass on your Copy of Production database.
•
Move to Production
Upgrade between your Copy of Production database and
your test or production system.
Select Upgrade Target Database
On the Select Target Database page, select the target database to upgrade. If the target database does not
exist, click the Create button to launch the Database Wizard. See Defining Databases
If the application upgrade includes a PeopleTools Upgrade, the Set path checkbox in the New Homes
section of the Define Database page must be selected and the New Home information entered.
306
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Image: Select Upgrade Target Database page
This example illustrates the fields and controls on the Select Upgrade Target Database page.
Select Upgrade Source Database
For the initial pass, the upgrade source database is the Release 9.2 Demo database certified for this
upgrade.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
307
Configuring Change Assistant for Upgrades
Chapter 21
Image: Select Upgrade Source Database
This example illustrates the fields and controls on the Select Upgrade Source Database.
Select Application Upgrade
On the Select Application Upgrade Page, the Upgrade source and target are displayed with the
PeopleTools release for the database, the current PS_HOME and the new PS_HOME.
308
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
Configuring Change Assistant for Upgrades
Image: Select Application Upgrade page
This example illustrates the fields and controls on the Select Application Upgrade page. You can find
definitions for the fields and controls later on this page.
Select the Packages to Apply:
•
Application Upgrade
•
Required for Upgrade Package
•
PeopleTools Upgrade
•
PeopleTools Patch
Check Compatibility Page
The check Compatibility page
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
309
Configuring Change Assistant for Upgrades
Chapter 21
Image: Check Compatibility page
This example illustrates the fields and controls on the Check Compatibility page. You can find definitions
for the fields and controls later on this page.
The following compatibility check are performed:
310
•
Check 1: PeopleTools Upgrade Check
•
Check 2: PeopleTools Version check for Upgrade
•
Check 3: RFU Change Package Check
•
Check 4: Target Application Version Check
•
Check 5: Source Application Version Check
•
Check 6: PeopleTools Version of Target Environment Check
•
Check 7: PeopleTools Version of Upgrade Patch Version Check
•
Check 8: ProductLine of Target Database
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 21
•
Configuring Change Assistant for Upgrades
Database type and PS home version
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
311
Configuring Change Assistant for Upgrades
312
Chapter 21
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 22
Running Upgrade Jobs with Change
Assistant
Running the Upgrade Job
When you create a new upgrade job, you will see a job view similar to the following example:
Image: Upgrade Job
This example illustrates the fields and controls on the Upgrade Job. You can find definitions for the fields
and controls later on this page.
In the job area on the left-hand side of the screen, you'll see one of the following icons next to the steps.
Indicates each step that must be performed manually. The status
of manual steps can be set only to Stop or Complete.
Indicates that Change Assistant can automatically run this step.
You can set the status to Stop, Run, Restart, or Complete.
If you set the status to Stop, this indicates that you want to stop
the upgrade job at that step or that a milestone has been reached.
The status can be reset to Run when desired.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
313
Running Upgrade Jobs with Change Assistant
Chapter 22
Indicates a restart process. If a step failed and you corrected the
problem, you can set the step to restart from the point of failure.
Indicates that the process is running.
Indicates a failure has occurred that needs immediate attention.
This appears if a Data Mover script, SQL script , or project copy
step fails. Resolve the error before continuing with processing.
Indicates a warning for this step which does not need immediate
attention. The job continues processing with no adverse affects.
After the job completes, review the steps in a warning state and
evaluate for further action.
Indicates that the step was completed by the system.
Indicates this step was completed manually.
Indicates this step is filtered at the job level.
Steps filtered at the job level will not execute and are equivalent
to Complete. To hide these steps, select View, and deselect Steps
Filtered at the Job Level.
Indicates this step is filtered by a filter query.
Steps filtered by filter query will not execute and are equivalent
to Complete. To hide these steps, select View, and deselect Steps
Filtered by Filter Query.
When you are ready to run your upgrade job, select Run from the Change Assistant toolbar. Monitor
the status of the automated upgrade steps in the Step Details box. After a automated step is completed
running in Change Assistant, you can view logs, scripts and update job properties for individual steps.
Note: Change Assistant uses Application Designer and Data Mover in the background to perform many
of the tasks. When using Change Assistant, make sure that any current Application Designer and Data
Mover sessions running on the same workstation as Change Assistant are closed before running Change
Assistant.
Viewing Upgrade Logs
You can view all the logs generated by the automated processes. After the process runs, you can select a
step to view.
To view a log:
1. Highlight or select the step.
2. Select Edit, View Log.
314
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 22
Running Upgrade Jobs with Change Assistant
3. Click OK
Note: If a step encounters an error, Change Assistant will automatically display the View Log.
Note: On the left side of the file list, Change Assistant displays both error and success symbols. These
indicate which step logs contain errors to help you troubleshoot.
Viewing Scripts
You can view SQL and Data Mover scripts that are used to automate processes. Before the step that
contains the script runs, you can view or modify the original script. After the process runs, you can view
or modify the updated script and then restart the step.
To view a script:
1. Highlight or select the step.
2. Select Edit, View Script.
3. On the View Script dialog box, select the script you wish to view and click OK.
Modifying Job Properties
You may want to maintain a record of how long your upgrade takes. In that case, you can view and
change the dates and durations for steps in the View/Edit Job Properties dialog box.
Change Assistant allows you to set the status for these sub-steps: DBTSFIX, UpgradePeopleTools and
LoadBaseData.
To modify job properties:
1. Highlight or select the step.
2. Select Edit, Job Properties.
3. Enter changes to a specific job property, or add comments, and click OK.
Running Process Scheduler Steps
This section discusses how to:
•
determine when to run Process Scheduler steps.
•
prepare to run Process Scheduler steps.
•
work with Process Scheduler steps.
•
ensure Process Scheduler security authentication.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
315
Running Upgrade Jobs with Change Assistant
Chapter 22
Determining When to Run Process Scheduler Steps
Running the ProcessScheduler step type is designed to improve performance and quicken completion
times of long-running, data-intensive steps, that can be run in parallel in an application upgrade. In most
cases, the steps that would require Process Scheduler processing are delivered in your upgrade template
configured to run on a Process Scheduler server. However, if you are creating a custom template, decide
that improved performance can be gained by running a step through Process Scheduler, as opposed to
running through a remote agent, you can configure a process to be run by a ProcessScheduler step.
Before setting up an upgrade process to be run through Process Scheduler:
•
always consult your specific upgrade documentation for any recommendations, considerations, or
restrictions.
•
make sure Process Scheduler is configured and defined within your upgrade environment.
Note: Refer to the PeopleSoft upgrade documentation for your upgrade path for additional information.
Preparing to Run Process Scheduler Steps
Before running an upgrade process though Process Scheduler, the following items need to addressed:
Task
Documentation Reference
Set up Process Scheduler.
See Process Scheduler
Define Process Scheduler servers in your upgrade database.
See Specifying Database Process Scheduler Settings.
Include a ProcessScheduler step type in your upgrade
template.
See Step Parameters.
Working With Process Scheduler Steps
This section discusses how to:
•
View Process Scheduler logs.
•
Restart Process Scheduler steps.
•
Cancel Process Scheduler steps.
Viewing Process Scheduler Logs
If in your upgrade environment you have configured Change Assistant to be able to access Process
Scheduler logging information, you can view the Process Scheduler processing information from within
Change Assistant just as you would for any other step (click on the step and select Edit, View Log).
The status returned by Change Assistant for the step matches the status returned by Process Scheduler
itself. The log files generated by Process Scheduler are not parsed for warnings or errors. Therefore, even
though Change Assistant may show a status of Complete for a Process Scheduler step type, you should
review the generated log files for more details.
316
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 22
Running Upgrade Jobs with Change Assistant
Restarting Process Scheduler Steps
If a Process Scheduler step has failed or has been stopped, you can restart the process by setting the step
to Restart. This is most useful for restart-aware process definitions using Application Engine. When a step
has been set to Restart, Change Assistant resubmits the process requests to Process Scheduler.
Canceling Process Scheduler Steps
While Change Assistant is executing the ProcessScheduler step, you can kill the step, by clicking on
the step and selecting Run, Kill. This is equivalent to stopping or cancelling scheduled processes on the
Process Scheduler. When you 'kill' the step, Change Assistant connects to the Process Scheduler, which
issues "cancel" commands to the appropriate processes.
Ensuring Process Scheduler Security Authentication
PeopleSoft Change Assistant uses the PROCESSREQUEST component interface object to submit jobs
to run on the PeopleSoft Process Scheduler server. You must ensure the user submitting the process has
the appropriate authentication set for the PROCESSREQUEST object in the database the process runs
against. You must edit security permissions to run the PROCESSREQUEST object.
To set up PROCESSREQUEST component interface security:
1. Log in to PeopleSoft through the browser.
2. Select PeopleTools, Security, Permissions & Roles, Permission Lists.
3. Select the permission list for which you want to set security. The Permission List component appears.
4. Access the component interfaces page and select the PROCESSREQUEST component interface.
5. Click Edit.
The Component Interface Permissions page appears, showing all of the methods (both standard and
user-defined) in the component interface and their method access.
6. Set the access permission for each method.
Select Full Access or No Access. You must grant full access to at least one method to make the
component interface available for testing and other online use.
7. Click OK, and then Save.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
317
Running Upgrade Jobs with Change Assistant
318
Chapter 22
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
Understanding Data Conversion Utilities
The Upgrade Data Conversion Application Engine Programs are organized into a series of Drivers or
Groups that guide the flow and order of execution at runtime for a particular upgrade path.
This topic contains information regarding People Tools Impact Analysis (PTIA) and the
PS_PTIA_DCAEPGMS table. The PTIA process consists of two Application Engine programs and is
intended to optimize the data conversion process by analyzing Source and Target tables and state records
to determine actual dependencies between Application Engine sections. This allows you to run your data
conversion process during your PeopleSoft application upgrade with optimal performance.
Using the PTIA Data Conversion Process
This section discusses:
•
Understanding the PTIA Data Conversion Process
•
Reviewing PTIA Initial Analysis
•
Reviewing Dependency Analysis
•
Reviewing Runtime for PTIADATACONV
•
Reviewing PTIA Reporting
Understanding the PTIA Data Conversion Process
The PeopleTools Impact Analysis (PTIA) process uses many pieces of the previous style data conversion
delivered in PeopleSoft 9.1 applications and lower. For example, PTIA uses the Application Engine
section grouping and sequencing in the PS_PTIA_DCAEPGMS table for its dependency modeling. The
PTIA process also uses the terminology – root or top section. A root or top section is an Application
Engine section defined in PS_PTIA_DCAEPGMS. We use root or top section to distinguish between
sections being called from the data conversion program as opposed to sections being called from an
Application Engine call section step.
The PTIA process includes analyzing the insert, update, and delete SQL steps in your data conversion to
determine the Source and Target tables and state records that are used. This includes analyzing dynamic
SQL, App Classes, SQLExec’s, and platform-specific code.
The Application Engine program gathers a list of Application Engine sections required for data
conversion from a given upgrade path. These sections are analyzed and SQL statements are extracted and
stored in the Application Engine Analyzer repository. Each SQL statement is analyzed to derive a list of
tables that are manipulated or queried during the execution of that SQL. Once all the SQL is analyzed,
the information is used to derive section dependency information, which is then saved in the Application
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
319
Using Data Conversion Utilities
Chapter 23
Engine Analyzer repository. PTIA allows the Application Engine data conversion to run out of the box on
a number of threads.
There are two types of analysis for PTIA: initial and dependency. This section will describe both analysis
types in detail.
Reviewing PTIA Initial Analysis
This section discusses:
•
Understanding Initial Analysis
•
Reviewing Data Conversion Query Parsing
•
Reviewing Custom Data Conversion Code
•
Reviewing Table Usage Information
•
Reviewing Non Parsable SQL
•
Reviewing the Data Conversion Repositories
Understanding Initial Analysis
The first part of the PTIA process is the PTIAANALYSIS Application Engine, also known as the
Application Engine Analyzer. PTIAANALYSIS accepts one parameter for the upgrade path, and then
queries PS_PTIA_DCAEPGMS to retrieve all the groups and sections for that upgrade path, ordering
by group and sequence. Starting with the first group and first sequence, PTIAANALYSIS parses each
Application Engine section definition following the flow from step to step and through any nested call
sections. As it follows the flow, it inserts rows into the PS_PTIA_ANALYSIS table for each Application
Engine Section, Step, and Action it comes across. PTIAANALYSIS maintains a counter as it goes and
increments the counter as it writes each Action to the PS_PTIA_ANALYSIS table. By the end of this
first task, the PS_PTIA_ANALYSIS table will describe the entire upgrade from top to bottom, from the
first Application Engine section in the first Upgrade Group to the last section in the last Upgrade Group.
By querying the PS_PTIA_ANALYSIS table and ordering by PTIA_AESTMTSEQ, the whole will be
described, including any nested call sections.
It is important to note that the PS_PTIA_ANALYSIS table contains every actual Step in the chosen
upgrade path. During the data conversion runtime phase, it is likely that not all these steps will be
executed because specific data composition and various application options will prevent some sections or
steps from running. With the PTIA process, data composition can affect the data conversion runtime flow,
which makes it impossible to predetermine the exact runtime flow the conversion will follow.
The PTIAANALYSIS Application Engine reads the data conversion code for your defined upgrade
path (where the path is defined in the PS_PTIA_DCAEPGMS table with PTIA_UPG_CONV_TYPE=
“MAIN”).
The Application Engine Analyzer program leverages two PeopleCode functions included with PeopleSoft
PeopleTools 8.50 or higher. The two PeopleCode functions are:
320
•
GetProgText: A function that retrieves a PeopleCode program as text.
•
ResolveMetaSQL: A function that returns a string of SQL text that has had its metasql resolved.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
Reviewing Data Conversion Query Parsing
After PTIAANALYSIS determines the upgrade path flow, it traverses the flow again looking at all the
different Step Actions to determine which SQL is being executed by that Step. Most action types are
straightforward; SQL, Do Select. PeopleCode is the most complicated action type. A Java program parses
the PeopleCode and pulls all the SQL executed in the PeopleCode. The results of the action type analysis
end up in a table called PS_PTIA_DTLIDSQLS, which stores a reference to PS_PTIA_ANALYSIS,
along with the SQL statements associated with each Step Action. In the case of PeopleCode, there may be
many rows in the PS_PTIA_DTLIDSQLS table for each PeopleCode reference in PS_PTIA_ANALYSIS.
In addition, a second shadow table, called PS_PTIA_DTLIDSQLSR, is also populated during action type
analysis. The only difference between PS_PTIA_DTLIDSQLS and PS_PTIA_DTLIDSQLSR is that
PS_PTIA_DTLIDSQLSR contains the fully resolved SQL statements. For example, if the original SQL in
a Step was:
UPDATE PS_BEN_DEFN_COST SET RATE_TBL_ID = %Substring(%Sql(UPG_HC_221,RATE_TBL_ID),1⇒
,4) %Concat ’-2’ WHERE RATE_TYPE=’2’ AND RATE_TBL_ID IN ( SELECT RATE_TBL_ID FROM P⇒
S_UPG_BN_RATES WHERE RATE_TYPE=’2’)
Then this would be resolved to platform-specific SQL. In the case of SQL server it would be:
UPDATE PS_BEN_DEFN_COST SET RATE_TBL_ID = SUBSTRING(RTRIM(RATE_TBL_ID),1,4) + ’-2’ ⇒
WHERE RATE_TYPE=’2’ AND RATE_TBL_ID IN (SELECT RATE_TBL_ID FROM PS_UPG_BN_RATES WHE⇒
RE RATE_TYPE=’2’)
Each of these SQL statements is further parsed to determine the tables that participate in the query. The
results are stored in the PS_PTIA_DTLIDTBLS table. A query can have zero or one target tables. If
the query is an INSERT, UPDATE, DELETE, etc, then there will be one target. If the query is a select
statement, then there will be no target table. For the previously stated query, you would expect to see 2
rows in the PS_PTIA_DTLIDTBLS table. The first row would be for the PS_BEN_DEFN_COST table
with an PTIA_TABLEUSAGE value of T because it is the target table of the query. The second row
would be for the PS_UPG_BN_RATES table with an PTIA_TABLEUSAGE value of S because it is a
source table in the query.
At this point we have gathered all the information we need about the specific upgrade path to build a
dependency model. The dependency model is solely based on which tables are affected by which steps
and follows some very simple rules. Most of these rules are inherent in the Upgrade Group model.
Reviewing Custom Data Conversion Code
You can include custom data conversion code in the Initial Analysis and subsequent steps in the PTIA
process by adding a row (or rows) to the PS_PTIA_DCAEPGMS table for each custom Application
Engine section that is to be executed, where a row is defined as PTIA_UPG_PATH, PTIA_UPG_GROUP,
SEQ_NUM, AE_APPLID, AE_SECTION, ACTIVE_FLAG, PTIA_UPG_CONV_TYPE,
PTIA_UPG_GROUP_LVL.
Reviewing Table Usage Information
The data conversion analysis process attempts not only to identify the tables that are used in a given
Application Engine step, but also how the tables are being used in the context of each step.
This information is stored in the analysis tables and documented in the Table Usage and Action columns
of delivered PTIA reports, such as PTIA0001.SQR.
Valid values for the Table Usage column are:
•
S for Data Source
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
321
Using Data Conversion Utilities
•
T for Data Target
•
X for Unknown
Chapter 23
Note: An X value in the Table Usage column for the PS_PTIA_DUAL, PS_PTIA_COMMON_AET,
PS_PTIA_NORECNAME, or PS_PTIA_STATE_AE tables is expected and does not impact the
subsequent Dependency Analysis Process.
See Reviewing Dependency Analysis
Valid values for the Action column are:
•
CREATE
•
DELETE
•
DROP
•
INSERT
•
SELECT
•
TRUNCATE
•
UPDATE
•
UPDSTATS
•
UNKNOWN
•
OTHER
A valid value for the action “Unknown” is only applicable to PeopleCode steps and only occurs in
instances when the parser encounters syntax such as GETRECORD, GETROWSET, CREATERECORD, or
CREATEROWSET, and cannot determine which actions were being done against the variable.
A valid value for the action “Other” occurs in instances when the parser encounters syntax such as the
“Invalid SQL Override” or other non-SQL statements such as application function calls.
Reviewing Non Parsable SQL
The data conversion analysis process may mark certain SQL statements as non parsable. This designation
refers to SQL statements that the Application Engine Analysis process could not correctly process. When
a SQL statement is marked non parsable, there are three options that you can use:
•
322
Modify the SQL so that the Application Engine Analyzer can process the statement. The following
table compares sample non parsable and parsable SQL statements:
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
NON PARSABLE SQL
UPDATE %Table(%BIND(RECNAME)) SET
RELATIONSHIP = ’C’ WHERE RELATIONSHIP IN (’S’,
’D’)
•
PARSABLE SQL
•
UPDATE %TABLE(BN_834_MEMBER) SET
RELATIONSHIP = ’C’ WHERE RELATIONSHIP IN
(’S’, ’D’)
•
UPDATE %TABLE(DEP_BEN_EFF) SET
RELATIONSHIP = ’C’ WHERE RELATIONSHIP IN
(’S’, ’D’)
•
UPDATE %Table(EMERGENCY_CNTCT) SET
RELATIONSHIP = ’C’ WHERE RELATIONSHIP IN
(’S’, ’D’)
For non parsable SQL statements in PeopleCode, add an override line directly above the non parsable
SQL to manually document the Source and Target tables that are in use.
Note: There is no override option for Application Engine SQL steps that are marked as non parsable.
Note: Entering inaccurate or incomplete information in the override statement may result in
data conversion sections being run in the incorrect dependent order, which can produce incorrect
conversion results, such as data errors.
Note: Tables defined in the override statement require the PS_ prefix.
Correct = PS_JOB
Incorrect = JOB
The following table gives sample override lines for various situations:
Syntax
When Source and Target tables are explicitly known and
static
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Sample Override Lines
For example:
•
REMSQLANALYSIS:T:<Tgt Table>,<Tgt
Table>:S:<SRC Table>,<SRC Table>;
•
REMSQLANALYSIS:T::S:<SRC Table>,<SRC
Table>;
•
REMSQLANALYSIS:T:<Tgt Table>,<Tgt Table>:S:;
323
Using Data Conversion Utilities
Chapter 23
Syntax
Sample Override Lines
When Source and/or Target Tables are determined based on
a query
For example:
•
REM SQLANALYSIS:T:%SQL(SQLid [,
paramlist]):S:[table name];
•
REM SQLANALYSIS:T:<Tgt Table>,<Tgt Table>:S:
%SQL(SQLid [, paramlist]);
•
REM SQLANALYSIS:T:%SQL(SQLid [,
paramlist]):S: %SQL(SQLid [, paramlist]);
•
REM SQLANALYSIS:T::S:%SQL(SQLid [,
paramlist]);
•
REM SQLANALYSIS:T:%SQL(SQLid [,
paramlist]):S:;
Where:
SQLid: Specify the name of an existing SQL definition.
paramlist: Specify a list of arguments for dynamic
substitutions at runtime. The first argument replaces all
occurrences of %P(1) in the referenced SQL definition, the
second argument replaces %P(2), and so forth.
Note: The paramlist arguments must be static values.
Variable values in the parmlist are not permitted.
Note: The Query is resolved at the time the Data
Conversion Analysis is executed. It is NOT resolved during
the Data Conversion Runtime.
Note: The Query must return one or more valid RECNAME
values. No other return results are permitted.
Where there is no Source or Target table to be defined an/or
the non parsable SQL is to be excluded from the table and
dependency analysis.
•
REMSQLANALYSIS:T::S:PS_PTIA_NORECNAME;
Note: The “REMSQLANALYSIS:T::S:;” syntax is not
a valid override and will be marked as “Invalid” by the
PTIAANALYSIS Program.
Leave the SQL as it is. This results in the non parsable SQL being marked as “dependent” on all steps
that exist prior to it, and all steps subsequent to the non parsable SQL become dependent on it.
Note: This will likely result in slowing the runtime of data conversion and is not recommended.
Reviewing the Data Conversion Repositories
The tables in the Data Conversion Analysis repository hold the following data:
324
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
•
Step actions stored in execution order.
•
SQL clauses extracted from step actions.
•
Tables featured in SQL clause.
•
Bind variables used in SQL.
Analysis information is stored in the following tables:
•
PS_PTIA_DCAEPGMS
•
PS_PTIA_ANALYSIS
•
PS_PTIA_ANALYSISTX
•
PS_PTIA_DATACONV
•
PS_PTIA_DTLIDSQLS
•
PS_PTIA_DTLIDSQLSR
•
PS_PTIA_DTLIDTBLS
•
PS_PTIA_RUNDEPEND
•
PS_PTIA_SECDEPEND
•
PS_PTIA_SECLISTTMP
•
PS_PTIA_STEPDEPEND
The following Analysis tables make up the PTIA process:
PS_PTIA_DATACONV
The PS_PTIA_DATACONV table is based on the table definition for PS_PTIA_DCAEPGMS. It stores
the upgrade Application Engine sections for the chosen upgrade path.
COLUMN
DESCRIPTION
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Stores the text equivalent of the standard DBTYPE codes
PTIA_UPG_GROUP
Upgrade Group
PTIA_UPG_GROUP_LVL
Upgrade Group Level
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
SEQ_NUM
Upgrade Sequence Copied from PS_PTIA_DCAEPGMS
AE_APPLID
Upgrade Application Engine Copied from PS_PTIA_
DCAEPGMS
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
325
Using Data Conversion Utilities
Chapter 23
COLUMN
DESCRIPTION
AE_SECTION
Upgrade Application Engine Section Copied from PS_PTIA_
DCAEPGMS
ACTIVE_FLAG
Active Flag Copied from PS_PTIA_DCAEPGMS
PTIA_RUNDURATION
Elapsed time for this section to run during data conversion
PTIA_RUNSTATUSFLAG
Run Status Flag (Y-complete, N-not run yet, R-Running, FFailed)
PTIA_GUID
GUID generated by the Data Conversion runtime engine
PS_PTIA_ANALYSIS
This is the main analysis table. The Application Engine Analyzer (PTIAANALYSIS) writes a row to this
table for every Action in each Root Section of the specified upgrade path.
COLUMN
326
DESCRIPTION
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Stores the text equivalent of the standard DBTYPE codes
PTIA_UPG_GROUP
Upgrade Group
PTIA_UPG_GROUP_LVL
Upgrade Group Level
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
SEQ_NUM
Upgrade Sequence copied from PS_PTIA_DCAEPGMS
PTIA_TOPAEAPPLID
Upgrade Application Engine copied from PS_PTIA_
DCAEPGMS
PTIA_TOPAESECTN
Upgrade Application Engine Section copied from PS_PTIA_
DCAEPGMS
PTIA_TOPAESTEP
Upgrade Section Step
PTIA_TOPAESEQNUM
Upgrade Section Sequence Number
PTIA_AELEVEL
Nesting level for Call Section
AE_APPLID
Actual Application Engine Program (same as PTIA_
TOPAEAPPLID if PTIA_AELEVEL is 1)
AE_SECTION
Actual Section (same as PTIA_TOPAESECTN if PTIA_
AELEVEL is 1)
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
COLUMN
DESCRIPTION
AE_STEP
Actual Step (same as PTIA_TOPAESTEP if PTIA_AELEVEL
is 1)
AE_SEQ_NUM
Actual Seq Num (same as PTIA_TOPAESEQNUM if PTIA_
AELEVEL is 1)
MARKET
Market
DBTYPE
DBTYPE
AE_DO_SECTION
If Step Action is Call Section, then this is the section to be
called
AE_DO_APPL_ID
If Step Action is Call Section, then this is the program to be
called
AE_DYNAMIC_DO
Indicates the Call Section is a dynamic call section
STEP_DESCR
Step Description
AE_STMT_TYPE
Action Type e.g. S-SQL, P-PeopleCode, D-DoSelect, HDoWhen etc
PTIA_STMTTYPENUM
Numeric identified for AE_STMT_TYPE (used for ordering
step actions)
PTIA_AESTMTSEQ
Sequence used to order the steps actions for the whole upgrade
AE_REUSE_STMT
Standard Application Engine Reuse Statement flag
AE_DO_SELECT_TYPE
Standard Application Engine Do Select Type
DETAIL_ID
Section.Step.Action identifier used as a key to most PTIA
tables
PTIA_INFO1
Extra Information mostly related to FUNCLIB calls
PTIA_INFO2
Extra Information mostly related to FUNCLIB calls
PTIA_INFO3
Extra Information mostly related to FUNCLIB calls
PTIA_INFO4
Extra Information mostly related to FUNCLIB calls
PTIA_INFO5
Extra Information mostly related to FUNCLIB calls
SQLID
For SQL step, the SQLID of the SQL this step action executes
PTIA_STMTDESCR
Description copied from Application Engine Step Description
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
327
Using Data Conversion Utilities
Chapter 23
COLUMN
DESCRIPTION
PTIA_HASPARENTS
This Step has dependencies on other one or more other Steps
PTIA_HASCHILDREN
One or more other Steps have a dependency on this step
PTIA_HASWHERE
The SQL has a where clause – Mostly used by PeopleSoft
Development
PS_PTIA_DTLIDSQLS
This table holds a reference to every SQL in the conversion code for the specified upgrade path.
COLUMN
328
DESCRIPTION
PTIA_GUID
GUID generated by the Data Conversion runtime engine
DETAIL_ID
Section.Step.Action identifier used as a key to most PTIA
tables
AE_APPLID
Actual Application Engine Program
DBTYPE
DBTYPE
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
PTIA_SQLNUM
SQL Number, for peoplecode there may be many SQL
statements
PTIA_AESTMTLEN
Length of the text of the SQL statement
PTIA_OBJ_TYPE
S-SQL or P-PeopleCode
TABLE_NAME
Main Table in the SQL Statement, Blank if SQL is SELECT
with many tables
PTIA_DMLACTION
INSERT, UPDATE, DELETE, SELECT etc
PTIA_LINENUM
Refers to the PeopleCode line number where the SQL is
defined
PTIA_SQLPASSDPARSE
Indicates whether SQL parser was able to successfully parse
the SQL statement
DESCR254
Description column
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
COLUMN
DESCRIPTION
PTIA_PARAMCLAUSE
Bind variable used in the SQL
PTIA_INFO1
Extra Information mostly related to FUNCLIB calls
PTIA_INFO2
Extra Information mostly related to FUNCLIB calls
PTIA_INFO3
Extra Information mostly related to FUNCLIB calls
PTIA_INFO4
Extra Information mostly related to FUNCLIB calls
PTIA_INFO5
Extra Information mostly related to FUNCLIB calls
PTIA_CHUNKSEQ
Statement Chunk Sequence
PTIA_TEXTCHUNK
Statement executed by this Step
PS_PTIA_DTLIDSQLSR
This table differs slightly from the PS_PTIA_DTLIDSQLS table in that the SQL statement has been fully
resolved into platform-specific SQL. This makes it much easier to see what is happening in the SQL.
COLUMN
DESCRIPTION
PTIA_GUID
GUID generated by the Data Conversion runtime engine
DETAIL_ID
Section.Step.Action identifier used as a key to most PTIA
tables
AE_APPLID
Actual Application Engine Program
DBTYPE
DBTYPE
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
PTIA_SQLNUM
SQL Number, for PeopleCode there may be many SQL
statements
PTIA_CHUNKSEQ
Statement Chunk Sequence
PTIA_TEXTCHUNK
Statement executed by this Step
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
329
Using Data Conversion Utilities
Chapter 23
PS_PTIA_DTLIDTBLS
This table holds a reference to every SQL in the conversion code for the specified upgrade path and which
Tables or Records are in use for each piece of SQL.
COLUMN
DESCRIPTION
PTIA_GUID
GUID generated by the Data Conversion runtime engine
DETAIL_ID
Section.Step.Action identifier used as a key to most PTIA
tables
AE_APPLID
Actual Application Engine Program
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
PTIA_SQLNUM
SQL Number, for peoplecode there may be many SQL
statements
RECNAME
Record Name
TABLE_NAME
Associated Table Name
PTIA_TABLEUSAGE
T-Target, S-Source
PTIA_TABLETYPE
R-Record, S-State Record, U-Upgrade Table, V-View, TTempTable
PTIA_INFO1
Extra Information mostly related to FUNCLIB calls
PTIA_INFO2
Extra Information mostly related to FUNCLIB calls
PTIA_INFO3
Extra Information mostly related to FUNCLIB calls
PTIA_INFO4
Extra Information mostly related to FUNCLIB calls
PTIA_INFO5
Extra Information mostly related to FUNCLIB calls
PS_PTIA_STEPDEPEND
By querying PS_PYIA_DTLIDTBLS and PS_PTIA_ANALYSIS, it is possible to determine which steps
have dependencies and what those dependencies are.
COLUMN
PTIA_UPG_PATH
330
DESCRIPTION
Upgrade Path copied from PS_PTIA_DCAEPGMS
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
COLUMN
DESCRIPTION
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
PTIA_P_UPG_GROUP
Parent Data Conversion Group
PTIA_P_UPGGRPLVL
Parent Data Conversion Group Level
PTIA_P_SEQNUM
Parent Application Engine Section Sequence Number
PTIA_P_TOPAEAPPLID
Parent Data Conversion Application Engine Program
PTIA_P_TOPAESECTN
Parent Data Conversion Application Engine Section
PTIA_P_TOPAESTEP
Parent Data Conversion Application Engine Step
PTIA_P_TOPAESEQNUM
Parent Data Conversion Application Engine Step Sequence
PTIA_P_AEAPPLID
Parent Application Engine Program
PTIA_P_AESECTION
Parent Application Engine Section
PTIA_P_AESTEP
Parent Application Engine Step
PTIA_P_AESEQNUM
Parent Application Engine Step Sequence within the Section
PTIA_P_AESTMTSEQ
Parent Application Engine Step Sequence across whole
upgrade
PTIA_P_DETAILID
Parent Application Engine Step Detail ID
PTIA_P_SQLNUM
Parent Application Engine Detail ID SQL Sequence
PTIA_C_UPG_GROUP
Child Data Conversion Group
PTIA_C_UPGGRPLVL
Child Data Conversion Group Level
PTIA_C_SEQNUM
Child Application Engine Section Sequence Number
PTIA_C_TOPAEAPPLID
Child Data Conversion Application Engine Program
PTIA_C_TOPAESECTN
Child Data Conversion Application Engine Section
PTIA_C_TOPAESTEP
Child Data Conversion Application Engine Step
PTIA_C_TOPAESEQNUM
Child Data Conversion Application Engine Step Sequence
PTIA_C_AEAPPLID
Child Application Engine Program
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
331
Using Data Conversion Utilities
Chapter 23
COLUMN
DESCRIPTION
PTIA_C_AESECTION
Child Application Engine Section
PTIA_C_AESTEP
Child Application Engine Step
PTIA_C_AESEQNUM
Child Application Engine Step Sequence within the Section
PTIA_C_AESTMTSEQ
Child Application Engine Step Sequence across whole
upgrade
PTIA_C_DETAILID
Child Application Engine Step Detail ID
PTIA_C_SQLNUM
Child Application Engine Detail ID SQL Sequence
PTIA_TABLENAME
Common table referenced by the parent and child step
PTIA_P_TABLEUSAGE
Parent table usage T-Target, S-Source
PTIA_C_TABLEUSAGE
Child table usage T-Target, S-Source
PS_PTIA_ SECDEPEND
This table is an aggregation of PS_PTIA_STEPDEPEND to the Section level.
COLUMN
332
DESCRIPTION
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_UPG_CONV_TYPE
Conversion type: MAIN or DDL
PTIA_P_UPG_GROUP
Parent Data Conversion Group
PTIA_P_UPGGRPLVL
Parent Data Conversion Group Level
PTIA_P_TOPSEQNUM
Parent Application Engine Section Sequence Number
PTIA_P_TOPAEAPPLID
Parent Data Conversion Application Engine Program
PTIA_P_TOPAESECTN
Parent Data Conversion Application Engine Section
PTIA_P_AESTMTSEQ
Parent Application Engine Step Sequence across whole
upgrade
PTIA_C_UPG_GROUP
Child Data Conversion Group
PTIA_C_UPGGRPLVL
Child Data Conversion Group Level
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
COLUMN
DESCRIPTION
PTIA_C_TOPSEQNUM
Child Application Engine Section Sequence Number
PTIA_C_TOPAEAPPLID
Child Data Conversion Application Engine Program
PTIA_C_TOPAESECTN
Child Data Conversion Application Engine Section
PTIA_C_AESTMTSEQ
Child Application Engine Step Sequence across whole
upgrade
PTIA_DEPENDSOURCE
Dependency Rule
PTIA_DEPENDRULE
DEPENDENT or INDEPENDENT
PTIA_EXCLUDEFLAG
Indicates whether this dependency should be excluded from
the runtime dependency calculation
PS_PTIA_RUNDEPEND
This table represents the section dependency model. You can query this table for any given data
conversion Application Engine Section to determine what it depends on and what depends on it. The
runtime data conversion Application Engine (PTIADATACONV) uses this table to determine which
sections are eligible to run.
COLUMN
DESCRIPTION
PTIA_UPG_PATH
Upgrade Path copied from PS_PTIA_DCAEPGMS
PTIA_DBTYPE
Text equivalent of the standard DBTYPE codes
PTIA_P_UPG_GROUP
Parent Data Conversion Group
PTIA_P_TOPSEQNUM
Parent AE Section Sequence Number
PTIA_P_TOPAEAPPLID
Parent Data Conversion AE Program
PTIA_P_TOPAESECTN
Parent Data Conversion AE Section
PTIA_C_UPG_GROUP
Child Data Conversion Group
PTIA_C_TOPSEQNUM
Child AE Section Sequence Number
PTIA_C_TOPAEAPPLID
Child Data Conversion AE Program
PTIA_C_TOPAESECTN
Child Data Conversion AE Section
PTIA_DEPTH
Dependency Nesting
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
333
Using Data Conversion Utilities
Chapter 23
Reviewing Dependency Analysis
This section discusses:
•
Understanding Dependency Analysis
•
Reviewing Data Conversion Runtime Rules
Understanding Dependency Analysis
The table usage information identified in the Initial Analysis is subsequently used to determine
the dependencies between AE Steps. The Step Dependency Information is then aggregated to the
“Root Section” level where a Root Section is defined as a row in the PS_PTIA_DCAEPGMS table
(PTIA_UPG_PATH, PTIA_UPG_GROUP, SEQ_NUM, AE_APPLID, AE_SECTION, ACTIVE_FLAG,
PTIA_CONV_TYPE, PTIA_UPG_GROUP_LVL).
Reviewing Data Conversion Runtime Rules
The following rules are the data conversion runtime rules:
334
•
Dependencies are derived from tables referenced in SQL or PeopleCode actions in Upgrade Sections.
•
Dependencies follow the Upgrade Group sequencing. If Section ABC in Upgrade Group 1 updates a
given table, then any Section assigned a higher sequence than ABC that updates or queries that same
table cannot run until Section ABC is complete.
•
Upgrade groups are further grouped into levels. For example, objects defined in Level 2 are dependent
on objects defined in Level 1. Additionally, objects defined in Level 3 are dependent on objects
defined in Level 1 and Level 2.
•
Upgrade groups within the same level do not depend on each other. If Section QWE in Upgrade
Group 2 updates table FFF and Section ASD in Upgrade Group 3 also updates table FFF and Upgrade
Groups 2 and 3 are at the same level, there is no dependency created.
•
Upgrade groups create dependencies on sections within their own upgrade group and upgrade groups
of lower levels. If Section ABC in Upgrade Group 1 updates table FFF and Section QWE in Upgrade
Group 2 also updates table FFF, and Upgrade Group 1 is in a lower level than Upgrade Group 2, then
Section QWE becomes dependent on Section ABC.
•
Tables as sources do not create dependencies. If Section ZXC in Upgrade Group 1 selects from
table FFF, and then Section BNM in Upgrade Group 1 also selects from table FFF, no dependency is
created.
•
If a Section has a SQL statement that PTIAANALYSIS cannot understand, the SQL is flagged as non
parsable from the parser point of view (the Data Conversion will still run fine) and a hard dependency
is created. This means for every Section with a query that cannot be parsed, it becomes dependent on
every Section sequentially above it in its Upgrade Group, and on every Section in Upgrade Group 1.
Furthermore, every Section sequentially afterward becomes dependent on it.
•
Usage of the PS_PTIA_DUAL, PS_PTIA_COMMON_AET, or PS_PTIA_NORECNAME tables
never results in a dependency.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
Example of Dependency Rules Calculation
In the following example, the highlighted row (with values in italics) would be dependent on
itself and all items in Level’s MAIN-1 and MAIN-2, but not the other items in Level MAIN-3 nor
items in Level DDL-1.
PATH
GROUP
SEQ_NUM
AE_APPLID
AE_
SECTION
PTIA_CONV
_TYPE
GROUP_
LEVEL
HC89
1
260
UPG_HR89
HCHRS01
MAIN
1
HC89
1
265
UPG_FG89
FGHCS01
MAIN
1
HC89
3
230
UPG_BN89
HCBNS06
MAIN
2
HC89
4
165
UPG_GPBR90 HCBRP040
MAIN
2
HC89
7
40
UPG_EP89
HCEPS25
MAIN
2
HC89
7
50
UPG_EP89
HCEPS30
MAIN
2
HC89
10
20
UPG_TL89
HCTLK01
MAIN
2
HC89
80
140
UPG_TL90
HCTLP04
MAIN
3
HC89
80
160
UPG_TL90
HCTLP06
MAIN
3
HC89
85
170
UPG_PY90
HCPYM01
MAIN
3
HC89
85
180
UPG_PY90
HCPYP01
MAIN
3
HC89
10
200
UPG_PY90
HCPYP09
DDL
1
HC89
10
210
UPG_PY90
HCPYP10
DDL
1
Reviewing Runtime for PTIADATACONV
This section discusses:
•
Understanding Runtime for PTIADATACONV
•
Querying the PTIA Tables
Understanding Runtime for PTIADATACONV
All runtime information for PTIADATACONV is stored in the following tables:
•
PS_PTIA_DATACONV
•
PS_PTIA_RUNSTATUS
•
PS_PTIA_RUNDETAIL
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
335
Using Data Conversion Utilities
•
Chapter 23
PS_PTIA_RUNCOUNT
The PTIADATACONV Application Engine leverages the Dependency Analysis to optimize the runtime
of the data conversion. The runtime of the data conversion is improved in the new PeopleSoft release by
running multiple instances of PTIADATACONV in parallel, executing against a single set of dependency
information. The optimal number of instances to be initiated will vary.
PTIADATACONV determines which “Root Sections” are able to run and executes them. A Root Section
is able to run when all Root Sections that are dependent on it have completed successfully.
In the event that multiple root sections are able to run at the same time, steps that have the largest number
of dependent Root Sections and/or Root Sections that have the longest runtime (in a previous run), are
given priority.
In the event of failure, the instance of PTIADATACONV that encountered the error will mark the step as
“Failed” and stop. All other instances of PTIADATACONV will continue to run. Steps that are dependent
on a “Failed” step will be marked as “Blocked” and will not be executed as part of the current run. Upon
restarting the process, the “Failed” section and any “Blocked” sections will be executed.
The following list describes the PTIADATACONV program flow:
•
The run is initialized.
This initial phase determines if this is a brand new run or if it is a restart of a previously failed run. If
it is a new run, then PTIADATACONV sets up a thread in PS_PTIA_RUNSTATUS.
•
PTIADATACONV performs a simple test to verify that there is work to do.
If there is work to do, then PTIADATACONV runs Data Conversion Application Engine Sections that
have not already run. This is a fairly simple Do While loop that counts eligible sections left to run. If
there are no more sections left to run, processing stops. The work inside the loop consists of executing
a process to check the status of any other thread that is running. If a thread dies, it cannot clean itself
up, so one of the other threads has to perform the cleanup. The cleanup mostly consists of setting the
status flag in PS_PTIA_DATACONV to “F” for the AE Section that failed.
•
SQLs run to look for work to do.
The SQL object PTIA_FINDSECTIONTORUN finds the next eligible section to run. If the query
returns nothing, we execute another SQL object called PTIA_COUNTSECTIONSNOTDONE to
count how many Sections are left to run. If PTIA_FINDSECTIONTORUN returns no work to do
and PTIA_COUNTSECTIONSNOTDONE returns Sections still need to be run, then there must be a
Section already running that must complete before anything else can run. If there is no work to do, the
loop issues a pause before the loop completes and executes the next loop.
•
PTIADATACONV performs more housekeeping to reset statuses on successful completion of all Data
Conversion Application Engine Sections.
•
A completion message is written to the log file.
Reviewing PTIA Reporting
This section discusses:
•
336
Understanding PTIA Reporting
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
•
Reviewing the Tables Referenced Report
•
Reviewing the Customization Impacts Report
•
Reviewing Execution Report by Section – Duration
•
Reviewing Execution Report by Section – Start Time
•
Reviewing the Execution Report by Step
•
Reviewing the Execution by Thread Report
•
Reviewing the Thread Duration Report
•
Reviewing the Execution Comparison Report
•
Reviewing the Table Analysis Report
•
Reviewing the Data Conversion Report
Understanding PTIA Reporting
You can query all tables populated and leveraged by PTIA (as identified previously) through the various
platform specific query tools or psquery. You can gather information in the PTIA tables to identify the
following:
•
Tables referenced in the data conversion code.
•
Steps impacted by customizations (prior to the initial data conversion run).
•
Performance issues (after the initial data conversion run).
•
Impact of changes (run to run timing comparisons).
Oracle has delivered a series of standard reports to address the most commonly accessed information in
the PTIA repository.
Reviewing the Tables Referenced Report
PTIA0001.SQR lists all tables referenced within the Application Engine data conversion programs. For
each table listed, the report displays the section and step in which it is used, whether it is a data source
or data target table, and the type of SQL statement in which it is referenced. This report is sorted by
table name. Data for this report comes from the PS_PTIA_ANALYSIS, PS_PTIA_DTLIDSQLS, and
PS_PTIA_DTLIDTBLS tables. This report can be run anytime after the PTIAANALYSIS Application
Engine program has run and populated the PTIA tables used by this SQR.
Reviewing the Customization Impacts Report
PTIA0002.SQR shows the section/steps within the Application Engine data conversion programs that
referenced tables with custom added fields. This report is sourced from the PS_PTIA_ANALYSIS table
and the PSPROJECTITEM table. This report must be run after the customizations project has been
compared against the New Release Demo database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
337
Using Data Conversion Utilities
Chapter 23
Reviewing Execution Report by Section – Duration
PTIA0003.SQR shows the duration or execution time for each Application Engine section. Since this
report is at a section level, the information is sourced from the PS_PTIA_RUNDETAIL table. The report
is ordered by execution time with the poorest performing steps at the top. This report can be run anytime
after the PS_PTIA_RUNDETAIL table has been populated for the data conversion run on which you want
to report.
Reviewing Execution Report by Section – Start Time
PTIA0004.SQR shows the duration or execution time for each section. Since this report is at a section
level, the information will be sourced from the PS_PTIA_RUNDETAIL table. The report would be
ordered by start time so that you can see the order in which the sections were executed. This report can
be run anytime after the PS_PTIA_RUNDETAIL table has been populated for the data conversion run on
which you want to report.
Reviewing the Execution Report by Step
PTIA0005.SQR shows the execution time for each section and the associated steps that were run.
This report requires a trace of 16,384 or higher.
Since this report is at a step level, it assumes that a trace of 16,384 or higher has been run so that the step
information could be obtained from the PS_PTIA_TIMINGS_DT table. If the appropriate trace has not
been run, then a report is not created and output files will be produced. The report will be ordered by
execution time with the poorest performing steps at the top.
Reviewing the Execution by Thread Report
PTIA0006.SQR shows the execution timing of each Application Engine section run as part of the data
conversion process. This report is sorted so that you can see which sections were executed by each thread.
This report is sourced from the PS_PTIA_RUNDETAIL table.
Reviewing the Thread Duration Report
PTIA0007.SQR shows the total duration time for each thread used during the data conversion
process. This report is sourced from the PS_PTIA_RUNDETAIL table. It can be run anytime after the
PS_PTIA_RUNDETAIL table has been populated from the data conversion run on which you want to
report.
Reviewing the Execution Comparison Report
PTIA0008.SQR shows the execution duration from the current run of data conversion as compared
to the execution duration from the previous run of data conversion. This report is sourced from the
PS_PTIA_RUNDETAIL table. This report can be run anytime after the PS_PTIA_RUNDETAIL table has
been populated for the data conversion runs on which you want to report.
Reviewing the Table Analysis Report
PTIA0009.SQR indicates how a particular application table is impacted by the create/alter scripts
as well as the data conversion process during the PeopleSoft upgrade. This report is sourced
from the PS_PTUALTRECDATA, PS_PTUALTRECFLDDAT, PS_PTIA_ALTRECDATA,
PS_PTIA_ANALYSIS, and PS_PTIA_DTLIDTBLS tables. This report can be run after the Alter
338
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
Analyzer and the AE Analyzer processes have successfully completed. This report is designed to be run
against the initial pass database as the data stored in the tables during the Move to Production will differ.
Reviewing the Data Conversion Report
Each of the upgrade data conversion sections contains comments that describe the processing performed
by the section. Oracle delivered an SQR (PTIA0010.sqr) to list all of these comments by the group and
sequence numbers that determine how they run. The name of this report is PTIA0010.
To run PTIA0010:
1. Using SQRW, run SQR PTIA0010 on your copy of Production database.
2. When prompted for upgrade path, enter (for example):
HC90
CR90
CR91
Using the Upgrade Driver Program
The sequence of Application Engine sections that are run by an upgrade driver is maintained in the
PS_PTIA_DCAEPGMS table. The Application Engine sections defined in the PS_PTIA_DCAEPGMS
table are referred to as root sections.
There are two categories of Upgrade Groups:
•
MAIN – Core Data Conversion
•
DDL – Data Conversion sections that contain Drop Table Statements (only)
Upgrade groups contain one or more Application Engine sections that are ordered within the group by
sequence number. The Application Engine program PTIADATACONV is used to execute the MAIN and
the DDL data conversion groups.
When data conversion is executed using the PTIADATACONV Application Program, the sequence
number is used to determine the “Relative Run Order” of Application Engine sections that reference the
same table or tables, but not the “Absolute Run Order” of the upgrade group(s).
This section discusses:
•
Defining an Upgrade Path
•
Accessing the Define Data Conversion Page
Defining an Upgrade Path
Before you can define data conversion sections, you must define an upgrade path.
To define an upgrade path:
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
339
Using Data Conversion Utilities
Chapter 23
1. From your browser, sign in to the Demo database.
2. Select PeopleTools, Lifecycle Tools, Upgrades, Define Upgrade Paths.
3. The Define Upgrade Path page appears.
4. Click theAdd a New Value tab.
5. Enter a value for Upgrade Path.
6. Click Add.
7. Select a value for Active Flag.
8. Enter description for the new upgrade path.
9. Click Save.
Image: Define Upgrade Path page
This example illustrates the fields and controls on the Define Upgrade Path page.
After you have defined an upgrade path, you can add sections for the upgrade path on the Define Data
Conversion page.
Accessing the Define Data Conversion Page
Before you run data conversion, you may need to change what the Upgrade Driver program runs. You can
add, remove, or deactivate Application Engine sections through the Define Data Conversion page.
To access the Define Data Conversion page:
1. From your browser, sign in to the Demo database.
2. Select PeopleTools, Lifecycle Tools, Upgrades, Define Data Conversion.
3. The Define Data Conversion page appears.
4. Enter your upgrade path.
For example:
HC90
CR90
340
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
5. Click Search.
The Define Data Conversion page displays information for the selected upgrade path, as shown in the
example below. Following the example of the Define Data Conversion page are descriptions for each
section of the page.
Image: Define Data Conversion page
This example illustrates the fields and controls on the Define Data Conversion page. You can find
definitions for the fields and controls later on this page.
Upgrade Path
This field contains the upgrade path on which the section
will be run.
Program Name
This is the Application Engine program that contains the
section.
Group Number
This is the group number. All sections with the same group
number will be run during the same run of the PTIA_
DATACONV Application Engine program.
Group Level
This is the group level.
Conv Type
This is the conversion type. PTIA supports two categories:
MAIN and DDL.
Section
This is the section that will be called from the PTIA_
DATACONV Application Engine program.
Sequence
This is the order in which the sections will be called during
the run of PTIA_DATACONV for the group number.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
341
Using Data Conversion Utilities
Chapter 23
Active Flag
This field determines whether the section will be run. If the
value of this field is Active, the section will be run. If the
value is Inactive, it will not be run. If you need to remove a
section, change the value in this field to Inactive.
Short Description
This field contains the Section description.
Long Descr
This field is optional.
This section also discusses:
•
Adding a new Section on the Define Data Conversion Page.
•
Inactivating a Section on the Define Data Conversion Page.
Adding a new Section on the Define Data Conversion Page
Follow the instructions below to add a new section to the Define Data Conversion page.
Note: To add a new section, the Application Engine program and section must exist on the Demo
database.
To add a new section to the Define Data Conversion page:
1. From your browser, sign in to the Demo database.
2. Select PeopleTools, Lifecycle Tools, Upgrades, Define Data Conversion.
3. The Define Data Conversion page appears.
4. Enter your upgrade path.
For example:
HC90
CR90
5. Click Search.
The Define Data Conversion page displays information for the selected upgrade path.
6. Add a new row.
7. Select a value for Program Name.
8. Enter a value for Group Number.
342
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 23
Using Data Conversion Utilities
Note: Each group number corresponds to a data conversion step in the PeopleSoft Change Assistant
template. If you select a group number that already exists in the PS_PTIA_DCAEPGMS table,
your section will be executed when PeopleSoft Change Assistant runs the data conversion step that
corresponds to the group number you selected. Alternatively, if you assign a group number to your
new section that does not already exist in PS_PTIA_DCAEPGMS, you must add a new step to your
PeopleSoft Change Assistant template. The new template step will have the same properties as the
other data conversion steps, except for the group number specified in the step properties Parameters
box.
9. Enter values for Group Level and Conv Type.
10. Select a value for Sectionand enter value for Sequence.
11. Select a value for Active Flag.
12. The Short Descriptionfield is populated from the Section description. The Long Descrfield is optional.
13. Click Save.
Inactivating a Section on the Define Data Conversion Page
Follow the instructions below to deactivate a section on the Define Data Conversion page. If a section is
deactivated, the section will not run as part of data conversion.
To inactivate a section on the Define Data Conversion page:
1. From your browser, sign in to the Demo database.
2. Select PeopleTools, Lifecycle Tools, Upgrades, Define Data Conversion.
3. The Define Data Conversion page appears.
4. Enter your upgrade path.
For example:
HC90
CR90
5. Click Search.
6. Find the row with the Program Name and Section you want to remove and change the value of the
Active Flag field to Inactive.
7. Click Save.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
343
Using Data Conversion Utilities
344
Chapter 23
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Part VI
Comparing and Merging
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
345
Comparing and Merging
346
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge
Select Object Types Action
Comparing and Copying Managed Objects Overview
You create and maintain upgrade projects using the Application Designer project management features.
Many of the same features are accessible through Project Administration in Change Assistant. Projects
can be viewed and copied and compare reports can be executed and viewed either through Change
Assistant Project Administration or Application Designer.
Related Links
"Using Projects" (PeopleTools 8.55: Application Designer Developer's Guide)
"Preparing Projects for an Upgrade" (PeopleTools 8.55: Lifecycle Management Guide)
"Setting Project Properties" (PeopleTools 8.55: Application Designer Developer's Guide)
Administering Projects
To access the Administering Projects tool:
1. In Change Assistant, select Tools, Change Actions.
2. Select Review Managed Object or Merge Select Object Types.
3. Click Next and select Compare/Copy Managed Objects.
4. Click Finish and select the environment to use from the list.
Note: The environment and all associated DLLs for the PS Home are loaded. The environment does
not have to be on the same PeopleTools release as Change Assistant.
If the environment has not been created, you will need to create the database .
a. Click Cancel on the Select Environment page.
b. Select Tools, New Database.
c. Define the database.
See Defining Databases
d. Select Tools, Project Administration.
e. Select the database from the list.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
347
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
5. Select File, Open to open an existing definition. Definition types are:
Managed Object Compare
Select this option to open the compare reports for a project.
Only compare reports created with the option Generate
Output to Tables are available from the drop down list.
Project
Select this option to display the project status and actions.
You can open projects that have been created in Application
Designer.
If you are already in Review Managed Object or Merge Select Object Types action, you can open the
Project Administration menu from the toolbar by selecting Tools, Project Administration.
Viewing Managed Object Compare Reports
When you select the Managed Object Compare and select a project, the compare report is displayed. You
can expand and collapse the objects to display.
Image: Managed Object Compare page
This example illustrates the fields and controls on the Managed Object Compare page. You can find
definitions for the fields and controls later on this page.
The Project Administration interface can logically be divided into three areas for the compare report:
1. Project-based data
2. Compare results
3. Copy actions
Project-Based Data
These columns display details for definitions in the compare project:
348
Object
Displays the name of the definition, plus any other key values,
in a hierarchical tree view.
Src (Source) Status
Displays the definition status in the source (current) database.
Tgt (Target) Status
Displays the definition status in the source (current) database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
Definition Status
By default, Source Status and Target Status are set to Unknown.
Following a compare, the values in the Source Status and Target Status columns are updated as follows:
Unknown
Definition has not been compared. This is the default status
for all definitions inserted manually into a project and the
permanent status of all non-comparison definitions.
Absent
The definition was found in the other database, but not in this
one. When upgrading to a new PeopleSoft release, all new
PeopleSoft definitions should have Absent status in the target
database and all of your custom definitions should have Absent
in the source database.
Changed
The definition has been compared, the LASTUPDOPRID value
is PPLSOFT, and the LASTUPDDTM value is greater than
the date/time stamp of the comparison release database. This
indicates that PeopleSoft modified the definition since the
comparison release.
Unchanged
The definition has been compared, the LASTUPDOPRID value
is PPLSOFT, and the LASTUPDDTM value is less than or
equal to the date/time stamp of the comparison release database.
This indicates that PeopleSoft modified the definition prior to
the comparison release.
*Changed
The definition has been compared, the LASTUPDOPRID value
is not PPLSOFT, and the LASTUPDDTM value is greater
than the date/time stamp of the comparison release database.
This indicates that a customer modified the definition since the
comparison release.
*Unchanged
The definition has been compared, the LASTUPDOPRID value
is not PPLSOFT, and the LASTUPDDTM value is less than or
equal to the date/time stamp of the comparison release database.
This indicates that a customer modified the definition prior to
the comparison release.
Same
The definition has been compared and is defined the same
in both databases. When a definition in one database has
this status its counterpart in the other database will have the
equivalent status. This status can be seen when performing
a project comparison because with a project comparison the
definitions are static; the project is not repopulated based on
the comparison results. This status is not seen in a database
comparison, because when doing so the project is populated
only with definitions defined differently.
See "Working with Definition Status" (PeopleTools 8.55: Lifecycle Management Guide).
Compare Results
The following table describes the columns that display compare results.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
349
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
Attribute
The attribute of the definition being compared.
Source Value
The value for the attribute in the source database.
Target Value
The value for the attribute in the target database.
Copy Actions
By default Action is set to Copy and Upgrade is checked.
The following table describes the columns that enable you to specify copy actions.
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
The system changes the Done checkbox to selected when the
definition has been copied. You cannot select Done check boxes
yourself, but you can deselect them. Only definitions that have
Upgrade selected and Done deselected are copied during an
upgrade.
See "Working with Upgrade Definition Columns" (PeopleTools 8.55: Lifecycle Management Guide).
Filtering
Select View, Filtering to define filters for the Source or Target status column.
Select View, Filtering to filter the listed items based on the following statuses for either source or target:
•
Absent
•
Changed
•
Changed*
•
Same
•
Unchanged
•
Unchanged*
•
Unknown
A checkmark indicates that a status is selected. By default, all statuses are selected.
Viewing Projects
When you select Projects and select a project, the project status is displayed. You can expand and collapse
the objects to display.
350
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
Image: Project Administration - Project before compare
This example illustrates the fields and controls on the Project Administration - Project before compare.
Project Administration allows you to perform all of the same actions as in Application Designer Upgrade
View for the project.
For details see "Working with Upgrade Definition Columns" (PeopleTools 8.55: Lifecycle Management
Guide)
Working With Project Administration Menu Options
This section describes the menu options available when using Project Administration.
File Menu
The File menu contains these Project Administration options:
Menu Option
Description
Open
Opens a managed object compare or project.
Save Project
Saves the project.
Note: Only available for projects.
Save Project As
Creates a copy of the project.
Note: Only available for projects.
Project Properties
Opens the Project Properties dialog box.
Note: Only available for projects.
Exit
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Exits Project Administration.
351
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
View Menu
The View menu contains these Project Administration options:
Menu Option
Description
Filtering
Select the status to display for the source and target database.
Tools Menu
The Tools menu contains these Project Administration options:
Menu Option
Description
Validate Project
Run the validate utility to make sure that all definitions
included in the project actually exist in your database.
Compare and Report
Run a compare report to a database.
Note: Only available for projects.
Copy Project
Copy the project to a database.
Note: Only available for managed object compare or project.
Comparing Definitions
To compare definitions in Project Administration:
1. In Change Assistant, select Tools, Project Administration.
Note: The action type must be Compare/Copy Managed Objects.
2. Select the Source database from the available environments or create a new environment and click
OK.
3. Select File, Open and select the definition type Project.
4. Select the Project you want to compare and click Open.
5. Select Tools, Compare and Report, To Database.
Select the Target database from the available environments or create a new database and click OK.
Note: You must exit Project Administration and select New Database to create a new database.
6. The Compare and Report Dialog is displayed. Enter your compare options and then click Compare.
352
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
The Compare and Report dialog box is the same as Application Designer. For details see "Setting
Upgrade Options" (PeopleTools 8.55: Lifecycle Management Guide)
7. The Compare Report will be populated, expand each section to view.
Image: Project Administration window with compare results
This example illustrates the fields and controls on the Project Administration window with compare
results. You can find definitions for the fields and controls later on this page.
Related Links
"Reviewing Upgrade Settings" (PeopleTools 8.55: Lifecycle Management Guide)
Copying Definitions
To copy definitions in Project Administration:
1. In Change Assistant, select Tools, Project Administration.
Note: The action type must be Compare/Copy Managed Objects.
2. Select the Source database from the available databases and click OK.
3. Select File, Open and select Project .
4. Select the Project you want to copy and click Open.
5. Review the Action and Upgrade columns to insure you have the correct selections.
6. Select Tools, Copy, To Database.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
353
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
Select the Target environment from the available environments or create a new environment and click
OK.
7. The Copy Database dialog is displayed. Enter your copy options and then click Copy.
The Copy Database dialog box is the same as Application Designer. For details see "Copying Projects
to a Target Database" (PeopleTools 8.55: Lifecycle Management Guide)
8. The Done column will be updated when the copy is complete
Validating Projects
An important part of the PeopleSoft upgrade process involves validating your upgrade project. PeopleSoft
Application Designer includes a validate utility to make sure that all definitions included in the project
actually exist in your database. This same functionality is available in Project Administration.
To validate a project:
1. Open the project in Project Administration.
2. Select Tools, Validate Project.
Related Links
"Validating Projects" (PeopleTools 8.55: Application Designer Developer's Guide)
Understanding Merging PeopleCode, SQL, XSLT Programs
Change Assistant enables you to compare the same PeopleCode, SQL or XSLT programs shared among
three databases. You can view the text together while the system detects each difference and clearly
indicates the differences using visual queues. During this comparison, you choose which lines from each
program to carry forward into the merged version.
Beginning a New Merge Session
To begin a new merge session in Change Assistant:
1. Select Tools, Change Actions.
2. Select Compare/Copy Managed Objects or Merge Select Object Types.
3. Click Next.
4. Select Begin New Merge Session.
5. Click Finish.
6. Select your merge databases and merge type and click Next.
354
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
7. Define the merge rules and click Next.
8. Click Merge to start the full database merge.
Selecting Merge Databases
The merge is a 3–way merge, so you must select the parent and child databases for the merge.
Image: Merge Databases page
This example illustrates the fields and controls on the Merge Databases page. You can find definitions for
the fields and controls later on this page.
Merge Session Name
Enter a name for the merge session.
Parent Database
Select an environment for the parent database.
Child 1 Database (Target)
Select an environment for the child 1 database.
Child 2 Database
Select an environment for the child 2 database.
Add Environment
Click this button to add a newdatabase. The database
configuration wizard will open. See Defining Databases
Merge PeopleCode
Select for a PeopleCode merge.
Merge SQL, XSLT
Select to merge SQL and XSLT
Defining Merge Rules
Use the Merge Configuration page to define how the code will be merged.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
355
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
Image: Wizard Merge Rules page
This example illustrates the fields and controls on the Wizard Merge Rules page. You can find definitions
for the fields and controls later on this page.
Using the Merge Interface
When you perform a merge, Change Assistant:
•
Compares the Parent database to the Child 1 database to detect changes in Child 1.
•
Compares the Parent database to the Child 2 database to detect changes in Child 2 of those objects
changed in Child 1.
•
Displays the compare results on the merge page.
Merge Page
When the full database merge has completed, the Merge page is displayed.
356
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
Image: Merge page
This example illustrates the fields and controls on the Merge page. You can find definitions for the fields
and controls later on this page.
The Merge page contains these panes:
•
Program list
•
Merge edit pane
•
Merge output pane
•
Parent (A) Data
•
Child 1 (B) Data
•
Child 2 (C) Data
Program List
This pane lists the programs that were changed in Child 1 (If something was changed only in Child 2, it
won’t show up here).
If the entire program name is not visible, hover over the name to display a tooltip with the full name.
Double-click an item in the list to open it for merging.
You can select a status for each program to indicate whether it is in progress, completed, or has no action.
Merge Edit Pane
Change Assistant displays the comparison in the merge edit pane. Lines from Child 1 and Child 2 are
listed in the merge pane and in the output pane according to the merge rules.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
357
Using Review Managed Object or Merge Select Object Types Action
Chapter 24
In the merge edit pane, the Action column shows the state of the line and the database to which it belongs.
The lines are also color coded to show the state of each line. The color codes are, by default:
Action
Color
COMMON
Black
ADDED
Green
CHANGED
Blue
DELETED
Red
COMMENT
Gray
READ ONLY
Black
Select View, Colors and Fonts to change the line display attributes.
Common lines are grouped in collapsed sections. Click the expand icon to expand each section.
Click in the text area of a line to edit the text.
To add lines to the merge edit pane from the individual data panes :
1. Highlight a line in the data pane.
2. Highlight a line in the merge edit pane.
The new line will be inserted below the highlighted line.
3. Click an action icon to either insert the line or insert it as a note.
To add a blank line or delete a line, select the line and click the Add line icon or the Delete line icon on
the Merge toolbar.
The Merge toolbar contains these options:
Add line.
Delete line.
Previous difference.
Next difference.
358
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Chapter 24
Using Review Managed Object or Merge Select Object Types Action
Insert Parent line.
Insert Parent line as note.
Insert Child 1 line.
Insert Child 1 line as note.
Insert Child 2 line.
Insert Child 2 line as note.
Merge Output Pane
The output pane displays the current merge results. Initially, the output pane displays the results of the
comparison based on the merge rules. When you apply changes, the new merge appears in the pane.
Data Windows
When you select a program, Change Assistant displays the three versions of the program in the respective
Parent, Child 1, and Child 2 windows.
Merge Menu
The Merge menu contains these options:
New Session
Create a new merge session.
Open Session
Open an existing merge session. [Crashes CA]
Save Session
Save the session.
Apply to Target
Apply changes to the Child 1 (Target) database and display the
merged program in the merge worksheet pane.
Set Merge Rules
Opens the Edit Session Rules dialog.
See Defining Merge Rules.
Purge Session
Purge the merge.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
359
Using Review Managed Object or Merge Select Object Types Action
360
Chapter 24
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix A
Working With Scripts
Understanding Process, Scripts, and Syntax
Before Change Assistant runs SQL and Data Mover scripts, it determines whether the scripts need
updating. This ensures that logs are sent to directories that are known to Change Assistant and that the
scripts run properly.
The following table shows the processes, what scripts are updated, and the updated syntax.
Process
Script Files
Updated Syntax
DataMoverBootstrap
<process name>.dms
SET LOG statements
<process name>.sql
CONNECT TO …
DataMoverUser
LoadBaseData
DB2 z/OS SQL Commands
SQL Scripts
SET CURRENT SQLID =
UpdatePeopleTools
Oracle SQL Commands
<process name>.sql
WHENEVER SQLERROR EXIT
SQL Scripts
SET ECHO ON
UpdatePeopleTools
SET TIME ON
SPOOL…
SPOOL OFF
EXIT
DB2 UDB SQL Commands
<process name>.sql
CONNECT TO …
SQL Scripts
UpdatePeopleTools
Running Scripts Outside of Change Assistant
If you are running a script outside of Change Assistant, keep in mind that the default behavior of Change
Assistant is to stop when any errors are encountered. To replicate that behavior outside of Change
Assistant, you will need to run the script using the correct options. The following table displays the
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
361
Working With Scripts
Appendix A
command line options required per database platform to either stop at errors or continue when errors are
encountered.
Database
Stop/Continue at Errors
Oracle
Exit on error:
<sqltool> <accessID>/
<password>@<dbname>@<scriptname>
Prepend script with: WHENEVER SQLERROR EXIT
Continue on error:
<sqltool> <accessID>/
<password>@<dbname>@<scriptname>
Prepend script with: WHENEVER SQLERROR CONTINUE
DB2 z/OS
Exit on error:
<sqltool> /c /w /i DB2 -tvf <script name> -z <log name> -s
Continue on error:
<sqltool> /c /w /i DB2 -tvf <script name> -z <log name>
DB2 LUW
Exit on error:
<sqltool> /c /w /i DB2 -vf <script name> -z <log name> -s
Continue on error:
<sqltool> /c /w /i DB2 -vf <script name> -z <log name>
Microsoft SQL Server
Exit on error:
<sqltool> -U <accessID> -P <password> -s <server name> -D
<database name> -i <script name> -o <log name> -e -n -I -b
Continue on error:
<sqltool> -U <accessID> -P <password> -s <server name> -D
<database name> -i <script name> -o <log name> -e -n -I
362
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Step Types
When creating custom steps, select one of these step types.
Note: When creating step types that Application Designer executes, such as Build Project or Compare
and Report, if there are specific settings that need to be set for Application Designer, make sure to
specify those using the Build, Upgrade, or Object Types buttons that appear to the right of the Step Type
dropdown list. Use these buttons to save any necessary settings to the Change Assistant template. At run
time, any Application Designer settings saved in the template override the current settings for Application
Designer on the machine where an Application Designer process runs.
Step Type
Definition
Application Engine
Runs the Application Engine process indicated by the Script/
Procedure value under Step Properties.
ApplicationEngineWithRunControl
Runs an Application Engine process with run controls. Use the
Options button to select the application engine program and
enter the run control parameters.
For ADS Compare/Copy see Setting AE With Run Control
Options for ADS Compare/Copy
Global Payroll (GP) application engine programs are used
to move GP rules and data between databases. There are 7
application engine programs available. The same parameters
are used for all the GP application engine programs. Run
Control ID needs to be the same name as the Package ID.
Package ID is the Package ID of the rule package. Version
indicates if this package is to be versioned, the default is Y.
Search Framework - Schedule Index runs the application
engine program PTSF_SCH_INDEX to build a Search
Framework search index. Click Options to enter the run
control options. The run control options are the same as the
Build Search Index page.
See "Building Search Indexes" (PeopleTools 8.55: Search
Technology).
The Logging Suffix option can be used to create a unique log
file for the step.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
363
Modifying Step Properties and Parameters
Appendix B
Step Type
Definition
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.
Use the Build button to select options based on the instructions
in the update documentation for your product and path.
Note: The Build dialog box that appears displays identical
options to Application Designer.
See "Selecting Build Options and Running the Build Process"
(PeopleTools 8.55: Application Designer Developer's Guide).
Compare And Report
Runs the project compare (which produces compare reports)
process using the project specified in the step properties
parameter as #Project= (for example, #Project=ALLTABS).
The compare is performed through the PeopleTools command
line.
For the Compare and Report and all Copy ... step types, use
the Upgrade button to select the appropriate options, which are
identical to those provided for Upgrade Options in Application
Designer.
See "Setting Upgrade Options" (PeopleTools 8.55: Lifecycle
Management Guide).
Compare from file
Runs the project compare (which produces compare reports)
process using the project specified in the step properties
parameter as #Project= (for example, #Project=PROJECT1).
The compare is performed through the PeopleTools command
line.
Use the Upgrade button to select the definition types to
compare and enter the Import/Export Directory that contains
the file.
Use the Options button on the Compare from File dialog box
to select the appropriate options, which are identical to those
provided for Upgrade Options in Application Designer.
See "Setting Upgrade Options" (PeopleTools 8.55: Lifecycle
Management Guide).
Compile PeopleCode
Compiles PeopleCode based on database or project.
Use the Options button to select the PeopleCode to compile.
For the database, you can select either all PeopleCode or just
directive PeopleCode. For a project select Project and enter the
project name.
Copy Database
364
Copies a project from the source database to the target
database as specified under the Step Properties. The project
used is the one specified in the step properties parameter as
#Project= (for example, #Project=ALLTABS). The copy is
performed through the PeopleTools command line.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Step Type
Definition
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).
Use the Upgrade button to select the definition types to copy
and enter the Import/Export Directory that contains the file.
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).
Use the Upgrade button to select the definition types to copy
and enter the Import/Export Directory for the file.
Create Customization Project
Creates a customization project within Change Assistant. Use
the Options button to launch the Create Project dialog box
where you can select any combination of definition types to
include in the project, such as pages, records, fields and so
on, as well as the user IDs. You can enter multiple user IDs
separated by commas.
The customization project will include all managed objects
for the object types selected that have any of the user IDs
selected as the last user ID for the object. If user ID all is
selected, the project will contain all managed objects for the
object types selected where the last user ID for the object is
not “PPLSOFT’.
Create project
Creates a project within Change Assistant. Use the Object
Type button to launch the Create Project dialog box where you
can select any combination of definition types to include in the
project, such as pages, records, fields and so on.
Note: If you select Pages, the system inserts all the page types
into the project, including pages, subpage and secondary
pages.
Merge project
Merges two project definitions.
For example, this is used in upgrades during the "Merge IB
Project" step, which merges pre and post-PeopleTools 8.48
Integration Broker metadata.
Data Mover-Bootstrap
Runs Data Mover scripts as the access ID specified in the
credentials panel in the Apply Wizard (bootstrap mode).
Data Mover-User
Runs Data Mover scripts as the user ID specified in the
credentials panel in the Apply Wizard (non-bootstrap mode).
DBTSFIX
(Applies to DB2 z/OS, DB2 LUW, and Oracle). Change
Assistant determines the source and target releases of the
databases defined under Step Properties as Source and Target.
Once this is completed, Change Assistant determines which
release scripts need to be generated by the DBTSFIX sqr to
produce release scripts for your environment.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
365
Modifying Step Properties and Parameters
Appendix B
Step Type
Definition
Deploy file
Deploys files in change packages to different servers.
Note: COBOL files are deployed to src/cbl for non-Windows
platform.
When you select the DeployFile type, an Additional Settings
button is available to set:
FileCopy
•
File Reference ID
•
File Type Code
Enables you to copy files or directories.
File Copy properties include:
•
Source Path
•
Destination Path
•
Overwrite Existing Files check box.
The Source and Target Paths can be defined as:
Execute process
•
actual paths for example: C:\temp
•
variablesfor example: %STAGINGDIRECTORY%
•
combination of variables and fixed paths for example:
%STAGINGDIRECTORY%\IMAGE\
Enables you to include custom processes, such as bat files, that
you can run as part of a Change Assistant job.
Enter the file path to the file in the Parameters edit box. For
example, if you want to run backup.bat, enter the following in
the Parameters edit box:
c:\bat\backup.bat
Note: Your custom file needs to be able to close without
needing human interaction. Change Assistant does not
officially recognize the step as being successfully completed
until the processes ran by the bat file have been closed.
ExportTemplate
This step exports the modified change package template.
Typically this step would be included in a Update change
package.
Load Base Data
366
Change Assistant determines the source and target releases
when running either the DBTSFIX or UpgradePeopleTools
steps (depending on your database type). Once these are
determined, Change Assistant will dynamically define which
Load Base Data scripts need to be run for the original target
release and the languages that you have installed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Step Type
Definition
Manual Stop
Defined as a step you must run manually. Change Assistant
automatically sets the run status to Stop. After you have
manually completed the step, you must change the Job Status
to Complete.
ProcessScheduler
Runs the specified upgrade process through Process Scheduler.
To further define the step, you use these required parameters:
#USE_PRCS_SERVER=
#PROCESS_TYPE=
#PROCESS_NAME=
#RUNCONTROLID=
#NUM_INSTANCES=
Note: If you don't specify the value to each parameter
correctly, the step will fail.
Example: To run one instance of an Application Engine
program on SERVER1, specify parameters as:
#USE_PRCS_SERVER=SERVER1
#PROCESS_TYPE=Application Engine
#PROCESS_NAME=MYAE
#RUNCONTROLID=TEST
#NUM_INSTANCES=1
Example: To run three instances of an SQR report (XRFWIN)
on SERVER2, specify parameters as:
#USE_PRCS_SERVER=SERVER2
#PROCESS_TYPE=SQR Report
#PROCESS_NAME=XRFWIN
#RUNCONTROLID=MYID
#NUM_INSTANCES=3
See Step Parameters.
PTFTest
SQL Command
This step is used to run a PTF test. Use the following
parameters:
•
#TST - test name
•
#TC - test case
•
#PFX - test case prefix
Runs the SQL command defined in the Parameters value under
the Step Properties. Change Assistant runs the command using
the SQL Query tool specified in the Database Configuration
dialog box.
For most SQL Query Tools, Change Assistant stops on an
error.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
367
Modifying Step Properties and Parameters
Appendix B
Step Type
Definition
SQL Script
Runs the SQL script defined in the Script/Procedure value
under the Step Properties. Change Assistant runs the script
using the SQL Query tools specified on the Database
Configuration.
For most SQL Query Tools, Change Assistant stops on an
error.
SQL Script DBO
Runs the SQL Script defined in the Script/Procedure value
under the Step Properties, using the DB Owner ID.
The DB Owner and password is set for the database when
the Set DB Owner Credentials is selected on the database
definition.
SQR Report
Runs SQRs using the pssqr command line. If parameters
are included in the Parameters section of the step properties,
Change Assistant will obtain the SQR settings from the
database definition.
See Setting SQR Report Output Options
SyncDatabaseInfoToCA
This step updates all of the target information to Change
Assistant.
This step will run as part of the Cleanup and Administrative
tasks in the Change Assistant Job.
SyncDatabaseInfoToPUMSource
This step is only used for PUM updates. If the user selects
Yes on the Synchronize Target Metadata (Requires Source)
radio button on the Change Package Settings page, this step
is executed in the job to update all of the target database
information to the PI.
UpdateChangePackage
UpdateChangePackage is a specialized function within the
Change Packager relating to the updating of change packages
created using Update Manager.
UpdateCurrentHomes
This step updates target database Current Homes PS_HOME
information by setting the Current PS_HOME to the value
of the New PS_HOME for Database definition associated to
the DB Orientation (Source or Target) of the step. It does not
update the PS_APP_HOME or PS_CUST_HOME.
Typically this step would be included in a PeopleTools
Upgrade.
UpgradePeopleTools
Change Assistant determines the source and target releases
of the databases defined under Step Properties as Source
and Target. Once this is completed, Change Assistant then
determines which Release scripts to run in order to upgrade
your PeopleTools release from the original source release to
the new target release.
Note: There is no limitation to the number of steps you can add to a template.
368
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Setting AE With Run Control Options for ADS Compare/Copy
The application engine process PTADSAEPRCS is used to copy a data migration project a a file, copy a
data migration project from a file or compare a data migration project from a file.
To set the AE run control options:
1. Insert a new step in the template and select Type ApplicationEngineWithRunControl or open an
existing step with the type ApplicationEngineWithRunControl.
2. Make sure the orientation is set correctly.
•
Source is used for Copy to File.
•
Target is used for Compare From File and Copy From File.
3. Click the Options button.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
369
Modifying Step Properties and Parameters
Appendix B
Image: AE With Run Control Options
This example illustrates the fields and controls on the AE With Run Control Options page. You can find
definitions for the fields and controls later on this page.
Process
370
Select the AE process, For ADS, the options are:
•
Compare From File
•
Copy to File
•
Copy From File
•
Validate From File
Project Name/Run Control
Enter the Data Migration Project Name. The project name is
also used as the run control and is automatically populated in the
Run Control ID.
Area Name
Enter the name of the area (folder) for the file. When you select
Copy to File, the file will be written to the Staging directory
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
defined for the job in a folder PTADSAEPRCS\<area name>.
For example:
D:\Staging\PTADSAEPRCS\TOOLS
Languages
Select the languages
Include Language Neutral Objects
Select to include language neutral objects (COMMON).
Object Types
ALL will include all data sets in the project. To select only
specific data sets, enter the data set name or names separated by
comma.
Merge
Select Yes to merge target configurations on the Copy From
File.
Overwrite Existing
Select Yes if you want to overwrite an existing file.
Ignore Shape Difference
Select Yes if you want to ignore shape difference. The allowed
shape changes include adding records or fields to a data set
definition.
Validate Before Apply
Select Yes to validate the data set before it is compared or
copied from file.
Validate After Apply
Select Yes if you want to check integrity after the copy.
Logging Suffix Options
Select whether to use the default log name or enter a custom
suffix value for the log file name.
The suffix is used to create a unique output log file name for the
step.
Note: Depending on the action selected, the available options are enabled.
Setting SQR Report Output Options
To set SQR output options:
1. Insert a new step in the template and select Type SQRReport or open an existing step with the type
SQRReport.
2. Enter the report name in the Script/Procedure field.
3. Click the Output Settings button.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
371
Modifying Step Properties and Parameters
Appendix B
Image: SQR Output Settings dialog box
This example illustrates the fields and controls on the SQR Output Settings dialog box. You can find
definitions for the fields and controls later on this page.
Unicode Only
Select this checkbox for Unicode Only.
Output Type
Currently File is the only supported value and is read-only.
Output Format
Select the output format. The allowable output values are
PDF, HTML, and SPF.
The default is SPF
Output File Suffix
Enter an output file suffix if applicable.
The suffix is used to create a unique output log file name for
the step. A change package may run the same SQR multiple
times, the suffix will ensure unique output log files.
Run Control ID
Enter the run control ID. The default is AD HOC.
4. Click OK.
5. Click OK on the step
Step Parameters
Depending on the step type, you may need to include additional parameters in the Parameter edit box of
the Step Properties dialog box.
372
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Parameter
Description
#Project=
Used primarily for functions that require a project name, like
Build Project, Create Project, and Merge Project.
For the Merge Project step type, you can specify two projects
separated by a comma. For example:
#PROJECT=PRJ656265,PRJ656265_IB_PRE848
#Directory=
Used when you need to run a script that is not located in the
one of standard home directories defined for the environment.
For example:
#Directory=#OutputDirectory
#RunLocation=
#FileLocation=
By default the scripts and processes are run on one of the
current home directories defined for the environment.
However if the script or process needs to run on the new
release, you need to specify the new release home directories
using the variable #ALL_NEW_PATHS_TGT. Example:
#RunLocation=#ALL_NEW_PATHS_TGT
#FileLocation=#ALL_NEW_PATHS_TGT
#P1= through #P5=
Used to pass parameters to SQR reports, for example, TEST.
sqr. In this case, you would pass the necessary value, such as:
#P1=#OutputDirectory
#OutputDirectory=
Used to specify the Output Directory variable that is defined in
the Options, Change Assistant, Directories screen.
#NT=
Used for DB2 Command Center, for Non-Terminated SQL
Scripts.
Note: The #NT parameter applies to DB2 LUW only. It is
ignored for DB2 zOS.
#Type=
Enables you to specify the type of record to insert into the
project. Choose 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.
#CI =
Connect ID (Used for Data Mover – Tools).
#CW =
Connect password (Used for Data Mover – Tools).
#EXTRACT_DMS=
Extracts DMS export script from file (Used for Data Mover –
Tools).
#DBSETUP=
Extracts dbsetup DMS import script from file and database
connectivity parameters (Used for Data Mover – Tools).
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
373
Modifying Step Properties and Parameters
Appendix B
Parameter
Description
#DATLOCATION=
Specifies the location of the .dat file (Used for Data Mover –
Tools).
#UNICODE=
Generates DMS script for UNICODE database (default is
NON-UNICODE) (Used for Data Mover – Tools).
#TABLESPACE=
Default tablespace (PTMINITS) (Used for Data Mover –
Tools, DB2 LUW, Oracle and Informix only).
#DBSPACE=
Physical dbname.tablespace (PTMINIDB.TABLESPACE) ) (
Used for Data Mover – Tools, DB2 z/OS only).
#STOGROUP_TS=
Storage group for tablespace (Used for Data Mover – Tools,
DB2 z/OS only).
#STOGROUP_IDX=
Storage group for index (Used for Data Mover – Tools, DB2 z/
OS only).
#TABLEOWNER=
Database owner ID (same as sqlid and tableowner) (Used for
Data Mover – Tools, DB2 z/OS only).
#INDEXSPC=
Default tablespace (PTMINITS) (Used for Data Mover –
Tools, Informix only).
#USE_PRCS_SERVER=
(Used only for ProcessScheduler step types).
Enter the name of the Process Scheduler server to run the step.
Valid values are SERVER1 or SERVER2, which correlate to
the Process Scheduler server definitions you have defined in
your upgrade environment.
#PROCESS_TYPE=
(Used only for ProcessScheduler step types).
Enter the process type, as defined in Process Scheduler. For
example, Application Engine, SQR Report, Data Mover, and
so on.
Note: This parameter is case sensitive. That is, the value
must appear in the exact case as the process type in
Process Scheduler. For example, for an Application Engine
program, the process type parameter should appear as
PROCESS_TYPE=Application Engine, not PROCESS_
TYPE=APPLICATION ENGINE.
#PROCESS_NAME=
(Used only for ProcessScheduler step types).
Enter the process name, such as DDDAUDIT.
374
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
Parameter
Description
#RUNCONTROLID=
(Used only for ProcessScheduler step types).
Enter the appropriate run control ID.
Note: If NUM_INSTANCES is greater than one, Change
Assistant will append unique sequence numbers to the end
of the Run Control ID before requests are submitted to the
Process Scheduler. This is required for submitting multiple
instances of the same process. If NUM_INSTANCES is equal
to one, Change Assistant will NOT append unique sequence
numbers to the end of the Run Control ID.
#NUM_INSTANCES=
(Used only for ProcessScheduler step types).
Used by Change Assistant to schedule multiple processes
through Process Scheduler as individual process requests.
However, the actual number of instances simultaneously
executed on the Process Server is controlled by the Max
Concurrent setting for the process type in the Process
Scheduler server definition.
#TST
Used with the PTFTest step to identify the test
#TC
Used with the PTFTest step to identify the test cas.
#PFX
Used with the PTFTest step to identify the test prefix.
Variables for All Step Types that Use Path
The order by which the PeopleTools runtime will pick up objects from the file system is as follows:
1. PS_CUST_HOME
2. PS_APP_HOME
3. PS_HOME
Change Assistant will loop through the paths in order of precedence until it finds the first instance of the
file object at which time it will execute the step.
The following variables can be used for parameters requiring a path.
Variable
Description
#ALL_PATHS_TGT
Uses the path values defined for the target database current
environment.
#ALL_PATHS_SRC
Uses the path values defined for the source database current
environment.
#ALL_PATHS_ODMO
Uses the path values defined for the copy of demo database
current environment.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
375
Modifying Step Properties and Parameters
Appendix B
Variable
Description
#ALL_PATHS_PROD
Uses the path values defined for the production database
current environment.
#ALL_OLD_PATHS_TGT
Uses the path values defined for the target database old
environment.
Filter Query Variables
The following variables in filter queries can be used to determine whether databases are the same
platform.
Variable
Description
#PLATFORM_TGT
Uses the platform values defined for the target database
current environment.
#PLATFORM_SRC
Uses the platform values defined for the source database
current environment.
#PLATFORM_ODMO
Uses the platform values defined for the copy of demo
database current environment.
#PLATFORM_PROD
Uses the platform values defined for the production database
current environment.
Example: Compare and Report
In order to run a compare and report to a database, the databases must be on the same platform. A query
filter can be set on the step to remove non-relevant steps, so only the applicable steps will run.
Step Set
Filter
CompareAndReport
#PLATFORM_SRC=#PLATFORM_TGT
Review Compares
returns true
CopyProject
CopyToFile
#PLATFORM_SRC=#PLATFORM_TGT
CompareFromFile
returns false
Review Compares
CopyFromFile
Platform Used in Command Line
Steps where the command line includes the platform are:
376
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix B
Modifying Step Properties and Parameters
•
ApplicationEngine
•
ApplicationEngineWithRunControl
•
BuildProject
•
CompareAndReport
•
CopyDatabase
•
CopyfromFile
•
CopyToFile
•
CreateProject
•
MergeProject
•
DataMoverBootstrap
•
DataMoverUser
•
SQLCommand
•
SQLScript
•
SQRReport
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
377
Modifying Step Properties and Parameters
378
Appendix B
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix C
Clearing Environment Management
Framework Cache
Clearing Environment Management Framework Cache Overview
To ensure consistent behavior across all the elements of the Environment Management Framework, at
times, it is necessary to clear the cache stored within each element. Clearing the cache just on the web
server for the Hub, for example, is not sufficient. To re-initialize the entire framework, you need to
perform this cleanup on:
•
All agents
•
Change Assistant
•
Viewer
•
Hub
When to Clear Environment Management Framework Cache
After analyzing customer environments and consulting PeopleSoft support, the following list reflects the
most common situations in which it is recommended that you clear cache files:
•
After applying a maintenance pack. Maintenance packs deliver a large number of files. Clearing the
cache after applying a maintenance pack may increase performance for applying future updates.
•
After applying a PeopleTools patch. Information related to previous PeopleTools releases stored in the
cached directories can cause a variety of issues for Change Assistant.
•
After receiving a warning during file deploys or during the validate process (Tools, Validate). This is
typically related to cached references to peer IDs that are no longer used. Clearing the cache removes
references to unused peer IDs.
•
After Change Assistant hangs during re-validation. This is often a sign of cache issues.
•
After receiving notifications that you need to apply prerequisites that have already been applied.
Note: The above list reflects the most common situations when cache should be cleared, not every
possible situation. If you are encountering unexpected behavior, one element of your troubleshooting
should be clearing the cache.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
379
Clearing Environment Management Framework Cache
Appendix C
Clearing EMF Cache
To clear EMF cache:
1. Close the Change Assistant, stop all agents, and stop PSEMHUB.
2. Delete cache files from Change Assistant, agents, and Viewer.
a. Navigate to the following EMF locations:
EMF Element
Location
Change Assistant
Change Assistant installation location. For example,
c:\Program Files\PeopleSoft\Change Assistant
\envmetadata
Agents
PS_AGENT_HOME\PSEMAgent\envmetadata
Note: If PS_AGENT_HOME is not defined, the data is
stored in PS_HOME.
Viewer
PS_HOME\PSEMViewer\envmetadata
b. Delete the following directories:
\PersistentStorage
\ScratchPad
\transactions (if it exists)
\data\ids
c. For Change Assistant and agents only, delete the following file:
\data\search-results.xml
3. Delete cached files on PSEMHUB.
a. On the web server, navigate to PIA_HOME\webserv\peoplesoft\applications\domain\PSEMHUB
\envmetadata.
b. Delete the files stored in these directories:
\scratchpad
\PersistentStorage
\transactions (if it exists)
c. Delete all objects in \data (files and subdirectories, but not the \data directory).
For example,
380
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix C
Clearing Environment Management Framework Cache
\data\*.*
4. Restart PSEMHUB.
5. Restart all agents.
6. Restart Change Assistant and Environment Management Viewer as needed.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
381
Clearing Environment Management Framework Cache
382
Appendix C
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix D
Troubleshooting Change Assistant and EMF
Peer Cannot Connect to the Hub
When an Environment Management peer (typically an agent or the viewer) can't communicate with the
hub, the following error messages appear in the logs and stdout:
Broken connection - attempting to reconnect
RemoteException while connecting to server - retrying attempt 1
RemoteException while connecting to server - retrying attempt 2
RemoteException while connecting to server - retrying attempt 3
The peer periodically attempts to reconnect to the hub (by default every ten seconds) with the parameters
that are specified in the configuration.properties file.
Determining the Error Condition
The peer may not be able to communicate with the hub for one of the following reasons:
•
The peer is started but the hub is not started.
The peer reconnects once the hub is started.
•
The peer is started but the web server is configured to run on a different machine.
Edit the configuration.properties file and change the hubURL parameter.
•
The peer is started but the web server is configured to listen on a different port.
Users continue to see the error messages described previously. Edit the configuration.properties file
and change the port number for the hubURL parameter. Shut down and restart the peer.
•
The peer is running and communicating with the hub, and the PIA web server is shut down.
Users see the broken connection error message. Once the PIA web server is started, the connection is
restored.
When the peer has a pinginterval configuration parameter set to a high value (60 seconds or more), the
following exception might appear in the log:
INFO Thread-48 org.apache.commons.httpclient.HttpMethodBase - Recoverable
exception caught when processing request WARN Thread-48
org.apache.commons.httpclient.HttpMethodBase
- Recoverable exception caught but MethodRetryHandler.retryMethod() returned
false, rethrowing exception Broken connection - attempting to reconnect
Sending pulse from 'com.peoplesoft.emf.peer:id=5'
This is due to an HTTP client connection timeout which does not affect functionality.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
383
Troubleshooting Change Assistant and EMF
Appendix D
Ensuring the Correct Configuration
To ensure that you've configured the peer (agent or viewer) to properly connect with the hub, try each of
the following actions in turn:
•
Ping the hub host machine.
At a command prompt, enter ping machinename, using the machine name configured in the
hubURL setting. You should see messages indicating a reply from the machine.
•
Ping the hub host domain.
At a command prompt, enter ping hostdomain, using the fully qualified domain name as it's
configured in the hubURL setting; for example, mymachine.mydomain.com. You should see messages
indicating a reply from the machine.
•
Use an IP address in the hubURL.
In configuration.properties, replace the domain name in the hubURL setting with the machine's IP
address, then restart the peer.
•
Ensure that you specify the right port number in the hubURL.
In configuration.properties, the port number in the hubURL setting must be <PIA port> if you set up
PIA for a single server. In single server configurations, the hub uses the same port to which PIA is
configured.
In multi-server configurations, the hub uses the application default port, which is 8001. If you need to
change this setting, it must be done in the web server configuration files.
Agent-Specific Resolutions
If an agent is still experiencing connection difficulties, delete the following agent directories if they exist:
•
PS_HOME\PSEMAgent\envmetadata\data\ids
•
PS_HOME\PSEMAgent\envmetadata\PersistentStorage
•
PS_HOME\PSEMAgent\envmetadata\transactions
Note: You must also delete these directories after you install an additional hub on the same machine
which doesn't replace the existing hub, then shut down the old hub and start the new hub using the same
settings.
Viewer-Specific Resolutions
If the viewer Java application can't connect to the hub, first ensure that you specify the right port number
when launching the viewer program.
If you set up PIA for a single server, 80 is the default port number, if you set up PIA for multiple servers,
8081 is the default listening port number for PSEMHUB.
If the viewer is still experiencing connection difficulties, delete the following viewer directories if they
exist:
•
384
PS_HOME\PSEMViewer\envmetadata\data\ids
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix D
Troubleshooting Change Assistant and EMF
•
PS_HOME\PSEMViewer\envmetadata\PersistentStorage
•
PS_HOME\PSEMViewer\envmetadata\transactions
Note: You must also delete these directories after you install an additional hub on the same machine
which doesn't replace the existing hub, then shut down the old hub and start the new hub using the same
settings.
Servlet Request Processor Exception
When running WebSphere on multiple servers the following error can occur in the stdout log of the server
running PSEMHUB:
[10/21/03 20:32:44:826 PDT] 136aa03 OSEListenerDi E PLGN0021E:
Servlet Request Processor Exception:
Virtual Host/WebGroup Not Found : The host pt-lnx03.peoplesoft.com
on port 6080 has not been defined
Use the following steps to correct the error: (the host now can accept redirected queries from your reverse
proxy. Normally this configuration is applied during PIA install).
1. Open your WebSphere administration console.
2. Select Environment, Virtual Hosts, default_host, Host Aliases.
3. Add *.* so the host now can accept redirected queries from the reverse proxy.
Normally this configuration is applied during PIA install.
Error Initializing Agent
When starting agents, if you receive the following error message, determine whether an agent is already
running:
Error initializing agent. Verify if another agent is not
running on this machine or if you have the required permission to run the
agent.
If the console for the agent is not visible, check the task manager for the list of Java processes that are
currently running. Stop a running agent by invoking the scripts to stop the agents and then restart the
desired agent.
Determine whether the agent port is available. If not, choose a different port to start the agent.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
385
Troubleshooting Change Assistant and EMF
Appendix D
Distributed Object Manager Errors
When running process, such as Application Engine, through the Process Scheduler (by way of
Change Assistant) the following error can occur if you do not have security set appropriately for the
PROCESSREQUEST.
Connecting to App Server: 10.138.124.216:9000
Error, exception caught: Distributed Object Manager: Page=Create Language=%2 (1,4)
See Ensuring Process Scheduler Security Authentication.
Cloned Databases Not Being Unique
When copying databases, it is extremely important to delete the GUID value in the new (copied)
database. If not deleted, the hub will assume that the two environments are the same, leading to confusing
environment records.
To resolve this, set the value of the GUID field in the PSOPTIONS table to <space> in the new database.
You can insert the blank value in the PSOPTIONS table using the SQL tool at your site. The next time an
application server connects to the database, the system generates a new, unique GUID.
Large SQL Scripts Fail on Microsoft SQL Server
In some situations, depending on various factors, such as memory available on the Change Assistant
workstation, large SQL scripts can fail when run against Microsoft SQL Server. For example, this can
occur when running the Microsoft conversion script during an upgrade.
To resolve this issue:
•
Set the step executing the SQL script to run manually.
•
Split the script into at least three separate scripts and run them individually.
Process Scheduler Logs Retrieved Using FTP Losing Formatting
When reviewing Process Scheduler files retrieved by way of FTP, in some cases formatting is lost.
This is typically an issue with the ANSI setting on the FTP server. For example, on a vsftpd server, in the
vsftpd.conf file, make sure ascii_download_enable is set to YES. If not, stop the FTP daemon,
modify the setting, and restart the FTP daemon. (Adjust this information as needed for your FTP server).
Viewing Change Assistant Log Files
Change Assistant provides the following log files:
386
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix D
Troubleshooting Change Assistant and EMF
•
Job log file
•
Step execution logs
Job Log File
The job.log file is a consolidated file that includes all of the information entered in the Apply Wizard, as
well as execution status of all the tasks and steps in the change package. There are five Apply Wizards in
Update Manager action.
•
Apply Change Package
•
Apply PeopleSoft Release Patch
•
Apply PeopleTools Patch
•
Upgrade Tools
•
Upgrade Application
The log file will contain the information on Check Compatibility, Apply Summary pages, as well as
information about the Target and PUM Source environments. Once the job starts to execute, the execution
status of each step will be logged. This consolidated job log can be used to check the environment
settings, track the status of job, or review the job.
The job log is located in the folder generated for the change package job in the output
directory defined on the Change Assistant General Settings page, for example C:\CA\output
\updPACKAGE1_1476310350534\job.log.
You can also access the job log from Change Assistant by right-clicking on the job name and selecting
View Log.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
387
Troubleshooting Change Assistant and EMF
Appendix D
Image: Accessing job log from Change Assistant
This example illustrates accessing job log from Change Assistant. Right-click on the job name and select
View Log.
The job log includes:
•
Check Compatibility Page
•
Apply Summary Page
•
PI Environment
•
Step/job execution status during job execution
Step Execution Logs
As a job executes, the logs are placed in the output directory specified in Change Assistant in a folder
with the job name. For each step there several logs created:
388
Log File
Description
Example
*_Search.log
Indicates whether or not the file for the step was
found.
CP_BUILD_search.log
Searching for file of bin\client\winx86\pside.exe in
D:\PT8.54.21_Client_ORA\ – File Found.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix D
Troubleshooting Change Assistant and EMF
Log File
Description
Example
*_CA.log
Displays the command line used.
CP_BUILD_CA.log
Command Line: D:\PT8.54.21_Client_ORA
\bin\client\winx86\pside.exe -CT ORACLE
-CS -CD HC920001 -CO PS -CP * -PJB
PACKAGE1 -HIDE -QUIET -SS NO SN NO -MN -LF D:\Labs\PUM\Output
\softwareupdatePACKAGE1{HR92U016HC920001}IP\CP_BUILD_cmdline.log -CI
people -CW *
*.log
Output of command line execution, created by the CP_BUILD.log
command itself.
SQL Build process began on 10/13/2016 at
12:00:20 AM for database HC920001.
SQL Build process ended on 10/13/2016 at
12:00:25 AM. 78 records processed, 0 errors, 0
warnings.
SQL Build script for Create Tables
written to file D:/Labs/PUM/Staging/
softwareupdatePACKAGE1{HR92U016HC920001}IP/Scripts/CP_crttbl.sql.
...
*_cmdline
Lists command line parameters used.
CP_BUILD_cmdline.log
PeopleSoft Project Command Line Build Project
Project Name: PACKAGE1 Tools Release: 8.54.
21 2016-10-13 : 00.00.20
-CT Source Database Type = ORACLE
-CS Source Database Server =
-CD Source Database Name = HC920001
-CO Source Database Operator = PS
Command line process successfully completed.
*_out.log
For SQR, Application Engine, Data Mover, and
RESETVERSIONS_OUT.log
Filter steps this log lists parameters used and
results, as well as path to output files if applicable. PeopleTools 8.54.21 - Application Engine
Copyright (c) 1988-2016 Oracle and/or its
affiliates. All Rights Reserved Application Engine
program VERSION ended normally
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
389
Troubleshooting Change Assistant and EMF
Appendix D
Errors Found in Log Files
Change Assistant scans log files that are generated when various processes run, such as SQL, Data
Mover, SQR, CopyDatabase and so on. The following table describes what logs are produced and what
Change Assistant determines to be an error:
The log files generated by Process Scheduler are not parsed for warnings or errors. Therefore, even
though Change Assistant may show a status of Complete for a Process Scheduler step type, you should
review the generated log files for more details.
Processes
Log File
Error
Warning Status
Application Engine
<process name>_out.log
Restart Failed.
Warning.
Invalid, Error.
Abended.
Abort.
Not Defined.
Build Project
<process name>.log
Error.
CompareAndReport
Invalid PeopleCode.
CopyDatabase
Copy process cancelled.
CopyFromFile
Project <xxx> does not exist.
Warning.
CopyToFile
CreateProject
DataMoverBootstrap
<process name>_out.log
Unsuccessful.
DataMoverTools
Note: Any logs generated
by the Data Mover SET
LOG statement will also be
available.
PSDMTX Error.
<process name>_0.out
TNS Error.
<process name>_out.log
Program Aborting.
DataMoverUser
LoadBaseData
DBTSFIX SQRReport
Warning.
NA
Not Defined Error.
Deploy File
<process name>_out.log
Failure.
•
Unable to connect.
•
Environment
Management
Components are
Unavailable.
NA
Warning status.
390
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
Appendix D
Troubleshooting Change Assistant and EMF
Processes
Log File
Error
Warning Status
DSAutoGeneration
<process name>_out.log
Failed.
NA
DSCompile
<process name>.log
Warning status.
DSGetLogs
<process name>_out.log
Failed.
DSInitialImport
<process name>_detailed.log
Warning status.
DSRunJob
<process name>.log
DSCustomReport
DSPatchCorrection
DSPatchImport
ProcessScheduler
SQLCommand
NA
The log files generated by
Process Scheduler are not
parsed for warnings or errors.
Therefore, even though
Change Assistant may show
a status of Complete for
a Process Scheduler step
type, you should review the
generated log files for more
details
<process name>.log
SQLScript
UpdatePeopleTools
DB2 z/OS and DB2 UDB:
•
SQLSTATE=value (value
cannot be 02000).
•
SQLxxxxxN.
•
DB2xxxxxE.
Warning.
Oracle: ORA.
Microsoft SQL Server:
•
Msg[Microsoft].
•
Cannot open database,
access denied.
•
Specified SQL Server not
found.
Transaction rolled back.
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.
•
ConnectionOpen (
Connect()).
•
Login failed.
391
Troubleshooting Change Assistant and EMF
392
Appendix D
Copyright © 1988, 2017, Oracle and/or its affiliates. All rights reserved.