resources cloud oracle global human · 2010. 1. 1. · oracle global human resources cloud using...

Oracle Global HumanResources Cloud

Using Fast Formula

20B

Oracle Global Human Resources CloudUsing Fast Formula

20BPart Number F27646-02Copyright © 2011, 2020, Oracle and/or its aliates.

Authors: Srinivas Vellikad, Holly Zimmerman, Carla Fabrizio, Angela Brown, Tim Bisset, Ravikumar Iyer, Ipsita Mohanty

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected byintellectual property laws. Except as expressly permied 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 nd any errors, please reportthem 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, thenthe following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed oractivated on delivered hardware, and modications of such programs) and Oracle computer documentation or other Oracle data delivered to oraccessed by U.S. Government end users are "commercial computer software" or "commercial computer software documentation" pursuant tothe applicable Federal Acquisition Regulation and agency-specic supplemental regulations. As such, the use, reproduction, duplication, release,display, disclosure, modication, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system,integrated software, any programs embedded, installed or activated on delivered hardware, and modications of such programs), ii) Oracle computerdocumentation and/or iii) other Oracle data, is subject to the rights and limitations specied in the license contained in the applicable contract. Theterms governing the U.S. Government's use of Oracle cloud services are dened by the applicable contract for such services. No other rights aregranted 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 usein any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware indangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safeuse. Oracle Corporation and its aliates 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 aliates. Other names may be trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarksor registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced MicroDevices. 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. OracleCorporation and its aliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, andservices unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its aliates will not be responsiblefor 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 applicableagreement between you and Oracle.


Contents

Preface i

1 Overview 1Overview of Using Formulas ....................................................................................................................................................... 1

2 Writing Formulas 3Overview of Writing Formulas ................................................................................................................................................... 3

Improve Formula Performance .................................................................................................................................................. 4

Formula Compilation Errors ....................................................................................................................................................... 6

Formula Execution Errors ........................................................................................................................................................... 7

Example of Writing a Fast Formula Using Expression Editor ............................................................................................. 9

Example of Writing a Fast Formula Using Formula Text .................................................................................................... 11

FAQs for Writing Formulas ....................................................................................................................................................... 12

3 Formula Components 13Overview of Using Formula Components .............................................................................................................................. 13

Types of Variables ....................................................................................................................................................................... 15

Formula Statements .................................................................................................................................................................... 15

Naming Schemes for Variables ................................................................................................................................................ 18

Database Items ............................................................................................................................................................................ 20

Overview of Generating Flexeld Database Items ............................................................................................................... 22

Example of Generating Flexeld Database Items ................................................................................................................ 22

Formula Operators ..................................................................................................................................................................... 24

Literals ........................................................................................................................................................................................... 25

How Formulas Determine Variable Data Types ................................................................................................................... 27

Array Variables ............................................................................................................................................................................ 28

Formula Contexts ....................................................................................................................................................................... 30

Overview of Working Storage Area ......................................................................................................................................... 31

Overview of Calling a Formula from a Formula ................................................................................................................... 32

Examples of Calling a Formula from a Formula .................................................................................................................. 34


4 Formula Functions 37Overview of Formula Functions .............................................................................................................................................. 37

Text Formula Functions ............................................................................................................................................................ 37

Numeric Formula Functions .................................................................................................................................................... 40

Date Formula Functions ............................................................................................................................................................ 41

Data Conversion Formula Functions ...................................................................................................................................... 43

Miscellaneous Formula Functions .......................................................................................................................................... 44

5 Formulas for Payroll 47Overview of Payroll Formulas .................................................................................................................................................. 47

Create Conversion Formulas for Proration ........................................................................................................................... 48

Congure Periodicity Conversion Rules ................................................................................................................................ 49

Element Input Validation Formula Type ............................................................................................................................... 50

User Table Validation Formula Type ...................................................................................................................................... 53

Payroll User Interface Conguration Formula Type ........................................................................................................... 54

Payroll Access to HR Formula Type ....................................................................................................................................... 60

Payroll Relationship Group Formula Type ............................................................................................................................ 62

Flow Schedule Formula Type .................................................................................................................................................. 64

Balance Exception Formula Type ........................................................................................................................................... 65

6 Formulas for Absence Management 69Options to Dene Qualication Plans .................................................................................................................................... 69

Options to Dene Accrual Plans ............................................................................................................................................. 70

Formulas for Accrual Plans ....................................................................................................................................................... 72

Formulas for Qualication Plans ............................................................................................................................................. 74

Formulas for Absence Type ..................................................................................................................................................... 75

7 Formulas for Compensation Plans 77Overview of Formulas for Compensation Plans .................................................................................................................. 77

Formula Type for Compensation Currency Selection ........................................................................................................ 77

Formula Type for Compensation Default and Override .................................................................................................... 80

Formula Type for Compensation Hierarchy Determination .............................................................................................. 83

Formula Type for Compensation Person Selection ............................................................................................................ 86

Formula Type for Total Compensation Item ........................................................................................................................ 88

8 Formulas for Benets 93Overview of Benets Formulas ............................................................................................................................................... 93


9 Formulas for Time and Labor 95Formulas and Types of Time Rule Templates ..................................................................................................................... 95


Preface

i

PrefaceThis preface introduces information sources that can help you use the application.

Using Oracle Applications

HelpUse help icons to access help in the application. If you don't see any help icons on your page, click your user imageor name in the global header and select Show Help Icons. Not all pages have help icons. You can also access the OracleHelp Center to nd guides and videos.

Watch: This video tutorial shows you how to nd and use help.

You can also read about it instead.

Additional Resources

• Community: Use Oracle Cloud Customer Connect to get information from experts at Oracle, the partnercommunity, and other users.

• Training: Take courses on Oracle Cloud from Oracle University.

ConventionsThe following table explains the text conventions used in this guide.

Convention Meaning

boldface Boldface type indicates user interface elements, navigation paths, or values you enter or select.

monospace Monospace type indicates le, folder, and directory names, code examples, commands, and URLs.

> Greater than symbol separates elements in a navigation path.

https://docs.oracle.com/en/cloud/saas/applications-help/

https://docs.oracle.com/en/cloud/saas/applications-help/

https://apex.oracle.com/pls/apex/f?p=44785:265:0::::P265_CONTENT_ID:27341

https://apex.oracle.com/pls/apex/f?p=44785:265:0::::P265_CONTENT_ID:27341

http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=OACPR158049

https://appsconnect.custhelp.com/

http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=906


Preface

ii

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website.

Videos included in this guide are provided as a media alternative for text-based help topics also available in this guide.

Contacting Oracle

Access to Oracle SupportOracle customers that have purchased support have access to electronic support through My Oracle Support. Forinformation, visit My Oracle Support or visit Accessible Oracle Support if you are hearing impaired.

Comments and SuggestionsPlease give us feedback about Oracle Applications Help and guides! You can send an e-mail to:[email protected].

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

mailto:[email protected]


Chapter 1Overview

1

1 Overview

Overview of Using FormulasFast formulas are generic expressions of calculations or comparisons that you can reuse with dierent input variables.This topic summarizes the usage of each formula that corresponds to one or more formula types, which requiresspecic formula inputs and outputs.

Formulas are translatable. The predened formulas are alphanumeric and can be in any language. Formula text isn'tsubject to translation and can handle non-English user-dened elements, input values, or balances. For example, if youdene an element name in Chinese, the base element name is stored in Chinese. The database Items are generatedusing the data in the base tables, so the generated database item contains the Chinese element name, and you can referto such database items in your formulas.

Note: You can use the Fast Formulas task in the Setup and Maintenance work area of Workforce Deployment,or in work areas relevant to the formula type, such as Payroll Calculation.

Calculate PayrollsYou can write payroll calculations and skip rules for elements to represent earnings and deductions.

You can do these tasks using fast formulas:

• Associate more than one payroll formula with each element to perform dierent processing for employeeassignments with dierent statuses.

• Dene elements and formulas for earnings and deductions with highly complex calculations requiring multiplecalls to the database.

• Associate a skip rule formula with an element to dene the circumstances in which it's processed.

• Modify the predened proration formula to control how payroll runs prorate element entries when theyencounter an event, such as a mid-period change in an element entry value.

Dene Calculations for Benets AdministrationYou can use formulas to structure your benet plans. Formulas provide a exible alternative to the delivered businessrules. Use formulas to congure:

• Date calculations, such as enrollment start and end dates, rate or coverage start and end dates, waiting periodsand enrollment periods, or action item due dates

• Calculations of rate and coverage amount, minimum and maximum, or upper and lower limits

• Certication requirements

• Partial month and proration calculations

• Eligibility and participation evaluation

For example, you can write a formula to calculate benets eligibility for those cases where the provided eligibilitycriterion doesn't accommodate your particular requirements.

Note: For more information, see Benets Fast Formula Reference Guide (1456985.1) on My Oracle Support athps://support.oracle.com.


Chapter 1Overview

2

Validate Element Inputs or User-Dened TablesUse lookups or maximum and minimum values to validate user entries.

For more complex validations you can write a formula to check the entry. You can also use a formula to validate entriesin user tables.

Edit the Rules for Populating Work Relationship or Payroll RelationshipGroupsYou can dene criteria to dynamically populate a payroll relationship group or work relationship group.

When you create a payroll relationship group or work relationship group formula type, you can choose to use anexpression editor or a text editor. The expression editor makes it easy to build criteria to dene the group. For morecomplex conditions, such as validations, you can select the text editor.

Dene Conguration for CompensationHere's what you can modify using formulas and add exibility to existing compensation plan conguration:

• Start and end dates for compensation allocations under individual compensation plans

• Person selection, hierarchy determination, column default values, and currency selection for workforcecompensation plans

• The source of items displayed in total compensation statements

Dene Formulas to Create Rule Templates for Time and LaborUse formulas with time repository rule templates to create rules. The formulas contain delivered combinations ofrule parameters and output results. You can use one formula with multiple rule templates by varying the templateconguration.

When creating a rule template, you select a formula name, and then congure the parameter type and display name ofthe parameters and variables. You don't have to redo the entire formula statement to determine what details to changeto achieve a particular outcome.

Here's what you can use formulas to apply in Time and Labor:

• Logic for processing or calculating time

• Parameters that enable rules to pass values to the formula for use in calculations

• Output variables that the formula uses to return calculation results to the rules

For example, the Period Maximum Hours Template uses the WFM_PERIOD_MAXIMUM_TIME_ENTRY_RULE formula tocompare reported time category hours to dened maximum hours.

Note: For more information, see Time and Labor Fast Formula Reference Guide (1990057.1) on My OracleSupport at hps://support.oracle.com.


Chapter 2Writing Formulas

3

2 Writing Formulas

Overview of Writing FormulasWriting fast formulas enables you to perform a wide variety of tasks using English words and basic mathematicalfunctions. There are several techniques that you can use to ensure your formulas are easy to read, use, and understand.You write fast formulas to validate or calculate data for payroll and other Oracle Fusion applications.

This table lists the key aspects of writing fast formulas.

Key Aspects Description

Using the expression editor Use the expression editor with these formula types:

• Deduction component groups• Deduction component detail groups• Payroll relationship groups• Work relationship groups

Use these formula types when creating dynamic object groups. Object groups dene subsetsof deduction components or people for processing or reporting.

Using formula text Most formula types use the text editor to dene formulas. The text editor is more exible than

the expression editor. Here's what you can do with the text editor:

• Add database items applicable to the formula type• Use functions to manipulate data• Use user-dened global values

Database items are read-only variables that the application uses to nd data. Functionsmanipulate data to return a value. Global values are variables that are referred to often. Globalvalues store information that doesn't change frequently.

Improving performance Here's what you can do to improve performance:

• Limit the number of elements you enter.• Shorten your formulas.• Don't refer to database items until needed.• Use an ALIAS instead of assigning a database item to a local variable.• Use input statements instead of database items.• Review formulas to ensure that they contain code that's required and properly coded.

Avoiding compilation errors Here's what you can do to avoid common compilation errors:

• Look for syntax errors, such as using IF1 instead of IF.• Ensure that the statement order is correct. For example ALIAS, DEFAULT, or INPUT

statements come after other statements.• Don't misuse ASSIGNMENT statements by assigning a value to a database item.



4

Key Aspects Description

• Don't misuse the ALIAS statement. It can only be used for database items.• Don't misuse DEFAULT statements. You must specify a DEFAULT statement for a

variable other than an input or database item.• Look out for missing DEFAULT statements. Database items that have a default value

specied must contain a DEFAULT statement.

Avoiding execution errors Here's what you can do to avoid common execution errors:

• Initialize your variables.• Don't try to divide a numeric value by zero.• Ensure that the formula compiler can nd the data.• Don't make incorrect assumptions about the data that your formula accesses.• Ensure that your formula doesn't return a NULL data value.• Ensure that the value that your formula generates doesn't exceed the permissible range.

Improve Formula PerformanceUse various approaches to ensure that your formulas are easy to read, use, understand, and processed eciently.

Variable Names and AliasesUse concise and meaningful variable names. If the names of database items are long, you can use aliases. The length ofdatabase item name doesn't impact the performance or memory usage of a formula.

Inputs StatementsTip: The best approach is to use INPUTS statements rather than database items whenever possible. You don'thave to access the database for input variables, which in turn speeds up your payroll run.

Here's an example of a formula without the INPUTS statement:

SALARY = SALARY_ANNUAL_SALARY / 12RETURN SALARY

Here's how you can use the INPUTS statement eciently:

INPUTS ARE ANNUAL_SALARYSALARY = ANNUAL_SALARY / 12RETURN SALARY



5

CHANGE_CONTEXTS StatementTip: The best practice approach is to use CHANGE_CONTEXTS statement only when required, becauseCHANGE_CONTEXTS can cause database item values to be fetched again from the database.

You can perform multiple context changes using a single CHANGE_CONTEXTS statement, instead of calling CHANGE_CONTEXTSfrom other CHANGE_CONTEXTS blocks.

For example, use a single CHANGE_CONTEXTS statement in the rst formula, which is ecient than the second formula:

CHANGE_CONTEXTS(EFFECTIVE_DATE = l_eff_date, AREA1= 'California')( /*Do something here*/)

CHANGE_CONTEXTS(EFFECTIVE_DATE = l_eff_date)(CHANGE_CONTEXTS(AREA1 = 'California') ( /*Do something here*/ ))

Don't use the CHANGE_CONTEXTS statement to set contexts that you would reasonably expect to be already set.

For example, the PERSON_ID context is generally already set in a formula that processes person information. If thiscontext isn't set, then GET_CONTEXT doesn't fetch any value. GET_CONTEXT only returns the default value of -1. This codedoesn't achieve anything:

l_person_id = GET_CONTEXT(PERSON_ID, -1)l_effective_date = GET_CONTEXT(EFFECTIVE_DATE, '0001-01-01 00:00:00)(DATE))

CHANGE_CONTEXTS(PERSON_ID = l_person_id, EFFECTIVE_DATE = l_effective_date)( /*Do something here*/)

Database ItemsTip: The best practice approach is to retain only the required database items in a formula. Don't refer todatabase items in a formula unless it's absolutely required. Sometimes a formula might contain databases thatit doesn't need, which causes the formula to make unnecessary database calls. As a result, the eciency of theformula is impacted.

In this example, the use of database items always causes a database fetch for AGE.

S = SALARYA = AGEIF S < 20000 THENIF A < 20 THEN TRAINING_ALLOWANCE = 30ELSE TRAINING_ALLOWANCE = 0

In this example, the use of database items fetches AGE only if salary is less than 20000:



6

IF SALARY < 20000 THENIF AGE < 20 THEN TRAINING_ALLOWANCE = 30ELSE TRAINING_ALLOWANCE = 0

Database Items for HCM ExtractsSome database items are intended only for HCM Extracts reporting. These database items return a high amount of dataand retrieve it ineciently when used in a formula.

For example, an HCM Extracts database item retrieves information for all employees on the application, or completeinformation of a particular employee since the start of employment. This data retrieval is ne for reporting as reportsprocess lots of data. Formulas usually process small amount of data limited to specic cases. HCM Extracts allow extraconditions to be added to limit the data returned, but formulas don't.

With these database items, more complex formulas are required to get the right data and the performanceof the formulas is extremely poor because of the large data volumes. For example, the array databaseitem PER_EXT_ALL_PHONE_AREA_CODE returns all phone area codes as of an eective date. Together withPER_EXT_ALL_PHONE_PERSON_ID, and PER_EXT_ALL_PHONE_TYPE, it's possible to get a person's home phone's area code.

But for a simpler formula and beer performance, you can use the PER_PER_HOME_PHONE_AREA_CODE database item toretrieve the home phone's area code. PER_PER_HOME_PHONE_AREA_CODE uses PERSON_ID and EFFECTIVE_DATE contexts to getits data. PER_EXT_ALL_PHONE_AREA_CODE only uses the EFFECTIVE_DATE context.

While LoopUse an EXIT statement or a change to the loop condition to leave a WHILE loop immediately once you complete your task.For example, don't continue when you have already found a single item that you were looking for.

Formula Compilation ErrorsCompilation errors are displayed in the Fast Formulas page after you compile the formula. The compiler stops thecompilation process when it encounters an error. Error messages display the line number and the type of error.

Common Compilation ErrorsHere's some of the common formula compilation errors.

Formula Compilation Error Description

Syntax Error

The formula text violates the grammatical rules for the formula language. For example, if youuse IF1 instead of IF in an IF statement.

Incorrect Statement Order

ALIAS, DEFAULT, or INPUT statements come after other statements.



7

Formula Compilation Error Description

Misuse of ASSIGNMENT Statement Occurs when any of these conditions exist:

• An ASSIGNMENT assigns a value to a database item.• A context is assigned a value externally to a CHANGE_CONTEXTS statement.• The formula assigns a value to a non-context variable within a CHANGE_CONTEXTS

statement.

You can use CHANGE_CONTEXTS statements in a formula.

Misuse of ALIAS Statement

You can use an ALIAS statement only for a database item.

Missing DEFAULT Statement

A database item that species a default value must have a DEFAULT statement.

Misuse of DEFAULT Statement

You specify a DEFAULT statement for a variable other than as an input or a database item.

Uninitialized Variable

The compiler detects that a variable is uninitialized when used. The compiler can't do this inall cases. This error often occurs when the formula includes a database item that requirescontexts that the formula type doesn't support. The formula treats the database item as alocal variable. For example, balance database items require the PAYROLL_ REL_ACTION_IDPAYROLL_ ASSIGNMENT_ID and CALC_ BREAKDOWN_ ID contexts. Typically, you use thesestatements in formulas of type Oracle Payroll.

Missing Function Call

The compiler doesn't recognize a function call. The combination of return type, function name,and parameter types doesn't match any available function.

Incorrect Operator Usage

An instance of a formula operator use doesn't match the permied uses of that operator. For example, the + operator has two permied uses. The operands are both of data typeNUMBER, or both of data type TEXT.

Inconsistent Data Type Usage

The formula uses a formula variable of more than one data type. Or the formula uses adatabase item or context with the wrong data type. For example, Variable A is assigned a NUMBER value at the start of the formula, but isassigned a TEXT value later in the formula.

EXIT Statement Not Within WHILELoop

A condition that eventually becomes false or an EXIT call for exiting the loop doesn't exist.

Misuse of Context

The formula uses a variable as a context, or a context as a variable. For example, a formula assigns a value to AREA1 as an ordinary variable, but later uses AREA1as a context in a GET_CONTEXT call.



8

Formula Execution ErrorsFast formula execution errors occur when a problem arises while a formula is running. Typically, data-related issuescause these errors either in the formula or in the application database.

Formula Execution ErrorsHere's some of the formula execution errors.

Formula Execution Error Description

Uninitialized Variable

When the formula compiler can't fully determine if a variable or context is initialized, itgenerates a code to test if the variable is initialized. When the formula runs, the code displays an error if the variable or context isn't initialized.

Divide by Zero

Raised when a numeric value is divided by zero.

No Data Found

Raised when a non-array type database item unexpectedly fails to return any data. If thedatabase item can't return data, then it should provide a default value. You can specify a default value using a DEFAULT statement. An error in formula function codecan also cause this error message.

Too Many Rows

Raised when a non-array type database item unexpectedly returns more than a single row ofdata. The cause is an incorrect assumption made about how the data is being accessed. An error in the formula function code can also cause this error message.

NULL Data Found

Raised when a database item unexpectedly returns a NULL data value. If the database item canreturn a NULL value, then it provides a default value.

Note: Some database items can't return a NULL value. If the database items canreturn a NULL value, then you can provide a default value for that database item.

Value Exceeded Allowable Range

Raised for a number of reasons, such as exceeding the maximum allowable length of a string.

Invalid Number

Raised when a formula aempts to convert a nonnumeric string to a number.

User Dened Function Error

Raised from within a formula function. The error message text is provided as part of theformula error message.

External Function Call Error

A formula function returns an error, but doesn't provide any additional information to theformula code. The function may have sent error information to the logging destination for theexecuting code.



9

Formula Execution Error Description

Function Returned NULL Value

A formula function returns a NULL value.

Too Many Iterations

A single WHILE loop, or a combination of WHILE loops has exceeded the maximum number ofpermied iterations. This error is raised to terminate loops that can never end, which indicatesa programming error within the formula.

Array Data Value Not Set

The formula tries to access an array index that has no data value. This error occurs in theformula code.

Invalid Type Parameter forWSA_EXISTS

You specify an invalid data type in the WSA_EXISTS call.

Incorrect Data Type For Stored Item

When retrieving an item using WSA_GET, the actual data type doesn't match that of the storeditem. This error occurs within the calling formula.

Called Formula Not Found

The called formula isn't found when aempting to call a formula from a formula. This errormay occur due to an issue in the calling formula, or because of installation issues.

Recursive Formula Call

An aempt was made to call a formula from itself. The call could be made directly or indirectlyfrom another called formula. Calling a formula in a recursive manner isn't permied.

Input Data Has Dierent Types inCalled and Calling Formulas

When calling a formula from a formula, the input data type within the called formula doesn'tmatch the data type specied in the calling formula.

Output Has Dierent Types In Calledand Calling Formulas

When calling a formula from a formula, the output data type within the called formula doesn'tmatch the data type specied in the calling formula.

Too Many Formula Calls

When a formula calls another formula in its text, resulting in a hierarchy. The maximum depthof the hierarchy is 10.

Example of Writing a Fast Formula Using ExpressionEditorIn this example, you create a fast formula that groups executive workers for reporting and processing. All executiveworkers are in department EXECT_10000. After you create the formula, you need to add it to the object groupparameters, so that only the workers that belong to the EXECT_10000 department are used in processing.

Here are the key decisions when deciding on which formula to create.



10

Key Decisions In This Example

Is the formula for a specic legislative data group?

Yes, InVision

What is the formula type for this formula?

Payroll Relationship Group

Creating a Fast Formula Using the Expression Editor1. On the Payroll Calculation Tasks page, click the Fast Formulas task.2. On the Fast Formula page, click the Create icon.3. On the Create Fast Formula page, complete these elds:

Fields for Fast Formula Values for Fast Formula

Formula Name

Executive Payroll Relationship Group

Type

Payroll Relationship Group

Description

Executive Workers

Legislative Data Group

Vision LDG

Eective As-of Date

1-Jan-2010

Type of Editor

Expression Builder

Note: For more complex conditions to create a group, you can select Text.However, after you save the formula, you can't change the type of editor.

4. Click Continue.5. In the Formula Details section, click Add After to add a row and complete these elds:

Conjunction Database Item Name Data Type Operand Literal Value

None applicable

DEPARTMENT

Character

=

'EXECT_10000'

And

SELECT_EMP

Character

=

'YES'

6. Click Compile.7. Click Save.



11

Example of Writing a Fast Formula Using Formula TextIn this example, you use the text editor to create a fast formula that returns two dierent ranges of scheduled hours:one range for managers, another range for other workers.

Here are the key decisions when deciding on which formula to create:

Key Decisions In This Example

Is the formula for a specic legislative data group?

No, this is a global formula that can be used by any legislative datagroup.

What is the formula type for this formula?

Range of Scheduled Hours

Are there any contexts used in this formula?

No

Are there any database item defaults?

Yes, ASG_JOB

Are there any input value defaults?

No

What are the return values?

MIN_HOURS, MAX_HOURS, FREQUENCY

Creating a Fast Formula Using the Text Editor to Determine aManager's Scheduled Hours

1. In the Setup and Maintenance work area, select these options:Oering: Workforce DeploymentFunctional Area: PayrollTask: Fast Formulas

2. Click Go to Task.3. On the Fast Formula page, click the Create icon.4. On the Create Fast Formula page, complete these elds:

Fields for the Fast Formula Values for the Fast Formula

Formula Name

Manager Range of Scheduled Hours

Formula Type Range of Scheduled Hours



12

Fields for the Fast Formula Values for the Fast Formula

Description

Manager's Range of Hours

Eective Start Date

1-Jan-2010

5. Click Continue.6. Enter these formula details in the Formula Text section:

/* DATABASE ITEM DEFAULTS BEGIN */DEFAULT FOR asg_job IS ' '/* DATABASE ITEM DEFAULTS END */JOB_1 = ASG_JOBIF JOB_1 = 'Manager' then(MIN_HOURS = 25MAX_HOURS = 40FREQUENCY = 'H')else(MIN_HOURS = 20MAX_HOURS = 35FREQUENCY = 'H')return MIN_HOURS, MAX_HOURS, FREQUENCY

7. Click Compile.8. Click Save.

FAQs for Writing Formulas

When do I run the Compile Formula process?When you create or update multiple fast formulas simultaneously, run the Compile Formula process on the Submit aProcess or Report page from the Payroll Administration work area.

What's the dierence between a formula compilation error and anexecution error?Compilation errors occur on the Fast Formulas page when you compile the formula. An error message explains thenature of the error. Common compilation errors are syntax errors resulting from typing mistakes. You can view errormessages on the dashboard or go to the messages tab directly after the process is run.Execution errors occur when a problem arises while a formula is running. Typically, data-related issues either in theformula or in the application database cause these errors.


Chapter 3Formula Components

13

3 Formula Components

Overview of Using Formula ComponentsWhen you're developing a formula, you must understand the formula language, the rules that the application imposeson the formula, and the calculation requirements.

Create formulas using these components:

• Assignment statements

• Return statements

• Variables

• Enter statements

• Expressions

• Conditions

• Comments

Note: Other topics explain additional components that you can use in formulas. These include literals,database items, working storage area, calls to other formulas, functions, and operators.

Let's look at an example to understand how each component is used in a formula. Suppose you want to calculate thepay value for the WAGEelement by multiplying the number of hours an employee works each week by the hourly rate.Here's how you can write the formula in this example:

WAGE = HOURS_WORKED * HOURLY_RATERETURN WAGE

Assignment StatementsAn assignment statement assigns a value to the WAGE element.

Return StatementsA return statement passes the WAGE value back to the payroll run. You can use a return statement to stop the formulaexecution without passing any values.

VariablesVariables are of these classes:

• Input variables appear in INPUTS statements and bring values into a formula.

• Output variables appear in RETURN statements and return values from a formula. A variable can be both aninput and output.

• Local variables are only used within one formula.

You can change a local variable within the formula by assigning a value to it using an assignment statement. Tocalculate the WAGE value, the formula needs to get the value for the HOURS_WORKEDvariable.



14

You can use local variables to store data in a formula. You might want to hold data temporarily while you perform someother calculations, or pass data back to the application. Here's an example of the ANNUAL_LEAVE variable.

/* Formula: Annual Leave Formula */IF YEARS_SERVICE >= 10THENANNUAL_LEAVE = 25ELSEANNUAL_LEAVE = 20 + FLOOR (YEARS_SERVICE/2)RETURN ANNUAL_LEAVE

Input StatementsYou can use HOURS_WORKED as an input value of the WAGE element. To pass the element input values to the formula duringprocessing, dene an input statement like this:

INPUTS ARE HOURS_WORKEDWAGE = HOURS_WORKED * HOURLY_RATERETURN WAGE

Note: This is a payroll application example. The name used in the input statement must be the same as thename of the element input value. Multiple words must be joined by underscores. Other input statements thathave nothing to do with elements would have their own rules for formula input variables. In this example,the HOURS_WORKED input variable is numeric. If the input variable isn't numeric, you must specify the type. Forexample,INPUTS ARE START_DATE (DATE)

ExpressionsEach function or calculation is one expression. You can nest expressions to create more complex calculations. You canuse brackets to control the order in which calculations are done.

The formula evaluates expressions within the brackets rst. Within nested brackets, evaluation proceeds from the leastinclusive set to the most inclusive set. If you don't use brackets, the formula evaluates expression in this order:

• Multiplication

• Division

• Addition

• Subtraction

Expressions combine constants and variables with operators (+, -, *, /), array methods, and functions to return a valueof a certain data type. For example, the expression (3 + 2) returns a value of 5, and is a NUMBER data type. The format ofan expression is:

SUBEXPRESSION [operator SUBEXPRESSION ...]

You can combine a number of sub-expressions into a single expression. For example, you can combine the sub-expressions (3 + 2) and MONTHS_BETWEEN(start_date, end_date) into a single expression as follows:

(3 + 2) + MONTHS_BETWEEN(start_date, end_date)

You can also use expressions inside functions, such as:

salary = GREATEST(minimum_wage, (hourly_rate * hours_worked))



15

Operands in an expression are usually of the same data type, which is the data type of the expression as a whole. Here'san example of an expression in which all the operands are numeric and the expression itself is numeric:

GREATEST(MINIMUM_WAGE, (HOURLY_RATE * HOURS_WORKED)) + BONUS

BONUS is the operand for the above expression. The return value is GREATEST. The arguments for GREATEST are separateexpressions.

ConditionsYou can use conditions to process expressions based on whether a certain condition occurs. For example:

TRAINING_ALLOWANCE = 0 IF (AGE < 20) THENTRAINING_ALLOWANCE = 30

This formula checks if the condition (AGE < 20) is true or false. If it's true, the formula processes the statement thatfollows the word THEN. If the condition is false, the formula ignores this statement.

CommentsUse comments to explain all or part of a formula. Also, you can change some formula lines into comments until they'reready to be used. Comments are designated by the comment delimiters of /* and */. Anything wrien inside thesedelimiters is a comment. You can place comments anywhere within a formula. The beginning of a formula shouldcontain these comments:

• The formula title and a short purpose statement.

• A description of the formula inputs.

• A list of variables and literals that may require updating.

• An explanation of the formula's calculation.

• The dates of any modications, the name of the person modifying the formula, and the reason for the change.

Note: Do not put a comment within a comment, because it causes a syntax error when you compile theformula.

Types of VariablesFormula variables can have values that change frequently. The variable's data type indicates the type of informationthe variable holds. The formula determines how you can use the variable. For example, if you set a variable to 'J. Smith',the formula interprets it as a TEXT variable. The application displays a warning if you try to perform any inconsistentoperations, such as trying to add a number to a text string.

Variables are of these types:

• Input variables appear in INPUTS statements and bring values into a formula.

• Output variables appear in RETURN statements and return values from a formula. A variable can be both aninput and output.

• Local variables are only used within one formula.

You can change variable values by using an assignment statement and by referencing them within expressions.However, if you reference a variable to which you didn't assign a value, the formula returns an error.



16

Formula StatementsYou use formula statements to provide instructions that you want your formula to carry out. When working withstatements, it's important to have knowledge of the dierent statement types, the required order, and how to groupstatements.

Statement TypesHere are the statements that you can use in your formulas to provide instructions.

Statement Statement Form Description and Example

ALIAS

ALIAS name1 AS name2

Provides a dierent name for a databaseitem or global value. Sometimes thedatabase item names that the applicationprovides are too long to use in a formula. Use the ALIAS statement to shorten thename of a database item. Once the ALIASis created, use it instead of the databaseitem name. Using an alias is more ecientthan assigning the database item to a localvariable with a short name.

ASSIGNMENT

variable = expression array[index] = expression

Assigns an expression value to a variableor an array variable at an index position.A formula evaluates the expression onthe right-hand side of the statement. Itplaces its result in the variable you nameon the left-hand side. The left side of anassignment statement must always be alocal variable because a formula can onlychange the value of local variables. Within a CHANGE_ CONTEXTS statement,assign values only to contexts. Outside aCHANGE_ CONTEXTS statement, assignvalues only to input, output, and localvariables.

CHANGE_ CONTEXTS

(context1 = expression1 [,context2 =expression2 ]

Changes one or more contexts within aformula. Within the CHANGE_ CONTEXTSstatement, use ASSIGNMENT statementsto assign the new values.

DEFAULT

DEFAULT FOR variable IS literal DEFAULT_ DATA_VALUE FOR variable ISliteral

The DEFAULT FOR statement provides avalue that the formula uses for a formulainput or database item in these situations:

• The input doesn't provide a value.• The database item isn't found



17


• The value of a non-array databaseitem is NULL

The DEFAULT_DATA_VALUE FORstatement provides a value for an arraydatabase item where individual datavalues are NULL.

Some database items are dened torequire a default value because they couldreturn no data or NULL values from thedatabase.

DEFAULT FOR HOURLY_RATE IS 3.00INPUTS ARE HOURLY_RATEX = HOURS_WORKED * HOURLY_RATE

EXIT

EXIT

Immediately exits from the enclosingWHILE loop. You can't use the EXITstatement outside of a WHILE loop.

FORMULA CALLING

t_ INSET_ INPUT(input[value]) EXECUTE(formula) The formula RATE_FORMULA is calledto get a value for HOURLY_RATE.RATE_FORMULA.

Calls a formula from another formula. For example, formulas can call a smallformula that performs a commoncalculation. You can use this approach toavoid writing long formulas.

IF

IF condition THEN statements IF condition THEN statements ELSEstatements

Executes one or more statements ifa condition is true. Use the IF ELSEstatement to specify a set of statements toexecute if the condition is false.

INPUT

INPUTS ARE input1 [,input2]

Lists the input variables for the formula.There's only one INPUT statement in aformula .

RETURN

RETURN [ output1 ] [,output2]

Causes a formula to stop executingimmediately. For its value to be returnedto the caller, you must enter a formulaoutput variable in the RETURN statementthat stopped the formula. You can enter multiple return statementsin a formula.

WHILE

WHILE condition LOOP statements In this example, 'A' is an array variablewith a numeric index.

Executes a number of statements as longas one condition is true. If the WHILE statement loop performs toomany iterations, an error occurs to preventendless looping.



18


WORKING STORAGE

WSA_ DELETE([item]) - Deletes valuesfrom the storage area. WSA_ EXISTS(item[type]) - Determine ifan item exists . WSA_GET(item, value) - Fetches valuesfrom the storage area. WSA_SET(item, value) - Sets values fromthe storage area. In the example, a number of rates are setup.

Stores reference data, which you can set,fetch, or delete.

Ordering StatementsPlace the statements in this order in the formulas:

1. ALIAS statements, if any2. DEFAULT statements, if any3. INPUT statements, if any4. Other statements

Grouping StatementsIf you want to group more than one statement under IF/THEN statements, ELSE clauses, WHILE loops, orCHANGE_CONTEXTS, enclose the group of statements within brackets. In the absence of brackets, the precedingstatement applies only to the rst statement.

Here's an example of how you can group statements:

I = A.FIRSTWHILE (A.EXISTS(I)) LOOP( A[I] = I I = A.NEXT(I,-1))

Here's an example of how you should not group statements::

I = A.FIRSTWHILE (A.EXISTS(I)) LOOP A[I] = I I = A.NEXT(I,-1) /* This is not executed as part of the loop. */



19

Naming Schemes for VariablesYou can use naming schemes for variables when adding them to formulas; however, you must avoid using reservedwords as variable names.

Naming SchemesYou can use one of these naming schemes:

• Variable names comprise one or more words, joined by underscores. The words must each start with a leerand can be followed by a combination of leers and digits.

• Variable names begin and end with double quotes (''). Between the quotes, you can use any printablecharacters, such as ''This is a quoted variable name,'' and any word consisting of only digits could be mistakenfor numbers.

Formulas aren't case sensitive. For example, the variable named EMPLOYEE_NAME is the same as the variableemployee_name.

Tip: The maximum length of a variable name is 255 characters.

Reserved WordsEnsure that you don't use these reserved words as variable names:

Source of Reserved Words Reserved Words

Statements ALIAS

ANDAREASCHANGE_CONTEXTSDEFAULTDEFAULT_DATA_VALUEDEFAULTEDELSEEXITFORIFINPUTSISLIKELOOPNEED_CONTEXTNOTORRETURNTHENUSINGWASWHILE

Array TypesEMPTY_DATE_NUMBER



20

Source of Reserved Words Reserved Words

EMPTY_NUMBER_NUMBEREMPTY_TEXT_NUMBEREMPTY_DATE_TEXTEMPTY_NUMBER_TEXTEMPTY_TEXT_TEXT

Formula Data Types DATE

DATE_NUMBERDATE_TEXTNUMBERNUMBER_NUMBERNUMBER_TEXTTEXTTEXT_NUMBERTEXT_TEXT

Array Methods COUNT

DELETEEXISTSFIRSTLASTNEXTPREVIOUSPRIOR

Built-in Calls CONTEXT_IS_SET

EXECUTEGET_CONTEXTGET_OUTPUTIS_EXECUTABLESET_INPUTWSA_DELETEWSA_EXISTSWSA_GETWSA_SET

Database ItemsDatabase items exist in the application database and have a computer code associated with them. The applicationuses this code to nd data. All database items are read-only variables. You can't change database item values within aformula. If you try to write a value to a database item, you receive a compilation error.

You can use database items in formulas and HCM extracts.

Database items are of these types:

• Static

• Dynamic

• Array



21

Static Database ItemsStatic database items are predened. They include generic information about an employee, such as sex, birth date, andwork location. They also include data about other objects, such as the start and end dates of a payroll period.

Dynamic Database ItemsThe application creates dynamic database items when you create these objects. In the case of exelds, you must runthe Generate Flexeld Database Items process to create the database items.

Object Description

Elements

The element name is the database item name prex.

Balances

The balance name followed by the balance dimension name is the database item name.

Formula global values

The global value name is the database item name.

Input values

The element and input value names are the database item name prex.

Flexelds

The Generate Flexeld Database Items process creates database items for the contexts andsegments of your registered HCM exelds.

Array Database ItemsArray database items have an index type of NUMBER with indexes that start at 1 and increment by 1 without gaps.Here's an example:

/* 1 is the starting index for an array database item. */I = 1WHILE DBI.EXISTS(I) LOOP( V = DBI[I] /* Do some processing with element at index I. */ I = I + 1 /* Array database items indexes go up in steps of 1. */)

You can use the DEFAULT_DATA_VALUE FOR statement to set a default value in scenarios where an array databaseitem returns a NULL value for an element. There can be only one DEFAULT_DATA_VALUE FOR statement for eacharray database item and it must appear at the start of the formula.

Here's an example of a DEFAULT_DATA_VALUE FOR statement:

DEFAULT_DATA_VALUE FOR A IS 0INPUTS ARE B, C

Here's an example of an array database item usage error:

/* Array database item A. */A[1] = 1 A = B



22

A.DELETE(1)A.DELETE

Overview of Generating Flexeld Database ItemsYou congure registered HCM exelds to add contexts and segments for your business requirements. After youdeploy the exeld, you can generate database items for the exeld for use in your formulas and extracts bysubmiing the Generate Flexeld Database Items process from the Payroll Checklist or Payroll Administration workareas.

You can generate database items for the following exelds:

• Descriptive exelds

• Extensible exelds for single and multiple row routes

• Key exelds

The process generates database items at the enterprise level only. As a best practice, when you submit the process, skipthe legislative data group parameter so that the process generates database items for use by any legislative data group.

You can determine which database items to generate by specifying or skipping the exeld and context parameters asshown in the following table.

Flexeld Parameter Context Parameter Result

Specify parameter

Skip parameter

Generate database items for all thecontexts and related segments for aspecied exeld

Skip parameter

Skip parameter

Generate database items for all registeredexelds and their contexts.

The process creates database item names with this following structure:

de<FLEXFIELD_CODE><CONTEXT_CODE><SEGMENT_CODE>

When you include the database item in a formula or extract, the application returns a value for the database item, basedon the exeld context, for the segments column in the underlying exeld table. After you generate database items,compile any formulas using these database items.

Periodically, you may need to update a exeld structure, for example to add a segment to capture additional data. Ifyou previously generated database items for a exeld, submiing the process deletes and regenerates the associateddatabase items. After the process regenerates the database items, be sure to compile any formulas using them.

Related Topics

• Overview of Flexelds

• Extract Components

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=96E89901A4049BF4E040D30A68811939

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=C11A5F07B0B768E7E040D30A688110C8



23

Example of Generating Flexeld Database ItemsThis example demonstrates how to add segments and contexts to a registered HCM exeld, and how to generatedatabase items for the exeld for later use in formulas and extracts.

The following table summarizes the key decisions for this scenario.

Decisions to Consider In this Example

Which registered HCM exeld requires database items?

Organization Information exeld

What is the name of the exeld code?

PER_ ORGANIZATION_ INFORMATION_ EFF

How many contexts include segments that require databaseitems?

Two contexts: HCM_ CN_ PSU_ TERMINATION_ INFO HRX_ CN_TRU_ TERMINATION_ INFO

Should I give all legislative data groups access to the generateddatabase items for use in their formulas and extracts?

Yes

In this example, Joe plans to create formulas for an implementation in China based on information captured in theorganization information exeld. Joe congures the exeld to add the contexts and segments. He writes a formula tocalculate severance pay that returns results for the leave compensation factor based on the tax reporting unit.

Congure the Flexeld1. In the Setup and Maintenance work area, go to the following:

◦ Oering: Workforce Deployment

◦ Functional Area: Organization Structures

◦ Task: Manage Extensible Flexelds

2. Search for the Organization Information EFF and click Edit.3. Click Manage Contexts.4. Click Create and create two contexts: HCM_CN_TRU_TERMINATION_INFO and

HRX_CN_PSU_TERMINATION_INFO.5. For each context, create two segments: LEAVE_COMPENSATION_FACTOR and

MONTHLY_SALARY_PAID_DAYS.6. Deploy the exeld.

Submit the Generate Flexeld Database Process1. In the Payroll Checklists or Payroll Administration work area, select the Submit a Process or Report task.2. Complete the following parameters.



24

This table lists which parameters you can skip and those that you can complete, and where the parameter isdisplayed.

Page Parameter Data

Select Flow Paern

Legislative Data Group

Skip this parameter

Select Flow Paern

Process or Report

Generate Flexeld Database Items

Enter Parameters

Payroll Flow

Organization exeld database items

Enter Parameters

Name

PER_ ORGANIZATION_ INFORMATION_EFF

Enter Parameters

Context

Skip this eld to generate database itemsfor all contexts.

3. Click Next and skip the Enter Interaction page.4. Click Next and skip the Schedule page.5. Click Next and review the submied parameters on the Review page.6. Click Submit to create the payroll ow.

The submied process creates database items for each context for the exeld segments:

◦ PER_ORGANIZATION_INFORMATION_HRX_CN_TRU_TERMINATION_LEAVE_COMPENSATION_FACTOR

◦ PER_ORGANIZATION_INFORMATION_HRX_CN_TRU_TERMINATION_MONTHLY_SALARY_PAID_DAYS

◦ PER_ORGANIZATION_INFORMATION_HRX_CN_PSU_TERMINATION_LEAVE_COMPENSATION_FACTOR

◦ PER_ORGANIZATION_INFORMATION_HRX_CN_PSU_TERMINATION_MONTHLY_SALARY_PAID_DAYS

Create a Formula1. Create a formula for calculating severance pay that returns a segment for LEAVE_COMPENSATION_FACTOR, if

the context code is the one specied for the database item, HRX_CN_TRU_TERMINATION_INFO.

Formula OperatorsFormula operators are expressions that can contain arithmetic operators. These operators determine how the formulamanipulates variables and literals. For example, the plus operator (+) indicates that two items are added together. Youcan also use operators to concatenate strings.

Types of OperatorsHere's a list of the operator types:



25

Operator Description Example

+

Addition

A = B + 1

+ | |

String concatenation

A = 'Hello ' + 'World' B = 'Hello ' || 'World'

-

Subtraction

A = B - 1

-

Unary minus

A = -B

*

Multiplication

A = B * C

/

Division

A = B / C

Using OperatorsYou can use the arithmetic operators, subtraction, multiplication, and division only with numeric operands. You canuse the addition operator with numeric or text operands. The operands can be variables, literals, or sub-expressions. Aformula error occurs in these scenarios:

• The second operand of a division equals zero

• The result of multiplication is too large

Whether a number is too large or not is determined by the normal limits in the database. For stringconcatenation, if the result is longer than 255 characters, a formula error occurs.

Expressions are evaluated in order from left to right. The unary minus has precedence over the other operators becauseit applies directly to a single sub-expression. The multiplication and division operators take precedence over additionand subtraction. For example, the expression 1 + 2 * 3 evaluates to 7 rather than 9. You can use brackets to change theprecedence of the operators. For example, (1 + 2) * 3 evaluates to 9.

LiteralsA literal is a piece of information that you manipulate or use in a formula.

Literals are of these types:

• Numeric

• Text

• Date

• Array



26

Numeric LiteralsFollow these rules when entering numeric literals:

• Don't use quotes to enclose the literal.

• Don't use commas or spaces in the number.

• Don't use exponents and oating point scientic notations.

• You can enter numbers that have a decimal component after a decimal point.

• To enter a negative number, precede it with a minus sign (-).

Here are a few examples of numeric literals:

• 63

• 3.55

• -2.3

• -.033

• -.2

• 10000

Text LiteralsWhen you enter text literals, enclose them in single quotes. Text literals can contain spaces. To enter a single quotecharacter in a text constant, enter two single quotes (for example, 'P O'Donnell'). Note that this isn't the same as thedouble quotes ('').

Here are a few examples of text literals:

• 'J. Smith'

• '1234'

• 'Manager'

• '12 Union Road'

• 'The Bonus this year is 23%'

Date LiteralsWhen you enter a date literal, enclose dates in single quotes and follow immediately with the word date in brackets.

Here are a few examples of date literals:

• '2010-11-04T00:00:00.000Z' (DATE)

• '1989-03-12 00:00:00' (DATE)

• '12-MAR-1989' (DATE)

Array LiteralsAn array holds multiple values that the formula can access using the corresponding index values. You dene arrayliterals only for an empty array of each type.



27

Array literals are of these types:

• Array of date values indexed by a numeric index (EMPTY_DATE_NUMBER)

• Array of number values indexed by a numeric index (EMPTY_NUMBER_NUMBER)

• Array of text values indexed by a numeric index (EMPTY_TEXT_NUMBER)

• Array of date values indexed by a text index (EMPTY_DATE_TEXT)

• Array of numeric values indexed by a text index (EMPTY_NUMBER_TEXT)

• Array of text values indexed by a text index (EMPTY_TEXT_TEXT)

How Formulas Determine Variable Data TypesVariables can be of these data types: numeric, text or date. The data type determines the type of information thevariable holds. You don't have to specify the variable type. Formulas determine the type based on how you use thevariable. For example, if you set a variable to 'J. Smith', the formula interprets it as a text variable.

Caution: Inconsistent or incorrect use of variables, such as trying to add a number to a text string, causesformula compilation errors.

Determine Variable Data TypesFormulas process the rules that determine the variable data type in the order listed:

1. The variable can be an input you name in the input statement. For example:

INPUTS ARE SALARY_AMOUNT,START_DATE (DATE),FREQUENCY (TEXT)

If you don't specify the variable data type in the statement, the formula assumes it's a number.

You can use the DEFAULT_FOR statement to determine the variable data type:

DEFAULT FOR B IS 0 /* B is a NUMBER variable. */

In the case of array database items, you can use the DEFAULT_DATA_VALUE FOR statement to determine theindex type and the value type:

DEFAULT_DATA_VALUE FOR A IS EMPTY_NUMBER_NUMBER /* A is a NUMBER_NUMBER array variable. */

You can use the DEFAULT_DATA_VALUE FOR statement to determine the variable data type:

DEFAULT_DATA_VALUE FOR A IS EMPTY_NUMBER_NUMBER /* A is a NUMBER_NUMBER array variable. */

In the case of array database items, you can use the DEFAULT FOR statement to determine the variable type:

DEFAULT FOR B IS 0 /* B is a NUMBER variable. */

2. The formula searches the list of database items. If the variable is in the list, the data type is known.



28

3. If the variable appears in a context handling statement, then the formula searches the list of contexts. If thevariable is in the list, then the formula knows the data type, otherwise it returns an error.

4. If the variable isn't a database item or a context, then the formula treats it as a local variable and determines thedata type based on how you use the variable. For example:

A = 'abc' /* A is a TEXT variable. */

Array VariablesYou can use arrays for input, output, and local formula variables. These array variables can store date, number, or textvalues. Arrays are similar to PL/SQL index-by tables.

Caution: The size of arrays and the extent of their usage directly impacts memory consumption. If the size ofan array is large or if the array is used extensively, the memory consumption will be high.

Array IndexesHere are some aspects of array indexes that you should be aware of:

• The index types are either text or number.

• Text indexes are upper case unique.

• Gaps in index value sequences are permied.

• Number indexes are truncated to remove any fractional part.

• You may iterate an array in an index either forwards or backward.

Array Data TypesYou specify array types as DATA_TYPE_INDEX_TYPE. Arrays are of these data types:

• NUMBER_NUMBER

• NUMBER_TEXT

• DATE_NUMBER

• DATE_TEXT

• TEXT_NUMBER

• TEXT_TEXT

Rules for Using ArraysFormula functions can't return arrays or take array parameters. Contexts can't be array types. If you try to reference anarray value at a nonexistent index, the application returns a formula execution error. However, you can delete an arrayvalue at a nonexistent index.

Array MethodsArray methods enable you to get the rst and last indexes, and to get the next or prior index. These methods return theindex data type. You can specify a default value for these methods, if the required indexes don't exist. You can use arraymethods to determine whether an index exists or not.



29

Note: The array method syntax doesn't work directly with the array literal values. For example, you can't use aconstruct such as EMPTY_DATE_NUMBER.COUNT.

Here's a list of the array methods, including their descriptions and usage examples:

Array Method Description Usage Example

<name> [ <index value> ]

Get the value for an index.

V = A[1]

<name> . FIRST( <default value> )

Get the rst index for an array. The defaultvalue is returned if the array is empty.

I = A.FIRST(-1)

<name> . LAST( <default value> )

Get the last index for an array.

L = B.LAST(' ')

<name> . EXISTS( <index value> )

Conditional checking if a value exists at anindex. The default value is returned if thearray is empty.

IF A.EXISTS(1) THEN

<name> . NEXT( <index value> , <defaultindex value> )

Get the next index given an index position.The default value is returned if there is nonext index.

N = A.NEXT(1)

<name> . PRIOR( <index value> , <defaultindex value> )

Get the prior index given the indexposition. The default value is returned ifthere is no prior index.

P = B. PRIOR('Two')

<name> , COUNT

Numeric method to count the arrayelements.

C = A.COUNT

<name , DELETE( <index value> )

Delete the element at an index position.

B. DELETE('three')

<name> , DELETE()

Delete all elements.

B.DELETE()

Iterating Through an ArrayIn this example, A is an array variable with a NUMBER index. -1234 is known to be an invalid index for A, so it's used as adefault value when the FIRST and NEXT calls can't nd an index.

/* -1234 is not a valid index for A in this instance, so use as default. */NI = A.FIRST(-1234)WHILE A.EXISTS(NI) LOOP( VA = A[NI] /* Do some processing with element at index NI. */ NI = A.NEXT(NI,-1234) /* Go to next index. */)

In this example, B is an array variable with a TEXT index. -1234 is known to be an invalid index for B, so it's used as adefault value when the FIRST and NEXT calls can't nd an index.



30

/* 'No Index' is not a valid index for A in this instance, so use as default. */TI = B.FIRST('No Index')WHILE B.EXISTS(TI) LOOP( VB = B[TI] /* Do some processing with element at index TI. */ TI = B.NEXT(TI, 'No Index') /* Go to next index. */)The following example iterates backwards from through an array C with a NUMBER inde./* -1234 is not a valid index for C in this instance, so use as default. */NI = C.LAST(-1234)WHILE C.EXISTS(NI) LOOP( VC = C[NI] /* Do some processing with element at index NI. */ NI = C.PRIOR(NI,-1234) /* Go to prior index. */

Formula ContextsFormulas run within an application-specic execution context, which determines the context variables that are availableto the formula. Context values act as SQL bind values when the formula fetches database item values from thedatabase. Formulas can also pass context values into formula function calls.

Here are some examples of the execution contexts:

• EFFECTIVE_DATE : The date on which the formula becomes eective.

• PAYROLL_ID: The payroll run for which the formula is processed.

• PERSON_ID: The person for whom the formula is processed.

Context Value SeingThe application code that's calling a formula usually sets all the context values. For some complex applications, such asthe payroll run, the code sets only the contexts necessary to meet general processing requirements.

Here's how formulas for payroll work:

• A payroll run sets contexts for the legislative data group, date earned, the payroll being processed, the payrollrelationship, payroll actions, and the person being processed.

• Additional, country-specic contexts are also available. For example, the jurisdiction area and tax code contextvalues are country-specic.

Formula Context-Handling StatementsIf you use a variable in a context-handling statement, the formula searches the list of contexts. The variable mustappear in the contexts list; otherwise the formula returns an error. The data type is stored along with the context listentry.

This table describes the formula context-handling statements.

Statement Purpose of the Statement Example

CHANGE_ CONTEXTS(assignment [. ..])

Changes context values within the contextchanging block. Inside this block, theformula function calls, the database items,

/*



31

Statement Purpose of the Statement Example

and the called formulas use the newcontext values. Outside the block, theformula uses the original values. You can nest context changing blocks toapply context changes in stages.

* Nested Context changes: DBI1 depends upon SOURCE_ID and SOURCE_TEXT. */CHANGE_CONTEXTS(SOURCE_TEXT = 'A')( /* SOURCE_TEXT = 'A' */ X = DBI1 /* Nesting used to change Contexts in stages. */ CHANGE_CONTEXT(SOURCE_ID = 2) ( /* SOURCE_TEXT = 'A',SOURCE_ID = 2 */ Y = DBI1 /* Overriding a Context change. */ CHANGE_CONTEXTS(SOURCE_TEXT = 'B',SOURCE_ID = 3) ( /* SOURCE_TEXT = 'B', SOURCE_ID = 3 */ Z = DBI1 ))

CONTEXT_ IS_ SET(context)

Tests whether or not a context value is set.

This code tests whether or not the AREA3context is set.

GET_ CONTEXT(context default value)

Returns a context's value if the context isset, otherwise it returns the default valuespecied in its second argument.

/* AREA1 is a context of type TEXT. */AREA1_VALUE = GET_CONTEXT(AREA1,' ')

Overview of Working Storage AreaThe working storage area is a mechanism for storing global values across formulas. Using the dierent call methods,you can test whether or not an item exists in the storage area, delete an item, set the value for an item, and get a valuefor an item. You can access the values by name. The names are case-independent.

This table lists the working storage area methods.

Method Description

WSA_ EXISTS(item [, type]) Tests whether or not the item called item exists in the storage area. If type is specied, then

the item must be of the same type. These are the valid values for type:

• DATE• DATE_NUMBER



32

Method Description

• DATE_TEXT• NUMBER• NUMBER_NUMBER• NUMBER_TEXT• TEXT• TEXT_NUMBER,• TEXT_TEXT

WSA_ DELETE([item])

Deletes the item called item. If you don't specify a name, then all the storage area data isdeleted.

WSA_SET(item, value)

Sets the value for the item called item. Any existing item of the same name is overwrien.

WSA_GET(item, default-value)

Retrieves a value for the item called item. If there is no item called item, then the methodreturns the default value. The data type of default-value is the expected data type for item.

Overview of Calling a Formula from a FormulaA formula call another formula. This enables some modularity in formula organization. You specify the called formulaname and any formula input or output names as TEXT values. The names are case-independent.

You can call a formula in any of these ways:

• Using a single call

• Using separate calls

As you write your formula, consider these points:

• Validation of the Called Formula

• Passing Contexts

• Call a Formula using any of these methods:

◦ Using Separate Calls

◦ Using a Single Self-Contained Call

• Use Cases to Compare Methods

Validation of the Called FormulaWhen a formula runs, it validates whether the called formula can be run, and whether the specied input and outputdata types are correct. You can use the IS_EXECUTABLE call to determine whether an executable formula with a speciedname exists. You must compile the formula to make it available for the specied legislative data group. Also, theformula must be valid on the eective date on which the calling formula runs. In addition, the payroll code imposesextra restrictions based on formula type combinations.



33

Passing ContextsContext values are inherited from the calling formula. You can also set or unset the context values explicitly in thenested formula call.

Alternative Methods to Call a FormulaYou can call a formula fro within another formula in any of these ways:

• Using a series of separate calls

• Using a single self-contained call

Using Separate CallsYou can use three separate calls:

1. Set the Inputs

Use the SET_INPUT call for each formula input and context that you need to explicitly set for the formula call. Youdon't need to specify all formula inputs and contexts. To explicitly unset a context value, use the SET_INPUT callwithout passing the optional value parameter. Any extra inputs specied in SET_INPUT calls are ignored.

2. Call the Formula

Use the EXECUTE call to call a formula.3. Get the Formula Outputs

Use one or more GET_OUTPUT calls to fetch outputs from the last formula call.

When the formula runs, it returns an execution error in these scenarios:

• The called formula isn't executable.

• The called formula is already running.

• The data type of an input variable (specied using SET_INPUT) or an output variable (specied usingGET_OUTPUT) doesn't match its actual data type within the called formula.

This table summarizes the methods for calling a formula using separate calls.

Method Use To

SET_ INPUT(input [,value])

Sets the value of the input to the value specied in the value parameter. The value parameteris optional. If you specify the value parameter, the input is set to this value. If you don't specifythe value parameter, the input is passed as unset to the formula. The data type of the value isthe expected data type for the input.

EXECUTE(formula)

Executes the called formula.

GET_ OUTPUT(output default-value)

Gets the value of the output parameter after calling a formula. If there is no formula outputcalled 'output' or it's not set, the formula returns the value specied in the default valueparameter. The data type of default value is the expected data type for the output.



34

Note: Formula inputs that are set using SET_INPUT persist as long as no EXECUTE or GET_OUTPUT calls are made.Output values from a called formula persist as long as no SET_INPUT or new EXECUTE calls are made. When thecalling formula exits, the process removes any saved input or output values.

Using a Single Self-Contained CallHere's what a single self-contained call does:

• Clears the input values at the start to not use prior SET_INPUT call values.

• Discards the outputs at the end so that the subsequent GET_OUTPUT calls only return the default values.

Here's how you can use the CALL_FORMULA method:

CALL_FORMULA(formula, [set statement, get statement])

A SET statement is a SET_INPUT call. A GET statement assigns the result of a GET_OUTPUT call to a variable in the callingformula. The calls execute in this order:

1. SET_INPUT calls2. EXECUTE call3. GET_OUTPUT assignments

The compiler generates code to execute in this order, even if SET and GET statements are interspersed.

Examples of Calling a Formula from a FormulaUse these examples to understand how to call a formula from another formula using these methods:

• A series of separate calls

• A single self-contained call

The examples include two versions of a wage formula, and a table comparing the two methods using a few use cases.

The rst two examples show dierent versions of the wage formula. These points apply to both examples:

• The formula calls RATE_FORMULA to get a value for HOURLY_RATE.

• The RATE_FORMULA enters text to call UNIT.

• The formula call sets to enter the UNIT to 'Hourly'.

• The RATE_FORMULA returns the rate in the output variable called RATE.

• The GET_OUTPUT call returns 0.00 if the RATE_FORMULA doesn't return RATE.

Wage Formula Using Separate CallsThis example shows how to call a formula using separate calls.

SET_INPUT('UNIT', 'Hourly')EXECUTE('RATE_FORMULA')HOURLY_RATE = GET_OUTPUT('RATE',0.0)WAGE = HOURS_WORKED * HOURLY_RATERETURN WAGE



35

Wage Formula Using a Self-Contained CallThis example shows how to call a formula using a self-contained call.

CALL_FORMULA ('RATE_FORMULA','Hourly' > 'UNIT' /* SET_INPUT('UNIT', 'Hourly') */,HOURLY_RATE < 'RATE' DEFAULT 0.0 /* HOURLY_RATE = GET_OUTPUT('RATE',0.0) */)WAGE = HOURS_WORKED * HOURLY_RATERETURN RATE

Sample Expressions to Compare MethodsHere's what you can do using sample expressions in the two methods:

• Call a formula

• Set inputs and context values

• Unset context values

• Get output values into a variable or array variable

• Provide a default output value

Note: SET_INPUT or > statements have no eect if the calling formula has no formula input or context of thesame name.

This table shows a few use cases that compare the two methods using sample expressions.

Use Case Using Separate Calls Using a Self-Contained Call

Execute a formula where the formulaGET_RATES is executed

EXECUTE('GET_RATES')Use within a CALL_FORMULA statement

Set an input value in the called formulawhere you round o EXTRA_HOURSto 2 decimal places and set the inputOVERTIME in the called formula. The called formula must contain thisstatement:

SET_INPUT('OVERTIME',ROUNDUP(EXTRA_HOURS,2))

Use within a CALL_FORMULA statement

Leave a formula input value unset insidethe called formula, where RATE isn't aformula context.

A SET_INPUTS statement isn't required,but you can this:

A SET statement isn't required, but youcan use this:

Inherit a context value from the calledformula.

No statements are required to do this.

No statements are required to do this.



36

Use Case Using Separate Calls Using a Self-Contained Call

For example, both the calling formulaand the called formula support the AREA1context. The called formula inherits theAREA1 context value from the callingformula.

Set a context value inside a called formula,where the called formula supports theAREA1 context and you must set AREA1 to'London' in the called formula.

SET_INPUT('AREA1','London')

'London' > 'AREA1'

Call a formula with an unset context value,where the called formula supports theAREA1 context and AREA1 has to be unsetin the called formula.

SET_INPUT('AREA1') > 'AREA1'

Get a formula output from the calledformula. Get BONUS_RATE output value into theRATE variable using the default value 0.0if the BONUS_RATE output doesn't existor wasn't set.

RATE = GET_OUTPUT('BONUS_RATE',0.0)

RATE <'BONUS_RATE' DEFAULT 0.0

Get a formula output from a calledformula into an array Get the BONUS_RATE output value intothe RATES array variable at index position'BONUS'. Use the default value 0.0 if theBONUS_ RATE output doesn't exist orwasn't set.

RATES['BONUS'] = GET_OUTPUT('BONUS_RATE',0.0)

RATES['BONUS'] <'BONUS_RATE' DEFAULT 0.0


Chapter 4Formula Functions

37

4 Formula Functions

Overview of Formula FunctionsFunctions manipulate data in dierent ways and always return a value. Functions are of these data types: date, number,and text. A function is identied by its name, return data type, data types, and usage behavior.

Here's how the general form of a function looks like:

NAME-OF-FUNCTION(operand,operand,...)

Operands can be optional or mandatory. You can use operands any number of times in a statement; for example,with the GREATEST function. The formula compiler resolves functions by matching function calls against functionspecications. You can use multiple functions with the same name within a formula , provided that they have dierentreturn or data types.

Some functions return values that are useful in specic formula types, such as absence management, benets, orcompensation. The more generic functions fall into these categories:

Category Purpose of Functions

Text

Manipulate text data

Number

Manipulate numeric data

Date

Manipulate dates

Data Conversion

Convert data to a dierent data type

Message Handling

Return messages

Text Formula FunctionsHere are the formula functions that you can use to manipulate text data:

CHR(n)Returns the character having the binary equivalent to a number operand n in the ASCII character set.

GREATEST(expr, expr [,expr]....)Compares the values of all the text string operands. It returns the value of the last string in alphabetic order.



38

INITCAP(expr)Returns the expression expr with the rst leer of each word in uppercase. Delimits the words or characters that aren'talphanumeric by a white space.

INSTR(expr1, expr2 [,n [,m]])Searches expr1 beginning with its nth character for the mth occurrence of expr2 and returns the character position inexpr1 for the rst character of this occurrence. If n is negative, INSTR counts and searches backward from the end ofexpr1. The value of m must be positive. The default values of both n and m are 1, meaning INSTR begins searching at therst character of expr1 for the rst occurrence of expr2. The return value is relative to the beginning of expr1, regardlessof the value of n, and is expressed in characters. If the search is unsuccessful (expr1 doesn't appear m times after the nthcharacter of expr1), the return value is 0.

INSTRB(expr1, expr2 [,n [,m]])Works in the same way as INSTR, except that n and the return values are expressed in bytes, rather than in characters.For a single-byte character set, INSTRB is equivalent to INSTR.

LEAST(expr, expr [,expr]...)Compares the values of all the text string operands. Returns the rst string in alphabetic order from among itsoperands.

LENGTH(expr)Returns the number of characters in the text string operand expr.

LENGTHB(expr)Returns the length of expr in units of bytes.

LOWER(expr)Converts a text string to lowercase.

LPAD(expr, n [,pad])Returns the text string operand expr left-padded to length n with the sequence of characters in pad. The default value forpad is a blank. If expr is longer than n, then LPAD returns the portion of expr that ts in n.

These are a few examples of this expression:

/* A is set to 'XYXYXhello' */A = LPAD ('hello, 10, 'XY')/* A is set to 'hell' */A = LPAD ('hello', 4 )

LTRIM(expr [,set])Returns the text string operand expr with all the left-most characters that appear in set removed. The default for set is ablank. If none of the left-most characters of expr appear in set, then LTRIM returns expr.

Examples:

/* A is set to 'def' */A = LTRIM ('abcdef','abc')



39

/* A is set to 'abcdef' */A = LTRIM ('abcdef','bc')

REPLACE(expr, search [,replacement])Returns the text string operand expr with every occurrence of search replaced with replacement. If you omit replacement,it removes all occurrences of search. Use REPLACE to substitute one string for another or to remove character strings.

Example:

/* Set A to 'BLACK and BLUE'. */A = REPLACE('JACK and JUE', 'J', BL')

RPAD(expr, n [,pad])Returns the text string operand expr right-padded to length n with the sequence of characters in pad. The default valuefor pad is a blank. If expr is longer than n, then RPAD returns the portion of expr that ts in n.

Examples:

/* A is set to 'helloXYXYX' */A = RPAD ('hello, 10, 'XY')/* A is set to 'hell' */A = RPAD ('hello', 4 )

RTRIM(expr [,set])Returns the text string operand expr with all the right-most characters that appear in set removed. The default value forset is a blank. If none of the right-most characters of expr appear in set, then expr is returned.

Examples:

/* A is set to 'abc' */A = RTRIM ('abcdef','def')/* A is set to 'abcdef' */A = RTRIM ('abcdef','de')

SUBSTR(expr, m [,n]) or SUBSTRING(expr, m [,n])SUBSTRING returns a substring of the text string operand expr of length n characters beginning at the mth character. If n isnegative, SUBSTR counts backward of expr. If you omit the n, the substring starts from m and nishes at the end of expr.

Example:

/* Check that the tax code starts with GG */IF length(Tax_code) <= 2 THEN(message = 'Tax code is too short'RETURN message)IF substr( Tax_code, 1, 2) = 'GG' THEN ...

SUBSTRB((expr, m [,n])The same as SUBSTR, except that the arguments m and n are expressed in bytes, rather than in characters. For a single-byte database character set, SUBSTRB is equivalent to SUBSTR.

TRANSLATE(expr,from,to)Returns the text string operand expr with all occurrences of each character in from replaced by its correspondingcharacter in to. Characters in expr that aren't in from aren't replaced. The argument from can contain more characters



40

than to. In this case, the extra characters at the end of from have no corresponding characters in to. If these extracharacters appear in expr, they're removed from the return value.

TRIM(expr)Trims leading and trailing spaces from a character string.

UPPER(expr)Converts a text string to uppercase.

Numeric Formula FunctionsHere are the formula functions that you can use to manipulate numeric data:

ABS(n)Returns the magnitude of a numeric operand n as a positive numeric value. If the value of the operand is positive, itsvalue returns unchanged. If the operand is negative, then the value's sign inverts and the value returns as a positivenumber.

Example:

ABS (-17)

It returns 17.

FLOOR(n)Returns the integer part of a numeric operand n. If the value of the operand contains information after the decimalpoint, FLOOR discards that information and returns a whole number.

Example:

FLOOR(35.455)

It returns 35.

GREATEST(n, n [, n] ...) or GREATEST_OF(n, n [, n] ...)Compares all the operands and returns the greatest value.

LEAST(n, n [, n] ...) or LEAST_OF(n, n [, n] ...)Compares all the operands and returns the smallest value.

MOD(m, n)Returns the remainder after dividing m by n.

POWER(m, n)Returns m raised to the nth power.



41

ROUND(m [,n])Rounds m to n decimal places. The default number of decimal places is 0.

Examples:

ROUND(2.3401, 2)

It returns 2.34.

ROUND (2.3461, 2)

It returns 2.35.

ROUNDUP(m [,n]) or ROUND_UP(m [,n])Rounds o m up to n decimal places. The default number of places is 0.

Examples:

ROUND_UP(2.3401, 2)

It returns 2.35.

ROUND_UP(2.3400, 2)

It returns 2.34.

TRUNC(n [,m]) or TRUNCATE(n [,m])Truncates m down to n decimal places. The default number of places is 0.

Examples:

TRUNC(2.3401, 2)

It returns 2.34.

Date Formula FunctionsHere are the formula functions that you can use to manipulate date data:

ADD_DAYS(date, n)Adds n whole days to date.

Example:

ADD_DAYS ('30-DEC-1990' (date), 6)

It returns 5 JAN 1991.

ADD_MONTHS(date, n)Adds n whole months to date.



42

ADD_YEARS(date, n)Adds n whole years to date.

DAYS_BETWEEN(date1, date2)Returns the number of days between date1 and date2. If date1 is later than date2, then the result is a positive number. Ifdate1 is earlier than date2, then the result is a negative number.

Here's an example of this function:

DAYS_BETWEEN('1995/06/27 00:00:00' (date), '1995/07/03 00:00:00' (date))

It returns - 6.

Similarly;DAYS_BETWEEN('2016/12/31 00:00:00'(DATE), '2017/01/01 00:00:00'(DATE))

It return -1.

GREATEST(date, date [, date] ...)Compares its operands and returns the latest date.

LAST_DAY(date)Returns the last day of the month containing date.

LEAST(date, date [, date] ...)Compares the operands and returns the earliest date.

MONTHS_BETWEEN(date1, date2)Returns the number of months between date1 and date2. If date1 is later than date2, the result is a positive number. Ifdate1 is earlier than date2, the result is a negative number. The return value has a numeric data type that can contain afraction if the dates don't dier by a whole number of months.

NEW_TIME(date, zone1, zone2)Returns the date and time in zone2 when the date and time in zone1 are date.

Here are the standard text strings that you can store in arguments zone1 and zone2:

Time Zone Description

AST

Atlantic Standard Time

BST

Bering Standard Time

CST or CDT

Central Standard or Daylight Time

EST or EDT Eastern Standard or Daylight Time



43

Time Zone Description

GMT

Greenwich Mean Time

HST or HDT

Alaska-Hawaii Standard Time or Daylight Time

MST or MDT

Mountain Standard or Daylight Time

NST

Newfoundland Standard Time

PST or PDT

Pacic Standard or Daylight Time

YST

Yukon Standard Time

NEXT_DAY(d, expr)Returns the rst date following d of the weekday named by expr.

ROUND(date [,format])Returns the result of rounding date according to format. The default format is DDD, which represents the nearest day.

TRUNC(date [,format])Returns the result of truncating date according to format. The default format is DDD, which represents a whole day.

Data Conversion Formula FunctionsHere are the formula functions that you can use to perform data conversions:

DATE_TO_TEXT(date [,format]), TO_CHAR(date [,format]), and TO_TEXT(date[,format])Converts date to a character string in the format specied by format. The default format is the application canonicalformat.

NUM_TO_CHAR(n, format)Converts the number n to a character string in the specied format. This function is equivalent to the SQL TO_CHARfunction.

TO_CHAR(n) and TO_TEXT(n)Converts the number n to a character string in canonical number format.



44

TO_DATE (expr [, format])Converts the character string expr to a date in the specied format. If no format is specied, then expr must be incanonical format.

TO_NUMBER(expr) and TO_NUM(expr)Converts the character string expr to a number. The character string must be in canonical number format. A period isused for the decimal point; for example, 1.234. Negative numbers are preceded with a minus; for example, -1.234.

Miscellaneous Formula FunctionsHere are the formula functions that you can use to manipulate messaging data or retrieve values from user-denedtables:

GET_MESG, GET_FND_MESGGET_MESG(appname, msgname [, token1, value1] [, token2, value2] [, token3, value3] [, token4, value4] [, token5,value5] )

GET_FND_MESG(appname, msgname [, token1, value1] [, token2, value2] [, token3, value3] [, token4, value4] [, token5,value5] )

Returns an expanded version of the application message specied using appname, msgname, and up to ve pairs ofmessage tokens and their corresponding values.

GET_RATEGET_RATE(from_currency, to_currency, rate_type[,default_rate])

Returns the rate between the two currencies for a given conversion date and rate type. The return type is NUMBER.

Contexts: EFFECTIVE_DATE (text) is the conversion date.

Parameters:

• FROM_CURRENCY (text): An example would be USD.

• TO_CURRENCY (text): An example would be GBP.

• RATE_TYPE (text): The source of a currency conversion rate, such as user dened, spot, corporate, or xed.

Note: During journal entry, the conversion rate is provided automatically by the General Ledgerbased on the selected conversion rate type and currency, unless the rate type is user. For user ratetypes, you must enter the conversion rate. Dene additional rate types as needed. Set your mostfrequently used rate type as the default.

• DEFAULT_RATE (number): The rate that's returned if GET_RATE can’t get a rate. A typical value for this wouldbe 1.0.

GET_RATE calls a General Ledger product API. The API retrieves the rate from the General Ledger daily rates or xedrates, where appropriate.



45

GET_TABLE_VALUEGET_TABLE_VALUE(table_name, column_name, row_value [,default_value])

GET_TABLE_VALUE(table_name, column_name, row_value, eective date)

Returns the value of a cell in a user-dened table on the eective date of the session or process. The rst three textoperands identify the cell. An optional fourth parameter does one of the following, depending on its data type:

• Text: Returns a text default value if no data is found.

• Date: Returns the value of the cell on the specied date.

Here’s an example of this function:

GET_TABLE_VALUE('WAGE RATES', 'Wage Rate', Rate_Code, 'DEFAULT'): Returns the row_value for Wage Rate or DEFAULTif it doesn’t nd a row.

GET_VALUE_SETGET_VALUE_SET(value_set_code, bind)

Returns the rst record of the given value set for the bind passed, whereby the bind needs to be in thisformat: <Separator character> <equal character><first parameter name><equal character><value><Separatorcharacter><second parameter name><equal character><value><Repeat the same for more bind parameters>

Here's an example of this function:

_NUMBER=GET_VALUE_SET('SAMPLE_GET_ASG_NUM' .'|=PERSON_ID= ' ' '||POSITION3||' ' ' '): Passes data to a fast formulafunction to retrieve assignment number and person ID that are passed through the position3 variable.

Note: Use the GET_VALUE_SET function to retrieve information when a database item isn't available. Thisfunction supports Value Set with Validation Type = Table, Value Data Type = Character and no aliases.

HR_TRACE(expr)Outputs a trace message.

Note: It's more ecient to use an application-specic logging function than HR_TRACE.



46


Chapter 5Formulas for Payroll

47

5 Formulas for Payroll

Overview of Payroll FormulasHere are the tasks you can do using payroll formulas in your application:

• Prorate payroll results

• Convert rate periodicities

• Validate element entry values

• Control preferences for payment methods

• Use HR database items in formulas

• Set default organization payment methods

• Return salary amounts

• Restrict the payroll run process to a specic set of employees

• Control when the application submits the current ow

• Return reference values for comparison in balance exception reports

• Control how the application loads a batch from a le

You can copy and edit the predened formulas or create your own.

This table describes the types of formulas that you can use within your payroll application.

Formula or Type Description Example

Proration Formula

Controls how the payroll calculationprorates an element entry. Prorationoccurs when the formula encounters anevent, such as a change to an elemententry value.

Return a proration factor or .25 forabsences based on an employee type,such as a system analyst on temporaryassignment.

Rate Conversion Formula

Creates a formula to convert rates forproration when you require dierentvalues for periodicity than the ones usedin the predened formulas.

Specify a dierent number of workinghours to use when converting annualvalues into hourly rates, such as 2080annual hours.

Element Input Validation Formula Type Here's what you can do with this formula:

• Validate element entry values• Provide a default value for an

element entry value• Calculate entry values based on

other entry values

Multiply the pay rate by 1.5 if theemployee works more than 40 hours aweek. Use this formula at the element orelement eligibility level.

User Table Validation Formula Type

Validates entries in user-dened tables.

Return an error message if a user enters avalue less than 10 or greater than 50 in theDues column of the Union Dues user table.



48

Formula or Type Description Example

Flow Schedule Formula Type

Creates a scheduling formula when thescheduling options for submiing aprocess, report, or ow don't cover yourrequirements. You can also determinehow often the formula submits futureinstances of the ow.

Load time card batches daily. Or, write aformula to increase the number of batchloads at the end of a payroll period whenworkers typically submit their time cards.

Payroll User Interface CongurationFormula Type

Create formulas to control preferencesfor payment methods for the enterpriseif you don't want to use the defaultconguration. After you create yourformulas, you aach them to theappropriate rows in the Payroll UserInterface Conguration user-dened table.

Set the default organization paymentmethod for each legislative data group.

Payroll Access to HR Formula Type

Calls a payroll formula when your payrollformula requires an HR database item.

Return salary amounts and then use thePayroll Access to HR formula to return afull-time equivalent (FTE) database itemfor a specic group of employees.

Payroll Relationship Group Formula Type

Returns Yes or No values to indicatewhether a person is part of a payrollrelationship group.

Restrict the payroll run process to aspecic set of employees, based onassignment and person level aributes.

Flow Schedule Formula Type

Controls when the application submitsthe current ow and how often it submitsfuture instances of the ow.

Create a formula that schedules thefrequency with which an extract processchecks for new starter details.

Balance Exception Formula Type

Creates formulas to return referencevalues for comparison in balanceexception reports.

Multiply the year-to-date gross earningsby 5 percent and return the value whenthe balance exception report to which it'sassociated is run.

Create Conversion Formulas for ProrationThe predened proration formula GLB_EARN_PRORATION controls how the payroll calculation prorates an elemententry when it encounters an event. This could happen when there's a change to an element entry value. You can copyand edit a predened proration formula to modify the calculation. Then, you can select the user-dened formula as theproration formula for your element.

Create a FormulaYou must create a modied rate conversion before you create its related proration conversion rule.

1. Select the formula type Payroll Run Proration.



49

2. Search for and copy the predened Rate Conversion Proration formula.3. Add the sux underscore _PRORATE to the name.4. Update these formula inputs:

◦ PRORATE_START_DATE (date)

◦ PRORATE_END_DATE (date)

◦ SOURCE_PERIODICITY (text)

◦ DAYS_WORKED (number)

◦ RATE_CONV_FORMULA (text)

◦ HOURS_WORKED (number)

◦ IN_AMOUNT (number)

◦ UNIT_TYPE (text)

◦ PRORATION_UNIT (text)

5. Add the formula outputs for the element input values.6. Save, submit, and compile the formula.

Some countries or territories supply predened proration formulas that you can use as the basis for your modiedversion.

Related Topics• Set Up Element Proration• How Prorated Earnings and Deductions are Calculated• Periodicity Conversion

Congure Periodicity Conversion RulesYou can use the predened periodicity conversion formulas when converting rates for hours multiplied by ratecalculations of an element run result. You can also use these formulas for rates based on rate denitions and prorationunless you specify another proration formula. The conversion rule applies to the Flat Amount, Hours * Rate, and Days *Rate calculation rules.

Here's what you can do to use a dierent value instead of the predened value for periodicity:

• Override the default periodicity for the element denition at the element entry level.

• Create your own periodicity conversion formula.

For example, you can create a formula to specify a dierent number of working hours when converting annual valuesinto hourly rates.

Note: As a best practice, if you congure a periodicity rate formula, you should also create a related prorationformula.

Congure a FormulaComplete these steps in the Payroll Calculation work area to congure a rate conversion formula:

1. Use the Manage Formulas task to search for formulas with the Rate Conversion formula type.2. Search for and display the rate conversion formula you want to copy.

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=A970FDB269F62944E040D30A6881739E

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=F640781693043551E040D30A68814C1B

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=1058944282184099E05362C3F00AA51A



50

3. Create a new formula with the formula type Rate Conversion.4. Copy the formula text into your new formula.5. Edit the periodicity values.

For example, if you create a rate conversion formula that uses 7.5 hours instead of 8 hours for the number ofwork hours in a day, you would edit the periodicity as follows:else if (out_periodicity = 'WORKHOUR') then l_amt = (l_year_amt /260)/ 7.5

6. Save, submit, and compile the formula.7. Use the Manage Elements task to search for the element and identify the formula used to calculate the

element.8. Use the Manage Formulas task to edit the formula.

Edit the rate converter call, replacing the rate conversion formula name with the name of your new formula. CALL_FORMULA( 'RATE_CONVERTER', l_rate > 'SOURCE_AMOUNT', l_source_periodicity > 'SOURCE_PERIODICITY', l_target_periodicity > 'TARGET_PERIODICITY', 'ANNUALIZED RATE CONVERSION' > 'method', /* replace with the name of new formula*/ l_actual_amount < 'TARGET_AMOUNT' DEFAULT 0)

9. Save, submit, and recompile the formula.

Related Topics• Periodicity Conversion• Overview of Using Formulas

Element Input Validation Formula TypeYou can use an element input validation formula to validate one or more element entry values. You can also use thisformula type to provide a default value for an element entry value. Additionally, you can calculate entry values based onthe user's entries in other entry values.

You select the formula on the Element Summary page in these elds:

Page Section Field Purpose When Does the FormulaRun?

Element Details or ElementEligibility

Validation Formula

Validates one or more entryvalues for the element basedon entries in other entryvalues.

When you save the elemententry.


Calculation Formula

Provides values for one ormore entry values using acalculation formula that takesinput from these entry valuesor other entry values.

When you save the elemententry.

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=1058944282184099E05362C3F00AA51A



51

Page Section Field Purpose When Does the FormulaRun?


Defaulting Formula

Provides default values forone or more entry values.

When you create the elemententry.

Input Value

Validation Formula

Validates one entry valueindependent of others.

When you enter a value.

Note: A formula at the element eligibility level always overrides an equivalent formula at the element level.

ContextsHere are the contexts that are available to all formulas of this type:

• LEGISLATIVE_DATA_GROUP_ID

• DATE_EARNED

• EFFECTIVE_DATE

These contexts are available to formulas only at element or element eligibility level; they aren’t available to validationformulas at the input value level:

• PERSON_ID

• PAYROLL_RELATIONSHIP_ID

• PAYROLL_TERM_ID

• PAYROLL_ASSIGNMENT_ID

• HR_RELATIONSHIP_ID

• HR_TERM_ID

• HR_ASSIGNMENT_ID

Input VariablesHere are the input variables that are available to formulas of this type.

Formula Usage Input Variables Comments

Validation formula at input value level

entry_value

Passes the value to be validated. Youmust declare the input variable as theappropriate type for the element inputvalue.

Validation formula at element or elementeligibility level

Any element input value name thatcorresponds to an entry value.

Replace spaces in the input value namewith underscores in the input variablename. It doesn't maer whether you useuppercase or lowercase for the name.



52

Formula Usage Input Variables Comments

Defaulting formula

None

Use database items or other logic instead.

Calculation formula

Any element input value name of an entryvalue.

Replace spaces with underscores. You need not provide all of the availableentry values.

Return ValuesHere are the return values that are available to formulas of this type.

Formula Usage Return Values Comments

Validation formula at any level.

formula_status

Must be either 'S' (success) or 'E' (error).Required.

Validation formula at any level.

formula_ message

The text of the message is passed to theuser if the validation fails. Optional.

Defaulting formula


A return value overrides any default valuethat’s provided on the input value in theelement or element eligibility record.

Calculation formula


You don't need to return all of theavailable entry values. You can return theentry values that were passed as inputvariables or other entry values.

Sample FormulaHere are a few sample formula that you can use:

• Validation formula at input value level

• Validation formula at element or element eligibility level

• Calculation formula at element or element eligibility level

• Defaulting formula at element or element eligibility level

Validation formula at input value level:

inputs are entry_value(date)if(entry_value = '01-APR-2008' (date)) then(formula_message = 'Valid date'formula_status = 'S')else(formula_message = 'Invalid date'formula_status = 'E'



53

)return formula_message, formula_status

Validation formula at element or element eligibility level:

inputs are hours_worked, rate, earning_date(date), comment(text)if(hours_worked > 80) then(formula_message = 'You are within the working limit.'formula_status = 'S')else(formula_message = 'You have worked too many hours.'formula_status = 'E')return formula_message, formula_status

Calculation formula at element or element eligibility level:

inputs are hours_worked, rate, comment(text)if(hours_worked > 80) then(rate = rate * 1.2 comment = 'Your rate has been increased')return rate, comment

Defaulting formula at element or element eligibility level:

if(CATEGORY = 'S') then(rate = 20)else(rate = 30)rate_code = 'B'return rate, rate_code

User Table Validation Formula TypeThe User Table Validation formula type validates entries in user-dened tables. When you create or edit user-denedtables, select the formula in the Formula eld for the user-dened columns.

You can use this formula type to ensure that entries are:

• Between a specied range

• Don’t contain a negative value

ContextsYou can use the EFFECTIVE_DATE (text) context for formulas of this type.

Input VariablesYou must use one input variable called ENTRY_VALUE of data type text.



54

Return ValuesThese return values are available to formulas of this type:

Return Value Data Type Required Description

FORMULA_ MESSAGE

Text

N

Returns a text message foreither or both statuses. Themessage is displayed on theCreate User-Dened Table:User-Dened Table Valuespage.

FORMULA_STATUS

Text

Y

Returns the value S (success)or E (error).

Sample FormulaThis formula checks whether the deduction value entered in the Union A column of the Union Dues table is between10.00 and 20.00:

/* Formula Name: Union A Dues Validation *//* Formula Type: User Table Validation */INPUTS ARE entry_value (text)IF TO_NUMBER(entry_value) < 10.00 OR TO_NUMBER(entry_value) > 20.00 THEN(formula_status = 'e' formula_message = 'Error: Union A dues must be between $10.00 and $20.00.')ELSE(formula_status = 's'formula_message = ' ')RETURN formula_status, formula_message

Payroll User Interface Conguration Formula TypeYou can use the Payroll User Interface Conguration formula type to control the congurable preferences for paymentmethods. On the Manage Fast Formulas page, you can create formulas to override the default values by creatingnew values for these preferences. After you create your formulas, you can aach them to the appropriate rows in thePAYROLL_USER_INTERFACE_CONFIGURATION user-dened table..

This table lists the congurable preferences, their predened row name in the user-dened table, purpose, and defaultvalues.



55

User-Dened Row Name Purpose Default Value

Default Organization Payment Method

Sets the default organization paymentmethod in the simplied UI for eachlegislative data group.

(Not applicable)

Execute Personal Payment MethodValidation

Validates the customer personal paymentmethod criteria. For example, you cancreate only one payment method with aspecic account type.

No

Maximum Number of Personal PaymentMethods

Sets the maximum allowed number ofpersonal payment methods.

No limit

Payment Types Available to Workers

Limits the creation of personal paymentmethods to a specic payment type.

All available organization paymentmethods

Prevent Edit Personal Payment Method

Prevents employees from modifying anypersonal payment method details thatmeet the criteria set in the formula.

No

Show Percentage or Amount

Displays only Amount or Percentageamount types on the Manage PersonalPayment Methods page.

Both

Note: Each preference that you congure must have its own formula. You can't combine dierentpreferences into a single formula. For example, you can't create a formula that sets the default organizationpayment method and also sets the maximum number of allowed personal payment methods.

Database ItemsThe Payroll User Interface Conguration formula type doesn’t support database items. As with other formula types, toretrieve information when a database item isn't available, use the GET_VALUE_SET function.

Note: When using the GET_VALUE_SET function, ensure that the Value Aributes Table Alias eld forthe value set has no value. The function fails if you provide an alias.

Input VariablesThese input values are available to all formulas of the Payroll User Interface Conguration formula type:

Input Variable Type Description

EFFECTIVE_DATE

Text

The eective date on which the formulavalidation will be applied.

LEGISLATIVE_ DATA_GROUP_ID

Text

The number that identies the legislativedata group for the variable.



56


PAYROLL_ RELATIONSHIP_ ID

Text

The number that identies the payrollrelationship for the variable.

These input values are available to the two personal payment method validation formulas:


AMOUNT

Text

Total amount to be paid to the personalpayment method.

BANK_ ACCOUNT_ NUMBER

Text

Bank account number for the externalbank account.

BANK_ ACCOUNT_TYPE

Text

Type of the external bank account for thepersonal payment method.

BANK_NAME

Text

Name of the bank associated with thepersonal payment method.

BRANCH_NAME

Text

Name of the bank branch associated withthe personal payment method.

CURRENCY_CODE

Text

The currency code of the personalpayment method.

ORGANIZATION_ PAYMENT_METHOD_NAME

Text

Name of the organization paymentmethod.

PAYMENT_ AMOUNT_TYPE

Text

Percentage or amount aributed to thepersonal payment method.

PAYMENT_ TYPE_NAME

Text

Payment type, such as check or directdeposit for a particular organizationpayment method.

PERCENTAGE

Text

The percentage amount aributed to thepersonal payment method.

PERSONAL_ PAYMENT_ METHOD_NAME

Text

The name of the personal paymentmethod.



57


PRIORITY

Text

The priority order of the personal paymentmethod.

This context is available only for formulas mapped to the Default Organization Payment Method row in the user-dened table.

• PAYMENT_TYPE_NAME (text)

Text representing the payment type in the expected format, for example, EFT or Check.

Return ValuesUnlike other formulas, the return values for the Payroll User Interface Conguration formula type are variables that youdeclare in your formulas. Refer to the sample formulas for examples.

Sample FormulaThis sample formula sets default organization payment methods in LDG_A (ID 300100001) based on thepayment type. To use this rule, aach your formula to the Default Organization Payment Method row in thePAYROLL_USER_INTERFACE_CONFIGURATION user-dened table. In this example, the valid return values forDEFAULT_OPM are the exact names of organization payment methods.

/***********************************************FORMULA NAME: Default OPM Formula FORMULA TYPE: Payroll User Interface Configuration/************************************************/* Configuration */IF (LEGISLATIVE_DATA_GROUP_ID = '300100001' AND PAYMENT_TYPE_NAME = 'EFT')THEN DEFAULT_OPM = 'NACHA_OPM_A' ELSE IF (LEGISLATIVE_DATA_GROUP_ID = '300100002'AND PAYMENT_TYPE_NAME = 'Check')THEN DEFAULT_OPM = 'CHECK_OPM_A'ELSE DEFAULT_OPM = 'NODATA' RETURN DEFAULT_OPM /* End Formula Text */

This sample formula limits personal payment methods to be based only on organization payment methods of EFT(electronic funds transfer) or check payment types. To use this rule, aach your formula to the Payment TypesAvailable to Workers row in the PAYROLL_USER_INTERFACE_CONFIGURATION user-dened table. In this example,the valid return values are the base payment type names dened in the table PAY_PAYMENT_TYPES_VL.

/****************************************************FORMULA NAME: Worker Payment Types Formula FORMULA TYPE: Payroll User Interface Configuration/******************************************************/* Configuration */PAYMENT_TYPE[1] = 'EFT'PAYMENT_TYPE[2] = 'Check' RETURN PAYMENT_TYPE/* End Formula Text */

This sample formula limits the number of personal payment methods for employees in LDG_A (ID 300100001) to 3, andemployees in LDG_B (ID 300100002) to 1. To use this rule, aach your formula to the Maximum Number of Personal



58

Payment Methods row in the PAYROLL_USER_INTERFACE_CONFIGURATION user-dened table. In this example, thevalid return values for MAX_NUM_PPMS are integers.

/****************************************************FORMULA NAME: Maximum PPM Formula FORMULA TYPE: Payroll User Interface Configuration*****************************************************//* Configuration */IF LEGISLATIVE_DATA_GROUP_ID = '300100001' THEN MAX_NUM_PPMS = '3' IF LEGISLATIVE_DATA_GROUP_ID = '300100002' THEN MAX_NUM_PPMS = '1' ELSE MAX_NUM_PPMS = 'NO DATA' RETURN MAX_NUM_PPMS/* End Formula Text */

This sample formula sets a restriction to display only the Percentage amount type and eld on the Manage PersonalPayment Methods page. To use this rule, aach your formula to the Show Percentage or Amount row in thePAYROLL_USER_INTERFACE_CONFIGURATION user-dened table. In this example, the valid return values forPAYMENT_AMOUNT_TYPE are AMOUNT or PERCENTAGE.

/*******************************************************FORMULA NAME: Show Percentage Formula FORMULA TYPE: Payroll User Interface Configuration********************************************************//* Configuration */PAYMENT_AMOUNT_TYPE = 'PERCENTAGE'RETURN PAYMENT_AMOUNT_TYPE/* End Formula Text */

This sample formula validates that the rst personal payment method is Pay Card and the payment type is either EFT orIAT. And the account type is Pay Card. This formula ensures that the rst personal payment method meets these criteriaand that an employee has only one personal payment method of this type.

/***************************************************FORMULA NAME: Execute Personal Payment Method ValidationFORMULA TYPE: Payroll User Interface Configuration***************************************************/ IF (PAGE_NAME = 'DETAILS'){ //PPM Validation //check if there is PPM for PAYROLL_RELATIONSHIP_ID COUNT = NUMBER_OF_PPMS

//This returns the number of PPMs for a payroll relationship ID using a value set //If this is first PPM IF(COUNT==0){ IF((PAYMENT_TYPE_NAME==EFT OR PAYMENT_TYPE_NAME==IAT) AND BANK_ACCOUNT_TYPE==PAYCARD){ //If first PPM and is of type PAYCARD, PPM can be created RETURN_VALUE[1]= 'N' } ELSE{ //If first PPM is not PAYCARD, throw error message RETURN_VALUE[1]='Y' RETURN_VALUE[2]='ANY_VALID_ERROR_MESSAGE' } } //This is not the first PPM. ELSE{ IF((PAYMENT_TYPE_NAME==EFT OR PAYMENT_TYPE_NAME==IAT)

AND BANK_ACCOUNT_TYPE==PAYCARD){



59

//If multiple PAYCARD PPMs, throw error message RETURN_VALUE[1]='Y' RETURN_VALUE[2]='ANY_VALID_ERROR_MESSAGE' } ELSE{ RETURN_VALUE[1]='N' } } } //When changing the priority of a PPM ELSE IF(PAGE_NAME == 'SUMMARY') { //Get the highest priority for PAYROLL_RELATIONSHIP_ID IF (PRIORITY == HIGHEST_PRIORITY){ //Gets the highest priority among the PPMs for a particular payroll relationship ID //by executing a value set. Change in priority throws error message. RETURN_VALUE[1]='Y' RETURN_VALUE[2]='ANY_VALID_ERROR_MESSAGE' } ELSE RETURN_VALUE[1]='N' } }

This sample formula prevents a self-service user from editing personal payment methods that are associated with anorganization payment method of payment type Check.

/**************************************************************************************FORMULA NAME: Prevent Edit Personal Payment MethodFORMULA TYPE: Payroll User Interface ConfigurationExpected Behavior : If value returned is N, no change in functionality If value returned is Y, Save/Submit buttons will be disabled in edit flow to prevent the edit of personal payment method. The Delete buttons will also be disabled for the personal payment methods

Sample Input File Format:User Interface|Legislative Data Group|Effective Date|Payroll Relationship|Payment Type ***************************************************************************************/

/* inputs */

INPUTS ARE PAGE_NAME (text), LEGISLATIVE_DATA_GROUP_ID (text), PAYROLL_RELATIONSHIP_ID (text), EFFECTIVE_DATE(text), PERSONAL_PAYMENT_METHOD_NAME (text), ORGANIZATION_PAYMENT_METHOD_NAME (text), PAYMENT_TYPE_NAME (text), CURRENCY_CODE (text),PAYMENT_AMOUNT_TYPE (text),PERCENTAGE (text),AMOUNT (text),PRIORITY (text),BANK_NAME (text),BRANCH_NAME (text),BANK_ACCOUNT_NUMBER (text), BANK_ACCOUNT_TYPE (text)

/* Configuration */

IF ORGANIZATION_PAYMENT_METHOD_NAME='Check' THEN(OUTPUT_VALUE = 'Y')ELSE(OUTPUT_VALUE = 'N')

RETURN OUTPUT_VALUE

/* End Formula Text */

Related Topics

• Congure Payment Method Preferences

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=2817D61B862E0E59E05362C3F00ABFC5



60

Payroll Access to HR Formula TypeUse the Payroll Access to HR formula type to call a payroll formula when your payroll formula requires an HR databaseitem.

For example, you can use the payroll formula to return the salary amount, and then use the Payroll Access to HRformula to return a full-time equivalent (FTE) database item for a specic group of employees.

ContextsThese contexts are available to all formulas of this type:

• HR_RELATIONSHIP_ID

• HR_TERM_ID

• GRADE_RATE_ID

• LEGAL_EMPLOYER_ID

• AREA1

• LOCATION_ID


• PERSON_ID

• JOB_ID

• GRADE_ID

• ADDRESS_ID

• ADDRESS_TYPE

• ACCRUAL_PLAN_ID

• EFFECTIVE_DATE


• ORGANIZATION_ID

Input VariablesThese input variables are available to formulas of this type.

Enter Data Data Type

ACTUAL_ END_DATE

Date

ACTUAL_ START_DATE

Date

EFF_DATE

Date

END_DATE

Date



61

Enter Data Data Type

ENTRY_LEVEL

Text

HR_ASSG_ID

Number

HR_ASSIGN_ID

Number

HR_ EFFECTIVE_ DATE

Date

HR_ENTRY_LEVEL

Text

HR_ID

Number

HR_ID2

Number

HR_TRM_ID

Number

MODE

Text

START_DATE

Date

UNIT_TYPE

Text


Return Value Data Type Description

L_SALARY

Number

Salary ID of employee

L_ SALARY_ BASIS_CODE

Text

Salary basis of employee

L_UNITS

Number

Number of units worked

X_OUTPUT

Date

Output date

X_OUTPUT

Text

Output text



62

Return Value Data Type Description

X_ OUTPUT_NUMBER

Number

Output number

X_OUTPUT_TEXT

Text

Output text

Sample FormulaThis sample Oracle Payroll formula returns the salary amount for employees based on their full-time equivalent (FTE),which is an HR database item. Because HR database items aren’t accessible through Oracle Payroll formulas, youmust create a Payroll Access to HR formula to retrieve the database item. And then call the formula that retrieves thedatabase item from the formula that returns the salary amount.

/***************************************************************FORMULA TYPE: Payroll Access to HRDESCRIPTION: Retrieve FTE DBI***************************************************************//* Default Statement Section */Default for PER_ASG_FTE_VALUE is 1/* Calculation Section */HR_FTE = PER_ASG_FTE_VALUE/* Return Statement Section */Return HR_FTE/*************************************************************FORMULA NAME: GB Salary by FTE FORMULA TYPE: Oracle Payroll DESCRIPTION: Calculate the salary amount for OK employees based on their FTE.**************************************************************//* Alias Statement Section */ALIAS ANNUAL_SALARY_UK_AMOUNT_ASG_ENTRY_VALUE AS UK_ASG_SAL/* Default Statement Section */Default for ASG_HR_ASG_ID is 1Default for UK_ASG_SAL is 0Default for Salary_UK is 0/* Calculation Section */Salary_UK = UK_ASG_SALSET_INPUT('HR_ASSIGNMENT_ID', ASG_HR_ASG_ID)EXECUTE('Call HR FTE DBI')FTE = GET_OUTPUT('HR_FTE',1)l_amount = round((FTE * Salary_UK),2)Message = 'Salary Value is'||to_Char(l_Amount)/* Return Statement Section */RETURN l_Amount,Message

Payroll Relationship Group Formula TypeThe Payroll Relationship Group formula type returns Yes or No to indicate whether a person is part of a payrollrelationship group. The formula contains the criteria that dene the group. You can use these groups to dene a set ofpeople for payroll processing, data entry, or reporting. On the Manage Object Groups page, select the formula whencreating a payroll relationship group.

For example, you can use the Payroll Relationship Group formula type to restrict the payroll run process to a specic setof employees based on assignment and person-level aributes.



63

By default, you create formulas of this type using the Expression editor on the Create Fast Formula page. However, youcan use the text editor to create more complex formulas, if required.



• PAYROLL_TERM_ID

• DATE_EARNED

• OBJECT_GROUP_ID

• EFFECTIVE_DATE


• PAYROLL_ID


Input VariablesYou must have at least one input value called LEVEL_NAME. The data type is text and these are the valid values:

• PAY_REL

• PAY_TERM

• PAY_ASG

Return ValuesThis return value is available to the INCLUDE_FLAG formula type. The data type is text.

Sample FormulaThis formula calls the summary formula for each of the levels in the person group until the membership is established.

*/DEFAULT_DATA_VALUE FOR PERSON_GROUP_LEVEL_SUMMARY_FORMULA_NAME is 'null' NEED_CONTEXT(PAYROLL_RELATIONSHIP_ID)NEED_CONTEXT(PAYROLL_TERM_ID)NEED_CONTEXT(PAYROLL_ASSIGNMENT_ID)NEED_CONTEXT(LEGISLATIVE_DATA_GROUP_ID)NEED_CONTEXT(PAYROLL_ID)NEED_CONTEXT(DATE_EARNED)NEED_CONTEXT(EFFECTIVE_DATE)

in_group = 'N'

SET_INPUT('level_name', 'PAY_REL')EXECUTE (PERSON_GROUP_LEVEL_SUMMARY_FORMULA_NAME[1])in_group = GET_OUTPUT('INCLUDE_FLAG', 'N')

IF (in_group = 'N') THEN(SET_INPUT('level_name', 'PAY_TERM')EXECUTE (PERSON_GROUP_LEVEL_SUMMARY_FORMULA_NAME[1])in_group = GET_OUTPUT('INCLUDE_FLAG', 'N'))IF (in_group = 'N') THEN(SET_INPUT('level_name', 'PAY_ASG')EXECUTE (PERSON_GROUP_LEVEL_SUMMARY_FORMULA_NAME[1])in_group = GET_OUTPUT('INCLUDE_FLAG', 'N'))IF in_group = 'Y' THEN INCLUDE_FLAG = 'Y'



64

RETURN INCLUDE_FLAG

Flow Schedule Formula TypeUse Flow Schedule formulas to control when to submit the current ow and how often to submit future instances ofthe ow. You create scheduling formulas on the Manage Fast Formulas page when the predened formulas don't meetyour requirements.

Let’s say you create a formula that loads time card batches daily, and increases to four times a day at the end of apayroll period when workers typically submit their time cards. You can create a formula that schedules the frequencywith which an extract process checks for new starter details.

Here are a few points to consider when creating or updating a scheduling formula:

• Specify a meaningful name to assist the person selecting the formula.

• Review the formula to ensure it doesn't contain negative numbers that might produce an error condition, suchas running a process continually.

• After updating the formula, cancel any scheduled ows that use the formula. Resubmit the ow to apply theupdated denition.

ContextsThe SCHEDULED_DATE (scheduled date) context is available to formula of this type.

Database ItemsHere’s the list of database items that are available to Flow Schedule formulas.

Database Item Data Type Description

FF_ADD_DAYS

Date

Function to add days to a date.

FF_ADD_MONTHS

Date

Function to add months to a date.

NEXT_ SCHEDULED_ DATE

Date

Calculated value for the date to schedulethe next ow.

SCHEDULED_DATE

Date

Date used to schedule the ow.

Input VariablesThese are the input variables available to Flow Schedule formulas.



65

Input Variables Data Type Required Description

SCHEDULED_ DATE(DATE)

Date

Y

Date on which to schedule theow. The date is passed to theformula when it calculates thenext date to schedule the ow.

Return ValuesUse predened names for return variables. These are the return values available to Flow Schedule formulas.

Return Values Data Type Required Description

NEXT_ SCHEDULED_ DATE

Date

Y

The date calculated by theformula to schedule the nextow.

Sample FormulaThis predened formula schedules a ow so that it's submied weekly from the date the ow owner initially submiedit.

/***********************************************************FORMULA NAME: WeeklyFORMULA TYPE: Flow Schedule DESCRIPTION: Formula to return a date time. Returns NEXT_SCHEDULED_DATE; Formula Results : NEXT_SCHEDULED_DATE This is a date time value with yyyy-MM-dd HH:mm:ss format.************************************************************//* Inputs */INPUTS ARE SUBMISSION_DATE(DATE), SCHEDULED_DATE(DATE)/* Calculations */NEXT_SCHEDULED_DATE = ADD_DAYS(SCHEDULED_DATE,7)/* Returns */RETURN NEXT_SCHEDULED_DATE /* End Formula Text */

You can calculate units smaller than a day by replacing the calculation portion of the formula text using a decimal or afraction. Let’s look at some examples of submiing a ow several times a day.

Flow Submission Formula Text for Calculation

Twice a day

Note: For accuracy, enter a value with at least ten decimal places. The formula textsupports a maximum of 14 decimal places.

Hourly NEXT_SCHEDULED_DATE =ADD_DAYS(SCHEDULED_DATE,1/24)



66

Balance Exception Formula TypeUse the Balance Exception formula type to create formulas to return reference values for comparison in BalanceException reports.

On the Create Balance Exception page, enter Formula in the Variance Type eld, and then enter the name of theformula that you create using this formula type in the Formula Name eld.


• EFFECTIVE_DATE

• PERSON_ID


• TAX_UNIT_ID


• PAYROLL_REL_ACTION_ID

• PAYROLL_TERM_ID



• PAYROLL_ID

• CALC_BREAKDOWN_ID

Database ItemsYou can reference any database item in the fast formula that uses any of the listed contexts.

Input VariablesYou can’t use input variables for this formula type. This formula is run by the balance exception report for each personrecord. It returns the reference value for that employee for comparison with the balance value that’s congured in therespective balance exception.



REFERENCE_ VALUE

Text

Y

Returns a reference valuefor comparing in the balanceexception report.

REFERENCE_INFO

Text

Y Returns the text that’s

displayed in the Reference



67


eld in the balance exceptionreport.

Sample FormulaThis formula returns 100 as a static value when the balance exception report it’s associated with is run.

/************************************************************FORMULA NAME: SAMPLE_BEX_FORMULA_1FORMULA TYPE: Balance ExceptionDESCRIPTION: This is a sample formula that returns a static value.Formula Results: reference_value - Reference Value for comparison in the Balance Exception Report. reference_info - Reference Value for reporting in the Balance Exception Report.*************************************************************/reference_value = 100reference_info = 'Ref Info'RETURN REFERENCE_VALUE,REFERENCE_INFO /* End Formula Text */

This formula returns a gap test global value and reference information when the balance exception report it’s associatedwith is run.

Note: GAP_TEST_GLOBAL_1 is the name of a user dened global value.

/************************************************************FORMULA NAME: SAMPLE_BEX_FORMULA_2 FORMULA TYPE: Balance ExceptionDESCRIPTION: This sample formula returns a Global Formula Results: reference_value - Reference Value for comparison in the Balance Exception Report. reference_info - Reference Value for reporting in the Balance Exception Report./************************************************************reference_value = GAP_TEST_GLOBAL_1reference_info = 'Ref Info' RETURN REFERENCE_VALUE,REFERENCE_INFO/* End Formula Text */

This formula multiplies the year-to-date gross earnings by 75 percent and returns the value when the balance exceptionreport it’s associated with is run.

/********************************************************FORMULA NAME: SAMPLE_BEX_FORMULA_3FORMULA TYPE: Balance ExceptionDESCRIPTION: This sample formula returns a Balance Value Formula Results: reference_value - Reference Value for comparison in the Balance Exception Report. reference_info - Reference Value for reporting in the Balance Exception Report./*********************************************************ytd_value = GROSS_EARNINGS_ASG_YTDreference_value = 0.75* ytd_valuereference_info = 'Ref Info' RETURN REFERENCE_VALUE,REFERENCE_INFO/* End Formula Text */

Related Topics• Balance Exceptions

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=21EBC1175CB77CE1E05362C3F00A29C9



68


Chapter 6Formulas for Absence Management

69

6 Formulas for Absence Management

Options to Dene Qualication PlansCongure the following rules when you create an absence qualication plan in accordance with the leave policy of yourenterprise:

• Plan term

• Plan eligibility

• Enrollment and termination

• Payments

Plan TermA qualication plan term is an assessment period for which the Evaluate Absence process calculates entitlements forthe total absent time recorded in that period. When you create an absence qualication plan, you must select the type ofplan term. For example, you can limit the duration of the plan term to the duration of the absence.

Plan EligibilityAssociate an eligibility prole with the qualication plan to determine the set of workers who are eligible to record anabsence that belongs to that plan.

Enrollment and TerminationDecide when to enroll workers in the qualication plan. Also, decide whether ongoing payments under this plan mustcontinue if a worker is terminated or loses eligibility for the plan.

PaymentsUse an entitlement band matrix to determine the payment percentages that apply for specic time periods during anabsence. Decide how you want to calculate the payment rate of a single unit of absence. You can use a rate denition toinclude the calculation rules, or use a formula. For example, you want workers who have completed a particular tenureto receive specic percentage of pay for a specic absence period.

The following table shows a sample scenario:

Length of Service Payment Rule

5 to 10 years

75 percent up to 10 absent days.

10 to 20 years

75 percent up to 20 absent days.



70

Decide how you want to calculate the payment rate of a single unit of absence. You can use a rate denition to includethe calculation rules, or use a formula.

Related Topics• Create a Maternity Plan

Options to Dene Accrual PlansCongure the following rules when you create an absence accrual plan in accordance with the leave policy of yourenterprise:

• Plan term

• Plan eligibility

• Enrollment and termination

• Transfer and rollover

• Prior balance reinstatement

• Vesting period

• Plan limits

• Balance Updates

• Payments

• Disbursement

• Donation

Plan TermAn accrual term is a period of time during which workers accrue time. You must specify the type of accrual term to usefor the plan. For example, you can dene one of these term types:

• An accrual term of one calendar year that restarts on January 1

• An accrual term that starts on the worker's annual hire date and restarts on every anniversary

Plan EligibilityAssociate an eligibility prole with the accrual plan to determine the set of workers who can enroll in that plan.

Enrollment and TerminationDecide when to enroll workers in the accrual plan. Indicate how to handle negative and positive balances where onlyplan enrollment ends, or both plan enrollment and employment ends.

Transfer, Rollover, and CarryoverDene the limits for transfer of some or all of the accrual balance to a new plan when the existing plan is terminateddue to loss of eligibility. The Transfer Rules section is enabled only when you select Transfer positive balance in theBalance Disposition section.

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=E1E7735171D509E1E040D30A68815F6F



71

Additionally, for year end processing, you can dene:

• Rollover limits so that employees can transfer remaining balance to a new plan. Select Unlimited if you don'twant to dene a limit for rollover.

• Carryover limits to determine the maximum unused leave time that employees can take over to the next termfor the same plan.

If the unused absence balance at the end of the term is above the dened rollover and carryover limit, you can chooseto pay out the remaining balance. If you don't select the Disburse remaining balance check box, the unused accrualbalance expires.

Prior Balance ReinstatementCongure accrual plans so that when a worker is terminated or loses plan eligibility, the remaining balance can beoptionally held for reinstatement upon rehire or return to plan eligibility.

Absence plan setup options allow you to dene the balance amount eligible for reinstatement along with the time framefor which the withheld balance can be reinstated. You can congure this option in the Re-enrollment Rules section. Youcan nd this section in the Plan Participation tab when you create or edit an absence plan.

If you select Allow Prior Balance Reinstatement, a new row in accruals called "Plan Balance close transaction" iscreated that deducts the remaining balance on the last day of the employee. This is the transaction that will act as areference to calculate the reinstated balance if the employee is re-hired within the time frame limit congured in theplan setup.

However, if you select Allow Prior Balance Reinstatement, and leave the Balance Reinstatement Limit and TimeFrame Limit elds blank, the entire closing balance can be reinstated any time.

Vesting PeriodDene if you want newly enrolled workers to accrue time, but not use it until after a specic amount of time.

Plan LimitsDene rules for the maximum leave time that workers can accrue. For incremental plans, Absence Managementapplies the limit to each accrual period. When there are accrual transactions such as adjustments, balance transfers,and disbursements, which impact the ceiling or carryover value, then the periodic accrual balance calculation takesprecedence and readjusts the balance accordingly.

Balance UpdatesYou can enable the following types of adjustments that HR specialists can make during maintenance of absence recordsand entitlements:

• Balance transfer across plans

• Other adjustments

• Elective disbursements



72

PaymentsDecide how you want to calculate payment of accrual balances for the following scenarios:

• When workers must be paid a dierent rate during the absence period

• When a part of the accrual balance must be disbursed to workers as cash

• When the cost of accrual balance must be calculated to determine employer liability

• When the accrual balance must be paid to workers when their plan participation ends

DisbursementDetermine whether workers are eligible for cash disbursement requests. Decide who can initiate the disbursement.Additionally, dene disbursement rules and the number of hours that can be disbursed.

DonationDene whether workers are eligible to donate accrual balances to a coworker. Decide who can initiate the donation.Additionally, dene donation rules and the number of hours that can be donated.

Related Topics• Create a Vacation Accrual Plan

Formulas for Accrual PlansUse the Absence Plan page to apply delivered accrual plan rules in the plan. However, if you want to dene other specialrules to suit your requirement, you can write your own formulas.

Formulas for Accrual PlansThe following table lists the aspects of an accrual plan for which you can write a formula and identies the formula typefor each.

Rule Description Formula Type to Use

Enrollment Start

Date when eligible workers are enrolled inthe plan. If a worker is already enrolled inan existing accrual plan, you can't use thisformula to change the enrollment startdate.

Global Absence Plan Enrollment Start

Enrollment End

Date when workers are disenrolled fromthe plan. This formula works only if thereis an eligibility prole associated with theplan.

Global Absence Plan Enrollment End

Conversion Formula

Method to override the default absenceplan entry duration.

Global Absence Plan Duration

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=E212ED8A4AF56BD0E040D30A6881459B



73


Example: You might have a requirementto consider only whole working days in avacation absence to update the accrualbalance. In such cases, you dene logic ina formula to convert the absence durationto a value that excludes partial days.

Anniversary Event

Method to determine the employmentanniversary date on which you want theaccrual plan to restart.

Global Absence Plan Period AnniversaryEvent Date

Accrual Event

Method to capture information aboutevents during a calendar year that aectthe accrual band of a worker. Example: An organization has a vacationplan in which enrolled workers accruea certain number of days every yearbased on their grade. When the gradeof a worker changes in the middle of thecalendar year, the organization mightwant to prorate their total accrual balance.You can congure this proration ruleusing the global absence accrual eventformula to capture the dates when suchchanges occur. This formula can't be aached to the plandenition at any point. When you createthis formula, the formula name needs tobe the same as the absence plan name.This automatically links the formula to theplan.

Global Absence Accrual Event

Accrual Vesting

A period during which workers accruetime, but can't use it.

Global Absence Vesting

Accrual Proration

Method to calculate the time workersaccrue if they enroll in the middle of anaccrual period.

Global Absence Proration

Ceiling

The maximum time that a worker canaccrue.

Global Absence Ceiling

Ceiling Proration

Method to return a multiplying factor toprorate the dened ceiling limit.

Global Absence Ceiling Proration

Carryover

The maximum unused time that a workercan transfer to the next accrual term.

Global Absence Carryover



74


Carryover Proration

Method to return a multiplying factor toprorate the dened carryover amount.

Global Absence Carryover Proration

Accrual Denition

Method to determine the paid time,eligible workers accrue over the course ofan accrual term.

Global Absence Accrual

Accrual Formula

Range of eligibility criteria that identifyhow much paid time eligible workersaccrue over the course of an accrualterm. The criteria may be years of service,grades, hours worked, or some otherfactor that you can dene.

Global Absence Accrual Matrix

Partial Accrual Period

Method to determine the prorated accrualamount for workers who enroll or disenrollfrom a plan during the plan period.

Global Absence Partial Accrual Period Rate

Absence Payment Rate

Method to calculate payment duringabsence period.

Global Absence Plan Use Rate

Discretionary Disbursement Rate

Method to calculate payment when payingout part of the accrual balance.


Disbursement Rule

Method to determine the minimum,maximum, and increment amounts thatthe worker is eligible for to request a cashdisbursement.

Global Absence DiscretionaryDisbursement Rule

Final Disbursement Rate

Method to calculate payment of accrualswhen plan participation ends.


Liability Rate

Method to calculate cost of accrualbalance to determine employer liability.


When you schedule an absence for a worker using an accrual plan with formulas dened, the absence doesn't appear inthe Absence Records section of the Manage Absences and Entitlements page. Instead, you can view the absence in thePlan Participation section. To view the absence:

1. In the Accrual Plans section, click the accrual plan to open the Accrual Plan Balance dialog box.2. Enter the Balance Calculation Date to view the details of the absence. The details are displayed in the

Summary and Details tabs.



75

Formulas for Qualication PlansUse the Absence Plan page to incorporate qualication plan rules. However, if you want to dene other special rules tosuit your requirement, you can write your own formulas.

Formulas for Qualication Plan RulesThe following table lists the aspects of a qualication plan for which you can write a formula and identies the formulatype for each.


Start Rule

When the rolling backward plan termstarts. A rolling backward term is a specictime period that precedes the absencestart date.

Global Absence Plan Roll Backward End

Qualication Date Rule

Date when eligible workers enroll in theplan.

Global Absence Plan Enrollment Start Date

Conversion Formula

Method to calculate the absence durationdierently. Example: You want to consider only wholeworking days in a sickness absence in theentitlement calculation. In such cases, youdene logic in a formula to convert theabsence duration to a value that excludespartial working days.

Global Absence Plan Duration

Entitlement Denition Type

Determines payment percentages to applyduring the absence period.

Global Absence Entitlement

Entitlement Formula (Qualication Details section)

A level that determines the payment thatworkers receive for a specic number ofdays during a long leave of absence basedon their length of service.

Global Absence Band Entitlement

Absence Payment Rate Rule

Method to calculate payment duringabsence period.




76

Formulas for Absence TypeUse the Absence Types pages to dene absence type rules. However, if you want to dene other special rules to suityour requirement, you can write your own formulas.

Formulas for Absence TypesThe following table lists the aspects of an absence type for which you can write a formula and identies the formulatype for each.


Conversion

Method to convert the absence durationto other units of measure. For example,your workers' work schedules are inwork hours, but you want to display theduration in work days.

Global Absence Type Duration You can use the formula to convertabsence duration values that are in workdays or work hours only.

Validation

Rules in addition to the ones that you candene on the Absence Types pages tocheck the validity of the absence.

Global Absence Entry Validation


Chapter 7Formulas for Compensation Plans

77

7 Formulas for Compensation Plans

Overview of Formulas for Compensation PlansUse compensation formulas in your application when you perform these actions:

• Specify compensation worksheet default values

• Refresh or process specic employees only

• Dene how local currency is determined for a plan component

• Create unique hierarchies for compensation

This table introduces the types of formulas that you use within your compensation application.

Formula Type Description Example

Compensation Currency Selection

Conrm the currency associated with aworkforce compensation component.

Verify the currency of a plan based on acomponent ID.

Compensation Default and Override

Alter the default values populated in acolumn for a workforce compensationplan.

Truncate a salary amount so there are fourdecimals.

Compensation Hierarchy Determination

Locate the hierarchy for an associatedworkforce compensation plan.

Find the name of an employee's managerusing an assignment ID.

Compensation Person Selection

Verify the person selected for anassociated workforce compensation plan.

Check if a person is eligible to be paid by aspecic legislative data group.

Total Compensation Item Formula

Access compensation information thatisn't stored in the other predened itemsource types.

Return multiple variables including aperson's ID, their start date, and their enddate.

Formula Type for Compensation Currency SelectionThe Compensation Currency Selection formula determines the currency associated with a workforce compensationcomponent. You select the formula on the Congure Compensation Components page.

ContextsThe following contexts are available to formulas of this type:

• DATE_EARNED



78

• EFFECTIVE_DATE

• END_DATE

• START_DATE


• HR_TERM_ID

• JOB_ID


• COMPENSATION_RECORD_TYPE

• ORGANIZATION_ID



• PAYROLL_TERM_ID

• PERSON_ID

Database ItemsDatabase items related to Person, Assignment, Salary, Element Entries, Compensation Record, and From and End Datesare available to formulas of this type.

Input VariablesThe following input variables are available to formulas of this type.

Input Value Data Type Required Description

CMP_IV_PLAN_ID

Number

Y

Plan ID

CMP_ IV_ ASSIGNMENT_ID

Number

Y

Assignment ID

CMP_ IV_PERIOD_ID

Number

Y

Period ID

CMP_ IV_ COMPONENT_ID

Number

Y

Component ID

CMP_ IV_ PLAN_START_DATE

Date

Y

Plan Start Date

CMP_ IV_ PLAN_END_DATE

Date

Y

Plan End Date

CMP_ IV_ PLAN_EXTRACTION_ DATE

Date

Y

Plan Extraction Date

CMP_ IV_ PLAN_ ELIG_DATE

Date

Y

Plan Eligibility Date



79


CMP_ IV_ PERFORMANCE_EFF_DATE

Date

Y

Performance Eective Date

CMP_ IV_ PROMOTION_EFF_DATE

Date

Y

Promotion Eective Date

CMP_ IV_ XCHG_ RATE_DATE

Date

Y

Currency Conversion Date


Number

Y

Assignment ID

CMP_ IV_PERSON_ID

Number

Y

Worker ID

Return ValuesThe following return variables are available to formulas of this type.


L_CURR_CODE

Char

N

Currency code from theformula

Sample FormulaThis sample formula determines the currency for a plan based on the component ID.

/*****************************************************************FORMULA NAME : Compensation Currency Selection Formula FORMULA TYPE : Compensation Currency Selection DESCRIPTION: It returns the currency code based on component_id.******************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/INPUTS ARE CMP_IV_ASSIGNMENT_ID (number), CMP_IV_PLAN_ID (number), CMP_IV_PERIOD_ID (number), CMP_IV_COMPONENT_ID (number)/*=========== INPUT VALUES DEFAULTS ENDS======================*/

/*================ FORMULA SECTION BEGIN =======================*/DEFAULT FOR CMP_IV_COMPONENT_ID IS 0l_curr_code = 'XXX' IF (CMP_IV_COMPONENT_ID = 489) THEN (l_curr_code = 'USD') ELSE IF (CMP_IV_COMPONENT_ID = 490THEN (l_curr_code = 'GBP') RETURN l_curr_code /*================ FORMULA SECTION END =======================*/



80

Related Topics

• Formula Compilation Errors

• Formula Execution Errors

• When do I run the Compile Formula process

• Example of Writing a Fast Formula Using Formula Text

Formula Type for Compensation Default and OverrideThe Compensation Default and Override formula determines the default values populated in a column for a workforcecompensation plan. When you congure the worksheet display for a column in the Congure Column Properties page,Default Values section, you can select this formula.

The following predened formulas are available for the eligible salary column for this formula type.

Caution: Use these formulas as samples for testing purposes only. Copy and create your own version of aformula for use in your own compensation plans. Modifying the sample formula might provide unexpectedresults upon upgrade.

Formula Description

CMP_ ELIGIBLE_ SALARY_PRORATION_ DAILY_AVERAGE

Eligible salary calculated by averaging daily salary. Accounts for number of days that a salary isin eect during the workforce compensation cycle evaluation period.

CMP_ ELIGIBLE_ SALARY_PRORATION_ MONTH_END_AVERAGE

Eligible salary calculated by averaging salary on the last day of each month in the workforcecompensation cycle evaluation period. Uses salary on the last day of the evaluation period formidmonth evaluation end dates.

CMP_ ELIGIBLE_ SALARY_PRORATION_ DAILY_ AVERAGE_NINETY_ DAY_MIN

Eligible salary calculated by averaging daily salary. Accounts for number of days that a salary isin eect during the workforce compensation cycle evaluation period. Returns zero for workerswho worked fewer than 90 days.

CMP_ ELIGIBLE_ SALARY_PRORATION_ DAILY_ AVERAGE_USING_FTE

Eligible salary calculated by averaging daily salary adjusted for part-time workers. Accountsfor number days that a salary is in eect and FTE during the workforce compensation cycleevaluation period.

CMP_ ELIGIBLE_ SALARY_PRORATION_ DAILY_ AVERAGE_FOR_JOBS

Eligible salary calculated by averaging salary for the number of days a worker holds a specicjob code on the assignment. Accounts for the number of days that a salary is in eect duringthe workforce compensation cycle evaluation period.


• DATE_EARNED

• EFFECTIVE_DATE



81

• END_DATE

• START_DATE


• HR_TERM_ID

• JOB_ID



• ORGANIZATION_ID



• PAYROLL_TERM_ID

• PERSON_ID




CMP_IV_PLAN_ID

Number

Y

Unique numeric identier forthe workforce compensationplan

CMP_ IV_PERIOD_ID

Number

Y

Unique numeric identier forthe scal calendar period


Number

Y

Unique numeric identier forthe workforce compensationplan component

CMP_ IV_ITEM_NAME

Char

Y

Name for the workforcecompensation plan item

CMP_ IV_PERSON_ID

Number

Y

Unique numeric identier forthe worker associated with theworkforce compensation plan


Date

Y

Date on which the workforcecompensation plan becomesactive



82



Date

Y

Date on which the workforcecompensation plan becomesinactive


Date

Y

Date on which the workforcecompensation plan becomeseligible


Date

Y

Date to use for compensationperformance ratings


Date

Y

Date on which job, grade, andposition changes take eect


Date

Y

Date on which the applicationobtains conversion rates fromthe GL daily rates table


Number

Y

Date to use for assignments



L_ DEFAULT_VALUE

Number/ Char/Date

Y

Default value from theformula. The date should be inyyyy/mm/dd format

L_DATA_TYPE

Char

Y

Data type of the column

Sample FormulaThis sample formula determines the value of a column based on its item name.

/***********************************************************FORMULA NAME : Compensation Default and Override FormulaFORMULA TYPE : Compensation Default and OverrideDESCRIPTION : Defaults the value of a column based on its item_name*************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/INPUTS ARE CMP_IV_PLAN_ID (number), CMP_IV_PERIOD_ID (number), CMP_IV_COMPONENT_ID (number), CMP_IV_ITEM_NAME (text)/*=========== INPUT VALUES DEFAULTS ENDS======================*/



83

/*================ FORMULA SECTION BEGIN =======================*/

DEFAULT FOR CMP_IV_ITEM_NAME IS 'YYYYYYY' L_DEFAULT_VALUE = to_char(0) IF (CMP_IV_ITEM_NAME = 'AmountComp1') THEN (L_DEFAULT_VALUE = to_char(3333))ELSE IF (CMP_IV_ITEM_NAME = 'AmountComp2') THEN (L_DEFAULT_VALUE = to_char(7777))ELSE(L_DEFAULT_VALUE = to_char(-999))RETURN L_DEFAULT_VALUE

/*================ FORMULA SECTION END =======================*/

Related Topics• Formula Compilation Errors• Formula Execution Errors• When do I run the Compile Formula process• Example of Writing a Fast Formula Using Formula Text

Formula Type for Compensation HierarchyDeterminationThe Compensation Hierarchy Determination formula determines the hierarchy for an associated workforcecompensation plan. You select the formula on the Congure Hierarchies page.


• DATE_EARNED

• EFFECTIVE_DATE


• END_DATE

• START_DATE

• HR_TERM_ID

• JOB_ID



• ORGANIZATION_ID



• PAYROLL_TERM_ID



84

• PERSON_ID





Number

Y

Assignment ID

CMP_IV_PLAN_ID

Number

Y

Plan ID

CMP_ IV_PERIOD_ID

Number

Y

Period ID


Number

Y

Component ID

CMP_ IV_PERSON_ID

Number

Y

Worker ID


Date

Y

Plan Start Date


Date

Y

Plan End Date

CMP_ IV_ PLAN_EXTRACTION_ DATE

Date

Y

Plan Extraction Date


Date

Y



Date

Y



Date

Y



Date

Y





85


L_PERSON_ID

Number

Y

Person ID of manager

L_ ASSIGNMENT_ID

Number

Y

Assignment ID of manager

Or


L_ PERSON_NUMBER

Number

Y

Person number of manager

You receive the following error if the formula returns an invalid PERSON_NUMBER and the application can't obtain theASSIGNMENT_ID:

Formula passed in an invalid person number <15465857>. Assignment ID could not be obtained.

Sample FormulaThis sample formula determines the manager of a person when the assignment_id is passed.

/***********************************************************FORMULA NAME : Compensation Hierarchy Determination Formula FORMULA TYPE : Compensation Hierarchy Determination DESCRIPTION: Hierarchy determination fast formula which is based on assignment_id************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/INPUTS ARE CMP_IV_ASSIGNMENT_ID (number), CMP_IV_PLAN_ID (number), CMP_IV_PERIOD_ID (number)/*=========== INPUT VALUES DEFAULTS ENDS======================*/

/*================ FORMULA SECTION BEGIN =======================*/DEFAULT FOR CMP_IV_ASSIGNMENT_ID IS 0 L_PERSON_ID = '0' L_ASSIGNMENT_ID = '0' if (CMP_IV_ASSIGNMENT_ID = 100000008154060 ) THEN (L_PERSON_ID = to_char(-999) //-999 indicates top level //Manager.L_ASSIGNMENT_ID = to_char(-999))ELSE (L_PERSON_ID = to_char(100000008153756)L_ASSIGNMENT_ID = to_char(100000008154060))

RETURN L_PERSON_ID , L_ASSIGNMENT_ID


Related Topics• Formula Compilation Errors• Formula Execution Errors• When do I run the Compile Formula process



86


Formula Type for Compensation Person SelectionThe Compensation Person Selection formula determines the person selected for an associated workforce compensationplan. You select the formula when you run the Start Workforce Compensation Cycle process.


• DATE_EARNED

• EFFECTIVE_DATE

• END_DATE

• START_DATE


• HR_TERM_ID

• JOB_ID



• ORGANIZATION_ID



• PAYROLL_TERM_ID

• PERSON_ID




CMP_IV_PLAN_ID

Number

Y

Plan ID

CMP_ IV_PERIOD_ID

Number

Y

Period ID


Date

Y

Plan Start Date

CMP_ IV_ PLAN_END_DATE Date Y Plan End Date



87



Date

Y



Date

Y



Date

Y



Date

Y



Number

Y

Assignment ID

CMP_ IV_PERSON_ID

Number

Y

Worker ID



L_SELECTED

Char

N

Y or N

Sample FormulaThis sample formula determines if a person is selected for a workforce compensation plan based on theirassignment_id.

/******************************************************************FORMULA NAME : Compensation Selection Formula FORMULA TYPE : Compensation Person Selection DESCRIPTION: Assignment_id based selection fast formula*******************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/INPUTS ARE CMP_IV_ASSIGNMENT_ID (number), CMP_IV_PLAN_ID (number)/*=========== INPUT VALUES DEFAULTS ENDS======================*/

/*================ FORMULA SECTION BEGIN =======================*/DEFAULT FOR CMP_IV_ASSIGNMENT_ID IS 0 l_selected = 'Y'/* 100000008154095 - [email protected] - GBI data*/if (CMP_IV_ASSIGNMENT_ID = 100000008154095) THEN (l_selected = 'N') else



88

(l_selected = 'Y') RETURN l_selected/*================ FORMULA SECTION END =======================*/

Related Topics

• Formula Compilation Errors

• Formula Execution Errors

• When do I run the Compile Formula process


Formula Type for Total Compensation ItemThe Total Compensation Item formula determines compensation information that isn't stored in the other predeneditem source types. You select the formula when you manage compensation items on the Create or Edit CompensationItems page.


• DATE_EARNED

• EFFECTIVE_DATE

• END_DATE

• START_DATE


• HR_TERM_ID

• JOB_ID



• ORGANIZATION_ID



• PAYROLL_TERM_ID

• PERSON_ID


Input VariablesThe following input variables are available to formula of this type.



89


CMP_ IV_PERIOD_ID

Char

Y

Period ID

CMP_ IV_ PERIOD_START_DATE

Date

Y

Statement Period Start Date

CMP_ IV_ PERIOD_ END_DATE

Date

Y

Statement Period End Date

Return ValuesThe following return variables are available to formula of this type.


COMPENSATION_ DATES

Date

Y

One to 15 transaction datesdelimited by semicolon,maximum 250 characters.

VALUES

Char

Y

One to 15 transaction valuesdelimited by semicolon,maximum 250 characters.Must be the same number ofvalues as dates.

ASSIGNMENTS

Char

N

One to 15 transactionassignments delimited bysemicolon, maximum 250characters. Must be the samenumber of assignments asdates. Can return an emptyspace with a delimiter (; ;).

LEGALEMPLOYERS

Char

N

One to 15 legal employerIDs delimited by semicolon,maximum 250 characters.Must be the same number ofassignments as dates. Canreturn an empty space with adelimiter (; ;).

COMPENSATION_ DATES1

Date

Y

Second variable fortransaction dates from 16 to30 if limit of 250 characters isexceeded.

VALUES1

Char

Y

Second variable fortransaction values from 16 to30 if limit of 250 characters isexceeded.



90


ASSIGNMENTS1

Char

N

Second variable fortransaction assignmentsfrom 16 to 30 if limit of 250characters is exceeded.

LEGALEMPLOYERS1

Char

N

Second variable for legalemployer IDs from 16 to 30if limit of 250 characters isexceeded.


Date

Y

Transaction dates from 31 to45.

VALUES2

Char

Y

Transaction values from 31 to45.

ASSIGNMENTS2

Char

N

Transaction assignments from31 to 45.

LEGALEMPLOYERS2

Char

N

Legal employers from 31 to 45.


Dates

Y

Transaction dates from 46 to60.

VALUES3

Char

Y

Transaction values from 46 to60.

ASSIGNMENTS3

Char

N

Transaction assignments from46 to 60.

LEGALEMPLOYERS3

Char

N

Legal employers from 46 to60.

Sample FormulaThis sample formula returns one date and one value based on the worker ID.

/*******************************************************************FORMULA NAME : Total Compensation Simple Item FormulaFORMULA TYPE : Total Compensation Item DESCRIPTION : Returns one date and one value.*******************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/INPUTS ARE CMP_IV_PERSON_ID (text), CMP_IV_PERIOD_START_DATE (date), CMP_IV_PERIOD_END_DATE (date)DEFAULT FOR CMP_IV_PERSON_ID IS '-1'DEFAULT FOR CMP_IV_PERIOD_START_DATE IS '4712/12/31' (date)



91

DEFAULT FOR CMP_IV_PERIOD_END_DATE IS '4712/12/31' (date)/*============ INPUT VALUES DEFAULTS ENDS =====================*/

/*=================== FORMULA SECTION BEGIN =================*/COMPENSATION_DATES = '2005/01/01'VALUES = '500.00'

ASSIGNMENTS = to_char(get_context(HR_ASSIGNMENT_ID,-1))

RETURN COMPENSATION_DATES, VALUES, ASSIGNMENTS


This sample formula returns multiple variables.

/*******************************************************************FORMULA NAME : Total Compensation Multi Item FormulaFORMULA TYPE : Total Compensation ItemDESCRIPTION : Returns multiple variables.*******************************************************************/

/*=========== INPUT VALUES DEFAULTS BEGIN =====================*/ INPUTS ARE CMP_IV_PERSON_ID (text), CMP_IV_PERIOD_START_DATE (date) , CMP_IV_PERIOD_END_DATE (date)/*=========== INPUT VALUES DEFAULTS ENDS =====================*/

/*================= FORMULA SECTION BEGIN =================*/

COMPENSATION_DATES = '2009/01/01;2009/02/01;2009/03/01'COMPENSATION_DATES1 = '2009/07/01;2009/08/01;2009/09/01'COMPENSATION_DATES2 = '2009/10/01;2009/11/01;2009/12/01'COMPENSATION_DATES3 = '2009/10/01;2009/11/01;2009/12/01'

VALUES = '200.00;200.00;300.00'VALUES1 = '300.00;500.00;500.00'VALUES2 = '500.00;500.00;600.00'VALUES3 = '600.00;600.00;700.00'

/* Returns only first two assignment */ASSIGNMENTS = ';1234567890;1234567890'ASSIGNMENTS1 = '1234567890;1234567890;1234567890'

/* Returns last two assignments */ASSIGNMENTS2 = ';1234567890;1234567890'/* Returns first and last assignments */ASSIGNMENTS3 = '1234567890;;1234567890'

LEGALEMPLOYERS = '0123456789;;0123456789'LEGALEMPLOYERS1 = '0123456789;0123456789;0123456789'LEGALEMPLOYERS2 = '0123456789;0123456789;0123456789'LEGALEMPLOYERS3 = '0123456789;0123456789'

RETURN COMPENSATION_DATES,VALUES,COMPENSATION_DATES1,VALUES1,COMPENSATION_DATES2,VALUES2,COMPENSATION_DATES3,VALUES3,ASSIGNMENTS,ASSIGNMENTS1,ASSIGNMENTS2,ASSIGNMENTS3,LGALEMPLOYERS,LEGALEMPLOYERS1,LEGALEMPLOYERS2,LEGALEMPLOYERS3


Related Topics• Formula Compilation Errors• Formula Execution Errors• When do I run the Compile Formula process• Example of Writing a Fast Formula Using Formula Text



92


Chapter 8Formulas for Benets

93

8 Formulas for Benets

Overview of Benets FormulasUse formulas to congure your plan design to the requirements of your enterprise. They provide a exible alternative todelivered business rules for such purposes as:

• Date calculations, such as:

◦ Enrollment start and end dates

◦ Rate or coverage start and end dates

◦ Waiting periods and enrollment periods

◦ Action item due dates

• Calculations of rate and coverage amount, minimum and maximum, or upper and lower limits

• Certication requirements

• Partial month and proration calculations

• Eligibility and participation evaluation

For example, you can write a formula to calculate benets eligibility for those cases where the provided eligibility criteriadon't accommodate your particular requirements.

Benets Fast Formula Reference GuideThe Benets Fast Formula Reference guide explains some of the most frequently used benets formula types. Allformula types explained in the guide include sample code, contexts, database items, input variables, and returnvariables. For more information, see Benets Fast Formula Reference Guide (1456985.1) on My Oracle Support athps://support.oracle.com.

Related Topics

• Guidelines to Test Benets Formulas

http://www.oracle.com/pls/topic/lookup?ctx=fa20b&id=0B6D2642457A6B57E05362C3F00A92CE


Chapter 8Formulas for Benets

94


Chapter 9Formulas for Time and Labor

95

9 Formulas for Time and Labor

Formulas and Types of Time Rule TemplatesUse formulas with time rule templates to create a variety of rules. For example, the template Period Maximum HoursTemplate uses the WFM_PERIOD_MAXIMUM_TIME_ENTRY_RULE formula to compare reported time categoryhours to dened maximum hours. Rules created with the template can specify all or certain time categories and denedierent maximum hours, such as 8 or 12.

This gure shows how to use the formulas to create rule templates. Then, you create rules using the templates andcombine the rules into rule sets for worker time setup and device processing proles.

FormulaTime Calculation RulesTime Device RulesTime Entry RulesTime Submission Rules

Time Repository Rule TemplateYou must select a formula when creating a template.

Time Repository RuleYou must select a rule template when creating a rule.

Time Repository Rule SetCollect related rules and rule sets

Create formulas using the Manage Fast Formulas task in the Setup and Maintenance work area. This task is part of theSetup and Maintenance work area, Workforce Deployment oering.

FormulasFormulas contain:

• Logic for processing or calculating time

• Parameters that enable rules to pass values to the formula for use in calculations

• Outputs that the formula uses to return calculation results to the rules

You can use a single formula in multiple rule templates.



96

Rule TemplatesRule templates make it easy to adapt a formula for use with dierent rules. The formula parameters and outputs areeasy to identify and congure in a template. You don't have to work with the whole formula statement to gure outwhat details you must change to achieve a particular result.

When you create a rule, you select a template to use rather than a formula. The template automatically populates thedescription of all outputs and helps you enter correct parameter values. You can create multiple rules from a singletemplate, varying the parameter and output values of each rule.

The rule template ensures that:

• The parameters are of the correct parameter type.

• The output uses only specic time aributes.

• The correct number of outputs is associated with the formula results.

Formula and Template TypesThe formula type determines the template type. This table lists and describes formula types that you can use whenconguring templates to create time repository rules.

Formula and Template Type Description Example Rule Usages

Time calculation

Creates or updates time card entries anduses the data to create calculated resultsbased on formula logic.

Handle overtime or premium pay byupdating reported time or creatingadditional calculated time.

Time device

Evaluates time events imported from timecollection devices and creates time entryexceptions.

Create time entry exceptions for entriesaected by reported time outside thespecied grace period.

Time entry

Validates time card entries and generatesa message with a dened severity.

When reported time exceeds a speciedweekly maximum, display the speciedmessage.

Time submission

Determines when to automatically saveand submit time card entries created withtime events imported from time collectiondevices.

• Automatically save a time card aftereach Out application event.

• Automatically submit a time cardafter receiving the Out applicationevent for the last scheduled shift ofthe week.

Time and Labor Fast Formula Reference GuideThe Time and Labor fast formula reference guides explain how to use Fast Formula with Time and Labor. These guidesprovide the contexts, database items, and parameters for the formula types used in Time and Labor. They also providesample formulas and the xed parameters, valid functions, and outputs for each.



97

For more information, see Time and Labor Fast Formula Reference Guides (1990057.1) on My Oracle Support at hps://support.oracle.com.



98


Glossary

99

Glossary

absence type

A grouping of absences, such as illness or personal business that is used for reporting, accrual, and compensationcalculations.

accrual absence plan

A benefit that entitles workers to accrue time for the purpose of taking leave.

assignment statement

A statement that formulas use to set a value for a local variable.

balance

Positive or negative accumulations of values over periods of time, typically generated by payroll runs. A balance cansum pay values, time periods, or numbers.

database item

An item of information with special programming attached, which formulas and HCM extracts use to locate and retrievethe data.

element

Component in the calculation of a person's pay. An element may represent a compensation or benefit type, such assalary, wages, stock purchase plans, pension contributions, and medical insurance.

fast formula

A simple way to write formulas using English words and basic mathematical functions. Formulas are genericexpressions of calculations or comparisons that repeat with different input values.

globals

Store values that are constant over a period of time. You can reference them in several formulas. Examples include thename of a rate, a specific date, or a company term.

local variable

A variable that you use in only one formula. You can change the value of a local variable by assigning a value in anassignment statement.

object group

User-defined set of elements or people that restrict the items you want to include in various processes and reports.


Glossary

100

qualification absence plan

A benefit that entitles workers to paid leave time as a result of an event, such as childbirth, illness, or injury.

return statement

A statement that formulas use to return values in local fast formula variables.

time collection device

A hardware device or software method used to collect time reporting data. Devices include true swipe clocks, acomputer or tablet, a kiosk with a touch screen, a cash register that collects in and out times, a badge reader, and abiometric recognition device.

time event

A single In or Out time transaction reported using a time collection device.

resources cloud oracle global human · 2010. 1. 1. · oracle global human resources cloud using...

Documents