SAP Knowledge Base Article - Public

2156278 - How To Set Up EC Alerts and Notifications Using Business Rules

Symptom

This KB article explains how to set up EC Alerts and Notifications using Business Rules

Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.

Environment

  • SAP SuccessFactors HXM Suite
  • SAP SuccessFactors Employee Central

Resolution

Overview:

  • Users can set up an Alert rule to trigger an e-mail Notification or ToDo action item when certain data changes are made, such as Job Information changes.
  • When the information change matches the rule criteria, an e-mail notification will be sent and/or a ToDo item will displayed to the workflow participants on the alert effective date.
  • Administrators can customize the e-mail and ToDo message for the Alert
  • You can customize and define templates for your Employee Central and MDF Alerts and Notifications to generate e-mail Notifications and create To-Do's (Homepage tile).

General Information

Prerequisite: EC Alerts and Notifications can only be used in an instance which has "Business Rules for Workflow Derivation" enabled.

What elements/objects can I create Alerts for?

Employee Central HRIS Element Alerts

See the Changes That Trigger Alerts section of the Workflows Implementation handbook.

Supported elements or base object are:

2856599 - 1911 - Rule Scenario Base Objects Used in Alert Triggering Rules for Employee Central Data Objects - Generate Alerts for Employee Central Data

Please refer to the Implementing and Managing Workflows - Setting Up To-Do Alerts Section.

  • Global Assignment (globalAssignmentInfo)
  • Employment Information (employmentInfo)
  • Non-Recurring Pay Components (payComponentNonRecurring)
  • Recurring Pay Components (payComponentRecurring)
  • Work Permit (workPermitInfo)
  • Compensation (compInfo)
  • Job Information (jobInfo)

Note: Any HRIS Element not mentioned above cannot be accessed by the EC Alert engine currently.

Employee Central Time Off Alerts

See the Setting Up Alerts and Notifications section of the Time Off implementation handbook for more information

Metadata Framework (MDF) Alerts

  • KB article 2532558 - How To Configure MDF Alerts and Notifications for MDF Objects 

EC Alerts and Notifications Job Execution

Please refer to the "Job Execution Overview" section in the handbook, to better understand how the EC Alerts and Notifications job will execute. This is very important to understand before planning to implement EC Alert rules.

Configuration Examples

Please do refer to the Alert Expamples Section of the Handbook for more information

Scenario: The alert/notification should trigger on the ‘Probation End Date’ of an employee.

 Steps:

  1.  In Admin tools-> Company Settings -> Configure Object Definitions, search for AlertMessage.
    • Change the Maximum Length of ‘alertDescription’ as 4000.
    • Note: This is to increase the length of Alert description as configured in step 2. Please note if you are using translations, you may also wish to carry this out for the alertDescriptionLocalized field also.
      1.jpg
  2. Admin tools-> Employee Files -> Manage Data, Create New AlertMessage.
    Currently you can use only the following tags: (Also see 2287616 - List of supported tags for EC Workflows and EC Alerts)
    • Subject user: [[SUBJECT_USER]]
    • Event reason: [[EVENT_REASON]]
    • Effective start date of the record which triggers the Alert & Notification: [[EFFECTIVE_DATE]]
      For non-effective dated elements it takes the change date - 2780466 
    • Start date: [[START_DATE]]
    • End date: [[END_DATE]]
    • Time off type: [[TIME_OFF_TYPE]]
  3. Time off status: [[TIME_OFF_STATUS]]
    2.jpg
  4. Admin Tools-> Manage Organisation, Pay and Job Structures, Create a workflow.
    Note: Here the Employee’s Manager will receive the notification.
    3.jpg
    Note:
    • Approvers receive a To Do Alert. - If no workflow is created and the sole approver of the workflow puts through the action No To Do Alert will appear as no action is required.
    • Cc Role's receive an e-mail Notification.
    • You need to be both an Approver and a Cc Role, to receive both an Alert and Notification.
  5. Admin Tools -> Configure Business Rules, Create New Rule as below:
    NOTE:
    • Never configure your Alert rule with "IF = Always". This will mean the rule will trigger EVERY time you save. Best Practice is to have at least 1 IF condition, similar to the one used in the example below, where the rule will only trigger when the value for the field changes. If the value does not change, an alert is not sent. The point here is that it will send an alert when you set the value the field time, and it will send an alert when you change the value. But you dont want it to send an Alert every time you update the employee's Job Information, which it will do if you dont have any IF condition.
    • Cross Portlet value checking is not supported - i.e. If the Base Object of the Alert Rule is "Job Information" you cannot check a value in "Global Assignment Info".
    • Be cautious of using the 'Date Plus ()' parameter in the if statement
      • This can have undesired outcomes depending on how it is configured
      • Best Practices suggest to not user the 'Date Plus ()' parameter
      • For a Detailed Example of an EC Alert and Notification Business Rule, please see the following KBA:
      • 2431478 - Example Configuration of an EC Alert and Notification Rule.
      • 2856599 - 1911 - Rule Scenario Base Objects Used in Alert Triggering Rules for Employee Central Data Objects - Generate Alerts for Employee Central Data 
      • Base object: Scenario : Generate Alerts : Base Objects Used in Alert Triggering Rules for Employee Central Data Objects
      • When you use Employee Information as a base object, you can access all entities through Employee Information. It is possible to define a saveAlert under jobInfo in the Manage Business Configuration tool and continue to use Employee Information as your base object. When you create the rule, specify fields from Job Information fields for your conditions.
      • View How Old Pending Alerts Are Handled
      • testrule.png
    1. Please Note: 2856599 - 1911 - Rule Scenario Base Objects Used in Alert Triggering Rules for Employee Central Data Objects - Generate Alerts for Employee Central Data 
      1. Alert Message (Optional) – We define the alert message that was created in step 2.
        If you do not define any alert message, the default message formet will be:
        • E-mail Header/todo name: Alert for "subject user name", "event reason"
        • E-mail Body/todo detail: Alert for "subject user name", "event reason" on "effective start date"
      2. Effective Date (Required) – Defines when the rule is triggered.
        • You can use Date Plus() function to define when the alert will be sent. If you wish for the alert to be triggered days before or after the Probation End date.(-10   means 10 days before)
      3. Workflow Information (Required) - defines which workflow is assigned to this rule. The workflow defines which user gets an alert and/or a notification message as configured in step 3.
    • Note: Here, ‘Probation End Date’ is a field in the Job Information Portlet. This Alert is only triggered when a change is made to the 'Probation End Date' field, this stops multiple alerts from being sent.
  1. Add the rule to the Succession Data Model, under ‘jobInfo’ HRIS element (or you can assign the rule via Admin Center > Manage Business Configuration > jobInfo element > Rule Type = saveAlert).
    <trigger-rule event="saveAlert" rule="test_Alert_PPED"/>

PS: Put saveAlert rules under Succession data model and not under country/region-specific data model. For example: put the rule under jobInfo instead of jobInfo_AUS
2.png

  1. Run the ‘EC Alerts and Notifications’  Scheduling Recurring Job for Regular Alert Triggering job.
    • Note: Create the job as recurring so that it is run daily. Also keep in mind that the rules will only be triggered to create the alert when the job runs.
       7.jpg

 Further example can be found here: 2431478 - Example Configuration of an EC Alert and Notification Rule. 

Manage Alerts and Notifications

You can manage your pending Employee Central Alerts and To-Dos using the Manage Alerts and Notifications Dashboard.

As an administrator, you can use the Manage Alerts and Notifications dashboard to filter, view, and delete pending Employee Central Alerts and To-Dos. The advance filter allows you to manage alerts and To-Dos based on specific criteria.

Job Execution Logic

For more information on how the EC Alerts and Notifications schedule job works View: Scheduling Recurring Job for Regular Alert Triggering

  • KB article 2677445 - EC Alerts and Notifications: Improved Details for EC Alerts and Notifications scheduled job log 

Best Practices: Things to consider when configuring Alerts

  • Alerts are created when the 'IF' condition of the Business Rule is met when the EC Alerts and Notifications job is comparing records against the Alert Rules for the given Element. (Do not use IF = Always)
  • The Alert Message is then created (as a Pending Alert) and waits statically in the system until the Alert Effective Date is reached.
  • When the effective date is reached and the 'EC Alerts and Notifications' job is ran the alerts are sent.
  • If you are setting up an EC Alert and Notification in your instance, please note, that the Alerts will only be triggered for changes made to the user information, which meet the criteria of your rule, from the day the rule is triggered on the corresponding Element. The alerts will not trigger for already existing data.
  • Workflows in conjunction with the EC Alerts and Notification feature, do not work the same as normal workflows. 
  • The expected behavior is as follows:
    • CC Roles will receive only a Notification (e-mail). Unlike normal CC roles, these emails will not appear in "Take Action" tile.
    • Approves will receive an Alert (To Do Notification). In the new home page these alerts appear in the "Take Action" Tile.
  • It is not possible to send Alerts to New Hire Employees in the system prior to their start date 

Troubleshooting Common Issues

EC Alerts and Notifications Job: Common Errors

  • 2601125 - EC Alerts: Which records are considered by EC Alerts and Notifications job and compared to Alert rules to create Pending Alerts?
  • 2676210 - EC Alerts and Notifications - Exclude Alerts for Terminated Users
  • 2408916 - EC Alerts: Rule Execution Error: No context object found to execute SET action
  • 2447386 - EC Alerts: EC Alerts and Notifications job fails with "null object loaded from local variable 'conn'"

Configuration FAQ

  • 2757243 - How To Create Termination Reminder Alert Rule
  • 2492826 - Alert Message Received in Incorrect Language
  • 2468444 - EC Alerts: Work Permit Expiration Alert Rule
  • 2471834 - How to configure an EC Alert Rule for Global Assignments
  • 2739112 - EC Alerts: How to create an Alert to notify both Home and Host Manager for the Start or End of a Global Assignment
  • 2537602 - EC Alerts and Notification Business Rules does not work with Base Object Employment Detail Model
  • 2576274 - EC Alerts: Alert Notification Email Content Error - [[OBJECT_NAME]]

Alert Behaviour FAQ

  • 2302229 - Receiving Multiple EC Alerts and Notifications
  • 2312196 - Receiving EC Alert and Notification When the Business Rule IF Conditions are no Longer Met
  • 2354283 - EC Alert and Notification not Being Sent to the Members of a Dynamic Group
  • 2506244 - Work Order Alert and Notification not triggering
  • 2449702 - Alert Notification is not being received by all the CC Roles

Take Action: Alerts (ToDos)

  • 2589090 - EC Alerts: Can I set Due date in ToDo list for an EC Alert?
  • 2676702 - EC Alerts and Notifications: What happens when the Alert Message definition used by a saveAlert rule is Deleted from Manage Data?
  • 2676650 - EC Alerts and Notifications: Deletion of record used to trigger an Alert (Alert is Pending) 

See Also

  • 2537602 - EC Alerts and Notification Business Rule does not work with Base Object Employment Detail Model
  • 2431478 - Example Configuration of an EC Alert and Notification Rule.
  • 2462860 - How to Configure EC Alerts and Notifications to be sent on Staggered Dates/Intervals
  • 2302229 - Receiving Multiple EC Alerts and Notifications
  • 2312196 - Receiving EC Alert and Notification When the Business Rule IF Conditions are no Longer Met
  • 2468444 - EC Alerts: Work Permit Expiration Alert Rule
  • 2537602 - EC Alerts and Notification Business Rules does not work with Base Object Employment Detail Model
  • 2287616 - List of supported tags for EC Workflows and EC Alerts
  • 2532558 - EC Alerts: Configuring Alerts for MDF Objects

Keywords

SF, success factors, successfactors, EC, save alert, saveAlert, notify, Base Object, workflow, EC Alerts and Notifications, , KBA , LOD-SF-EC-ALR , Alerts & Notifications (saveAlert - EC Core only) , LOD-SF-EC , Employee Central , LOD-SF-EC-RUL , DO NOT USE - Business Rules & Event Derivation , How To

Product

SAP SuccessFactors Employee Central all versions ; SAP SuccessFactors HXM Suite all versions