Element

Upgrade
Process
Oracle Cloud Human Capital Management for the
US

WHITE PAPER / FEBRUARY 1, 2019

DISCLAIMER
The following is intended to outline our general product direction. It is intended for information purposes
only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or
functionality, and should not be relied upon in making purchasing decisions. The development, release, and
timing of any features or functionality described for Oracle’s products remains at the sole discretion of
Oracle.

2 W HITE PAPER / Element Upgrade Process

Table of Contents
Run Element Upgrade Process ................................................................... 4

Critical Considerations ................................................................................................................. 4

Process Parameters .................................................................................................................... 4

Process Output ............................................................................................................................ 6

Upgrading Existing Pretax Deductions: Explained ...................................... 9

Pretax Deduction Element Upgrade for Iterative

Calculation Enhancements for the US: Worked
Example..................................................................................................... 11

Upgrading Existing Involuntary Deductions for

Recalculation of Disposable Income for the US:
Explained ................................................................................................... 12

Involuntary Deduction Element Upgrade for

Recalculation of Disposable Income for the US:
Worked Example ....................................................................................... 13

Upgrading Existing Involuntary Deduction Support

Elements for the US: Explained ................................................................. 14

Appendix A: Manual Upgrade Steps for Involuntary

Deductions for Use with Pretax Iteration for the US:
Explained ................................................................................................... 15

3 W HITE PAPER / Element Upgrade Process

RUN ELEMENT UPGRADE PROCESS

When you create an element through the element template, it creates child
objects, such as input values, formulas, and balances. When Oracle HCM
Cloud Applications delivers changes to these child objects as part of an
enhancement to existing functionality, those changes would be reflected in any
new elements you create after the new functionality is delivered.

The new changes would not be available in any existing elements.

Use the Run Element Upgrade process to upgrade your existing elements with
the new features. Run this process from the Checklists work area whenever
your elements require updating.

Critical Considerations
Consider the following before running this process:

 Read this document carefully and completely.

 Check this document’s My Oracle Support entry for any updates regarding this process: Oracle Cloud
Human Capital Management for the US: Element Upgrade Process (2458385.1).

 Before you perform any action in a production environment, run this process in a test environment.
This process performs changes to your elements that cannot be rolled back. You must first thoroughly
test your scenarios to ensure they will perform correctly during payroll processing after the upgrade.
Only after you have verified your scenarios in a test environment should you run this process in a
production environment.

 Regardless of whether you are in the test environment or production, run this process initially in Draft
mode, and use the output report to review the changes to be made. Once your evaluation is complete,
and you approve of the changes, perform it in Final mode to implement the element upgrade.

 By default, when you enter the primary classification, this process runs against all eligible secondary
classifications and elements. To limit the scope of the output, run it against specific secondary
classification and element combinations.

 When this process updates formula objects, it overrides any manual configurations you may have made
NOTE: After updating formulas,
to the formulas. Check the Oracle Delivered Modified Formula column of the Draft mode output report you must run the Compile Formula
to identify these formula objects. Use the Formula Upgrade Option parameter to replace or preserve process from the Checklist work
these formulas. area to recompile them. Use % as
a wild card entry for the formula
Process Parameters and Oracle Payroll for the formula
type parameter.
The Run Element Upgrade process uses the following parameters:

Parameter Descriptions

PARAMETER
NAME DESCRIPTION OPTIONAL OR MANDATORY

4 W HITE PAPER / Element Upgrade Process

Mode
Primary Classification
Secondary Classification
Enable Feature
Element Name
Formula Upgrade Option
5 W HITE PAPER / Element Upgrade Process
Will have two values to select from: Mandatory
 Select Draft to perform a test run of this
process for data verification purposes.
 Select Final to run this process against
your live data.
Select the primary element classification you Mandatory
want to upgrade.
Select the secondary element classification you Optional
want to upgrade.
The values in this field are determined by the
primary classification you select.
Leave blank to run for all secondary
classifications.
Select one of the following: Optional
 Iteration on Pretax Element
Use this option to enable iteration on Pretax
elements. This option is available when you
select the Pretax Deductions primary
classification.
 Pretax Iteration for Use with Involuntary
Deduction Elements
Do not use this feature.
 Disposable Income Recalculation
Use this option to enforce the recalculation of
disposable income for your involuntary
deduction elements.
This option is available when you select the
Involuntary Deduction primary classification.
Select this option when upgrading your
involuntary deduction elements.
Select the element you want to upgrade. Optional
Leave blank to run for all elements.
Will have these values to select from: Mandatory NOTE: When enabling iteration
 Display all formulas for pretax deductions, you must
override their formulas. Therefore
Generates a list of all formulas that would be
when running in Final mode, if you
impacted during a Final run. Applicable to
select Iteration on Pretax
Draft mode only.
Element for Enable Feature,
 Override the existing formula Override the existing formula is
Replaces any existing formulas with new selected by default and cannot be
ones and renames the original formulas. changed.
Applicable to Final mode only.
 Do not make changes to the existing formula
Makes no changes to formulas. New
formulas are not added.
Figure 1. This image shows the process parameters.

Process Output
When you run this process, it performs different actions upon the objects related to the elements. It also
generates an output file that describes these changes.

ELEMENT UPGRADE OF OBJECTS

When run in Final mode, this process upgrades the different objects and their dependents in different ways.
If a new version of the element template includes any other objects apart from those listed in this table,
those objects are not upgraded.

The following table describes the conditions determining when the flow updates the listed objects:
NOTE: In most cases, when this
process makes changes to
OBJECT CONDITIONS existing objects, those changes
are applied as corrections.
Defined Balances No conditions. Always updates.
However, in the case of pretax
deductions, you must perform
Fast Formulas Based on the value you selected for the Formula Upgrade Option parameter at flow run
additional configuration that
time.
applies the upgrades as date-
effective changes. For further
Formula Results Does not apply to any specific conditions unless the dependent object already exists.
information, see Upgrading
For example, if the Element Upgrade process is creating an input value, the formula
Existing Pretax Deductions:
results must include it.
Explained below.

Status Processing Rules Does not apply to any specific conditions unless the dependent object already exists.
For example, if the Element Upgrade process is creating a status processing rule for a fast

6 W HITE PAPER / Element Upgrade Process

 formula, then that formula must already exist.

Balances Does not apply to any specific conditions unless the dependent object already exists.
For example, if the Element Upgrade process is creating a balance with new element input
values, then those input values must already exist. When the process creates the
balance, it creates it with an effective date of 01-JAN-1951. If any of the element balance
feeds do not exist as of this date, the process uses the effective date of the element when
creating the feed.

Balance Feeds The Element Upgrade process must have created the element input values before it
creates any balance feeds.

Input Values The Element Upgrade process creates an input value only when the following are true:
 Element is not retroactively enabled.
 Input value is not mandatory.
 Input value does not have default values.
 Input value does not have “Default at Run Time” enabled.
 No user-defined input value already exists.
 If the new input value is enabled for DBI and that DBI exists.
 Special Purpose value of the new input value does not exist for any existing input
values on the same element.

Element Eligibility Input Before the Element Upgrade process adds the element eligibility input values, those input
Values values must exist.
See the previous row for conditions on input values.

Element Entries The Element Upgrade process creates the appropriate element entries with the new input
values. It creates the entry for all date-effective records.

Calculation Unit Does not apply to any specific conditions. The Element Upgrade process links the
calculation value definition, element, and calculation logic.

Calculation Card Override Does not apply to any specific conditions. The Element Upgrade process links the
Usages calculation component as the override usage for a calculation value definition. This is
listed on the report as DIR Override Usages.

Calculation Card The process links the component details flex field with the calculation components. The
Components components include:
 DIR Comp Flex
 DIR Comp Flex Usages
 DIR Comp Flex Rships

OUTPUT REPORT

This process generates an output report in Microsoft Excel format. This report includes the following
worksheets:

 Sheet 1 - Parameters

Displays parameter details:

7 W HITE PAPER / Element Upgrade Process

 Figure 2. This image shows your parameter details.

 Sheet 2 – Upgrade Details

Displays object details – Sample of a report run in Draft mode:

Displays object details - Sample of a report run in Final mode:

Figure 3. This image shows Upgrade Details.

Description of Output Columns

COLUMN TITLE DESCRIPTION

Primary Classification Primary Classification of the element.

Secondary Classification Secondary Classification of the element.

8 W HITE PAPER / Element Upgrade Process

 Element Name Name of the element being upgraded.

Upgrade Object Type of object being upgraded, such as Balance Type, Input Value, Fast Formula,
and Formula Results.

Object Name Actual name of the object.

Object Details Any additional details with respect to the object.

For example, if the Upgrade Object is “Balance Feed”, then the Object Name would
display the actual balance feed (element input value) and Object Details would
display the Balance Type to which this balance feed belongs.

New or Existing Identifies if the process is making a change to an existing object.

For example, if the process is modifying a fast formula, it would be considered an
existing object on this report. However, if an input value is being added, it would
display as New.

Backup Formula Name When the process upgrades a fast formula, it saves the original formula as a
backup. This column of the report displays the backup formula name in Final
mode.

Status Upgrade status of the object.

Message Displays any messages related to the upgraded object.

Oracle Delivered Modified
Formula
Identifies if a predefined formula has been modified by the user. This column NOTE: This column is blank when
populates only when you run the process in Draft mode. you run this process in Final mode.
Use this column to help you decide if you want to upgrade your formulas. If you
elect to upgrade the formulas in Final mode, your configurations would be lost. You
can refer to the backup formulas generated in Final mode if needed.

UPGRADING EXISTING PRETAX DEDUCTIONS: EXPLAINED

In Release 18C and later, you can enable iterative functionality as part of the element creation. Use the
Element Upgrade process to enable iterative functionality for your existing pretax deductions.

When upgrading your pretax deductions, consider the following:

 If you have enabled proration on a pretax element, you cannot upgrade it.

 To upgrade your existing pretax deductions, you must run the Element Upgrade process first on your
Pretax Deduction elements and then perform the manual upgrade steps described in Appendix A on
your Involuntary Deduction formulas. This is required only when using existing involuntary deduction
elements and you have not already enabled the disposable income recalculation.

 To ensure a methodical and comprehensive upgrade approach, run this process in one of the following
ways:

– For each pretax secondary classification separately

– For each pretax element individually

 To ensure a methodical and comprehensive upgrade approach for your existing involuntary deduction
NOTE: This is not related to
elements, perform the manual upgrade steps as documented in Appendix A for each involuntary disposable income recalculation.
deduction element.

9 W HITE PAPER / Element Upgrade Process

 Because iterative processing requires the following values, the Element Upgrade process ignores any
NOTE: These conditions remain
settings you may have made during element definition: valid for all other element
classifications.
– Retroactive Processing check

– Required option

– Default value check

– Apply default at run time check

To upgrade your existing pretax deduction elements:

1. Perform the following prerequisite steps in your test environment:

a. Find and select the Manage Payroll Process Configuration task through the Page Controls.

b. Using the default group tab, select Create from the Actions menu.

c. Add the following parameter:

Date used in element upgrade process for iteration indicator. The date used by the
element upgrade process to update the iteration indicator for pretax element. This
indicates the effective date for pretax iteration process.

d. Set the configuration parameter to the next date after the latest payroll process for all payrolls.

The process uses this date to create the Enable Iterative Calculation field on the pretax element.
To avoid triggering retroactive processing prior to this date, you must set this parameter
appropriately.

For example, if the latest payroll process’s completion date is November 15, 2018, set this
parameter to 2018-11-16.

e. To change the number of iterations the payroll process performs, add the following parameter: NOTE: Increasing iterations may
impact performance.
Maximum Iterations allowed per Run Action Maximum number of iterations allowed per
run action. Default: 15.

Change the default to the number of iterations if you require a different value.

2. Submit the Run Element Upgrade process for all pretax deduction secondary classifications that need
iterative functionality. Repeat this step for each necessary pretax deduction secondary classification
before proceeding to the next step.

For further information, see Pretax Deduction Element Upgrade for Iterative Calculation Enhancements:
Worked Example below.

3. Submit the Compile Formula process to recompile all impacted formulas. Use % as a wild card entry for
the formula and Oracle Payroll for the Formula Type parameter.

4. Perform the manual upgrade steps as documented in Appendix A. This enables your involuntary NOTE: This step is not related to
deductions to work with the pretax elements enabled for iterative processing. Repeat this step for each disposable income recalculation.
involuntary deduction element.

For further information, see Pretax Deduction Element Upgrade for Iterative Calculation Enhancements:
Worked Example below.

10 W HITE PAPER / Element Upgrade Process

5. Run payroll and verify the results.

6. Once you have tested all of your pretax iteration scenarios and ensured they process correctly in
payroll, repeat these steps in your production environment. Review the My Oracle Support note for
current instructions before running in a production environment.

PRETAX DEDUCTION ELEMENT UPGRADE FOR ITERATIVE CALCULATION

ENHANCEMENTS FOR THE US: W ORKED EXAMPLE
This example assumes you are using existing pretax and involuntary deduction elements.

To take advantage of the new iterative calculation enhancements, you must upgrade any existing elements
of the following types:

 Selected pretax deductions

 All involuntary deductions

For this example, Company ABC decides to upgrade all Pretax Deduction elements to utilize the new
iterative calculation feature. Company ABC has already updated the default payroll process configuration
group to set the date used in element upgrade process to 2018-12-01.

To do this, perform the following in your test environment:

1. Run the process in Draft mode:

a. Navigate to the Run Element Upgrade process in the Checklists work area.

b. Enter the following parameters:

PARAMETER VALUE

Mode Draft

Primary Classification Pretax Deductions

Secondary Classification Deferred Compensation 401k

Enable Feature Iteration on Pretax Element

Element Name Blank

Formula Upgrade Option Display All Formulas

2. Review the output of the report. Ensure the pretax elements you want to upgrade are showing on the
report.

3. If you are satisfied with the proposed changes, run it again in Final mode:

a. Navigate to the Run Element Upgrade process in the Checklists work area.

b. Enter the following parameters:

PARAMETER VALUE

Mode Final

Primary Classification Pretax Deductions

11 W HITE PAPER / Element Upgrade Process

 Secondary Classification Deferred Compensation 401k

Enable Feature Iteration on Pretax Element

Element Name Blank

Formula Upgrade Option Override the Existing Formula

c. Review the output of the report. Ensure the pretax elements you want to upgrade are showing on
the report.

d. Repeat these steps for each necessary pretax secondary classification.

4. Submit the Compile Formula process to recompile all impacted formulas. Use % as a wild card entry for
the formula and Oracle Payroll for the Formula Type parameter.

5. To enable your involuntary deductions to work with the pretax elements enabled for iterative
functionality, use the steps in Appendix A to update each involuntary deduction element.

6. Run payroll and verify the results.

7. Once you have tested all of your pretax iteration scenarios and ensured they process correctly in
payroll, repeat these steps in your production environment. Review the My Oracle Support note for
current instructions before running in a production environment.

Once you have upgraded each involuntary deduction element, you do not need to perform this upgrade
again in the applicable environment even if you later decide to upgrade an additional pretax secondary
classification.

UPGRADING EXISTING INVOLUNTARY DEDUCTIONS FOR RECALCULATION OF

DISPOSABLE INCOME FOR THE US: EXPLAINED
In Release 18C and later, involuntary deduction elements automatically recalculate disposable income as
part of element creation. Use the Element Upgrade process to enable recalculation of disposable income
for any existing involuntary deduction elements created prior to Release 18C.

When upgrading your involuntary deductions, consider the following:

 Perform the upgrade first in a test environment. Verify all involuntary scenarios to confirm they process
correctly in payroll. Only after you have successfully verified all of the results should you perform these
steps in your production environment. Review the My Oracle Support note for current instructions
before running in a production environment.

 Once you upgrade any involuntary deduction secondary classification element, you must upgrade your
involuntary deduction elements for all secondary classifications before processing the elements in
payroll. Any employee with multiple involuntary deductions must not have a mix of old and new
involuntary deduction elements where the disposable income recalculation is enabled for some
elements but not for others.

 Run the Element Upgrade process for each Involuntary Deduction secondary classification and element
name combination separately.

 Depending on the age of your existing involuntary deduction elements, other new features are applied
as part of the upgrade process. This could include items such as legislative changes, new calculation
value overrides, formula changes, calculation changes, and new balances.

12 W HITE PAPER / Element Upgrade Process

 If for any reason the upgrade process is unable to successfully update an existing element, you must
replace it with a new element.

 To use the new Support Order Proration feature in Release 18C, you must upgrade your involuntary
deduction elements for all involuntary deduction secondary classifications.

To upgrade your existing involuntary deduction elements in a test environment:

1. Submit the Run Element Upgrade process in Draft mode for a given involuntary deduction secondary
classification and element name combination.

2. Select Disposable Income Recalculation in the Enable Feature parameter. Do not leave this
parameter blank.

3. Review the output of the report, and resolve any issues it identifies.

4. Repeat these steps for each secondary classification and element name combination. Proceed to the
next step only if no issues are identified.

5. Submit the Run Element Upgrade process in Final mode for the selected involuntary deduction
secondary classification and element name combination.

6. Select Disposable Income Recalculation in the Enable Feature parameter. Do not leave this
parameter blank.

7. Review the output of the report, and resolve any issues it identifies.

8. Repeat the steps for each secondary classification and element name combination.

9. Submit the Compile Formula process to recompile all impacted formulas. Use % as a wild card entry for
the formula and Oracle Payroll for the Formula Type parameter.

10. Run payroll and verify the results.

11. Once you have tested all of your involuntary deduction scenarios and ensured they process correctly in
payroll, repeat these steps in your production environment. Review the My Oracle Support note for
current instructions before running in a production environment.

For further information, see Involuntary Deduction Element Upgrade for Recalculation of Disposable Income:
Worked Example below.

INVOLUNTARY DEDUCTION ELEMENT UPGRADE FOR RECALCULATION OF DISPOSABLE

INCOME FOR THE US: WORKED EXAMPLE
For this example, Company ABC wants to enable disposable income recalculation for all their existing
involuntary deduction elements.

To do this, perform the following in your test environment:

1. Run the Run Element Upgrade in Draft mode:

a. Navigate to the Run Element Upgrade process in the Checklists work area.

b. Enter the following parameters:

PARAMETER VALUE

13 W HITE PAPER / Element Upgrade Process

 Mode Draft

Primary Classification Involuntary Deductions

Secondary Classification Garnishment

Enable Feature Disposable Income Recalculation

Element Name <your element name>

Formula Upgrade Option Display All Formulas

c. Review the output of the report. Ensure the involuntary deduction element has no errors on the
report.

2. Repeat these steps for each secondary classification and element combination.

3. If you are satisfied with the proposed changes for all your involuntary elements, run it again in Final
mode:

a. Navigate to the Run Element Upgrade process.

b. Enter the following parameters:

PARAMETER VALUE

Mode Final

Primary Classification Involuntary Deductions

Secondary Classification Garnishment

Enable Feature Disposable Income Recalculation

Element Name <your element name>

Formula Upgrade Option Override the Existing Formula

c. Review the output of the report. Ensure the involuntary deduction element has no errors on the
report.

4. Repeat these steps for each secondary classification and element combination.

5. Submit the Compile Formula flow pattern to recompile all impacted formulas. Use % as a wild card entry
for the formula and Oracle Payroll for the Formula Type parameters.

6. Run payroll and verify the results.

7. Once you have tested all of your involuntary deduction scenarios and ensured they process correctly in
payroll, repeat these steps in your production environment. Review the My Oracle Support note for
current instructions before running in a production environment.

UPGRADING EXISTING INVOLUNTARY DEDUCTION SUPPORT ELEMENTS FOR THE US:

EXPLAINED
When you upgrade involuntary deduction support elements for the Child Support, Spousal Support, and
Alimony secondary classifications, the Process Output file may include the following entries:

14 W HITE PAPER / Element Upgrade Process

 UPGRADE OBJECT OBJECT DETAILS

DIR Comp Flex HRX_US_EIWO_HEADER_DATA

DIR Comp Flex HRX_US_EIWO_RECEIPT_DATA

DIR Comp Flex HRX_US_EIWO_DETAIL_DATA

DIR Comp Flex HRX_US_EIWO_ACKN_DATA

DIR Comp Flex usage HRX_US_EIWO_HEADER_DATA

DIR Comp Flex usage HRX_US_EIWO_RECEIPT_DATA

DIR Comp Flex usage HRX_US_EIWO_DETAIL_DATA

DIR Comp Flex usage HRX_US_EIWO_ACKN_DATA

These values are no longer used, and you can disregard them.

APPENDIX A: MANUAL UPGRADE STEPS FOR INVOLUNTARY DEDUCTIONS FOR USE

WITH PRETAX ITERATION FOR THE US: EXPLAINED
Use the following steps to upgrade your involuntary deductions. Use these steps to upgrade the base fast
formula for each involuntary deduction element to work with pretax deduction elements enabled for iterative
functionality. These manual steps are not applicable for the recalculation of disposable income.

1. Start the Manage Fast Formulas task.

2. Open the <element name>_Base formula for editing.

3. Search for the following statement:

IF(l_tmp_rel_action_id <> l_payroll_rel_action_id) THEN

4. Replace this line with all of the following text:

/*Pretax Iteration Flag Key is needed to cleanup the Global WSA cache*/
l_pretax_iterator_flag_key =
'PRETAX_ITERATE_FLAG_'||TO_CHAR(l_payroll_rel_action_id)
l_pretax_iterator_flag = WSA_GET(l_pretax_iterator_flag_key,'N')
l_prev_pretax_iter_counter_key =
'PRETAX_ITERATE_PREV_COUNTER_'||TO_CHAR(l_payroll_rel_action_id)
l_prev_pretax_iter_counter = WSA_GET(l_prev_pretax_iter_counter_key, 0)
dummy = PAY_INTERNAL_LOG_WRITE('(GLBINV_BASE) Previous Pretax Iteration
counter ::::' || to_char(l_prev_pretax_iter_counter))
GLB_PRETAX_ITERATE_COUNTER_KEY = 'PRETAX_ITERATE_COUNTER_'||TO_CHAR(
l_payroll_rel_action_id)
l_pretax_iterate_counter =WSA_GET(GLB_PRETAX_ITERATE_COUNTER_KEY,0)
dummy =PAY_INTERNAL_LOG_WRITE('(GLBINV_BASE) GLB_PRETAX_ITERATE_COUNTER='
||to_char(l_pretax_iterate_counter))
/* Call formula to clean WSA variables */
IF(l_tmp_rel_action_id <> l_payroll_rel_action_id OR (
l_pretax_iterator_flag = 'Y' AND l_prev_pretax_iter_counter!=
l_pretax_iterate_counter ) ) THEN

15 W HITE PAPER / Element Upgrade Process

5. Save, and compile the formula.

6. Repeat for each involuntary deduction base element formula.

16 W HITE PAPER / Element Upgrade Process

ORACLE CORPORATION

Worldwide Headquarters
500 Oracle Parkway, Redwood Shores, CA 94065 USA

Worldwide Inquiries
TELE + 1.650.506.7000 + 1.800.ORACLE1
FAX + 1.650.506.7200
oracle.com

CONNECT W ITH US
Call +1.800.ORACLE1 or visit oracle.com. Outside North America, find your local office at oracle.com/contact.

blogs.oracle.com/oracle facebook.com/oracle twitter.com/oracle

Copyright © 2019, Oracle and/or its affiliates. All rights reserved. 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 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. 0219
White Paper Oracle Cloud Human Capital Management for the US Element Upgrade Process
February 2019
Author: Kim Linden/Mary Nell Mclaurine
Contributing Authors: John Lawson