Summary
Event Notifications allow your application to be aware of data change events. They can also be used to retrieve the latest data in order to sync your system with ADP products and applications. When data is updated in an ADP application, ADP generates an event notification message. Then, the message is sent to a subscriber's message queue. To regularly check and retrieve event notification messages, subscribe your application to data change events.
What's New
August 2020
A queue is established when the client receives the first notification message. Instead of returning a 404 when the queue is not yet established, we made an enhancement and respond a 204 response when there is no queue yet for the client.
Supported Product Version and Customer Base
For more information, see the product specific data dictionaries and application programming interface (API) guides for supported products.
About Events and Event Notifications
Events
Events mark every change made in the system. ADP Representational State Transfer (REST) APIs use an event-based pattern for resource modification. Clients or partners need to know if there are any changes in the ADP System of Record (SOR) to act upon or keep themselves aware. Partners or clients will get to know about the changes after they subscribe to the specific changes for which they want to be notified.
Event Notifications
Event Notifications provide the details about the changes to partners. This prompts action by the partners and keeps their records updated.
Process Overview
When data is updated in an ADP application, ADP generates an event notification message. Then, the message is sent to a subscriber's message queue. To regularly check and retrieve, event notification messages subscribe your application to data change events.
For example, you can subscribe to the Worker Hire event to be notified when a new hire is added to an ADP product. This is so you can do some work with the new hire's data.
|
# |
Actor |
Description |
|---|---|---|
|
1 |
A human user or a system |
Makes a change to a record. For example, an employee updates a worker's email address in an ADP product. |
|
2 |
ADP product |
Generates an event notification message and sends copies to a subscriber's message queue. Messages are queued based on the first in, first out (FIFO) method. |
|
3 |
Consumer application |
On scheduled time, retrieves one event notification message from its message queue and acts as needed. |
|
4 |
Consumer application |
Deletes the event notification message from its message queue and repeats steps 3 and 4 until there are no more messages in the queue. |
Required Setup Steps
To subscribe to an event notification, contact your ADP Representative.
Data Dictionary References
1. Schema of event notifications varies depends on /events/eventNameCode/codeValue as well as the ADP Product. Once you identifies the interested event notification(s) to subscribe for your application, you should analyze the response payload and map out interested resources;
2. We recommend your application to use event notifications as a trigger instead of true source of real time data as there is always a time lag between when a notification was generated and when your application retrieves it; For example, if a notification indicates a worker is hired, your application should do GET /hr/v2/workers/{aoid} to retrieve the real time data for the worker instead of relying on the value provided in the worker.hire notification as the data may have changed since the notification was generated;
3. About effective dating - in most cases, when a change has an effective date, the notification is generated at the time when the change is issued, and not on the effective date and your application should be able to lookup the effective date in the notification response payload;
|
Schema Location |
Description |
Note |
|---|---|---|
|
/events/data/eventContext/worker/associateOID |
Indicates the worker record being changed. |
In most cases, the object in the eventContext is worker. |
|
/events/eventNameCode/codeValue |
Indicates the event which triggered this notification. |
Your application should use this value to build logic on actions to take for each event. |
|
/events/transform/ |
Specifies the object's new value. |
Depends on the product and event. Your application may need to retrieve the record to get the current value, instead of leveraging the data within this component as there may be additional change events to the same record occurring from the time when the notification was generated. |
Use Cases
Refer to the following table to find the use case aligning with your business needs as well as the supported ADP Product.
|
# |
Use Case Name |
ADP Vantage HCM |
ADP Enterprise HR |
ADP Workforce Now |
RUN Powered by ADP |
|---|---|---|---|---|---|
|
1 |
Retrieving an Event Notification |
Yes |
Yes |
Yes |
Yes |
|
2 |
Deleting an Event Notification |
Yes |
Yes |
Yes |
Yes |
Use Case 1: Retrieving an Event Notification
Use Case Description
When you complete a change for a worker in an ADP system, a notification is pushed to a message queue for you to query. Let's assume that your application subscribes to the Worker Personal communication email Add notification. When you add a new personal email for a worker, it creates a notification and pushes it to your message queue. After retrieving and processing the message, you must delete the notification to retrieve later notifications .
API Usage
| Method | Uniform Resource Identifier (URI) | Description | Note |
|---|---|---|---|
| GET | /core/v1/event-notification-messages | Retrieves an Event Notification. | Refer to the specific product's ADP API data dictionary and API guide for a list of supported Event Notifications related to your use case. |
Request Header Parameters
|
Parameter Name |
Value |
Required |
Usage |
|---|---|---|---|
|
Authorization |
Bearer {token} |
Yes |
Type of authorization. |
|
prefer |
/adp/long-polling |
No |
Server delays response for a certain time. |
Each event notification message has a unique ID located in the header of the response, which is coded as adp-msg-msgid. It needs to be used for message deletion.
Prefer Header Usage
- If a header is included while making a GET Event Notification call, the server delays its response, waiting for events to display on the respective subscriber's event notification queue. When no event notifications are available for a given time, a timeout occurs. The wait time is 15 seconds.
-
If prefer header is not included while making a GET Event Notification call, the server will not wait for any events to display in the queue. It just responds with whatever is present in the queue.
It is always recommended to use prefer:/adp/long-polling while making GET Event Notification calls to get an accurate response from the queue.
Actors
ADP APIs enforce data entitlement and access control. The actors listed on the following table are supported for this use case.
| Request Parameter roleCode Value | Usage |
|---|---|
| practitioner | Retrieves event notifications as a practitioner. A practitioner can usually access information for a broader collection of workers. |
Sequence of Interactions
The following are the steps shown in the previous diagram:
- Your consumer application makes a /core/v1/event-notification-messages request to the ADP API endpoint for a notification.
- The ADP API endpoint responds with the events to your consumer application.
Responses
|
Response Code |
Condition |
messageText |
Tips to Handle |
|---|---|---|---|
|
200 OK |
Request is processed successfully. |
|
|
|
204 No Content |
When there are no messages in the queue. |
empty body |
There are no messages existing in the queue. |
|
304 Not Modified |
When performing a GET without first deleting a previous read message. |
empty body |
|
|
403 Forbidden |
The request is not authorized. |
empty body |
Contact your ADP representative to add the notification to your application scope. |
| 404 Not Found | empty body | Contact your ADP representative. |
Use Case 2: Deleting an Event Notification
API Usage
| Method | URI | Description |
|---|---|---|
| DELETE | /core/v1/event-notification-messages/{adp-msg-msgid} | Deletes an event notification message. |
Response header adp-msg-msgid is returned when retrieving an event notification. For example: adp-msg-msgid: 0x_414d51204253494e464f425136202020f2f4ca5503748720
Request Header Parameters
| Parameter Name | Required (Y/N) | Usage | Value | Sample |
|---|---|---|---|---|
| Authorization | Y | Type of authorization. | Bearer token | Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Actors
ADP APIs enforce data entitlement and access control. The actors in the following table are supported for this use case.
| Request Parameter roleCode Value | Usage |
|---|---|
| practitioner | Deletes an event notification as a practitioner. A practitioner can usually access information for a broader collection of workers. |
Sequence of Interactions
The following are the steps shown in the previous diagram:
- Your consumer application makes a /core/v1/event-notification-messages/{adp-msg-msgid} request to the ADP API endpoint for a notification.
- The ADP API endpoint responds to your consumer application with the events deleted.
Responses
|
Response Code |
Condition |
messageText |
Tips to Handle |
|---|---|---|---|
|
200 OK |
Request is processed successfully. |
|
|
|
404 Not Found |
When trying to delete the same message again. |
empty |
The message is already deleted. |
|
|
When invalid {adp-msg-msgid} is passed in the request. |
empty |
Make sure a valid {adp-msg-msgid} is passed in the request.
NOTE: {adp-msg-msgid} is obtained from the response headers of the GET /core/v1/event-notification-messages/ call. |
Known Issues and Limitations - US1191638: Ability to perform bulk retrieval and deletion
Issue Description
Currently, bulk retrieval and deletion of events are not supported.
Suggested Work Around
One event is retrieved and deleted at a time. In order to retrieve the next event, clients have to delete the current event using the /core/v1/event-notification-messages/ {adp-msg-msgid}. Then, they need do a GET /core/v1/event-notification-messages.
