Use Case Description
This use case is used to change a general deduction instruction for a single worker.
API Usage
|
Method |
URI |
Description |
GitHub Sample Request Payload |
GitHub Sample Request Payload |
|---|---|---|---|---|
|
POST |
/events/payroll/v2 /worker-general-deduction-instruction.change |
Changes a worker's general deduction instruction information. |
||
|
GET |
/events/payroll/v2/worker-general-deduction-instruction.change/meta |
Returns event metadata. |
NA |
- In the meta response, the codeList values are not available for DeductionGoal > Goal ID. Currently, 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-change-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.change
Supported Actors
|
Request Parameter roleCode Value |
Usage |
|---|---|
| practitioner | Changes 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:
- Your consumer application makes a request to the ADP API endpoint for Worker-general-deduction-instruction change meta.
- The ADP API endpoint responds to your consumer application with the meta payload, which lists the eligible deductions for the worker under the /meta/data/transforms/ /payrollInstruction/generalDeductionInstruction/deductionCode/codeList collection. Your consumer application needs to validate the Deduction Code to be 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 step 3.
- Your consumer application makes a request with the payload to the ADP API endpoint for the Worker-general-deduction-instruction change API.
- The ADP API endpoint responds to the consumer with the details of the Worker-general-deduction-instruction change.
Data Dictionary
|
Schema Location |
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 |
The associateOID will get this from the worker call API. |
|
/events/data/eventContext/payrollInstruction |
Not Displayed |
N |
|
|
/events/data/eventContext/payrollInstruction/itemID |
Not Displayed |
Y |
The itemID will get this from the payroll Instructions GET call. |
|
/events/data/eventContext/payrollInstruction/payrollGroupCode |
Not Displayed |
Y |
The payrollGroupCode will get this from the payroll Instructions 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 will get this from the payroll Instruction GET call. |
|
/events/data/eventContext/payrollInstruction/payrollAgreementID |
Not Displayed |
Y |
The payrollAgreementID will get this from the payroll Instruction GET call. |
|
/events/data/eventContext/payrollInstruction/generalDeductionInstruction |
Not Displayed |
N |
|
|
/events/data/eventContext/payrollInstruction/generalDeductionInstruction/deductionCode |
Not Displayed |
Y |
|
|
/events/data/eventContext/payrollInstruction/generalDeductionInstruction/deductionCode/codeValue |
Not Displayed |
Y |
|
|
/events/data/transform/effectiveDateTime |
Effective |
Y |
|
|
/events/data/transform/payrollInstruction |
Not Displayed |
|
|
|
/events/data/transform/payrollInstruction/ generalDeductionInstruction |
Not Displayed |
|
|
|
/events/data/transform/payrollInstruction/generalDeductionInstruction/deductionRate |
Not Displayed |
Y |
|
|
/events/data/transform/payrollInstruction/generalDeductionInstruction/deductionRate/rateValue |
Deduction Amount |
Y |
|
|
/events/data/transform/payrollInstruction/ generalDeductionInstruction/deductionGoal |
Deduction Goal |
Y |
|
|
/events/data/transform/payrollInstruction/generalDeductionInstruction/deductionGoal/goalID |
Not Displayed |
Y |
|
|
/events/data/transform/payrollInstruction/generalDeductionInstruction/deductionGoal/ goalLimitAmount |
Deduction Goal Limit |
Y |
|
|
/events/data/transform/payrollInstruction/ generalDeductionInstruction/deductionGoal/ goalLimitAmount/amountValue |
Not Displayed |
Y |
|
|
/events/data/transform/payrollInstruction/ generalDeductionInstruction/deductionGoal/ goalBalanceAmount |
Not Displayed |
Y |
|
|
/events/data/transform/payrollInstruction/ generalDeductionInstruction/deductionGoal/ goalBalanceAmount/amountValue |
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 |
messageTxt |
GitHub Sample Request Payload |
GitHub Sample Response Payload |
Tips to Handle |
|---|---|---|---|---|---|
| 200 OK | Changing a deduction with InactiveIndicator as true | deductionChange-Inactive-true-200.request.json | deductionChange-Inactive-true-200.response.json | ||
| 200 OK | Changing a deduction with InactiveIndicator as false | deductionChange-Inactive-false-200.request.json | deductionChange-Inactive-false-200.response.json | ||
|
200 OK |
When changing a deduction, without a deduction goal, with effective date as current. |
NA |
|
||
|
200 OK |
When changing a deduction with deduction goal with effective date as current date. |
NA |
|
||
|
200 OK |
When changing a deduction with the deduction goal effective on a future date. |
N/A |
|
||
|
400 Bad Request |
When trying to change a deduction but the goal limit amount is invalid. |
|
|
||
|
400 Bad Request |
Trying to change a deduction but the deduction goal code is invalid. |
|
|
||
|
400 Bad Request |
Trying to change a deduction but the deduction goal balance amount is invalid. |
|
deduction-change-Invalid-GoalBalanceAmount-400.response.json |
|
|
|
400 Bad Request |
When the invalid payroll GroupCode/codeValue is passed in the request. |
{"userMessage": {"messageTxt": "payrollGroupCode/codeValue is invalid."}} |
deduction-change-400.invalid- payroll-groupCode-request.json |
deduction-change- 400.invalid- payroll-groupCode- response.json |
Make sure a valid payrollGroupCode/codeValue is passed in the request. |
|
400 Bad Request |
When the invalid payrollFileNumber is passed in the request. |
{"userMessage": {"messageTxt": "payrollFileNumber is invalid."}} |
deduction-change-400.invalid-payroll-fileNumber-request.json |
deduction-change-400.invalid-payroll-fileNumber-response.json |
Make sure a valid payrollFileNumber is passed in the request. |
|
400 Bad Request |
When the invalid payrollAgreementID is passed in the request. |
{"userMessage": {"messageTxt": "payrollAgreementID is invalid."}} |
deduction-change-400.invalid-payroll-agreementID-request.json |
deduction-change-400.invalid-payroll-agreementID-response.json |
Make sure a valid payrollAgreementID is passed in the request. |
|
400 Bad Request |
When the invalid itemId is passedin the request. |
{"userMessage": {"messageTxt":"itemId is invalid."}} |
Make sure a valid itemID is passed in the request. |
||
|
400 Bad Request |
When an invalid deductionCode is passed in the request. |
{"userMessage": {"messageTxt": "deduction Code is invalid."}} |
Make sure a valid deductionCode is passed in the request. |
||
|
400 Bad Request |
When the future effective date is passed in the request without a changing deduction amount or deduction goal. |
"userMessage": {"messageTxt": "To save, please change the Deduction Amount field and/or the Active field."} |
