Stage Payroll

Prerequisites

Before staging payroll or accruals for export, you must create a custom table. Each custom table acts as a lookup table, for example, you might create an Effective Wage Lookup Table. You must create and maintain custom tables to generate variance reports.

You must understand how to work with asynchronous calls. For a brief introduction, refer to the overview of A Guide to Running Payroll.

Example

In this example, we stage an asynchronous payroll job and retrieve status and details about that job.

Stage Payroll

The staging request:

• the ignoreSignOff Boolean defaults to true and ensures payroll is processed whether or not employees' timecards are signed off
• the processBasedOn object allows you to specify the conditions on which to base payroll processing and contains the properties filterBy and type
  • the filterBy property is only needed if the type is WORKED or POSITION_ASSIGNMENT. The default value is JOB and valid values include: JOB, LABOR_CATEGORY, COST_CENTER, and POSITION_CUSTOM_FIELD.
  • the type property accepts a value of PRIMARY, WORKED, or POSITION_ASSIGNMENT.
    • PRIMARY - stages payroll based on each employee's primary, or home, pay group attributes
    • WORKED - currently only supports orgJob; does not filter based on any other categories
    • POSITION_ASSIGNMENT - stages payroll based on each employee's position assignment
• the exportType can be Payroll for payroll integrations, Accrual for accrual integrations, or Both for both payroll and accruals; see note below
• accepts the name of the paycode mapping table as a qualifier in the payCodeMappingTable object
• allows you to define the historicalCorrections as Include in Totals, Exclude in Totals, or Correction Only. Include in Totals is the default.

Note: When the exportType is set to Both, you must include the exportType query parameter (defining either Payroll or Accrual) when you query the asynchronous job's status or details as described in the following sections.

Additional Details about the processBasedOn property

If the processBasedOn property is PRIMARY, the employees associated with the job are filtered on the basis of primary attributes. After filtering, the system pushes all punches, regardless of where they occurred or of the cost center.

If the processBasedOn property is WORKED, the employees associated with the job are filtered only on the basis of orgJob. After filtering, the system pushes all punches regardless of labor category or cost center. During the export process, unwanted records must be filtered out. Using WORKED only filters based on the worked job location. Labor category and cost center are NOT applied or factored in when WORKED is selected.

If the processBasedOn property is POSITION_ASSIGNMENT, the employees associated with an assigned position are filtered on the basis of the job associated with that position regardless of any transfers.

Example request 1

Call the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) operation with the following request payload.

{
   "employees" : {
    "qualifiers" : "20335"
  },
  "payCodeMappingTable": {
    "qualifier": "Payroll Paycode Mapping1"
  },
  "dateRange": {
    "symbolicPeriod": {
      "id": 0
    }
  },
  "exportType": "Payroll",
  "historicalCorrections": "Included in Totals",
  "processTerminatedEmployeesOnly": false,
  "processBasedOn": {
    "type": "PRIMARY"
  },
  "ignoreSignOff": true,
  "customParameter1": "Cust Para 1",
  "customParameter2": "Cust Para 2"
}

Example request 2

Call the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) operation with the following request payload.

{
  "where": {
    "employeeIn": [
      {
        "payGroup": {
          "positionCustomField": [
            {
              "label": {
                "id": 1,
                "qualifier": "Category One"
              },
              "values": []
            }
          ]
        }
      }
    ]
  },
  "exportType": "Payroll",
  "processBasedOn": {
    "type": "POSITION_ASSIGNMENT",
    "filterBy": "POSITION_CUSTOM_FIELD"
  }
}

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
    "requestId": "10982d9f-ea2e-46ad-8370-1e60d5a665b7",
    "status": "PENDING",
    "message": "The request is being processed.",
    "nextPing": 60
}

Retrieve job status

To retrieve the job status for an asynchronous payroll staging job, call the Retrieve Payroll Staging Asynchronous Request Status by ID (GET /v1/commons/payroll/staging/{requestId}/status) operation.

Note: When the exportType is set to Both, you must include the exportType query parameter (defining either Payroll or Accrual).

Success example

Calling GET /v1/commons/payroll/staging/10982d9f-ea2e-46ad-8370-1e60d5a665b7/status returns the following for a successful job:

{
    "status": "success",
    "message": "The request completed successfully.",
    "nextPing": 60,
    "requestId": "10982d9f-ea2e-46ad-8370-1e60d5a665b7"
}

Queued success example

Calling GET /v1/commons/payroll/staging/10982d9f-ea2e-46ad-8370-1e60d5a665b7/status returns the following for a queued job:

{
  "status": "queued",
  "message": " The requested process was successfully initiated and has been placed in the queue.",
  "nextPing": 60,
  "executionKey": "8e3e1948-7444-4588-8dc9-c1dc9b0acbed"
}

Queued failed example

Calling GET /v1/commons/payroll/staging/10982d9f-ea2e-46ad-8370-1e60d5a665b7/status returns the following for a job that failed to enter the queue:

{
  "status": "queued_failed",
  "message": "The requested process failed and could not be placed in the queue. The queue is limited to {NumberOfEntriesMaxLimit} and the requested process is {EntryNumber}.",
  "nextPing": 60,
  "executionKey": "6cba5f19-aaef-49df-acf4-76735c21cbaa"
}

Retrieve job details

To retrieve the job details for an asynchronous payroll staging job, call the Retrieve Asynchronous Payroll Staging Details by ID (GET /v1/commons/payroll/staging/{requestId}/details) operation.

Calling GET /v1/commons/payroll/staging/10982d9f-ea2e-46ad-8370-1e60d5a665b7/details returns:

{
    "status": "success",
    "message": "The request completed successfully."
}

Note: The job details operation is meant to provide enhanced success and failure details for partial success scenarios. If all items in a job are successful, this operation is not necessary.

Note: When the exportType is set to Both, you must include the exportType query parameter (defining either Payroll or Accrual).