Employee Payroll Class Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the EmployeePayrollClassBuilder, which is your primary tool for creating the JSON payload needed to create EmployeePayrollClass records with the EmployeesService.

1. Importing the EmployeePayrollClassBuilder

To get started, import the EmployeePayrollClassBuilder from the models directory.

from easy_acumatica.models.employee_payroll_class_builder import EmployeePayrollClassBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure, such as {"value": ...}. The EmployeePayrollClassBuilder handles this formatting for you automatically, allowing you to construct a valid payload using a fluent, chainable interface. It simplifies the creation of nested objects like PayrollDefaults and lists like PTODefaults.

3. EmployeePayrollClassBuilder Methods

The following table summarizes the primary methods available in the EmployeePayrollClassBuilder.

Method	Description	Parameters
.set()	Sets any top-level field on the payroll class.	field (str), value (Any)
.employee_payroll_class_id()	(Required) Sets the EmployeePayrollClassID.	id (str)
.description()	Shortcut for setting the Description.	description (str)
.payroll_defaults()	Sets fields within the nested PayrollDefaults object.	**kwargs
.add_pto_default()	Adds a PTO default object to the PTODefaults list.	**kwargs
.to_body()	Constructs the final JSON payload for the request.	(None)

4. Building a Payroll Class Payload

You can set top-level fields using the generic .set() method or the convenient shortcut methods.

Setting Defaults

The .payroll_defaults() method sets key-value pairs for the PayrollDefaults object, and .add_pto_default() adds an entire object to the PTODefaults list. You can chain these methods to build a complete configuration.

Example: Building a complete employee payroll class

# 1. Create a builder instance
payroll_class_payload = (
    EmployeePayrollClassBuilder()
    .employee_payroll_class_id("EXECUTIVE")
    .description("Executive-level employee class")
    .set("IsActive", True)
    .payroll_defaults(
        earningType="S", 
        payGroup="MONTHLY", 
        paymentMethod="Check"
    )
    .add_pto_default(
        ptoBank="VACATION", 
        disbursingType="Current Rate", 
        accrualMethod="Percentage of Gross"
    )
    .add_pto_default(
        ptoBank="SICK", 
        disbursingType="Current Rate", 
        accrualMethod="Fixed Amount"
    )
)

5. Generating the Final JSON Body

Once you have configured the builder, call the .to_body() method to generate the final dictionary ready for the API request.

# 1. Build the payroll class
payroll_class_payload = (
    EmployeePayrollClassBuilder()
    .employee_payroll_class_id("EXECUTIVE")
    .description("Executive-level employee class")
    .add_pto_default(ptoBank="VACATION")
)

# 2. Get the final dictionary
json_body = payroll_class_payload.to_body()

# The json_body will look like this:
# {
#     "EmployeePayrollClassID": {"value": "EXECUTIVE"},
#     "Description": {"value": "Executive-level employee class"},
#     "PTODefaults": [
#         {
#             "PTOBank": {"value": "VACATION"}
#         }
#     ]
# }

6. Complete Example with EmployeesService

Here is a complete example of how to use the EmployeePayrollClassBuilder to create a new employee payroll class.

from easy_acumatica.models.employee_payroll_class_builder import EmployeePayrollClassBuilder

# 1. Build the employee payroll class payload
class_to_create = (
    EmployeePayrollClassBuilder()
    .employee_payroll_class_id("SALARIED")
    .description("Standard Salaried Employees")
    .set("IsActive", True)
    .payroll_defaults(
        earningType="S",
        payGroup="BIWEEKLY",
        paymentMethod="DirectDeposit"
    )
    .add_pto_default(
        ptoBank="VAC",
        accrualMethod="Percentage of Gross",
        accrualPercent=5.0
    )
)

# 2. Use the payload with the EmployeesService to create the record
try:
    new_class = client.employees.create_employee_payroll_class(
        "24.200.001",
        builder=class_to_create
    )
    print(f"Successfully created payroll class: {new_class['EmployeePayrollClassID']['value']}")
except Exception as e:
    print(f"Failed to create payroll class: {e}")