Work Assignment API Guide for ADP Workforce Now

ADP Copyright Information

ADP, the ADP logo, Always Designing for People, and ADP Workforce Now are trademarks of ADP,

LLC.

All other trademarks are the property of their respective owners.

Copyright © 2019 ADP, LLC. ADP Proprietary and Confidential - All Rights Reserved. These materials

may not be reproduced in any format without the express written permission of ADP, LLC.

ADP provides this publication “as is” without warranty of any kind, either expressed or implied, including,

but not limited to, the implied warranties of merchantability or fitness for a particular purpose. ADP is not

responsible for any technical inaccuracies or typographical errors which may be contained in this

publication. Changes are periodically made to the information herein, and such changes will be

incorporated in new editions of this publication. ADP may make improvements and/or changes in the

product and/or the programs described in this publication.

Publication Date: 12/31/2019 3:23 PM

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Contents

About the Work Assignment API .............................................................................................................. 1

Supported Product Version and Customer Base ...................................................................................... 1

Required Setup Steps .............................................................................................................................. 1

Postman Collection .................................................................................................................................. 2

Use Case - Updating Work Assignment Details for an Employee ............................................................. 2

Use Case Description ........................................................................................................................... 2

API Usage ............................................................................................................................................ 2

Application Scope ................................................................................................................................. 2

Supported Actors .................................................................................................................................. 3

Request Header Parameters ................................................................................................................ 3

Sequence of Interactions ...................................................................................................................... 3

Data Dictionary ..................................................................................................................................... 4

Responses ........................................................................................................................................... 6

Known Issues and Limitations – USXXXX: Event notification not supported ............................................ 9

Impacted APIs ...................................................................................................................................... 9

Issue Description ................................................................................................................................ 10

Suggested Workaround ...................................................................................................................... 10

About the Work Assignment API 1

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

About the Work Assignment API

Work Assignment Application Programming Interface (API) updates the work assignments details such

as a worker’s Job Title and Job Function.

Supported Product Version and Customer Base

The Work Assignment API is available for United States (U.S.) clients in ADP Workforce Now.

Required Setup Steps

Clients need to make sure the codes used by your application are added and configured in ADP

Workforce Now. Refer to the following table on setup pages.

Records ADP Workforce Now

Job Title Setup > Tools > Validation Tables > Employment Profile > Position > Job

Title

Job Change Reason Setup > Tools > Validation Tables > Employment Profile > Position > Job

Change Reasons

Job Function Setup > Tools > Validation Tables > Employment Profile > Position > Job

Function

Job Class Setup > Tools > Validation Tables > Employment Profile > Position > Job

Class

FLSA Code Setup > Tools > Validation Tables > Employment Profile > Position > FLSA

Code

NAICS Workers

Comp

Setup > Tools > Validation Tables > Employment Profile > Position >

NAICS Workers Comp

Pay Grade Setup > Tools > Validation Tables > Employment Profile > Pay Rates > Pay

Grade

EEO Establishment Setup > Tools > Validation Tables >Employment Profile > Position > EEO

Establishment

Postman Collection 2

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Postman Collection

Postman allows you to import a collection of APIs, created by others, so you can try them out. For more

information on Postman, see Making Your First API Call Using Postman.

To download API collections for the Work Assignment API from the ADP GitHub library and import them

to Postman, go to Postman Collection.

Use Case - Updating Work Assignment Details for

an Employee

Use Case Description

The Work Assignment API updates the work assignments for a worker.

API Usage

Method Uniform Resource

Identifier (URI)

Description Sample Request

Payload

Sample Response

Payload

POST /events/hr/v1/worker.work-

assignment.modify

Updates work

assignment

details for an

Associate.

Workassignment-

update-success-http-

200-request.json

Workassignment-

update-success-http-

200-response.json

GET /events/hr/v1/worker.work-

assignment.modify/meta

Retrieves the

meta

information.

NA workassignment-

meta-call-http-200-

response.json

Application Scope

The canonical URI corresponding to the API needs to be added in the Consumer Application Registry

(CAR) for the subscription following which a user can access this API and make successful API calls.

The following canonical needs to be added to your application scope to enable this use case:

/hr/workerInformationManagement/workerManagement/workAssignmentManagement

/worker.workAssignment.modify

Use Case - Updating Work Assignment Details for an Employee 3

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Supported Actors

Request Parameter

roleCode Value:

Practitioner

Usage: Updates work assignment details for an employee as a practitioner. A

system user is considered a practitioner.

Request Header Parameters

There are no Request Header Parameters, in addition to the ADP standard header parameters.

Sequence of Interactions

1. Your consumer application makes a request for /events/hr/v1

/worker.work-assignment.modify/meta to the ADP API endpoint.

2. The ADP API endpoint responds to your consumer application with the meta payload. See the

table in Responses on page 6. Your consumer application processes the meta payload to

validate data included in the payload in step 3 and prompts the user to fix any validation issues.

Otherwise, compose the payload for the /events/hr/v1/worker.work-assignment.modify request.

3. Your consumer application makes an /events/hr/v1/worker.work-assignment.modify request to the

ADP API endpoint.

4. The ADP API endpoint responds to the consumer application concerning the details of

/events/hr/v1/worker.work-assignment.modify request.

Use Case - Updating Work Assignment Details for an Employee 4

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Data Dictionary

Resources listed in the following table can be accessed in ADP Workforce Now, under People >

Employment > Employment Profile > Position.

Schema Location Field Name in ADP

Workforce Now

User Interface (UI)

Is

Required

(Y/N)

Note

/associateOID Not Displayed Y

/workAssignmentID Not Displayed Y

The workAssignmentID

can be obtained by making

hr/v2/workers API call. Use

itemID under

workAssignments of API

response.

/effectiveDateTime Effective Y

/eventReasonCode Job Change

Reason

Y

/eventReasonCode/codeValue

/workAssignment/wageLawCoverage FLSA Y

/workAssignment/wageLawCoverage/c

overageCode

/workAssignment/wageLawCoverage/c

overageCode/codeValue

/workAssignment/expectedStartDate Position Start Date Y

/workAssignment/jobTitle Job Title Y

/workAssignment/JobFunctionCode Job Function Y

/workAssignment/JobFunctionCode

/codeValue

Use Case - Updating Work Assignment Details for an Employee 5

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Schema Location Field Name in ADP

Workforce Now

User Interface (UI)

Is

Required

(Y/N)

Note

/workAssignmentManagement

/PositionIndicator

Management

Position

Y

/workAssignment/PayGradeCode Pay Grade Y

/workAssignment/PayGradeCode

/codeValue

/workAssignment/Industry

Classifications

NAICS Worker's

Comp

Y

/workAssignment/Industry

Classifications/ClassificationCode

/workAssignment/Industry

Classifications/ClassificationCode

/codeValue

/workAssignment/Occupational

Classifications

EEOC/Job

Class/EEO

Establishment

Y

/workAssignment/Occupational

Classifications/NameCode

/workAssignment/Occupational

Classifications/NameCode/codeValue

/workAssignment/Occupational

Classifications/ClassificationCode

EEOC Job

Classification

or

Job Class

or

EEO Establishment

Y

/workAssignment/Occupational

Classifications/ClassificationCode

/codeValue

Use Case - Updating Work Assignment Details for an Employee 6

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Schema Location Field Name in ADP

Workforce Now

User Interface (UI)

Is

Required

(Y/N)

Note

/workAssignment/OfficerTypeCode Officer/Owner Y

/workAssignment/OfficerTypeCode

/codeValue

Responses

You may encounter exceptions outside your common success scenarios. You must account for these

exceptions during your initial development.

For more information, see API Common Exceptions and Tips for Handling.

Response

Code Condition messageTxt

GitHub Sample

Request

Payload

GitHub Sample

Response

Payload

Tips to

Handle

200 OK

Update work

assignment details

for an employee

with valid data.

NA

Workassignment

-update-success-

http-200-

request.json

Workassignment

-update-

success-

http-200-

response.json

400 Bad

Request

Update work

assignment details

with Incorrect

Associate ID.

"userMessage": {

"messageTxt":

"associateOID is

invalid." }

Workassignment

-invalid-AOID-

http-400-

request.json

Workassignment

-invalid-AOID-

http-400-

response.json

Update work

assignment details

with Invalid Work

assignment ID.

"userMessage": {

"messageTxt":

"workAssignmentID is

invalid."

Workassignment

-invalid-itemID-

http-400-

request.json

Workassignment

-invalid-itemID-

http-400-

response.json

Update work

assignment details

with Invalid code

value for the job

change reason.

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/workAssignm

ent/eventReasonCode/

codeValue is invalid." }

Workassignment

-invalid-

JobReason-http-

400-request.json

Workassignment

-invalid-

JobReason-http-

400-

response.json

Use Case - Updating Work Assignment Details for an Employee 7

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Response

Code Condition messageTxt

GitHub Sample

Request

Payload

GitHub Sample

Response

Payload

Tips to

Handle

400 Bad

Request

(cont.)

Update work

assignment details

with Invalid Effective

date.

"userMessage": {

"messageTxt":

"transform/

effectiveDateTime is

not a valid date. Enter

the date in the format

yyyy-MM-dd."}

workassignment-

invalid-

effectiveDate

Time-http-400-

request.json

workassignment-

invalid-

effectiveDate

Time-http-400-

response.json

Update work

assignment details

with Invalid

wageLawcoverage

(FLSA).

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/work

Assignment/wageLaw

Coverage is invalid." }

Workassignment

-invalid-wageLaw

coverage-http-

400-request.json

Workassignment

-invalid-

wageLaw

coverage-

http-400-

response.json

Update work

assignment details

with invalid position

start date.

"userMessage": {

"messageTxt": "An

employee's position

start date must be

greater than or equal

to the effective hire

date (the greater of the

hire date or the rehire

date)." }

workassignment-

invalid-

positionstartdate-

http-400-

request.json

workassignment-

invalid-

positionstartdate

-http-400-

response.json

Update work

assignment details

with invalid Job

Title.

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/workAssignm

ent/jobTitle is invalid."

}

Workassignment

-invalid-jobTitle-

http-400-

request.json

Workassignment

-invalid-jobTitle-

http-400-

response.json

Update work

assignment details

with invalid JOB

function code.

"userMessage":{

"messageTxt":"/events/

data/transform/workers

/workAssignment

/jobFunctionCode/code

Value is invalid." }

Workassignment

-invalid-

jobfunction-code-

http-400-

request.json

Workassignment

-invalid-

jobfunction-

code-http-400-

response.json

Use Case - Updating Work Assignment Details for an Employee 8

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Response

Code Condition messageTxt

GitHub Sample

Request

Payload

GitHub Sample

Response

Payload

Tips to

Handle

400 Bad

Request

(cont.)

Update work

assignment details

with invalid NAICS

(industry

classification code)

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/workAssignm

ent/industryClassificati

ons/classificationCode

is invalid." }

Workassignment

-invalid-industry

classification-

code-http-400-

request.json

Workassignment

-invalid-industry

classification-

code-http-400-

response.json

Update work

assignment details

with Invalid

officerTypeCode.

"userMessage": {

"messageTxt":

"/events/data

/transform/workers

/workAssignment

/officerTypeCode/code

Value is invalid." }

Workassignment

-invalid-

officerTypecode-

code-http-400-

request.json

Workassignment

-invalid-

officerTypecode-

code-http-400-

response.json

Update work

assignment details

with Invalid Pay

grade code.

"userMessage": {

"messageTxt":

"/events/data

/transform/workers

/workAssignment

/payGradeCode is

invalid." }

Workassignment

-invalid-

payGrade-code-

http-400-

request.json

Workassignment

-invalid-

payGrade-code-

http-400-

response.json

Known Issues and Limitations – USXXXX: Event notification not supported 9

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Response

Code Condition messageTxt

GitHub Sample

Request

Payload

GitHub Sample

Response

Payload

Tips to

Handle

400 Bad

Request

(cont.)

Update work

assignment details

with invalid EEOC

job classification

code.

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/work

Assignment

/occupational

Classifications/

classificationCode

(EEOC) is invalid." }

Workassignment

-invalid-

jobclassification-

code-http-400-

request.json

Workassignment

-invalid-

jobclassification-

code-http-400-

response.json

Update work

assignment details

with invalid EEO

Establishment.

"userMessage": {

"messageTxt":

"/events/data/transform

/workers/work

Assignment/

occupational

Classifications/

classificationCode/

codeValue (EEO

Establishment) is

invalid." }

Workassignment

-invalid-EEO-

Estalishment-

http-400-

request.json

Workassignment

-invalid-EEO-

Estalishment-

http-400-

response.json

Known Issues and Limitations – USXXXX: Event

notification not supported

This section details all reported and known issues. This is so developers can be aware of those issues

when using APIs.

Impacted APIs

Method: POST

URI: /events/hr/v1/worker.work-assignment.modify

roleCode: Practitioner

Known Issues and Limitations – USXXXX: Event notification not supported 10

ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.

Copyright © 2019 ADP, LLC.

Issue Description

When a change is made to the position details of an associate, either through the

/events/hr/v1/worker.work-assignment.modify API or ADP Workforce Now, event notifications are not

generated to Infolink. Infolink is unable to retrieve the event notifications through the GET event

notification call.

Suggested Workaround

There are no workarounds available.