Event Notifications

Event Notifications is a feature of the Dayforce web services. This feature sends out notifications when specific events occur in Dayforce. Configuration data within the Dayforce web services tracks which events a customer is subscribed to and specifics about how to call the client notification receiver web service.

There are two methods available to receive event notifications:

• Push Method: To use this method, your organization needs to implement a notification receiver web service based on the WSDL that Dayforce provides.
• Pull Method: To use this method, you have to make a specific call with the DFNotificationsRequest and send matching acknowledgments by making a separate call.

Important: The notification receiver web service only receives contextual data about the event. The actual data referenced by the notification must be retrieved with a separate call.

Event Types

The types of events that can initially be subscribed to are Employee Hired, Rehired, and Terminated, and their associated cancellations.

Subscription Configuration Data

To configure this feature, the following subscription information must be provided to Dayforce:

• Event detection only. If set as Yes, Dayforce won’t push the detected event notifications for the current subscription. If you don't plan to build the notification receiver for the push method, but rather want to pull event notifications by calling the Dayforce web service periodically, then you must set this parameter to Yes for the current subscription. Otherwise, set it to No.
• Event Type to subscribe to: It’s best practice to subscribe to all of the available events: hire, rehire, terminate, and their associated cancellations.
• Effective dates of the subscription.
• Maximum number of attempts and maximum number of minutes to attempt to send a notification to a client. The recommended maximums are 100 attempts and 1440 minutes.
• Web Service information for the Notification Receiver service including the URI, user name, and password.
• Contact information of those that should be notified if failures occur in sending notifications.

Acquire Event Notifications Directly (Pull Method)

As mentioned above, you can acquire event notifications directly from the Dayforce web service for subscriptions which are defined with Event Detection Only set to “Yes”.

To acquire and acknowledge unread event notifications:

1. Instantiate and submit a DFNotificationsRequest object to the Query method.
2. For each returned event notification, instantiate a populate a DFAckNotificationRequest:
   1. On this object, set the NotificationDataId to the one being acknowledged.
   2. The DFAckNotificationRequest is then submitted to the Query method.

Sample Code - Creating a Request to Acquire Event Notifications

Data Returned

The response from the Query method call is a list, with each item containing the following:

• A NotificationDataId value
• The event type
• The event date and time
• Context data

Note: The data is returned in list form because it's possible that multiple events were detected and are to be notified.

Sample Code - Acknowledging an Event Notification

In the example above, you received a list of event notifications from Dayforce. The code sample below demonstrates how to acknowledge these event notifications back to Dayforce:

Build the Notification Receiver Web Service (Push Method)

The notification receiver web service is a service developed and hosted by the customer. This service will be called by Dayforce when an event occurs for which there is a subscription. This service must process the event notifications as they arrive and return acknowledgements to Dayforce. If an acknowledgement isn’t received by Dayforce, the event will be resent at a later time, and all future events will be held until the failing event is acknowledged.

Both .NET and Java allow for the creation of web services from a top-down approach by using a predefined WSDL file to generate the source code for the service. That WSDL file can be retrieved from Dayforce at: https://www.dayforcehcm.com/DataSvc/DFNotificationReceiverService.svc?singleWsdl

Receive Method on the Notification Receiver Web Service

The Receive method is the only method on this service.

Sample Code – Receive method on DFNotificationReceiverService

The following is a simplified sample of how the implementation might look:

Retrieve the Data That Caused the Event Notification

The data that caused the event notification isn’t sent to the Receive method shown above, or in reply to the DFNotificationsRequest shown above, because the data might include private information that only authorized users should see. Therefore this data must be retrieved using the normal retrieval methods. See Use the Query Method to Retrieve Data.

To retrieve the data associated with the event notification:

1. Instantiate and populate a DFNotificationDataRequest object.
2. On this object, you will set the NotificationDataIds property to an array of IDs based on the IDs that you received in the Receive method above.
3. Important: The maximum number of NotificationDataIds that can be included in a single request is 1,000. This value is returned in the Authentication response and should be taken from there in case it changes in future releases.
3. The DFNotificationDataRequest is then submitted to the Query method.

Sample Code – Created a Request to Retrieve Data

Data Returned

The response from the Query method call is a list with each item containing the following:

• A NotificationDataId value.
• The data associated with the notification.

The data is returned in list form because it's possible that multiple entities of the same type were all associated with the notification.

Sample Code – Processing the Response Containing the Data

In the example below, we are processing the list of lists. The outer list is the DFNotificationData objects and the inner list is of the entities associated with the notification. In this case, the code is expecting Employee objects which are then processed by writing the employee name to the console window.

Refining Your Results

Depending on the event types that are subscribed to, you might get back entities of types other than an Employee type. In that case, you might consider using a switch statement rather than the if..then statement to detect the type of object you have to process. You can also make use of the event type that was included on the DFNotificationEvent object passed to the Receive method.

Configure End-Time for Subscription Groups with Unacknowledged Notifications

If a customer fails to acknowledge notifications for 14 days, the application stops processing for the subscriber to avoid a large build-up of unprocessed items. The application then sends an email to the Alert Email address using the following template:

The "[subscriber name]" subscriber has not [acknowledged or retrieved] notifications since [date/time]. As a result, Dayforce has automatically suspended notifications by applying an end date to all remaining subscriptions for this subscriber.

To resume notifications for this subscriber, please ensure the associated web services application is running properly, and then use the Dayforce Notification Status and Notification Subscriptions features to reset outstanding notifications and/or configure continuing subscriptions.

Notifications are either pulled by subscribers or pushed to subscribers, which you can set by going to the Features tab of System Admin > Roles under Web Services > Notification Subscriptions and choosing from the following options:

• To configure a subscriber to pull notifications, select a subscriber and select the checkbox in the Event Detection Only column to set it to Yes.
• To configure a subscriber to have notifications pushed to it, select a subscriber and clear the checkbox in the Event Detection Only column to set it to No.