ADP Event APIs and Event Notification Guide

Summary: Event Notifications allow your application to be aware of data change events. They can also be used to retrieve the latest data, 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.

Overview

Event Notifications allow your application to be aware of data change events. They can also be used to retrieve the latest data, 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.

Supported Product Version and Customer Base

For more information, see product specific data dictionaries and Application Programming Interface (API) Guides for supported products.

About Events and Event Notifications

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 System of Record (SOR) at ADP to act upon or keep themselves aware . Events mark every change made in the system. 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 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

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 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

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:

GET

URI:

/core/v1/event-notification-messages

Description:

Retrieves an Event Notification.

Note:

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 the 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 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 default waiting 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 on 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:

practitioner

Usage:

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:

  1. Your consumer application makes a /core/v1/event-notification-messages request to the ADP API Endpoint for a notification.
  2. 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 When no message is created in the queue. empty body The 404 response remains only until the first notification is entered to the queue. After that notification is deleted and no other notifications exist, the response returned is a 204 No Content.

Use Case 2: Deleting an Event Notification

Description

Delete an Event Notification message.

API Usage

Method:

DELETE

URI:

/core/v1/event-notification-messages/{adp-msg-msgid}

Description:

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:

Authorization

Required (Y/N):

Y

Usage:

Type of authorization

Value:

Bearer token

Sample:

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:

practitioner

Usage:

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:

  1. Your consumer application makes a /core/v1/event-notification-messages/{adp-msg-msgid} request to the ADP API Endpoint for a notification.
  2. 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 GET /core/v1/event-notification-messages/ call.

Known Issues and Limitations

US1191638: Ability to Bulk Retrieval and Deletion

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.