Employees Sub Service - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the EmployeesService, which is your primary tool for interacting with employee-related records through the contract-based API.

1. Importing Helpers

Before you start, import the necessary builders and query helpers. The EmployeesService methods rely on these to construct payloads and define query parameters.

from easy_acumatica.models.employee_builder import EmployeeBuilder
from easy_acumatica.models.employee_payroll_class_builder import EmployeePayrollClassBuilder
from easy_acumatica.models.employee_payroll_settings_builder import EmployeePayrollSettingsBuilder
from easy_acumatica.models.query_builder import QueryOptions

2. Understanding the Service's Purpose

The EmployeesService provides a set of methods for creating and managing core employee records, payroll classes, and payroll settings. It acts as the main interface for all employee-related actions, orchestrating the calls to different API endpoints.

3. EmployeesService Methods

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

Method	Description	Key Parameters
.create_employee()	Creates a new employee record.	api_version, builder
.get_employees()	Retrieves a list of employees based on query options.	api_version, options
.create_employee_payroll_class()	Creates a new employee payroll class definition.	api_version, builder
.update_employee_payroll_settings()	Updates the payroll settings for a specific employee.	api_version, builder

4. Creating and Retrieving Employees

A common workflow is to create new employees or query for existing ones.

create_employee(api_version, builder)

This method creates a new employee record. You must provide an EmployeeBuilder instance containing the employee's details.

Example: Create a new employee

# 1. Build the employee payload
employee_payload = (
    EmployeeBuilder()
    .employee_id("NEWEMP01")
    .employee_name("Jane Doe")
    .status("Active")
    .set("Department", "SALES")
)

# 2. Use the payload to create the record
try:
    new_employee = client.employees.create_employee("24.200.001", employee_payload)
    print(f"Successfully created employee: {new_employee['EmployeeID']['value']}")
except Exception as e:
    print(f"Failed to create employee: {e}")

get_employees(api_version, options)

This method retrieves a list of employees. You can use QueryOptions to filter, select, and expand the results.

Example: Get all active employees in the engineering department

# 1. Define query options
query = (
    QueryOptions()
    .select("EmployeeID", "EmployeeName", "Status")
    .filter("Status eq 'Active' and Department eq 'ENGI'")
)

# 2. Retrieve the employees
try:
    active_engineers = client.employees.get_employees("24.200.001", options=query)
    for emp in active_engineers:
        print(f"ID: {emp['EmployeeID']['value']}, Name: {emp['EmployeeName']['value']}")
except Exception as e:
    print(f"Failed to get employees: {e}")

5. Creating an Employee Payroll Class

create_employee_payroll_class(api_version, builder)

This method creates a new, reusable payroll class. You must provide an EmployeePayrollClassBuilder instance.

# 1. Build the payroll class payload
payroll_class_payload = (
    EmployeePayrollClassBuilder()
    .employee_payroll_class_id("CONTRACTOR")
    .description("1099 Contractors")
    .payroll_defaults(payGroup="WEEKLY", paymentMethod="Check")
)

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

6. Updating Employee Payroll Settings

update_employee_payroll_settings(api_version, builder)

This method allows you to modify the payroll settings for a specific, existing employee. You must identify the employee using the EmployeePayrollSettingsBuilder.

Example: Assign a payroll class and payment method to an employee

# 1. Build the settings update payload
settings_payload = (
    EmployeePayrollSettingsBuilder()
    .employee_id("EP00000099")
    .class_id("CONTRACTOR")
    .payment_method("DirectDeposit")
    .cash_account("10100")
)

# 2. Use the payload to update the record
try:
    updated_settings = client.employees.update_employee_payroll_settings(
        "24.200.001",
        builder=settings_payload
    )
    print(f"Successfully updated settings for: {updated_settings['EmployeeID']['value']}")
except Exception as e:
    print(f"Failed to update settings: {e}")