PeopleSoft Red Paper Series

HCM 9 Mass Update

By: David Lambert
June 2006
 HCM 9 Mass Update

Copyright © 2006, Oracle. All rights reserved.

The information contained in this document is proprietary and confidential to Oracle.

No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying and recording, for any purpose without the
express written permission of Oracle.

This document is provided for information purposes only and the contents hereof are
subject to change without notice. This document is not warranted to be error-free, nor
subject to any other warranties or conditions, whether expressed orally or implied in
law, including implied warranties and conditions of merchantability or fitness for a
particular purpose. We specifically disclaim any liability with respect to this document
and no contractual obligations are formed either directly or indirectly by this document.
This document may not be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without our prior written permission.

Oracle, JD Edwards, and PeopleSoft are registered trademarks of Oracle Corporation

and/or its affiliates. Other names may be trademarks of their respective owners.

.
Table of Contents

TABLE OF CONTENTS ........................................................................................................................................................... 3

CHAPTER 1 - INTRODUCTION ............................................................................................................................................ 4

Structure of this Red Paper....................................................................................................................................................... 4
Related Materials ....................................................................................................................................................................... 5

CHAPTER 2 - PERFORMANCE............................................................................................................................................. 6
Load Balancing........................................................................................................................................................................... 6
Parallel Processing using Mass Update .................................................................................................................................... 7
Performance Parameters ........................................................................................................................................................... 7

CHAPTER 3 - EXTEND MASS UPDATE TO CUSTOMER DATA ................................................................................... 8

services ........................................................................................................................................................................................ 8
Mass Update services ................................................................................................................................................................. 9
Mass Update data types ........................................................................................................................................................... 10
Transaction Processor.............................................................................................................................................................. 12
Integration ................................................................................................................................................................................ 13
Creation of a Mass Update service: Step by step................................................................................................................... 14

3
 HCM 9 Mass Update 1/18/2007

Chapter 1 - Introduction

This Red Paper is a practical guide for technical users, installers, system administrators, and programmers, who use, implement,
maintain, or develop applications for your PeopleSoft system. In this Red Paper, we hope to provide some insight and guidance
to Mass Update; this paper was developed because the application has been enhanced since HCM 89 and previous versions of
the product.

Based on customer’s requests, the application was redesigned in order to improve performance, to increase flexibility, to
provide a preview, enhance usability and to extend it to customer data. Mass Update introduces the concept of parallel
processing and was developed based on a Service Oriented Architecture. Parallel processing is the main (but not only) answer
to performance enhancements. The new architecture does not need special configuration, but this document provides some
guidance for administrators and power users in order to understand correctly how to setup the system and how to take profit of
mechanisms such as load balancing. A Service Oriented Architecture allows customer to extend Mass Update for their own
needs, which requires a good knowledge of the concept of services and how they need to be implemented for Mass Update.

We would recommend that this Red Paper be reviewed prior to extensive use of the Mass Update feature, for performance
concerns, or used as a resource throughout the process of designing and implementing an extension of Mass Update to customer
data, customized data or delivered data. We hope that it will be useful, and have made it as inclusive and accurate as possible as
of the time of this writing.

STRUCTURE OF THIS RED PAPER

This Red Paper is divided into 2 parts:

 Performance: parallel processing and process load balancing.

 Extend Mass Update to customer data: services, configuration.

© Copyright Oracle Corporation 2005. All rights reserved. 4

HCM 9 Mass Update 1/18/2007

RELATED MATERIALS
Please note that this paper is not a general introduction to Mass Update functionality, PeopleTools, or environment tuning and
we assume that our readers are experienced IT professionals, with a good understanding of PeopleSoft’s Internet Architecture.
To take full advantage of the information covered in this document, we recommend that you have a basic understanding of
system administration, basic Internet architecture, relational database concepts/SQL, and how to use PeopleSoft applications.

The functionality of Mass Update 9 is discussed in the following PeopleSoft PeopleBooks:

PeopleSoft Enterprise HRMS 9 Application Fundamentals

Many of the fundamental concepts related to PIA are discussed in the following PeopleSoft PeopleBooks:
PeopleSoft Internet Architecture Administration (PeopleTools | Administration Tools | PeopleSoft Internet
Architecture Administration)
Application Designer (Development Tools | Application Designer)
PeopleCode (Development Tools | PeopleCode Reference)
PeopleSoft Installation and Administration
PeopleSoft Hardware and Software Requirements
PeopleSoft Process Scheduler (Managing PeopleSoft Master Scheduler Servers)

© Copyright Oracle Corporation 2005. All rights reserved. 5

HCM 9 Mass Update 1/18/2007

Chapter 2 - Performance

The main answer to performance concerns regarding Mass Update is the ability to run a process in parallel on different
hardware. This functionality is an option available at run time from the run control page. When it’s activated, a couple of
options become available. Then, as part of PeopleTools functionality, the system can be configured in order to leverage the
processing of batch programs on different Process Scheduler servers.

LOAD BALANCING
The objective of load balancing is to automatically route requests to Process Scheduler servers in order to maintain optimal
processing at all time, and to offer fault tolerance in a batch environment.
Even, though it’s not mandatory, this functionality will produce the best performance when lots of processes, including large
ones, are submitted to the system. The principle is quite simple: each process is submitted to a Master Scheduler that assigns
a specific Process Scheduler server to execute the process. The algorithm for server assignment depends on the workload of
each server, server priority, and some basic rules configured in the system.
This mechanism is provided by PeopleTools, and it’s documented in:
PeopleSoft Process Scheduler (Managing PeopleSoft Master Scheduler Servers)

© Copyright Oracle Corporation 2005. All rights reserved. 6

HCM 9 Mass Update 1/18/2007

PARALLEL PROCESSING USING MASS UPDATE

When a user prepares a Mass Update for execution, it uses a run control page in order to enter the Mass Update Ids then submit
an Application Engine process to the system. By default, the process executes each Mass Update in sequence, one after another.
Then, in order to use parallel processing, one single option (checkbox) is available on the run control page. When it’s activated,
the same Application Engine process is submitted. In that case, the process will create separate sets (or chunks) of Mass
Updates, and submit to the system one Application Engine process per chunk of updates. These processes (or sub-processes,
that are called instances) can be executed in parallel, and on different hardware if a load balancing mechanism is activated.
Each chunk is composed of a limited number of updates: this limit is determined by an option on the run control page. In
addition, in order to limit the number of instances running in parallel, another option is present on the run control page. When
the sub-processes are submitted, then executed, the first Application Engine process (or main process) monitors the execution
of sub-processes. Monitoring of the instances is required in order to insure all updates will be executed. It means, when a sub-
process completes its execution, if there are some updates that are not executed yet, the main process will submit a new sub-
process with a new chunk of updates, and this happens until there is no more updates to be executed. This mechanism is called
‘spawning’.

PERFORMANCE PARAMETERS
Using parallel processing can dramatically improve performance. However, gains vary a lot depending on the architecture of
the system. Using load balancing (with a Master Scheduler server) provides the best environment for large updates, and this
does not require attention from users for ‘regular’ updates. Then, various parameters need to be evaluated in case of huge
updates: the number of Process Scheduler servers available on the system, the maximum number of concurrent processes on
those servers, and the maximum number of parallel processes submitted by the Mass Update main process. The best
performance is obtained when each instance is executed on one separate CPU. As a very basic example, if only 2 servers with 1
CPU each are available, then obviously, the maximum number of instances is equal to 2. Now, if each server has 2 CPUs, the
maximum number of instances can be extended to 4.

© Copyright Oracle Corporation 2005. All rights reserved. 7

HCM 9 Mass Update 1/18/2007

Chapter 3 - Extend Mass Update to customer data

One key requirement coming from customers, is the ability to process updates on any data in the system, including customer-
specific information. The first concept behind the Mass Update is the concept of an application update rather than a database
update. The purpose of Mass Update is to apply all the business logic required for a change. Thus, because we can’t update
tables directly using SQL statements, we need to trigger that business logic from the application itself. In HCM 9, the key
mechanism used to manage application data from external systems, but also for internal products, is the Service Oriented
Architecture. This means, rather than trigger SQL on the database, Mass Update triggers services on the application. As a
consequence, to be able to update data using Mass Update, one service that manages that data must be available and properly
configured in the system. The purpose of this chapter is to document how to define and configure these kind of services.

As a reminder, the product ‘Mass Change’, provided by PeopleTools, is available for any update on tables. But, as specified in
HRMS PeopleBooks, we don’t recommend using it for changes on HRMS data, where business logic must be triggered. Thus,
we don’t deliver any template for that product; some old templates are left in the database, but using them must be avoided.

SERVICES

The framework for Service Oriented Architecture was introduced in HRMS 8.9. It was reserved for internal use in this release,
but heavily used in applications such as Campus Solutions. In release 9, the framework was enhanced and opened for external
use. In addition, the set of services provided by the Core HR product was extended, as well as new services delivered by other
products, including Job Profile Manager.

As a prerequisite, people who design, develop, maintain and administer the product need to understand the concept of services,
which is based on object-oriented design techniques.

As a basic introduction, a service is a piece of logic (or operation) exposed to the public. The information regarding what the
service does and how to use it is available through a repository. What the service does represents a contract, and how to use it is
represented by its interface or signature. Then, the service is implemented using an application class that stores the logic itself.
Different kinds of services are provided: services that retrieve information from the application (represented by a ‘get’ prefix),
services that send information into the application (represented by a ‘set’ prefix). These services use arguments for input and
output, as like as functions. Example: getDriverLicense (that retrieves driver license information in a specific data
structure based on a person ID), setDriverLicense (that changes license information based on a specific data structure).
Implementation of services can vary a lot, and is hidden to service consumers. Various options can be used and are used by
delivered services: manage data using SQL to the database, manage data using a Component Interface, trigger other services,
access to web services, etc. In release 9, most of the delivered services are based on Component Interfaces.

Service registry is available on: Set Up HRMS > System Administrator > HCM Registry > Service Registry

© Copyright Oracle Corporation 2005. All rights reserved. 8

HCM 9 Mass Update 1/18/2007

MASS UPDATE SERVICES

In order to manage large updates, dedicated services must be designed and constructed. There are several reasons behind that:

 Mass Update is a generic functionality. Standard services can’t apply because they manage lots of data structures,
coded in application classes. To be flexible enough (meaning to be able to extend it) requires having a generic data
structure. It also preferred in order to minimize the lines of required code (to avoid redundancy).

 Mass Update services require a special logic to be executed: management of process options (effective dates, effective
sequence number) and ‘carry forward’.

 For performance reasons, we need these services to update data with a minimum amount of data retrieval. What we
expect is to change only a few elements attached to employee information. Thus, we would like to be able to update
data without doing any ‘get’ or ‘set’ operation that requires a lot of data to be moved.

Thus, services designed for Mass Update need to follow the same architecture, e.g. the same signature. A single data type
represents this signature, which is generic. Basically, this data type contains the list of changes to be applied for a single
employee: list of sections, elements and values.

Delivered services are located in the registry in HCM Registry > HR Core > Mass Update > Services.

The definition of services designed for Mass Update must derive the abstract class HCR_MASS_UPDATE_SERVICES:
MassUpdateBase. This class defines the abstract method DoService(&transaction As
HCR_MASS_UPDATE_TYPES:MassUpdateType_v1_0:MassUpdateType).

Thus, all services implement the same method, which is called with the transaction data to be executed.

Delivered Mass Update services access data using Component Interfaces. Then, they are all based on the same basic logic:

 The service initiates the access to one Component Interface based on parameters included in the argument
(transaction), including access keys (EMPLID, EMPL_RCD).

 Then, the service executes a loop on the list of changes included in the transaction. A change is represented by a
section, element and value.

 For each change, the service accesses the collection of the Component Interface that corresponds to the section. Then,
it applies the change on the field that corresponds to the element, using the value.

 Note that most of the time; the mapping between sections and elements with collections and fields is hard-coded. This
is not required (for instance Job Profile Manager service), because Job Profile Manager is based on a configuration.

For i := 1 to changes.len
If changes[i].section = 'aaa' then
Coll_aa.property(changes[i].element) = changes[i].value;

 Specific logic needs to be defined in addition for collections at level 2 or 3. For instance, data such Compensation or
Addresses needs to be based on Rate Codes or Address Types. Thus, the logic in the service needs to take care about
these keys.

© Copyright Oracle Corporation 2005. All rights reserved. 9

HCM 9 Mass Update 1/18/2007

MASS UPDATE DATA TYPES

The only data type used for Mass Update represents a transaction, which is a change composed by a lists of elements and
values, several options and a list of eligibility dates.

Data type is located in the registry in HCM Registry > HR Core > Mass Update > Types.

The main data type MassUpdateType is composed by the following information:

 SOURCE represents the module that requests the update. Today, the unique module, Mass Update, is represented by
the value ‘MASSUPDATE’.

 REFERENCE represents an ID managed by the source module. Mass Update module uses the Mass Update ID.

 ID represents a unique ID (integer) that identifies the change for the specified source and reference.

 PERSID represents the person ID the change applies to.

 EMPL_RCD represents the employee record number the change applies to.

 PRCS_MODE_FLG represents the process mode option as defined in a Mass Update definition (values are ‘I’ for
insert, ‘C’ for correct current information).

 REFERENCE_DT represents the date to be used as a reference.

 FUTURE_IND indicates if eligible future rows are included in the update.

 changes represents the details of the update (collection).

o SEQ_NUM represents the order of elements for the update.

© Copyright Oracle Corporation 2005. All rights reserved. 10

HCM 9 Mass Update 1/18/2007

o SECTION represents a section as defined in the Mass Update definition.

o ELEMENT represents an element as defined in the Mass Update definition.

o VALUE represents the associated value to the element as defined in the Mass Update definition.

o COPY_FWD indicates if the value of the element is forwarded in rows in the future, as defined in the Mass
Update definition.

 eligibilities represents the sequence of dates and effective sequences the person is eligible for the change
(collection).

o FROM_EFFDT represents the lower limit of the effective date the person is eligible to.

o FROM_EFFSEQ represents the lower limit of the effective sequence the person is eligible to.

o TO_EFFDT represents the upper limit of the effective date the person is eligible to.

o TO_EFFSEQ represents the upper limit of the effective sequence the person is eligible to.

 messages represents the messages generated during execution (collection). They are populated by services during
the execution.

o MES_SEVERITY represents the message severity (error, warning).

o DESCRLONG represents the text of the message.

Mass Update is designed in order to be able to update data related to a person (per extension to an employee). This is a strong
requirement; the selection phase is for instance based on Job data. That means services designed for Mass Update must apply to
a person. But, there are ways to define services that will be triggered by the Transaction Processor outside of Mass Update (see
Integration chapter). In that case only, such services don’t need to apply on a person, but the customer must define the whole
logic.

Then, in order to manage this information, a couple of public methods on MassUpdateType are available to services:

 addMessage(): Add a new message to the transaction log.

 gotCopyForward(): Indicates if any 'copy forward' flag is activated in the change.

 isUpdate(): Indicates if the change is an update.

 isEligible(): Indicates if given effective date and sequence is eligibilible.

 isEligibleDate(): Indicates if given effective date is eligible.

 isInRange(): Indicates if given effective date is in range.

 getValidEffdt(): Returns the first valid eligibility date after the reference date.

 isSectionExists(): Indicates if a specific section is defined in the change.

© Copyright Oracle Corporation 2005. All rights reserved. 11

HCM 9 Mass Update 1/18/2007

TRANSACTION PROCESSOR
A generic module called Transaction Processor composes the heart of Mass Update. The role of this module (implemented with
an Application Class) is to load, then interpret a change (a transaction) from 2 tables, to call the appropriate service or services
for this change with appropriate data based on a setup, and to manage a message log.

Here is the schema of tables used by Transaction Processor:

Transaction Processor

MU_TP_TRANS_TBL MU_TP_TRANS_LOG
0..*
MU_TRANS_SRC MU_TRANS_SRC
MU_TRANS_REF MU_TRANS_REF
MU_TRANS_ID MU_TRANS_ID
MU_EXEC_STATUS_FLG SEQ_NUM5
MU_TRANS_XML LASTUPDDTTM
LASTUPDOPRID
MSG_SEVERITY
0..* DESCRLONG

MU_TP_DATES
MU_TRANS_SRC
MU_TRANS_REF
MU_TRANS_ID
MU_FROM_EFFDT
MU_FROM_EFFSEQ
MU_TO_EFFDT
MU_TO_EFFSEQ

The module executing the Transaction Processor, for instance Mass Update, needs to populate tables MU_TP_TRANS_TBL
and MU_TP_DATES. This is part of the selection phase of Mass Update. The field MU_TRANS_XML represents the details of
the change, using XML format.

When the Transaction Processor is activated (using MU_TRANS_SRC, MU_TRANS_REF, MU_TRANS_ID as parameters), it
does the following:

 Load data from the tables in memory, using the data type structure MassUpdateType.

 Interpret the XML string and populate changes in the data type.

 Loop on changes.

© Copyright Oracle Corporation 2005. All rights reserved. 12

HCM 9 Mass Update 1/18/2007

o Identify the appropriate service that needs to be called based on the section.

o Create one MassUpdateType object for each identified service.

 Trigger each identified service with appropriate MassUpdateType object.

 Catch every message coming from service execution.

 Update transaction status and populate messages table.

INTEGRATION
Transaction Processor is designed as an independent module. It’s delivered as a part of Mass Update, but can be used within
other products, thus could be integrated in different processes. For instance, a batch process that requires updating person or
employee information can leverage cost of development using calls to Transaction Processor.

In order to make the integration, processes only need to populate MU_TP_TRANS_TBL and MU_TP_DATES tables. Then, for
each transaction, the process calls Transaction Process to load a transaction (method load()), then execute it (method
execute()).

As an example, please refer to Application Engine step HR_MASS_UPD.PAR=NO.GBL.default.1900-01-

01.Step05.OnExecute.

© Copyright Oracle Corporation 2005. All rights reserved. 13

HCM 9 Mass Update 1/18/2007

CREATION OF A MASS UPDATE SERVICE: STEP BY STEP

1 - Service Registration

Enter the registration wizard (Set Up HRMS > System Administrator > HCM Registry > Registration Wizard) in order to register the
service. You need to provide the following information:

 Type: Service

 Name: enter the name of the service you are registering.

 Version: enter the version number, which is 1.0 by default.

 Object owner identifier: enter the owner identifier for the new service.

 Parent Folder: select a folder in the registry used as parent folder. Selection is related to the object owner identifier.

 DoService Request: you only need to enter one element used as input.

o Element Name: transaction

o Category: Complex

o Complex Type: MassUpdateType

2 - Service interface

Once the service is registered; you can generate interface and implementation PeopleCode (using the “Generate Provider Code”
button) in order to create an application package. You then need to update the service definition with:

 Deployment: Local

 Package Root: enter the name of the application package you created.

 Class Path: enter the path to the class that defines the service interface.

 Implementation Class Path: enter the path to the class that defines the service implementation.

You have to change the definition of the interface: your class must extend the Mass Update base class
HCR_MASS_UPDATE_SERVICES:MassUpdateBase.

3 - Transaction Processor

In order to make data available for Mass Update users, you need to enter information for the transaction processor. You need to
enter the following information into Workforce Administration > Collective Processes > Mass Update > Configure Processor :

 Section: enter the name of the section you are creating.

 Level: indicates if the section applies at Person Level or Employee Level.

 Allow Copy Forward: indicates if the section allows to use the Copy Forward option (when data is effective dated) or
not.

 Service: enter the name of the service you created.

© Copyright Oracle Corporation 2005. All rights reserved. 14

HCM 9 Mass Update 1/18/2007

 Version: enter the version of the service you created.

 Elements: enter the list of elements you want to allow to Mass Update.

o Element: enter the name of element.

o Description: enter the description of the element shown in Define Mass Update.

o Prerequisites: use this part in order to define prerequisites and relationships between elements.

 Section Prerequisite: enter the name of the section that defines a prerequisite.

 Element Prerequisite: enter the name of element used as prerequisite.

 Prompt Field: enter the name of the field used to select information when a record is used as a
prompt. For instance, for element DEPT_ID, the prompt is defined with DETP_TBL. The element
has prerequisite BUSINESS_UNIT. In that case, the prompt field to be used with the prompt table is
SETID.

 Sequence: enter a sequence number in order to define an order of prerequisites.

o Prompt: indicates if the element is shown with a prompt.

o Edit Record or Field: enter the name of a record or a field when a prompt is defined.

4 - Service Implementation

The services delivered in release 9 should be used as examples for the implementation of new services. These services are

 HCR_MASS_UPDATE_SERVICES.MassUpdateJob_v1_0

 HCR_MASS_UPDATE_SERVICES.MassUpdatePerson_v1_0

 HCR_MASS_UPDATE_SERVICES.MassUpdatePersonProfile_v1_0

 HCR_MASS_UPDATE_SERVICES.MassUpdateMilitaryApprv_v1_0

The main logic of Mass Update services is to access to a specific Component Interface, to loop on the details of changes loaded
in the transaction and to apply the value of each change in the appropriate collection of the Component Interface, then to save
the Component Interface. Most of the time, the system does not need to retrieve information from the Component Interface, to
update a value in a collection is enough. However, sometime the process needs to retrieve values in order to manage additional
keys located in level 2 or 3 on the components.

In order to understand how services can manage data, here is the general framework used by Mass Update services (using
MassUpdateJob as a reference).

 Declarations (private attributes)

o The class defines objects based on HMCR_API2CI package in order to manage links with Component
Interfaces (&CIIdent, &CIHandler).

o The class defines an object of type ciNameValuePairCollection for each collection available in the
Component Interface (level 1, level 2…).

o The class defines arrays of object of type ciNameValuePairCollection for each collection available
in the Component Interface that requires any specific logic, when the system needs to take care of additional
keys, for instance Compensation. Most of the time, one array is defined for keys and one array is defined for
data. Also, the system defines the same for data at level 1, for instance for Job data component. Here the
system needs to know the list of effective dates and sequences stored in the system in order to manage an
© Copyright Oracle Corporation 2005. All rights reserved. 15
HCM 9 Mass Update 1/18/2007

insert or a correction, then to apply the ‘copy forward’ functionality. In that case, the system loads a
collection of keys before executing the update.

o Some variables are defined in order to keep track on the effective date of effective sequence currently
processed (&currentEffdt, &currentEffSeq), plus general options coming from Mass Update
definition (&gotCopyForward, &isUpdate).

 Constructor

o The system instantiates some collections or arrays of collection used internally.

 Do Service

o init()

 Initiates the access to the Component Interface.

 Sets the access keys of Component Interface, based on PERSID and EMPL_RCD coming from
transaction data).

 Stores in internal variables options coming from the Mass Update definition, using methods
gotCopyForward() and isUpdate().

o Retrieves information from collections on level 1, and stores it in internal arrays of collections.

 Retrieves information in upper levels, such as compensation and stores it in appropriate arrays of
collections.

o Depending on the Process Mode Option (‘Insert Effective Date’ / ‘Correct Current Information’), and on the
existence of the ‘Copy Forward’ option and on eligibility dates, the system determines the effective date to be
inserted, or fetches on existing effective dates in order to update, then calls the method
updateElements().

o updateElements()

 The purpose if this method is to loop over the details of the changes and to call the method
updateElement() for each of them. Then, the internal collections populate the Component
Interface collections using the method updateRecord().

 When a collection requires any specific logic based on keys, the system loops on appropriate keys
and data using the arrays of collection.

o updateElement()

 This method is based on a main evaluate based on section and element names. Using this data,
the system populates the appropriate collection with the value of the change with the method
pushCollection().

 When specific logic is required, such as for Compensation, the system needs to loops on key data
(for instance Rate Code), in order to insert, update or delete data from internal collections.

o pushCollection()

 Populates an internal collection with a value.

o updateRecord()

 Populates a Component Interface collection based on an internal collection.

o populateMessages()

© Copyright Oracle Corporation 2005. All rights reserved. 16

HCM 9 Mass Update 1/18/2007

 Populates the internal message table.

© Copyright Oracle Corporation 2005. All rights reserved. 17