Work Calendar Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the WorkCalendarBuilder, which is your primary tool for creating the JSON payload needed to create WorkCalendar records.

1. Importing the Builder

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

from easy_acumatica.models.work_calendar_builder import WorkCalendarBuilder

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 WorkCalendarBuilder handles this formatting for you automatically, allowing you to construct a valid payload for a new work calendar using a fluent, chainable interface.

[!NOTE] As noted in the builder's source code, there is currently no public method to add calendar exceptions or define specific workdays through this builder.

3. WorkCalendarBuilder Methods

The following table summarizes the methods available in the WorkCalendarBuilder.

Method	Description	Key Parameters
.set()	Sets any top-level field on the work calendar.	field (str), value (Any)
.work_calendar_id()	(Required) Sets the WorkCalendarID.	work_calendar_id (str)
.description()	Sets the Description of the work calendar.	description (str)
.time_zone()	Sets the TimeZone using Acumatica's specific format.	time_zone (str)
.to_body()	Constructs the final JSON payload for the request.	(None)

4. Building a Work Calendar Payload

You can use the builder's methods to construct the payload for the new work calendar.

Example: Creating a basic work calendar

# 1. Create a builder instance
calendar_payload = (
    WorkCalendarBuilder()
    .work_calendar_id("STANDARD")
    .description("Standard Mon-Fri Work Week")
    .time_zone("GMTM0600C") # Example: US Central Time
)

5. Generating the Final JSON Body

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

# 1. Build the work calendar
calendar_payload = (
    WorkCalendarBuilder()
    .work_calendar_id("STANDARD")
    .description("Standard Mon-Fri Work Week")
)

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

# The json_body will look like this:
# {
#   "WorkCalendarID": {"value": "STANDARD"},
#   "Description": {"value": "Standard Mon-Fri Work Week"}
# }

6. Complete Example with WorkCalendarsService

Here is a complete example of how to use the WorkCalendarBuilder to create a new work calendar record.

from easy_acumatica.models.work_calendar_builder import WorkCalendarBuilder

# 1. Build the work calendar payload
calendar_to_create = (
    WorkCalendarBuilder()
    .work_calendar_id("24-7-OPS")
    .description("24/7 Operations Calendar")
    .time_zone("GMT")
)

# 2. Use the payload with the WorkCalendarsService to create the record
try:
    new_calendar = client.work_calendars.create_work_calendar(
        "24.200.001",
        builder=calendar_to_create
    )
    print(f"Successfully created work calendar: {new_calendar['WorkCalendarID']['value']}")
except Exception as e:
    print(f"Failed to create work calendar: {e}")