HomeBuildGuidesDeduction Instruction Guide for ADP Workforce Now
Chapter 3
Use Case: Using the General Deduction Instruction Start API
from Deduction Instruction Guide for ADP Workforce Now Guide
Published on
Mar 26, 2020 5:28PM
Last modified
Mar 30, 2020 4:00PM
ADP Copyright Information
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, Inc.
Windows is a registered trademark of the Microsoft Corporation.
All other trademarks are the property of their respective owners.
Copyright © 2021 ADP, Inc. ADP Proprietary and Confidential - All Rights Reserved. These materials may not be reproduced in any format without the express written permission of ADP, Inc.
These materials may not be reproduced in any format without the express written permission of ADP, Inc. 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 inaccurancies 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 programes described in this publication.
Published on
Mar 26, 2020 5:28PM
Last modified
Mar 30, 2020 4:00PM
Chapter Contents
Deduction Instruction Guide for ADP Workforce Now
Jump to chapter:
CHAPTER 3

Use Case: Using the General Deduction Instruction Start API

Use Case Description

This use case is used to start a general deduction instruction for a worker.

API Usage

Method

URI

Description

GitHub Sample Request Payload

GitHub Sample Response Payload

POST

/events/payroll/v2 /worker-general-deduction-instruction.start

Starts worker general deduction instruction information.

deduction-start- 200.request.json

deduction-start- 200.response.json

GET

/events/payroll/v2 /worker-general-deduction-instruction.start/meta

Returns an event metadata.

NOTE:
Sample payload can be built from the meta call.

NA

deduction-start-meta- 200.response.json
  • In meta response for DeductionGoal > Goal ID, the codeList values are not available. For now, it's hardcoded from (1 to 9 ).
  • sub-resource, with the value of "null", is optional and not in use.
  • sub-resource, payrollInstructionGeneralDeductionInstructionDeductionGoalGoalStartDate, is optional and not in use.

In the given payload (deduction-start-currentdate-200.request.json), the following is the purpose of the eventContext and transform sections:

  • eventContext: A set of keys, identifying the subject. In the payload, the associateID field is present under eventContext. The associateID identifies the subject.
  • transform: Provides the values added or changed with respect to the subject keys defined in the eventContext section.

Application Scope

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

/payroll/payrollManagement/payrollInstructionManagement/workerGeneralDeductionInstructionManagement/
workerGeneralDeductionInstruction.start

Supported Actors

Request Parameter roleCode Value Usage
practitioner Starts deduction instructions for workers.

Request Header Parameters

None, in addition to the ADP standard header parameters.

Sequence of Interactions


The following are the steps shown in the previous diagram:

  1. Your consumer application makes a request to the ADP API endpoint for Worker-general-deduction-instruction start meta.
  2. The ADP API endpoint responds to your consumer application with the meta payload, which lists eligible deductions for the worker under the /meta/data/transforms/ payrollInstruction/generalDeductionInstruction/deductionCode/codeList collection. Your consumer application needs to validate that the Deduction Code processed is returned in the codeLIst collection before building the payload for the next call. If the Deduction Code you need to start is not part of the collection, your application needs to provide user error handling and stop or go to the next step.
  3. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction start API with the payload.
  4. The ADP API endpoint responds to the consumer application about the details of the Worker-general-deduction-instruction start.

Data Dictionary

The fields listed in the following table can be found in the ADP Workforce Now UI by selecting People > Pay > Deductions.

Schema Location

ADP Workforce Now Field Name

Required (Y/N)?

Note

/events/data/eventContext

Not Displayed

N

 

/events/data/eventContext/worker

Not Displayed

N

 

/events/data/eventContext/worker /associateOID

Not Displayed

Y

 

/events/data/eventContext/payrollInstruction

Not Displayed

N

 

/events/data/eventContext/payrollInstruction /payrollGroupCode

Not Displayed

Y

The payrollGroupCode found in payroll.
This is an Instruction GET call.

/events/data/eventContext/payrollInstruction /payrollGroupCode/codeValue

Not Displayed

Y

 

/events/data/eventContext/payrollInstruction /payrollGroupCode/shortName

Not Displayed

Y

 

/events/data/eventContext /payrollInstruction/payrollFileNumber

Not Displayed

Y

The payrollFileNumber found in payroll.
This is an instruction GET call.

/events/data/eventContext/payrollInstruction /payrollAgreementID

Not Displayed

Y

The payrollAgreementID found in payroll.
This is an instruction GET call.

/events/data/effectiveDateTime

Effective Date

Y

 

/events/data/payrollInstruction

Not Displayed

N

 

/events/data/payrollInstruction /generalDeductionInstruction

Not Displayed

N

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionCode

Not Displayed

Y

 

/events/data/payrollInstruction/generalDeductionInstruction/deductionCode /codeValue

Not Displayed

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionCode /shortName

Deduction Code

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionRate

Not Displayed

N

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionRate /rateValue

Deduction Amount

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal

Deduction Goal

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalID

Not Displayed

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalLimitAmount

Not Displayed

N

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalLimitAmount/amountValue

Deduction Goal Limit

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalLimitAmount/currencyCode

Not Displayed

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalBalanceAmount

Balance

N

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalBalanceAmount/amountValue

Not Displayed

Y

 

/events/data/payrollInstruction /generalDeductionInstruction/deductionGoal /goalBalanceAmount/currencyCode

Not Displayed

Y

 

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

Response Condition

message Txt

GitHub Sample Request Payload

GitHub Sample Response Payload

Tips to Handle

200 OK

When adding a deduction without a deduction goal and the effective date as the current date.

NA

deduction-start- 200.request.json

deduction-start- 200.response.json

 

200 OK

When adding a deduction with a deduction goal and the effective date as the current date.

NA

deduction-start-currentdate-200.request.json

deduction-start-currentdate-200.response.json

 

200 OK

When adding a deduction with a deduction goal and effective date as the future date.

NA

deduction-start-asOfDate-200.request.json

deduction-start-asOfDate-200.response.json

 

400 Bad Request

When trying to start a deduction but the goal limit amount is invalid.

 

deduction-start-Invalid-GoalLimitAmount-400.request.json

deduction-start-Invalid-GoalLimitAmount-400.response.json

 

400 Bad Request

When trying to start a deduction but the deduction goal code is invalid.

 

deduction-start-Invalid-GoalCode-400.request.json

deduction-start-Invalid-GoalCode-400.response.json

 

400 Bad Request

When trying to start a deduction but the deduction goal balance amount is invalid.

 

deduction-start-Invalid-GoalBalanceAmount-400.request.json

deduction-start-Invalid-GoalBalanceAmount-400.response.json

 

400 Bad Request

When trying to start the deduction for the associate who already has this deduction.
For example, Deduction Code: H.

{"userMessage": {"messageTxt": "You cannot add this employee deduction because the deduction currently exists with the effective date of 08/20/2018."
}}

deduction-start-400.deduction-already-applied- request.json

deduction-start- 400.deduction- already-applied-response.json

The specified deduction is already started. Make sure to check all the deductions are started for an associate. Try with a different deduction, which is not yet started.

400 Bad Request

When the invalid deduction code is passed in the request.

{"userMessage": {"messageTxt": "deductionCodeis invalid."}}

deduction-start-400.invalid-deduction- code-request.json

deduction-start-400.invalid-deduction-code-response.json

Make sure a valid supported Deduction Code is passed in the request.

400 Bad Request

When there is an invalid "payrollGroupCode/codeValue" in the request.

{
"userMessage": {"messageTxt": "payrollGroupCode/codeValue is invalid."
}}

deduction-start-400.invalid-payroll- groupCode-request.json

deduction-start-400.invalid- payroll-groupCode-response.json

Make sure a valid payrollGroupCode /codeValue is passed in the request.

400 Bad Request

When there is an invalid payrollAgreementID in the request.

{"userMessage": {"messageTxt": "payrollAgreementIDis invalid."
}}

deduction-start-400.invalid-payroll-agreementID-request.json

deduction-start-400.invalid-payroll-agreementID-response.json

Make sure a valid payrollAgreementID is passed in the request.

400 Bad Request

When there is an invalid payrollFileNumber in the request.

{"userMessage": {"messageTxt": "payrollFileNumber is invalid."
}}

deduction-start-400.invalid-payroll-fileNumber-request.json

deduction-start-400.invalid-payroll-fileNumber-response.json

Make sure a valid payrollFileNumber is passed in the request.

400 Bad Request

When a DeductionAmount is passed as an invalid value in the request.

{"userMessage": {"messageTxt": "Deduction Amountfield must contain a non-zerovalue between -99,999,999.99and 99,999,999.99 with a decimalprecision of 2 places."
}}

deduction-start-400.invalid-deduction-amount-request.json

deduction-start-400.invalid-deduction-amount-response.json

Make sure you have entered the amount value correctly.

NOTE:

Deduction Amount must contain a non-zero value between-99,999,999.99 and 99,999,999.99 with a precision of 2.
Prev chapter: Use Case: Retrieving Payroll Instructions (Payroll Instructions API)
Next chapter: Use Case: Changing a General Deduction Instruction
ADP Marketplace
About Marketplace
Apps
Partners
Developers
About ADP
API Reference
Core APIs
HR APIs
Payroll APIs
Staffing APIs
Talent APIs
Tax APIs
Time APIs
Learn
Key concepts
How-to articles
FAQs
Build
Integration by solution
API explorer
Developer libraries
Guides
Support
Status
Help center
ADP and the ADP logo are registered trademarks of ADP, Inc. All other marks are the property of their respective owners.
Copyright © 2021 ADP, Inc.
Terms|Privacy