Configurable rules allow you to define how the system reacts when the user performs a specific action, for example, when changing a specific field, or saving the job information for a newly hired employee. Earlier, you could only default values that the Admin had entered for a foundation object to an employment object using HRIS propagation rules.
Now you can set up configurable rules to do the following:
● Set default values
You can define default values for specific fields.
Example: The OK to rehire field on the termination screen is always Yes by default.
● Set conditional values
You can define which default value is set when a specific condition is met: IF this condition is met, THEN this is how the system should react.
Example: When the Admin selects the business unit ENG, the job classification is automatically set to Engineering.
See Examples for conditional values [page 113].
● Set field properties
You can dynamically default a field as visible or required.
Example: If the company is COMP_USA, the phone extension is always required.
● Display error messages
You can define that an error message is displayed.
Example: The Admin forgot to maintain the national ID for a new employee; the error message National ID is required is displayed. See Example for error messages [page 120].
● Calculate transient fields
You can define transient fields that are calculated “on the fly” when the user opens a page. The calculated values are not meant to be written to the database, as they are not fix values.
Example: The user can see the employee's current age in the system.
What you – or the customer's Admin – have to do to set up configurable rules is to follow this 2-step process:
Step... What do you do? Where do you do it?
1. Create a configurable rule
1. Decide which page in the system is affected and select the base object accordingly.
2. Define IF and THEN conditions for the rule.
Administration Tools:
In the Company Processes & Cycles portlet, select Company Settings Manage Rule Objects .
2. Assign this rule to a specific field or HRIS element
Define if the rule is triggered when loading or saving a page, or when changing a field, for example
● For person and employment objects:
○ Succession Data Model
○ Country-specific Succession Data Model
Note: You can also use the Business Configuration UI to assign the rule to person and employment objects. For more information, see Using the Business Configuration UI to maintain elements of the Succession Data Model [page 57].
● For foundation objects:
Corporate Data Model
When is a configurable rule triggered?
There are different types of rule events that define when a rule is triggered:
● onInit
saveAlert is an event that is only used for setting up workflow notifications. For more information, see How do you set up alerts and notifications? [page 133]
Here you see when to use which rule event type:
Rule is triggered when... Use this rule event type in
data model: Assign the rule event type in
data model to: Use this event type to:
Portlet or page is loaded onInit HRIS element Set field properties (for
example, making fields mandatory, hiding fields), or to default values that should be shown as soon as the user calls up a page
Rule is triggered when... Use this rule event type in
data model: Assign the rule event type in
data model to: Use this event type to:
Portlet or page is saved onSave HRIS element Validate user entries when the
user wants to save the changes
For example, if the user did not enter a mandatory field, an error message is displayed.
Field value is changed onChange HRIS field Trigger rules as soon as the
user makes a change to a field Portlet or page with transient
field is loaded
onView HRIS element Calculate fields that are
transient (that means the result is not a fix value stored on the database, but calculated during runtime when the user calls up the page)
For example, to calculate an employee's age.
Note: Requires an additional onSave rule that sets the transient field back to null.
Portlet or page is opened in
edit mode onEdit HRIS element
onEdit is currently derived from other fields in the user context.
Please note: onEdit is different from onInit: While both are similar in use (to set defaults using rules), onInit is used on the Add New Employee page (if base object is a person or employment object) or the Manage Organization, Job and Pay Structures page (if base object is a foundation object) only, whereas onEdit is used on all other editable pages.
What do you need to do before you set up configurable rules?
1. You use the Rules Engine to define configurable rules. To set up the Rules Engine, you have to:
1. Enable generic objects
For more information, see How do you configure and manage generic objects? [page 89]
2. Configure rule types
In the use case of configurable rules, the rule type has no function, but it is a mandatory field.
For more information on how to create rule types, see https://confluence.successfactors.com/display/
ENG/Rule+Objects .
2. To configure rules that trigger messages, you have to create a generic object called MessageDefinition with the text that the message shall display, as in this example:
To create a MessageDefinition, go to Administration Tools. In the Company Processes & Cycles portlet, select Employee Files Manage Generic Objects .
Note that you have to refer to the external code of this message when you create the configurable rule.
How do you set up configurable rules?
1. Create the configurable rule:
1. Go to Administration Tools. In the Company Processes & Cycles portlet, select Company Settings Manage Rule Objects .
2. Click Create New Rule .
3. Enter the following information about the rule:
● Rule ID: This is the external code of the rule itself. The code has to be unique in the system.
In step 2, you have to refer to this code, so we recommend you note it down.
● Rule Name: This is the name for the rule. It does not have to be unique.
● Base Object: This is a list of data objects that exist in the system. It includes the data objects that correspond to HRIS elements in the Succession Data Model, the Corporate Data Model, as well as generic objects. The names of the HRIS elements listed here correspond to the labels you defined in the corresponding data model.
The base object defines what you can enter in the rule; for example, to set field properties, you have to choose a Model base object. At the same time, the base object defines what event types you can use in a later step when you assign the rule to the HRIS element in the data model. For example, you cannot use onView events for changes done on the Add New Employee screen. Here's a short overview of how base objects, event types and pages in the system belong together:
When the user is on
this page: And you want to trigger the
rule when the user is... Then choose this type of base object:
● Changing a field value (see onChange event)
● Saving a portlet or page (see onSave event)
● Viewing a transient field (see onView event)
● Opening a portlet or page in Edit mode (see onEdit event)
Note: Select a Model base object to set field properties in the rule (for more information, see below).
Add New Employee ● Opening a page or portlet (see onInit event)
● Changing a field value (see onChange event)
● Saving a portlet or page field properties in the rule (for more information, see
About the Model base objects:
You can set the following properties for Model base objects:
○ required: You can make a field required or not by entering true or false accordingly.
○ visibility: You can enter the following values:
○ both: Field is visible and editable.
○ view: Field is read-only.
○ none: Field is not visible on the user interface.
○ previous: Use this property when you want to compare an old value with a new value, for example, when a rule is triggered only when a certain value is changed to a specific new value. You can also define that any data change to a specific field triggers the rule by setting up the rule as follows:
New value is not equal to previous value
For example: FTE.Value is not equal to FTE.Previous Value
When you use previous in the Then condition, do not use Set as output type; it will be ignored by the system, as you cannot change a previous value using the previous property.
○ value: Use this property when you want to combine setting field properties with setting default or conditional values. When you select value, you have to select the corresponding value in the dropdown list when creating the rule.
Current limitations for Model base objects:
● Consider if the onSave event makes sense for setting field properties. For example, a field should be set to mandatory as soon as the user opens a page (then choose the onInit event), or when the user makes certain changes (onChange event), but not when the user saves a change.
● Country-specific fields are currently not supported.
● Rule Type: For configurable rules, there is no function behind this field, so it is up to you if you want to use an existing rule type, or if you want to create an own rule type for configurable rules.
For some modules, like variable pay, the rule type defines that only rules with the rule type varpayEligibility can be selected from the variable pay screens, for example.
4. Enter the IF and THEN conditions for the rule.
You can find some examples for rules further below under Examples [page 111].
Please note the following:
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). However, there are the following limitations:
● You have to use an onSave event.
● In the Then condition, you can only refer to the following employment objects:
○ 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) For all other event types or data objects, the following is valid:
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, that means it can refer to some other HRIS element 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.) 2. Assign this rule to an HRIS field or HRIS element:
1. Download the Succession Data Model or the country-specific Succession Data Model XML file from Provisioning.
2. Open the XML file in an XML editor and add the rule to the corresponding HRIS field or HRIS element after the <label> tag, as in this example:
<hris-element id=”nationalIdCard”>
● event for the event type onChange has to be assigned to the HRIS field; all other event types have to be assigned to the HRIS element.
● rule is the external code of the configurable rule that you have created in step 1.
● In the Succession Data Model, do not add configurable rules for the
userAccountInfo HRIS element. userAccountInfo does not correspond to a portlet on the UI, it is just used to show the user name field on the Add New Employee screen. A rule assigned to this HRIS element would not be triggered.
How do you know to which HRIS element or HRIS field to assign the rule to?
● If the base object is Employee Information or Employee
Information Model, assign the rule to the HRIS element in the XML file that is used in the THEN condition.
● For all other base objects, assign the rule to the HRIS element or HRIS field of the base object.
3. Save your changes.
4. Upload the Succession Data Model XML file in Provisioning.
Examples
Examples for default values
National ID for new hire is defaulted (onInit event)
You want to define that the national ID is already filled with default values when the Admin wants to add a new employee, as shown in this example:
This is the configurable rule you have to create to achieve this system behavior:
● You select Employee Information as the base object because you want these values only to be defaulted when the Admin adds a new employee in the system. The rule will not take effect on other screens.
● You select Always True for the If condition because the values defaulted on the user interface do not depend on a specific user entry or user action.
This is how you assign the rule to the national ID portlet in the Succession Data Model XML file:
<hris-element id=”nationalIdCard”>
<label>National ID Information</label>
<trigger-rule event=”onInit” rule=”ONINIT_NID” />
<hris-field max-length=”100” id=”country” visibility=”both” required=”true”>
...
You select the rule event onInit because you want the default values to show up as soon as the Admin opens the Add New Employee screen, independent of any values that the Admin might add on this page.
Examples for conditional values
Default values are set depending on selected company (onInit event)
You want to define that when the Admin adds a new employee and selects the company SAP_USA in the Job Information portlet, the phone type should be defaulted to Home and the Is Primary field should be defaulted to Yes as in this example:
This is the configurable rule you have to create to achieve this system behavior:
This is how you assign the rule to the Phone Information portlet in the Succession Data Model XML file:
<hris-element id=”phoneInfo”>
<label>Phone Information</label>
<trigger-rule event=”onInit” rule=”INIT_PHONE” />
<hris-field max-length=”100” id=”phone-type” visibility=”both” required=”true”>
...
● You select the rule event onInit because you want the default values to show up as soon as the Admin opens the Personal Information page when adding a new employee, independent of any values that the Admin might add on this page (the company is selected on the pages before and thus can be used to define what shows up when the Personal Information page is opened).
● This rule would not work if you refer to portlets (hris-elements) on the entry screen of adding a new employee in the THEN condition, because the company needs to be selected first before this rule can be triggered.
Default values are set depending on Employment Details (onChange event)
You want to define that when the Admin adds a new employee and selects the company SAP_USA in the Job Information portlet, and Eligible for Stock is set to Yes, the initial stock grant is automatically set to 200 as in this example:
This is the configurable rule you have to create to achieve this system behavior:
This is how you assign the rule to the Initial Stock Grant field in the Succession Data Model XML file:
<hris-element id=”employmentInfo”>
<label>Employment Details</label>
...
<hris-field max-length=”256” id=”initialStockGrant” visibility=”both” >
<label>Initial Stock Grant</label>
<trigger-rule event=”onChange” rule=”EMPL_ONCHANGE” />
...
Selecting the business unit defaults the manager (onChange event)
You want to define that the manager is defaulted when the Admin selects the business unit ENG as in this example:
This is the configurable rule you have to create to achieve this system behavior:
This is how you assign the rule to the Business Unit field in the Succession Data Model XML file:
<hris-element id=”jobInfo”>
<label>Job Information</label>
...
<hris-field max-length=”256” id=”business-unit” visibility=”both” >
<label>Business Unit</label>
<trigger-rule event=”onChange” rule=”JOB_CHN” />
</hris-field>
Default values for compensation information (onSave event)
When the Admin defines that an employee is highly compensated in the Compensation Information portlet and saves this information, the employee is automatically eligible for a company car as in this example of:
This is the configurable rule you have to create to achieve this system behavior:
This is how you assign the rule to the Compensation Information portlet in the Succession Data Model XML file:
<hris-element id=”compInfo”>
<label>Compensation Information</label>
<trigger-rule event=”onSave” rule=”COMP_INFO” />
Automatic generation of external codes for foundation objects (onInit event)
Instead of having the Admin manually create external codes for new foundation objects, you can let the system automatically generate external codes for foundation objects. In this example, the system defines the external codes for the job code foundation object, following a sequence you have defined beforehand.
1. Create a Sequence generic object:
1. Go to Administration Tools.
2. In the Company Processes & Cycles portlet, select Employee Files Manage Data . 3. Select Create New: Sequence.
4. Enter the following:
● externalCode: Enter an external code for the Sequence object that serves as unique identifier.
● externalName: Enter a name or short description for the Sequence object.
● start: Enter the first value of the sequence.
● step: Enter the step width of the sequence that is used to calculate the next sequence number.
For example, if step is 5, and start is 1000, the number sequence would be 1000, 1005, 1010, 1015, and so on.
● current: This field displays the value that will be used as the next sequence number when the Sequence object is called up.
Here's an example:
5. Save your changes.
2. Create a rule like in this example:
Note the following:
● The base object is the foundation object Job Classification.
● The If condition defines when the rule is triggered — in this example, when the Job Code field is empty.
● The Then part of the rule defines that the external codes created by the system follow the template Job
%d:
○ “Job” is the prefix for the number that is taken from the sequence.
○ “Job” is the prefix for the number that is taken from the sequence.