Manage Element Entries

You can process element entries within a payroll run or QuickPay to produce payments and deductions for employees. You can classify them as Regular Earnings, Voluntary Deductions, or information elements. Within a payroll period, you can also create, update, and delete additional recurring and nonrecurring element entries as per business processes and policies to ensure that employees are paid correctly. It's important that employees' element entries are accurate for each payroll period. You can use the elementEntries resource to manage payroll element entries for employees.

Let's discuss these scenarios:

• Review Element Entries
• Create an Element Entry
• Update an Element Entry
• Delete an Element Entry

Review Element Entries

Let's say that John, a payroll user, is aware of a large bonus payment made to a senior executive. John wants to review the element entries for the current period to ensure that the bonus element has been entered correctly. To review the details, he submits a GET request on the elementEntries resource.

To retrieve the bonus element entry:

1. Submit a GET request on the elementEntries resource using the PersonNumber as the query parameter.
2. Verify the details returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/elementEntries/?q=PersonNumber='300100003143709'

Example Response

Here's an example of the response body in JSON format.

{
"items" : [ {
  "ElementEntryId" : 300100004914639,
  "EffectiveStartDate" : "2010-01-01",
  "EffectiveEndDate" : "4712-12-31",
  "CreatorType" : "F",
  "ElementTypeId" : 300100003068055,
  "EntryType" : "E",
  "EntrySequence" : null,
  "PersonId" : 300100003143709,
  "Reason" : null,
  "Subpriority" : null,
  "PersonNumber" : "300100003143709",
  "AssignmentId" : null,
  "AssignmentNumber" : "E300100003143709",
  "PayrollRelationshipNumber" : "300100003143743",
  "ElementName" : "ZHRX_USP_RegEarnings_One",
  "UsageLevel" : "PA",
  "links": [
     {
       ...}
  ]
}

Create an Element Entry

Let's say that Mike, an employee, has submitted a late approved time card to payroll. Bran, a payroll user, wants to create an element entry for 10 hours overtime for Mike. To create the entry, he submits a POST request on the elementEntries resource.

To create an element entry for an employee:

1. Perform a POST operation on the elementEntries resource by providing the worker details in the request body.
2. Verify the details returned in the response.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/elementEntries

Example Request

Here's an example of the request body in JSON format.

{
   "PersonId": 300100003143709,
   "ElementTypeId": 300100003068055,
   "AssignmentId": 300100003143747,
   "EntryType": "E",
   "CreatorType": "F",
   "EntrySequence": 1,
   "elementEntryValues": [
    {
     "InputValueId": 300100003068067,
     "ScreenEntryValue": "1000"
    }
   ]
}

Example Response

Here's an example of the response body in JSON format.

{
    "ElementEntryId": 300100559371979,
    "EffectiveStartDate": "2020-07-25",
    "EffectiveEndDate": "4712-12-31",
    "CreatorType": "F",
    "ElementTypeId": 300100003068055,
    "EntryType": "E",
    "EntrySequence": 1,
    "PersonId": 300100003143709,
    "Reason": null,
    "Subpriority": null,
    "PersonNumber": "300100003143709",
    "AssignmentId": 300100003143747,
    "AssignmentNumber": "E300100003143709",
    "PayrollRelationshipNumber": "300100003143743",
    "ElementName": "ZHRX_USP_RegEarnings_One",
    "UsageLevel": "PA",
    "elementEntryValues": {
    "items": []
    }
}

Update an Element Entry

Diane, a payroll user, has been informed that an employee, Ben, has passed his safety certificate training, which means he should be paid at a higher rate for safety training allowance. Diane now needs to update the Safety Allowance element entry to reflect that Ben has completed the appropriate training.

To update an element entry

1. Query (GET) the employee and identify the element entry to be updated by using a query parameter. For example: /hcmRestApi/resources/11.13.18.05/elementEntries/?q=PersonNumber='123'.
2. Go to the child link for the element.
3. Go to the canonical link of the input value (example: Amount) and perform a GET operation.
4. Perform a PATCH operation on this URL by providing the Effective-Of header and the element entry in the request body.
5. Verify the details returned in the response.

Example URL

Use this resource URL format.

PATCH

hcmRestApi/resources/11.13.18.05/elementEntries/{ID}/child/elementEntryValues/{ID}

Example Request

Here's an example of request body in JSON format.

Provide the header.

Effective-Of : RangeMode=CORRECTION;RangeStartDate=2010-01-01;RangeEndDate=4712-12-31

{
  "ScreenEntryValue": "5000"
}

Example Response

Here's an example of the response body in JSON format.

{
  "ScreenEntryValue": "5000",
  "ElementEntryValueId": 300100559414098,
  "InputValueId": 300100003068067,
  "InputValueName": "Amount"
}

Delete an Element Entry

Susan, a payroll user, noticed that two element entries have been created by mistake for the same allowance payment for an employee, Mark. She wants to delete one of Mark's allowance payments for this payroll period.

To delete an element entry:

1. Query (GET) the employee and identify the element entry to be updated by using a query parameter. For example: /hcmRestApi/resources/11.13.18.05/elementEntries/?q=PersonNumber='123'.
2. Go to the canonical link and perform a GET operation.
3. Perform a DELETE operation on the URL for the element entry by providing the Effective-Of header.

Example URL

Use this resource URL format.

DELETE

/hcmRestApi/resources/11.13.18.05/elementEntries/{ID}

Example Request

Provide the header. You don't need a payload for this operation.

Effective-Of : RangeMode=ZAP;RangeStartDate=2010-01-01;RangeEndDate=4712-12-31

Example Response

Here's an example of the response body in JSON format.

204 - No content