CHAPTER 4

Use Case: Changing a General Deduction Instruction

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.

deduction-change-200. request.json

deduction-change-200. response.json

GET

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

Returns event metadata.
NOTE: 

Sample payload can be built from the meta call.

NA

deduction-change-meta-200.response.json

  • In the meta response, the codeList values are not available for DeductionGoal > Goal ID. 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-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:

  1. Your consumer application makes a request to the ADP API endpoint for Worker-general-deduction-instruction change meta.
  2. 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.
  3. Your consumer application makes a request with the payload to the ADP API endpoint for the Worker-general-deduction-instruction change API.
  4. 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

When changing a deduction, without a deduction goal, with effective date as current.

NA

deduction-change-200.request.json

deduction-change-200.response.json

 

200 OK

When changing a deduction with deduction goal with effective date as current date.

NA

deduction-change-currentdate-200.request.json

deduction-change-currentdate-200.response.json

 

200 OK

When changing a deduction with the deduction goal effective on a future date.

N/A

deduction-change-asOfDate-200.request.json

deduction-change-asOfDate-200.response.json

 

400 Bad Request

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

 

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

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

 

400 Bad Request

Trying to change a deduction but the deduction goal code is invalid.

 

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

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

 

400 Bad Request

Trying to change a deduction but the deduction goal balance amount is invalid.

 

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

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."}}

deduction-change-400.invalid-ItemID-request.json

deduction-change- 400.invalid-ItemID- response.json

Make sure a valid itemID is passed in the request.
NOTE: 

The itemID is obtained from the Payroll Instructions API.

400 Bad Request

When an invalid deductionCode is passed in the request.

{"userMessage": {"messageTxt": "deduction Code is invalid."}}

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

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

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."}

deductionChange-400-effectiveDate-change-request.json

deductionChange-400-effectiveDate-change-response.json