Employee Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the EmployeeBuilder, your primary tool for creating the JSON payload needed to create new Employee records with the EmployeesService.

1. Importing the EmployeeBuilder

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

from easy_acumatica.models.employee_builder import EmployeeBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, the Employee endpoint requires a nested JSON structure. The EmployeeBuilder handles the creation of this structure for you, including the ContactInfo, FinancialSettings, and EmployeeSettings objects. It also wraps each field in the required {"value": ...} format.

The builder provides a fluent, chainable interface for setting all the necessary fields for a new employee.

3. Building an Employee Payload

You can set fields using the dedicated methods for each section of the employee record.

.status(status)

Sets the top-level status of the employee.

builder = EmployeeBuilder().status("Active")

.contact_info(...)

Sets fields within the ContactInfo object. Common fields are available as named arguments, and any others can be passed as keyword arguments.

builder.contact_info(  
    first_name="Jane",  
    last_name="Doe",  
    email="[email protected]",  
    Title="Lead Developer" # Example of a kwarg  
)

.financial_settings(...)

Sets fields within the FinancialSettings object. Common fields are available as named arguments.

builder.financial_settings(  
    ap_account="20000",  
    payment_method="CHECK",  
    terms="NET30",  
    PrepaymentAccount="12345" # Example of a kwarg  
)

.employee_settings(...)

Sets fields within the EmployeeSettings object. Common fields are available as named arguments.

builder.employee_settings(  
    branch_id="HEADOFFICE",  
    department_id="RND",  
    employee_class="EMPSALARIED",  
    Calendar="MAIN" # Example of a kwarg  
)

4. Generating the Final JSON Body

Once you have set all the required fields, call the .to_body() method to generate the final dictionary. This dictionary is formatted correctly and is ready to be sent as the JSON body in your API request.

# Build a complete employee payload  
employee_payload = (  
    EmployeeBuilder()  
    .status("Active")  
    .contact_info(first_name="Jane", last_name="Doe")  
    .financial_settings(payment_method="DIRECT")  
    .employee_settings(department_id="SUPPORT")  
)

# Get the final dictionary  
json_body = employee_payload.to_body()

# The json_body will look something like this:  
# {  
#     "Status": {"value": "Active"},  
#     "ContactInfo": {  
#         "FirstName": {"value": "Jane"},  
#         "LastName": {"value": "Doe"}  
#     },  
#     "FinancialSettings": {  
#         "PaymentMethod": {"value": "DIRECT"}  
#     },  
#     "EmployeeSettings": {  
#         "DepartmentID": {"value": "SUPPORT"}  
#     }  
# }

5. Complete Example with EmployeesService

Here is a complete example of how to use the EmployeeBuilder to create a new employee.

from easy_acumatica.models.employee_builder import EmployeeBuilder  
from easy_acumatica.models.query_builder import QueryOptions

# 1. Build the employee payload  
employee_to_create = (  
    EmployeeBuilder()  
    .status("Active")  
    .contact_info(first_name="John", last_name="Smith", email="[email protected]")  
    .financial_settings(  
        ap_account="20000",  
        payment_method="CHECK",  
        terms="NET30"  
    )  
    .employee_settings(  
        branch_id="HEADOFFICE",  
        department_id="SALES",  
        employee_class="EMPSALARIED"  
    )  
)

# 2. Use QueryOptions to get the nested details back in the response  
options = QueryOptions(expand=["ContactInfo", "FinancialSettings", "EmployeeSettings"])

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