SF Rules Engine AdminGuide

(1)

SuccessFactors HCM Suite

August 2014 Release

Document Version: 1.0 - August 22, 2014

Configuring Business Rules in

SuccessFactors

(2)

1 Overview

1.1 About Configuring Business Rules

You can configure the business rule logic for various modules and features using the Rules Engine.

You can configure business rules that cover legal regulations ('The FLSA status is required for employees working in the USA'), company policies ('All employees moving to the London office get a compensation for the high cost of living'), or other requirements. These requirements vary from customer to customer, and also depend on how the customer has set up the system, so the rules cannot be delivered as 'out-of-the-box' rules, but have to be highly configurable. The Rules Engine is a tool that allows you to create such customer-specific rules. You define the business rules in the Rules Engine and the system executes these rules during runtime.

Technically, the Rules Engine is based on the Metadata Framework (MDF), but uses its own user interface (UI) in the Administration Tools.

1.2 Who configures business rules using the Rules Engine?

There are two main areas that use the Rules Engine to create rules: Employee Central (EC) and the Metadata Framework (MDF).

Both areas use different types of data objects, so you have to distinguish the following: ● EC Objects

These are objects that are delivered for Employee Central to set up company and employee data. They comprise person objects, employment objects, and foundation objects. Take a look at the Employee Central Implementation Handbook for a list of all these objects.

● MDF Objects

These are objects that are created in the Metadata Framework (MDF). As these can be used to define company data as well as employee data, they are also called 'generic objects' (GO). MDF objects are created by:

○ Customers

The customer can enhance the business objects and their functionality delivered by creating customer-specific objects. For example, the customer can create customer-customer-specific foundation objects.

○ Development Teams

Development teams use MDF objects for new features like Time Off, Position Management and so on, where the rules have to be highly configurable so that customers can adapt them to their very specific requirements. It is recommended that you stick to the rule examples that are described in the

corresponding handbook of the feature, as these have been tested thoroughly. You can find a list with features and modules that use rules under Module-Specific or Feature-Specific Rules.

(7)

2 Use Cases for Configuring Business Rules

Using the Rules Engine

2.1 Workflow

You can define rules that automatically determine the right workflow when the manager or employee changes employee data. To achieve this, you create a workflow foundation object and assign it to the rule in the Rules Engine UI.

Note

The use of workflows in the Rules Engine is currently only supported for MDF objects.

You can find more information about workflows in the Metadata Framework Implementation Handbook, and an example in the Position Management handbook.

2.2 Propagation

You can define propagation rules to have the system automatically copy over the data from one field to another field. This way you can have the same data in several places of the system, while keeping just one data record.

Note

For EC objects, you can also use the HRIS propagation XML to propagate values. However, you can only propagate values from foundation objects to employment objects. This limitation does not exist in the Rules Engine.

Here are some examples for typical use cases:

● Example 1: Update Job Codes in Employee Central IF…

the job code is changed in Employee Central THEN…

retrieve all the job-code-related data from the job-related foundation objects to update the data in the Employee Central

● Example 2: Propagate FLSA Status IF…

the country is USA

AND the job classification is changed THEN…

propagate the FLSA status to jobInfo ● Example 3: Propagate Standard Hour

IF…

the legal entity is changed in Employment Info THEN…

(8)

propagate the standard hour to Employment Info ● Example 4: Propagate Job Code to Position

You can find an example of how to propagate the job code to the Position MDF object in the Position Management handbook.

2.3 Calculation

You can define rules that automatically perform calculations using the various functions the Rules Engine supports.

Here are some examples for use cases. To achieve these use cases, you can make use of mathematical functions as well as time-related and date-related functions. You can find more information about the various functions available under Function Groups.

● Example 1: Age/Year of Service

To get an employee's current age, you can calculate the difference between the current date and the

employee's birth date. You can find an example rule in the Employee Central Implementation Handbook under Setting up configurable rules.

● Example 2: Time in Job

You want to calculate an employee's time in the job, following the calculation:

Number of years/months/days = current date - start date of the current job classification ● Example 3: EEO Report

To fulfill equals employment opportunity (EEO) requirements, you want to calculate the following: Months remaining on visa = Expire date - current date

2.4 Validation

You can use validation rules to let the system check the user's input before saving. You can set a field to mandatory, or you can trigger error messages.

● Example 1: Setting a Field to Mandatory IF...

the country is USA THEN...

the FLSA status is required

● Example 2: Displaying Error Message IF...

the national ID is not entered THEN...

the message 'Please enter the national ID' is displayed

(9)

2.5 Time Off

Time Off is a component used in Employee Central to handle all types of absence, such as vacation, sick leave, and moving house.

You can update the employee’s vacation days based on the year of service, for example. You can find rule examples in the Time Off handbook.

2.6 Eligibility

You can define which employees should be included in a bonus plan or compensation planning form. To achieve this, you have to integrate the modules Variable Pay or Compensation with Employee Central.

● Example for a Variable Pay Eligibility Rule IF...

the employee was hired on or after January 1, 2008 AND belongs to the Business Unit 'Seoul-Korea' AND has either the job code 'HR Receptionist' OR the job code 'Operations Director'

THEN...

this employee should be eligible (for a variable pay program or bonus plan) ● Example for a Compensation Eligibility Rule

IF...

the employee type does not equal Contract, Temporary or Union AND the employee is regular

AND the rate type is 'Hourly' and 'Salaried' AND the hire date is after 10/01/2010 AND the rehire date is after 10/01/2010 AND the employee status is Active or STD THEN...

this employee should be eligible (for a specific compensation form)

2.7 Defaulting Values

You can define default values for specific fields. Here are some typical use cases:

● Example 1: Default National ID

When the Admin adds a new employee, the national ID is filled with default values (for example, Is Primary: Yes). You can find an example rule in the Employee Central Implementation Handbook.

● Example 2: Default Employment Details

(10)

If the Admin adds a new employee for the company COMP_USA, the employee is automatically eligible for stock, and the initial stock grant is set to 200. You can find an example rule in the Employee Central Implementation Handbook.

2.8 Module-Specific or Feature-Specific Rules

You can find more information about rules that are specific to modules or features in the following handbooks or guides:

This handbook/guide... Describes how to configure rules to:

Employee Central Implementation Handbook Default values, raise messages, and send alerts and no tifications to workflow approvers. See chapters... ● Setting up configurable rules

● How do you set up alerts and notifications - Set up

alerts and notifications using rules

...of the Employee Central Implementation Handbook. Position Management Handbook Propagate job code fields to Position Management Time Off Handbook Define accrual rules and accrual eligibility

Advances Implementation Handbook Define eligibility rules for Advances Employee Central - Compensation Integration Hand

book

Define eligibility rules for compensation plans Employee Central - Variable Pay Integration Handbook Define eligibility rules for variable pay programs and

bonus plans

Mass Changes Update employee fields after a reorganization in a legal entity

Note

Mass Changes uses its own user interface (UI) for creating mass change rules.

(11)

3 Before Configuring Business Rules

There are some settings you need to make before you can configure business rules using the Rules Engine.

3.1 Assigning Role-Based Permissions

You can only create rules if you have the corresponding permissions.

Procedure

Here's how you assign the corresponding permissions for creating rules: 1. Go to Administration Tools.

2. In the Manage Employees portlet, select Set User Permissions Manage Permission Roles .

3. On the Permission Role List page, under Permission Role, click the permission role for which you want to manage the permissions.

The Permission Role Detail page opens.

4. In the Permission settings section, click the Permission… button to specify the permission you want to assign to the role.

The Permission Settings window opens.

5. In the Administrator Permissions section, click on Metadata Framework. 6. Select all the checkboxes on the right side of the dialog.

Here's some information on what the permissions are used for: ○ Configure Object Definitions

You need this authorization to be able to create rule types and lookup tables. ○ Configure Business Rules

This is the only permission used directly for the Rule Engine. You need this authorization to be able to access the Rules Engine UI.

○ Manage Data

You need this authorization to be able to create MessageDefinitions for raising messages. You need this authorization also to be able to create Sequence objects for defining sequences. Both MessageDefinitions and Sequence objects are MDF objects.

○ Import permission on Metadata Framework

You need this authorization to be able to import and export data for generic objects or business rules using the Import and Export Data link in the Administration Tools.

7. Save your changes.

(12)

3.2 Creating Rule Types

You have to assign a rule type to every rule you create.

Procedure

To create a rule type:

1. Go to Administration Tools.

2. In the Company Processes & Cycles portlet, select Company Settings Configure Object Definitions . 3. Click Search: Picklist and select RuleType (RuleType) from the dropdown list.

4. Click the Insert New Record button. 5. As Effective Start Date, enter 01/01/1900.

If you enter a later date, you have to keep in mind that effective-dated rules only work if the rule type is active on or before the date when the rule becomes effective. For example, if you change the Job Info record in the past, but the rule type is only valid as of today, the rule is not triggered.

6. In the Values section, enter an external code for the rule type you want to create.

When you create rules for the following modules or features, it is important that you stick to the spelling and capitalization of the external code of the rule type, as they have a specific function:

For this module or fea

ture… …enter exactly this external code: Here's why:

Compensation, inte grated with Employee Central

compensationEligibility From the compensation screens for eligibility rules, the user can select only the rules assigned to this rule type.

Variable Pay, integrated with Employee Central

varpayEligibility From the variable pay screens for eligibility rules, the user can select only the rules assigned to this rule type.

Mass Changes (in Em ployee Central)

massChange You can create rules on the Mass Changes page.

For all other use cases, you can create your own rule types even if there is no specific behaviour defined for them yet. However, we suggest you use the rule type to sort the rules according to their purpose, for example, to differentiate Time Off rules from Position Management rules.

7. Enter a label.

8. Select the status Active. 9. Save your changes.

(13)

3.3 Setting Up Employee Central

When you want to set up rules for Employee Central, you need to have set up the following before you can create rules for EC objects:

● Corporate Data Model ● Succession Data Model ● Country-specific data models ● Picklists

● Foundation and employee data ● Business Configuration UI (BCUI)

Note

The Business Configuration UI allows you to assign rules to employment and person objects from the Administration Tools. See also: Assigning a Rule to an EC Object in Administration Tools.

For more information, please refer to the Employee Central Implementation Handbook.

3.4 Creating MDF Objects

When you want to set up rules for MDF objects, such as for Position Management, Time Off, or for customer-specific MDF objects, you need to have set up the MDF objects for these features before you can create rules for them.

For more information, please refer to the module-specific or feature-specific handbooks or guides, and the Metadata Framework Implementation Handbook.

(14)

4 General Limitations

Here's a list of the general limitations that apply to the Rules Engine at the moment: No localization of decimal formats

Currently, there is no localization of decimal formats. That means that, irrespective of the logon language, you always have to use the US format when you enter decimal numbers in a rule (for example, 0.2 - using a dot to indicate the decimal).

No test run

Currently, there is no test run tool that helps you prevent or find errors that would cause the rule to fail. Refer to Common Errors for some tips and tricks on how to prevent errors.

(15)

5 Business Rules

5.1 What are business rules?

Business rules are a way to add application logic to determine the outcome of a change made to particular data in the system. Rules follow the logic 'If this data is changed in a certain way, then the system reacts in this way.' Here is an example for a rule in plain language:

IF…

the company is SAP_USA

AND the employee is eligible for stock THEN…

the initial stock grant is set to 200.

This is what this rule looks like in the system:

A rule consists of the following parts:

● Information about the rule object itself (Rule ID, Rule Name, Rule Type)

● Objects and fields that determine what can be defined in the rule (defined by Base Object, Manage Parameters)

● IF statement

You can enter only one IF statement, but you can add multiple conditions in one IF statement. You can also add ELSE IF statements (see below).

● THEN statements

You can add several THEN statements for one rule. ● ELSE statements

You can add several ELSE statements for one rule. The ELSE statement follows the THEN statement (IF - THEN - ELSE).

● ELSE IF statements

You can add several ELSE IF statements for one rule. The ELSE IF statement follows the THEN statement.

(16)

In the following chapters, you can find more information about the different parts of a rule.

5.2 What are base objects?

Base objects are the starting point for your rule. They correspond mainly to the data objects available in the system, which are either EC objects (foundation objects, employment objects, or person objects) or MDF objects. The base object defines what kind of input you can use for the rule. You can use the fields, attributes, and related data objects of the base object as input.

For example, if you want to create a rule that is triggered when the employee status is changed, you choose Job Information as base object, as the employee status field is part of the Job Information EC object.

Note

To find out which fields are part of which EC object (which corresponds to an HRIS element), refer to the data object tables of the Employee Central Implementation Handbook.

To find out which fields are parts of which MDF object, you can look up the object in the MDF UI.

What types of base objects exist?

Here's a list of the base objects you can choose from:

Base object Description

EC object (person or employ ment object)

For example:

● Compensation Information ● Job Information

These base objects refer to HRIS elements that are displayed as portlets on the user interface of Employee Central (EC). They correspond to the person and employment objects used in EC. The names of these base objects are de rived from the HRIS-element labels in the Succession Data Model. You can find a complete list of these HRIS elements and their standard labels in the Employee Central Implementation Handbook, under Setting up the Succes sion Data Model.

Person and employment objects are used to store employee data. Foundation object, for example:

● Cost Center ● Department

These base objects refer to HRIS elements that can be defined on the Manage Organization, Job and Pay Structures page. The names of these base objects are derived from the HRIS-element labels in the Corporate Data Model. You can find a complete list of these HRIS elements and their standard labels in the Employee Central Implementation Handbook, under Setting up the Cor porate Data Model.

Foundation objects are used to store company data.

(17)

Base object Description

Employee Information This base object refers to the Add New Employee page. It is a composite of the different EC objects that are displayed on this page. Rules that use this base object are only triggered for changes made from the Add New Employee page. [EC object] Model

([person or employment object] Model)

For example:

● Compensation Information Model

● Job Information Model ● Personal Information Model

The Model base objects are used to set field properties for EC objects (for ex ample, making a field mandatory, or hiding fields). Each EC object is defined once as a base object, and then as a Model base object. In addition, there is a Model base object for changes made from the Add New Employee page (Employee Information Model).

MDF objects, for example: ● Position

● Advance

● Alternate Cost Distribution

All MDF objects existing in the system are listed here as base objects. They refer to:

● Features that are based on the Metadata Framework, like Position Man agement, Advances, and so on

● MDF objects created by the customer, for example, to be used as custom foundation objects

For more information about how base objects are used in rules, see Creating a Rule with EC Objects.

5.3 How do you add objects that are not related to the base

object?

You can create rules that span across several data objects, even when these have no relationship with the base object. This is like a cross-reference to an unrelated data object.

How you add additional objects depends on whether the object you want to add is an EC object or an MDF object.

5.3.1 Adding MDF Objects

You can add MDF objects that are not related to the base object using the Manage Parameters link in the Rules Engine.

Procedure

(18)

2. In the Company Processes & Cycles portlet, select Company Settings Configure Business Rules . 3. You can either:

○ Create a new rule by clicking Create New Rule.

○ Search for an existing rule, and edit the rule by clicking Take Action Make Correction . 4. Click the Manage Parameters link:

5. In the dialog box that opens, click Add New Parameter.

6. In the Code field, enter a unique external code for the data object you are adding.

For module-specific or feature-specific rules, you often have to stick exactly to the code that the development team has used in their coding. Refer to the corresponding handbooks for more information.

7. In the Name field, enter a name or description for the data object. This does not have to be unique. For module-specific or feature-specific rules, you often have to stick exactly to the name that the development team has used in their coding. Refer to the corresponding handbooks for more information. 8. In the Object field, select the MDF object you want to reference to. Here's an example, where you add the Alert

MDF object:

9. Click Apply.

Results

The object you added now shows up in the left expression at the bottom of the dropdown list as in this example, where the MDF object Alert was added:

(19)

5.3.2 Removing MDF Objects

You can remove MDF objects that you have added to an unrelated base object using the Manage Parameters link. This only removes the MDF object from the dropdown lists used to navigate to the data objects and fields in the Rules Engine, it does not delete the MDF object.

Procedure

2. In the Company Processes & Cycles portlet, select Company Settings Configure Business Rules . 3. Search for the corresponding rule, and edit the rule by clicking Take Action Make Correction . 4. Click the Manage Parameters link:

(20)

5. In the dialog box that opens, click the Remove icon next to the MDF object that has been added to the rule. 6. Click Apply.

Results

You can no longer navigate to the MDF object and its fields that are not related to the base object.

5.3.3 Adding EC Objects

You can define cross-portlet rules to determine that the change in one portlet (for example, Job Information) leads to a change in another portlet (for example, Compensation). You use the Employment Details object to navigate from the base object to an unrelated EC object.

Here's an example of such a rule where the pay component is pro-rated:

On the UI, the change happens in the Job Information portlet, but the update of fields is done in the Compensation portlet. In the IF or THEN statements, you select first the Employment Details object and then the corresponding EC object that is not related to the base object.

Please note the following limitations for cross-portlet rules: ● You have to use an onSave event.

(21)

○ Employment Details (employmentInfo HRIS element) ○ Job Information (jobInfo HRIS element)

○ Compensation Information (compInfo HRIS element) ○ Compensation (payComponentRecurring HRIS element) ○ Spot Bonus (payComponentNonRecurring HRIS element) ○ Job Relationships (jobRelationsInfo HRIS element) The following applies for all other event types or data objects:

The THEN condition of the rule has to refer to a field that is part of the current entity, meaning the HRIS element that you assign the rule to in the data model. The IF condition can refer to data objects or fields that are not part of the current entity itself, which means it can refer to some HRIS element other than the one the rule is assigned to in the data model.

Example:

● Base Object: Employment Details

● IF condition: JobInformation.company is equal to USA

(Note that Job Information is a different HRIS element than Employment Details.) ● THEN condition: Eligible for Stock is equal to Yes

(Note that Eligible for Stock is an HRIS field of the Employment Details HRIS element. You should not select a different HRIS element, such as JobInformation.EventDate, because such a rule would not be triggered.)

5.4 What are rule types?

Rule types are a way to sort the rules into different groups. Development can then add logic for specific rule types in the coding. At the moment, rule types are used for filtering the rules that are displayed in specific modules or features.

When you create rules for the following modules or features, it is important that you stick to the spelling and capitalization of the external code of the rule type, as they have a specific purpose:

For this module or fea ture…

…enter exactly this exter nal code:

Here's why:

Compensation, integrated with Employee Central

compensationEligibility From the compensation screens for eligibility rules, the user can select only the rules assigned to this rule type. Variable Pay, integrated

with Employee Central

varpayEligibility From the variable pay screens for eligibility rules, the user can select only the rules assigned to this rule type. Mass Changes (in Em

ployee Central)

massChange You can create rules on the Mass Changes page.

For all other use cases, you can create your own rule types even if there is no specific purpose defined by

development for them yet. However, we suggest you use the rule type to sort the rules according to what they are used for, for example, to differentiate Time Off rules from Position Management rules.

See also Creating Rule Types for information about how to create a rule type.

(22)

5.5 What is effective dating?

In business rules, effective dating means entering a date from which you want the rule to take effect. You do this in the Start Date field of a rule. Here's an example:

You need to note a few things about effective dates:

● When you create a new rule, the system defaults January 1, 1900, as the effective date.

● If you have rules in your system from an earlier release and upgrade to a later one, a migration script runs automatically, setting the effective date in your rules to January 1, 1900.

You can overwrite the default effective date with the date that suits your requirements.

(23)

6 IF, THEN, and ELSE statements

6.1 What are IF statements?

IF statements are the part of the rule that describe which condition has to be met before the system actions defined in the THEN statement are executed.

Is it possible to have a rule without IF statements?

It is possible to create a rule without IF statements by selecting the Always True checkbox. This removes all IF conditions.

For example, if you want to default values or set field properties that are displayed to the user as soon as the user opens a page, you do not need to enter an IF statement. Here's an example:

(24)

6.2 What are THEN statements?

THEN statements define how the system reacts to the conditions contained in the IF statement of the rule. For example, an error message is raised, a field is set to a specific value, or new data is created.

Is it possible to have a rule without THEN statements?

It is possible to create rules that have only IF statements if the system's reaction is defined by a module or feature. For example, in eligibility rules for variable pay, you want to filter the employees that are eligible to take part in a variable pay program or bonus plan. Such a rule consists only of IF conditions as in this example:

IF...

the employee was hired on or after January 1, 2008 AND belongs to the Business Unit 'Seoul-Korea' AND has either the job code 'HR Receptionist' OR the job code 'Operations Director'

THEN...

this employee should be eligible (for a variable pay program or bonus plan)

For which variable pay program or bonus plan the employee is then eligible for is defined in the variable pay module, therefore you do not enter a THEN statement in the rule itself.

6.3 What are ELSE statements?

ELSE statements define how the system reacts if the IF condition is not true. The THEN statement is then skipped and the system executes what is defined in the ELSE statement.

ELSE statements allow you also to combine multiple rules in the same rule. For example, you can combine the following two rules into one using the ELSE statement:

First rule: IF Country = USA

THEN set EEO Category to EEO-US1 Second rule:

IF Country is not equal to USA THEN set Notes = Non-USA Combined to one rule: IF Country = USA

(25)

THEN set EEO Category to EEO-US1 ELSE set Notes = Non-USA

Here's another example, showing what a rule in Time Off might look like. It shows that employees in the USA get 12 days of a particular leave type. Employees in other locations get 25 days.

Is it possible to have a rule without ELSE statements?

You only use ELSE statements if you want to define how the system should react if the IF condition is not met. If you do not define an ELSE statement, and the IF condition is not met, the rule is not executed.

(26)

6.4 What are ELSE IF statements?

ELSE IF statements allow you to combine several conditions in the same rule. Only the statements following the first condition that is true are executed. All other statements are skipped.

Here's an example:

6.5 Left Expression

A left expression is the part of a rule statement that is compared to the right expression. In the dropdown menu of the left expression, you can select:

● Data Related to the Base Object This can be one of the following:

○ Fields assigned to the base object as configured in the data model (for EC objects) or the object definition (for MDF objects)

(27)

Note

You can select only fields that have been defined as visible.

○ Data objects and their fields that have one-to-one or one-to-many relationship with the base object These are indicated by a plus sign next to the data object.

Example: You have selected Time Account as base object. In the left expression, you can navigate to the data object Time Account Details, as this has a one-to-many relationship with Time Account. Other related data objects are Time Account Type and User.

● Functions

Functions are used to set up more sophisticated rules that include mathematical calculations and formulas, for example. You can identify functions by the brackets that follow the function name; for example, Add(). You can find all available functions under Function Groups.

● Additional MDF Objects

MDF objects that have no relationship with the base object are listed at the bottom of the dropdown list as in this example, where you reference the Alert MDF object:

(28)

You have to add the data object that is not part of the base object to be able to refer to it in the rule. For information about how this is done, refer to Adding MDF Objects.

● Current User

This option is only available for EC objects. The user information is derived from the base object. For example, if the base object is Job Information, then the current user for the Job Information is passed to the Rules Engine as part of the base object.

Select Context to navigate to the current user as in this example:

● Effective Date

This option is available for those EC objects that are effective dated, as well as for all MDF objects.

(29)

Select Context to navigate to the effective date as in this example:

6.6 Right Expression

A right expression is the part of a rule statement that is compared to the left expression. In the dropdown menu of the right expression, you can select:

● Field Type

Select the field type when you want to enter or select a specific value. In our example, you select the Date field type and then a specific date:

● Fields assigned to the base object that have the same field type as the left expression

Note

You can select only fields that have been defined as visible.

● Functions that are available for the field type of the selected left expression

Functions are used to set up more sophisticated rules that include mathematical calculations and formulas, for example. You can identify functions by the brackets that follow the function name; for example, Add(). You can find all available functions under Function Groups.

● Additional MDF Objects

MDF objects that have no relationship with the base object are listed at the bottom of the dropdown list as in this example, where you reference the Alert MDF object:

(30)

You have to add the data object that is not part of the base object to be able to refer to it in the rule. For information about how this is done, refer to Adding MDF Objects.

○ Current User

This option is only available for EC objects. The user information is derived from the base object. For example, if the base object is Job Information, then the current user for the Job Information is passed to the Rules Engine as part of the base object.

Select Context to navigate to the current user as in this example:

○ Effective Date

This option is available for those EC objects that are effective dated, as well as for all MDF objects.

(31)

Select Context to navigate to the effective date as in this example:

● Null

Select Null as in this example when you want to set the field values back to null:

6.7 Comparing Left and Right Expressions

You can select comparative operands for a rule statement to define the relationship between the left and the right expression of a rule statement.

The following comparative operands are supported:

This comparative operand... Is supported for these field types:

Is equal to All field types

Is not equal to All field types

Is greater than: > Date, Number, Decimal

(32)

This comparative operand... Is supported for these field types:

Is less than: < Date, Number, Decimal

Is greater than or equal: >= Date, Number, Decimal Is less than or equal: <= Date, Number, Decimal

6.8 Collection Filters

Collection filters are used to get a unique value from a list of values. This is relevant when there is a parent-child relationship between data objects.

Note

Understanding Collection Filters

Imagine you ask for a piece of fruit. However, you do not define what kind of fruit you like, so you cannot influence what you get in the end - it could be a banana, a strawberry, an orange, and so on. But if you ask for a piece of fruit, and then define that this piece of fruit should be an apple, you will get an apple.

In the following business example, Job Relationship is the child of Job Information, which is the parent object. This means you can have multiple Job Relationships for a single employment. You use a collection filter to define which Job Relationship should be used in the rule.

In the Rules Engine, collection filters ask you to select a unique value (Select….where…):

Select the plus sign and make your entry:

This is an example for selecting the pay component for the recurring pay component (Compensation):

(33)

Here's an example for selecting the posting type for Time Account:

How can you prevent errors using collection filters?

If you are too unspecific using the collection filter, then it returns more than one result. The system always picks the first result from this list. Which result is defined as being the first result depends on a SQL statement, so the user cannot control which value is the first one.

Therefore, when creating the rule, make sure the collection filter returns only one value as in the examples we looked at above. In the following, you can see an example of a collection filter that returns a list with many values, because you ask for any amount that is larger than 1, which probably is true for all the posted amounts and thus returns more than one result. Only the first result would be picked for the rule, and the user cannot control which result is the first result. The results following the first result will be ignored. Here's the example of how not to do it:

6.9 Connecting IF Conditions with AND/OR

If you have more than one IF condition in a rule, you can define the relationship of these conditions by adding an AND or OR logical operand. If you have just one condition in the rule, it does not require an AND or OR. You can add logical operands only for IF statements.

Procedure

1. To add an AND or OR connection, click on the context menu of an IF statement and select Add from the dropdown list:

(34)

2. Select the corresponding logical operand. Here's an overview of the available options:

Select this... To do this:

Expression: AND Join IF conditions, using AND as logical operand

Expression: OR Join IF conditions, using OR as logical operand

Expression: Insert Before Add a new IF condition before the currently selected IF condition

Expression: Insert After Add a new IF condition after the currently selected IF condition

Parent And Add a parent AND logical operand

Parent Or Add a parent OR logical operand

3. Add the IF condition that is connected to the IF condition from step 1.

6.10 System Actions for THEN and ELSE Statements

In the THEN and ELSE statement, you define how the system should react when a certain rule condition is met. You select the system action in the output type field of the THEN or ELSE statement.

Here's an overview of the available system actions:

Select this action... To do this:

Set Change the data record for a field to a specific value. For example, you can set the manager to Carla Grant (cgrant).

Raise Message Raise an error message that is displayed to the user. For more information, see Creating a Rule: Raising a Message.

Create _{Create data on the database when the rule is triggered.}

For example, you can define that when the employee's location changes to London, a new pay component is created. See the Employee Central Imple mentation Handbook, under Setting up configurable rules for an example rule. Delete _{Delete data from the database when a rule is triggered.}

For example, you can remove a pay component when the employee moves away from London. See the Employee Central Implementation Handbook, un der Setting up configurable rules for an example rule.

(35)

7 Functions

7.1 What are functions?

A function performs a specific task on the data object or field of a rule. Functions help you to define more complex rules that perform calculations or application-specific tasks.

In the system, you can identify functions by the brackets that follow the function name; for example, Add().

7.2 Mapping of Data Types and Field Types

The field type defines which function you can select for a certain field. For EC objects, this field type differs from the EC object data type for the different HRIS elements that you can find in the Employee Central Implementation Handbook.

Here is a mapping of the EC object data types to the Rule Engine field types, where the column defines the following:

● EC Object Data Type: This is the data type that you can find in the Employee Central Implementation Handbook, in the data object tables. This is based on the database field data type.

● Rule Engine Field Type: This is the field type that is used in the Rules Engine.

● Manual Entry Value for Field Type: This defines what the user can enter or choose from on the Rules Engine UI.

EC Object Data Type Rule Engine Field Type Manual Entry Value for Field Type

String Text String

Boolean Boolean Yes/No

Date Date Date

Double Decimal Decimal

Decimal Decimal Decimal

Big Decimal Decimal Decimal

Long Number Integer

(Picklist) Value Dropdown list for user to select from (Foundation object, for example:

department, division)

Value Dropdown list for user to select from (Enum, for example: Gender, which has

a picklist)

Enum Dropdown list for user to select from

(36)

7.3 Input Parameters for Functions

While the field type of the left expression of a rule defines which function you can select, the function defines the field type of the input parameters.

To find out what input parameters you can enter or select for a specific function, click the dropdown menu next to the entry field, and scroll to the very top where the field type is listed, as in this example:

In our example, the field type is Decimal. So, in general, you can either: ● Select Decimal and enter a decimal:

(37)

● Select a field of the same field type. For example, Shift Percent:

● Select another function that is available for the field type Decimal (you might have to scroll down to see all functions listed):

For some functions, the input parameters are restricted. This is described in the input parameters of the corresponding function.

(38)

● For some fields, you can select Context Current User (at the bottom of the dropdown list):

7.4 Function Groups

To help you find the functions you need to create your rules, we have divided them thematically into groups: These are the function groups:

● Mathematical functions

In this group, you can find functions that help you perform mathematical operations. ● Module-specific or feature-specific functions

In this group, you can find functions that are specific to a module or feature, for example, for the Employee Central module or the Time Off feature.

Caution

Please refer to the module-specific or feature-specific handbooks before using these functions. Especially the features have to be set up in a specific way so you can use these functions.

● String functions

In this group, you can find functions that create specific texts or strings. ● Time-related and date-related functions

In this group, you can find functions that help you calculate or determine dates or periods. ● Other functions

In this group, you can find those functions that do not fit in any of the other groups.

In the following, you can find the available functions sorted by group, and from A-Z within the group. The field type defines for which fields you can select the function.

7.4.1 Mathematical Functions

For fields of type... ...you can use this function: Choose this function to:

Decimal Number

Add/Minus/Divide/Multiply Add, subtract, divide, or multiply values

Decimal Number

Math Expression Define your custom formula

(39)

Decimal Minimum Find the smallest value in a list of values Decimal Opposite Sign Get a value with the opposite sign Decimal

Number

Round Define how values are rounded

7.4.2 Module-Specific or Feature-Specific Functions

Note

For some of these functions, you have to enable the corresponding feature in Provisioning before you can use them on the Configure Business Rules page.

Decimal Amount from Pay Scale Struc ture

Note: Use only when you have defined pay scale structures in Employee Central

Get the amount from the pay scale structure

Decimal Avg FTE for Accruable Period Note: Use only with Time Off

Calculate the average FTE for the accruable period based on calendar days

Decimal Avg FTE for Accruable Period based on Month

Note: Use only with Time Off

Calculate the average FTE for the accruable period based on calendar months

Decimal Avg FTE for Accrual Period Note: Use only with Time Off

Calculate the average FTE for the accrual period of the time account based on calendar days

Decimal Avg FTE for Accrual Period based on Month

Calculate the average FTE for the accrual period based on calendar months

Decimal Calculate Balance

Calculate the balance for a time account on a specific date

Decimal Calculate FTE based on Stand ard Hours

Note: Use only with Position Management

Include positions in standard hours calculation

(40)

Decimal Cap Accrual

Determine the accrual value within the accrual balance limit

Text Currency from Pay Scale Struc

ture

Get the currency from the pay scale structure

Value Frequency from Pay Scale Structure

Get the frequency from the pay scale structure

Text Generate External Code Time Off Note: Use only with Time Off

Generate external code for Accruals in Time Off

Decimal Get Absence Days

Calculate how long an employee has been absent within one year

Decimal Number

Get Completed Calendar Weeks Between ISO

Calculate the number of weeks the employee works in the accrual period

Decimal Number

Get Completed Remaining Cal endar Weeks ISO

Calculate the number of weeks the employee works in the hire period

Text Get Incumbent By Position

Get the user ID of the incumbent of the position

Text _{Get Matrix Position Code By}

Type

Get the matrix position code

Decimal Number

Get Months From Hire Date Tak ing Account Of Threshold Note: Use only with Time Off

Calculate the number of months the employee is work ing in the hire period

Decimal Number

Get Months Taking Account Of Threshold

Calculate the number of months the employee is work ing in the accrual period

(41)

Text _{Get Next Available Manager By} Position

Get the user ID of the next available manager in the po sition hierarchy

Decimal Number

Get Number Of Child Positions Note: Use only with Position Management

Get the number of child positions

Decimal Get Number Of Eligible Days Note: Use only with Time Off

Calculate the number of eligible days

Decimal Number

Get Number Of Months From Hire Date

Calculate the number of months the employee is work ing as of the hire date

Decimal Get Pensionable Salary Note: Use only with Employee Central

Calculate the pensionable salary on a certain effective date

Decimal Get Pensionable Salary with Global Assignment

Note: Use only with Employee Central and Global Assignment

Calculate the pensionable salary on a certain effective date, considering global assignments

Decimal Number

Get Work History Days ADD ALL Note: Use only with Employee Central

Sum up days of all employments (current and previ ous)

Decimal Number

Get Work History Days CONTIN UOUS

Note: Use only with Employee Central

Sum up days of all employments back until a specified event reason

Decimal Number

Get Work History Days CUR RENT

Sum up days of the current employment

Decimal Number

Get Work History Days PREVI OUS

Sum up days of previous employments

(42)

Boolean Is Employee Full Time

Determine whether the employee is full-time on a spe cific date

Boolean Is Position Below User's Position Note: Use only with Position Management

Determine whether a position is below user's position in user's hierarchy

7.4.3 String Functions

Text Concatenate Combine strings to one string

Text Format Combine different objects to a meaningful text

Text Format Number Format numbers following a custom template and se

quence

7.4.4 Time-Related and Date-Related Functions

Text Convert Days To YY/MM/DD Convert a number of days into the format of years/ months/days

Decimal Number

Date Determine the number of the week for a date (US-de fined)

Date Date Plus Add/subtract days or months to/from a given date

Number Day Of Month Determine the number of the month for a specific date Number Day Of Week Determine the number of the weekday for a specific

date Date

Decimal Number

Difference in Calendar Years Calculate the time difference between 2 dates in calen dar years

(43)

Date Decimal Number

Difference In Years Round Down Calculate the time difference between 2 dates in calen dar years, rounding down the result

Date Decimal Number

Difference In Years Round Up Calculate the time difference between 2 dates in calen dar years, rounding up the result

Decimal Number

Get Completed Weeks Between Calculate the number of completed weeks within a pe riod

Date Get First Day Of Month Get the first day of the same month of a specified date

Date Latest Date Get the latest date of two dates

Text Timestamp Current Time UTC

plus Offset Minutes

Create a current or future timestamp in UTC time standard

Date Today Get the date of today

Decimal Number

Week Of Year ISO Determine the number of the week for a date (ISO-de fined)

7.4.5 Other Functions

Number Get Next Value Get next value from a Sequence MDF object

Boolean Is Empty Check if an input field is empty

Text Login User Get the currently logged-in user

All field types Lookup

Note: Use only for MDF objects

Get values from a lookup table (that is stored as MDF object)

Decimal Treat Null As Give a default value for an empty field

7.5 Functions A-Z

In the following chapters, you can find more information about the several functions; the functions are listed A-Z.

(44)

7.5.1 Add/Minus/Divide/Multiply

With these functions, you can perform basic calculations for adding, subtracting, dividing and multiplying values. These functions do not have the limitations that the Math Expression function currently has and can therefore be used to build complex formulas.

Limitations

● You can only use the US format for decimals (using dots, not commas).

● When you combine several of these functions, the system goes through the calculation from top to bottom. It does not consider the convention 'multiplication and division first, then addition and subtraction'.

Use Case

Use Case 1: Base Salary Calculation

The Admin wants the system to automatically calculate the base salary following the formula: Amount or Percentage = 100 + (300/1.5)

This is the corresponding rule:

Use Case 2: T-Rate Calculation

(45)

The T-Rate is a benchmark figure which is calculated when the screen is loaded (as a transient field, that is, an onView rule event).

The Admin wants to calculate the hourly wage derived from the base salary and the weekly hours as in this example rule:

In the above rule, the first calculation gets the annual salary by adding the relevant pay components and

displaying the result in a custom field. In the second step, the annual working hours are estimated by multiplying the weekly hours with 52 weeks (the estimated amount of working weeks in a year). In the third step, the results from the first and second calculation steps are divided to get the hourly wage, which is displayed in another custom field (T Rate).

(46)

The calculation results are displayed in the custom fields as in this example:

You can also find a calculation example for pro-rating a pay component in the Employee Central Implementation Handbook.

7.5.2 Amount from Pay Scale Structure

This function gets the amount from the pay scale structure based on the pay scale level, pay component, and effective date. The pay scale structure is configured in the MDF object Pay Scale Level.

Limitations

Use only if the Pay Scale Group and Pay Scale Level fields are included in the job information.

For more information about how to set up pay scale structures, see the SuccessFactors Employee Central Payroll Integration handbook.

Input Parameters

For this parame

ter... Of typ

e...

Which

is... Make this entry:

Pay Scale Level Tex t

Required Select the pay scale level you want to use. This is usually the value which is entered in the job information.

Pay Component Val ue

Required Select the Value field type, and select the pay component you want to search for in the pay scale structure. Usually, this is the pay component you want to create in the compensation model.

(47)

For this parame ter... Of typ e... Which is...

Make this entry:

Effective Date Dat e

Required Enter or select the effective date you want to use to read the data from the pay scale structure. Usually, this is the event date of the job informa tion.

Use Case

You can create rules that automatically assign the correct pay components to an employee based on the pay scale level and pay scale group you define for that employee.

Here's an example of what such a rule could look like – for the complete process of how to set up such rules, please refer to the SuccessFactors Employee Central Payroll Integration Handbook:

Related Information

Currency from Pay Scale Structure [page 54]

(48)

This function gets the currency from the pay scale structure based on the pay scale level, pay component, and effective date. The pay scale structure is configured in the MDF object Pay Scale Level.

Frequency from Pay Scale Structure [page 63]

This function gets the frequency from the pay scale structure based on the pay scale level, pay component, and effective date. The pay scale structure is configured in the MDF object Pay Scale Level.

7.5.3 Avg FTE for Accruable Period

This function calculates the average full-time equivalent (FTE) as defined in the job information for the accruable period. The accruable period is the period the employee is allowed to get an accrual for. The average calculation is based on the amount of days within the accruable period.

Limitations

Use only with Time Off.

7.5.4 Avg FTE for Accruable Period based on Month

This function calculates the average full-time equivalent (FTE) as defined in the job information for the accruable period. The accruable period is the period the employee is allowed to get an accrual for. The average calculation is based on calendar months, meaning that the average of each month within the accruable period is calculated first. The results lead to an overall average for the accruable period.

Limitations

Use Case

You can find a rule example in the Time Off handbook, under Notes on Rule Functions.

(49)

7.5.5 Avg FTE for Accrual Period

This function calculates the average full-time equivalent (FTE) as defined in the job information for the accrual period of the time account. The accrual period is defined by the time account type.

Limitations

7.5.6 Avg FTE for Accrual Period based on Months

This function calculates the average full-time equivalent (FTE) as defined in the job information for the accrual period of the time account. The accrual period is defined by the time account type. The average calculation is based on calendar months, meaning that the average of each month within the accrual period is calculated first. The results lead to an overall average for the accrual period.

Limitations

Use Case

You can find a rule example in the Time Off handbook, under Notes on Rule Functions.

7.5.7 Calculate Balance

This function calculates the account balance for a time account on a specific date.

Limitations

Use only with Time Off. Please refer to the Time Off handbook before using this function.

SF Rules Engine AdminGuide

SuccessFactors HCM Suite

August 2014 Release

Document Version: 1.0 - August 22, 2014

Configuring Business Rules in

SuccessFactors

Table of Contents

1

Overview

1.1

About Configuring Business Rules

1.2

Who configures business rules using the Rules Engine?

2

Use Cases for Configuring Business Rules

Using the Rules Engine

2.1

Workflow

Note

2.2 Propagation

Note

2.3 Calculation

2.4 Validation

2.5 Time Off

2.6 Eligibility

2.7 Defaulting Values

2.8 Module-Specific or Feature-Specific Rules

Note

3

Before Configuring Business Rules

3.1

Assigning Role-Based Permissions

Procedure

3.2 Creating Rule Types

Procedure

3.3 Setting Up Employee Central

Note

3.4 Creating MDF Objects

4 General Limitations

5

Business Rules

5.1

What are business rules?

5.2 What are base objects?

Note

What types of base objects exist?

5.3 How do you add objects that are not related to the base

object?

5.3.1

Adding MDF Objects

Procedure

Results

5.3.2 Removing MDF Objects

Procedure

Results

5.3.3 Adding EC Objects

5.4 What are rule types?

5.5 What is effective dating?

6

IF, THEN, and ELSE statements

6.1 What are IF statements?

Is it possible to have a rule without IF statements?

6.2 What are THEN statements?

Is it possible to have a rule without THEN statements?

6.3 What are ELSE statements?

Is it possible to have a rule without ELSE statements?

6.4 What are ELSE IF statements?

6.5 Left Expression

Note

6.6 Right Expression

Note

6.7 Comparing Left and Right Expressions

6.8 Collection Filters

Note

How can you prevent errors using collection filters?

6.9 Connecting IF Conditions with AND/OR

Procedure

6.10 System Actions for THEN and ELSE Statements

7

Functions