Setting up event-reason derivation rules - EC Implementation Handbook

What are event-reason derivation rules?

When the manager or Admin changes an employee’s data, for example, by increasing the salary or changing the department information, the reason behind this change is normally that an event has taken place in that employee’s professional life. In our example, the event could be a promotion or a transfer to another department. The information about which event lies behind this change is stored in the system for reporting purposes. However, such a change might also include a change to the employee’s status, for example, if the employee leaves the company, the employee status would be changed accordingly to reflect that the employee is no longer an active user in the system.

You can create rules that define the event reason according to what change is done to an employee’s data, so that the system automatically selects the appropriate event reason. Depending on the event reason, the employee status is updated, if necessary.

Why do you want to use event-reason derivation rules?

If you don’t create derivation rules, the user has to manually select the event and the event-reason from the UI every time the user makes a change to the employee data that is linked to an event. However, this is time-consuming and more error-prone, as the employee status depends on the event reason that is selected.

What are events?

Events are occurrences that span the various stages of an employee’s lifecycle from hire to rehire. Technically, events are defined in picklists. Events are predelivered by SuccessFactors; you can’t create new events or change existing ones, except for their labels.

This is a list of events delivered by SuccessFactors:

● Additional Job

● Assignment

● Assignment Completion

● Job Change

● Completion of Probation

● Data Change

● Demotion

● Furlough

● Hire

● Job Reclassification

● Return from Disability

● Return to Work

● Suspension

● Termination

● Transfer

● Add Global Assignment

● End Global Assignment

● Obsolete

● Start Pension Payout

What are event reasons?

Event reasons are defined by the customer. They are used to define more specifically the reason why an event has taken place. For example, the event “Termination” can take place either because the employee’s performance was not sufficient, or because the employee wanted to change company. In this example, if the company wants to differentiate between the two possibilities, you define two event reasons that you could call “Terminated-Performance Issues”, or “Terminated – By Employee”. You can create as many event reasons for an event as you like.

Technically, event reasons are foundation objects. This means that the Admin can create event reasons under Administration Tools, in the Company Processes & Cycles portlet, under Employee Files Manage Organization, Pay and Job Structures , or mass upload data via CSV file under Administration Tools, in the Company Processes

& Cycles portlet, under Employee Files Import Foundation Data .

Are event reasons mandatory?

Yes. Even if a company decides not to create own event reasons for the purpose of narrowing down the reasons why an event takes place, the Admin has to create an event reason for each event that the company uses. This is because the system defines the employee status after an event has taken place by what has been defined in the event reason.

For example, the employee status after the event reason “Terminated – By Employee” is “Terminated”. If the employee status was “Active” before, it will change to “Terminated” after the event with the corresponding event reason has taken place.

For a minimum setup, the Admin should create one (or several) event reasons for the following:

● Hire event

● Rehire event

● Termination event

● changes to Job Information and Compensation Information

You can associate the event reason for such changes to the Data Change event, or you create more specific event reasons for the events Promotion, Transfer, Pay Rate Change, and so on.

● If Leave of Absence is activated, you need to create event reasons for the events Leave of Absence and Return to Work.

What do you need to do before you can use event-reason derivation rules?

1. Upload events and employee status picklists.

There is a predelivered list of events and employee statuses that you should not change. You can change the labels, but you cannot add new events or employee statuses. You can also choose to use only part of the predelivered events.

For more information about picklists, see How do you manage picklists?

2. In Provisioning, go to Edit Company Settings Company Settings . Under Employee Central, select the checkbox Enable youCalc rules engine for HRIS [Not Ready for Sales/Production] — requires “Employee Central V2 (i.e., Event Reason Derivation)” and “Effective Dated Data Platform”.

Only after enabling this setting will you see the link for importing/exporting the XML file for event-reason derivation rules. If you do not enable this setting, you cannot upload the XML file, and the user has to manually select the event and event-reason from the UI when changing an employee’s data.

3. The Admin creates event reasons in the system. You might have to show the Admin where this is done in the system:

● To create an event reason, go to Administration Tools. In the Company Processes & Cycles portlet, select Employee Files Manage Organization, Pay and Job Structures .

● To mass upload event reasons via CSV file, go to Administration Tools. In the Company Processes &

Cycles portlet, select Employee Files Import Foundation Data .

SuccessFactors delivers a predefined list of standard event reasons. You can use this as a basis, even if you decide to use just some of them. You can find the most current version of this list as CSV file under this link: http://confluence.successfactors.com/display/PRODINFO/Data +Models+and+Picklists .

● If an event or event reason leads to a change of the employee status, the Admin has to define the corresponding employee status accordingly. For example, if the contract with an employee is terminated, the employee status should change to “Terminated”. If the employee is rehired, the employee status becomes “Active” again.

If the event or event reason does not lead to a change of the employee status, for example, if an employee is promoted, the Admin has to leave this field on No Selection.

● The Admin has to tell you the external code (Event ID) that was used to define the event reasons, as you need these later for the <trueoutput> value in the XML file for event-reason derivation rules.

How do you set up event-reason derivation rules?

1. Download the XML file for event-reason derivation rules.

● If you're setting up event-reason derivation rules the first time for a company, download the most current version from this link: http://

confluence.successfactors.com/display/PRODINFO/Data+Models+and +Picklists .

● If you're changing already uploaded event-reason derivation rules, download the XML file from Provisioning under Succession Management Import/Export Rules XML for EventReason Derivation .

2. Open the XML file in an XML editor and adjust it according to the company's requirements.

You do this by copying an existing rule and changing the following values:

1. Enter a unique rule ID (for example, rule-18).

2. Enter the external code of the event reason the Admin has created before as the

<trueoutput> value of the event-reason derivation rule.

Consider the following:

● You can only configure rules for events and event reasons that are used under Employment Information in the Job Information portlet (HRIS-element ID:

jobInfo) or in the Compensation Information portlet (HRIS-element ID:

compInfo), and for the foundation object payComponentGroup which is used to identify salary changes.

● You cannot create rules for the following events:

○ Hire

○ Rehire

○ Termination

○ Leave of Absence

○ Return to Work

● Consider the sequence of events as the system reads the file from top to bottom and the first rule that is met is applied (see below under Sequence of event reasons in the XML file).

3. Choose the logical operand you want to use: <and>, <or>, or <xor>. For some examples, see below under XML examples in section Logical operands for rules configuration.

4. Choose the comparative operand you want to use: <greater>, <lesser>, or

<equal>. For some examples, see below under XML examples in section Comparative operands for rules configuration.

5. Enter the ID for the field change that is supposed to trigger the rule. Follow this format:

hris-element-id.hris-field-id

You can find examples below under XML examples in section Examples for event-reason derivation rules.

6. A catch-all event reason is included at the end of the standard XML file — keep this in the XML file and do not change it.

For more information, see below under XML examples in section Catch-all event.

3. Upload the XML file in Provisioning under Succession Management Import/Export Rules XML for EventReason Derivation .

XML examples

Examples for event-reason derivation rules

Field change triggers rule

To have any kind of change to a field value on the UI trigger a rule, use the inverse=”true” attribute as in the following example:

<trueoutput>JOB_CHANGE</trueoutput>

<and>

In the first rule, you define that if the job code is changed, the event reason code is JOB_CHANGE. Job code is a field of the HRIS element jobInfo. To refer to the field use the syntax hris-element-id.hris-field-id. If this field is changed, the event reason JOB_CHANGE is applied. The <trueoutput> value has to be the same as the external code of the event-reason foundation object the Admin creates under Administration Tools, in the Company Processes

& Tools portlet under Employee Files Manage Organization, Pay and Job Structures .

The second rule defines that when location and cost center are changed, but the manager stays the same, the event-reason code is XFER for transfer.

Field change to a certain value triggers rule

Instead of just checking if a field is changed, you can also define a rule that is met when a certain value is chosen.

For this, you use the compareToNew attribute and specify the value that triggers the rule.

In the following example, if an employee's department is changed to “ENG”, the rule ENG_DEPT_CHANGE is used.

The compareToNew attribute determines whether to use the new value for comparison or the old value; that is, if the compareToNew attribute value is true, the rule is met:

<trueoutput>ENG_DEPT_CHANGE</trueoutput>

<and>

</and>

</conditions>

</rule>

You can also set the compareToNew attribute to “false” if you want to evaluate the initial value of an attribute as in the following example:

Change to specific data object triggers rule

Instead of defining the HRIS-field ID as you did in the previous examples, you can also define the ID of a specific foundation, person or employment object. In the following example, the pay component group “A1” has been defined in the system. “A1” is the external code of the pay component group (standard label on the UI is Pay Component Group ID). In the XML file, you follow this syntax: hris-element-id.externalCode

The following rule is met when a change, such as a salary change, to A1 takes place:

<and>

</and>

</conditions>

</rule>

Logical operands for rules configuration

● AND: Both conditions have to be true.

● OR: At least one of the conditions has to be true.

● XOR: a XOR b is true only when one of a, b is true, but NOT both are true (a so-called “exclusive OR”).

Example for “AND”

The logical operand “AND” allows you to define events that involve changes on fields belonging to different HRIS elements. For example, the customer can define an event called promotion, when the job code changes (job-code) and the salary increases (AnnualizedSalary). job-code and AnnualizedSalary come from different HRIS elements (jobInfo and payComponentGroup). You would define this as follows:

job-code is a field that belongs to the HRIS element jobInfo. jobInfo is an employment object that is defined in the Succession Data Model.

PayComponentGroup is a foundation object that is defined in the Corporate Data Model. AnnualizedSalary is the external code of a payComponentGroup that the Admin creates under Administration Tools, in the Company Processes & Tools portlet under Employee Files Manage Organization, Pay and Job Structures .

The above rule means that if the job code field from the Job Information portlet is changed and the

AnnualizedSalary (which is the sum of the Pay Component Groups) is changed in the Compensation Information portlet, the event reason will be determined as JOBTRN.

You cannot combine AND with OR, but you would have to create 2 different rules. For example, if you want a rule for a data change to manager and cost center or department, you have to set up a rule for a data change to manager and cost center, and then a second rule for manager and department.

Comparative operands for rules configuration

● Greater: The new value is greater than the old value.

● Lesser: The new value is less than the old value.

● Equal: The new value is the same as the old value.

If you want to set something to unequal, meaning data has changed, add inverse=”true” to it as in this example:

Example for “greater”

In this example, the rule is met when the value for the pay grade is increased:

<trueoutput>PAYGRADEINC</trueoutput>

<and>

In this example, the rule is met when the value for the pay grade is lower than before:

“Equal” is mostly used in its reverse sense, meaning, that something has changed and thus is not equal anymore.

This is achieved by adding the inverse=”true” attribute. In the following example, the rule is met when the location in the job information portlet is changed:

Sequence of event reasons in the XML file

When a change occurs for job information or compensation information, the system checks whether an event reason derivation rule applies by reading the XML file from top to bottom. The first rule that applies is picked; all following ones are ignored. So, in the following example, if the user changes the company AND the cost center on the UI, only the first rule will be applied:

This means that, when setting up rules, you either have to prioritize the event reasons accordingly or configure the various combinations by using logical operands as explained above. So in this example, if you want a rule to be triggered when the user changes the company OR the cost center OR both, you define this as follows:

If the system has not detected a matching rule in the XML file, the catch-all event defines that the data change is stored as such in the system. This is to make sure that even if no matching rule is found, the system derives an event reason. This is necessary because all changes that are connected to an event need an event reason assigned to them as described above under Are event reasons mandatory?

In document EC Implementation Handbook (Page 98-105)