Case Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the CaseBuilder, which is your primary tool for creating the JSON payload needed to create or update Case records with the CasesService.

1. Importing the CaseBuilder

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

from easy_acumatica.models.case_builder import CaseBuilder

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: {"value": ...}. The CaseBuilder handles this formatting for you automatically, so you can focus on the data itself.

The builder provides a fluent, chainable interface for setting the fields of a case record, including related cases and custom fields.

3. CaseBuilder Methods

You can set fields using either the generic .set() method or one of the convenient shortcut methods. The following table summarizes all available methods.

Method	Description	Parameters
.set()	Sets any top-level field on the case record.	field (str), value (Any)
.class_id()	Shortcut for setting the ClassID.	class_id (str)
.business_account()	Shortcut for setting the BusinessAccount.	account (str)
.contact_id()	Shortcut for setting the ContactID.	contact_id (str)
.subject()	Shortcut for setting the Subject.	subject (str)
.add_related_case()	Adds a case to the RelatedCases list.	case_id (str)
.set_custom_field()	Sets a custom field value.	view (str), field (str), value (Any), field_type (str)
.to_body()	Constructs the final JSON payload.	(None)

4. Adding Related Cases and Custom Fields

The builder also has dedicated methods for handling more complex data structures.

add_related_case(case_id)

Use this method to link the new case to an existing one. You can chain this method to link multiple cases.

case_payload = (
    CaseBuilder()
    .subject("Duplicate of existing issue")
    .add_related_case("CR000123")
)

set_custom_field(view, field, value, field_type)

This method allows you to set custom fields defined in your Acumatica instance.

case_payload = (
    CaseBuilder()
    .subject("Inquiry about support tiers")
    .set_custom_field(
        view="Case",
        field="UsrSupportTier", # Custom field name
        value="Gold",
        field_type="CustomStringField"
    )
)

5. 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 the case
case_payload = (
    CaseBuilder()
    .class_id("SUPPORT")
    .business_account("ABCCORP")
    .subject("Cannot log in to portal")
    .add_related_case("CR000455")
    .set_custom_field("Case", "UsrSupportTier", "Gold")
)

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

# The json_body will look like this:
# {
#     "ClassID": {"value": "SUPPORT"},
#     "BusinessAccount": {"value": "ABCCORP"},
#     "Subject": {"value": "Cannot log in to portal"},
#     "RelatedCases": [
#         {"CaseID": {"value": "CR000455"}}
#     ],
#     "custom": {
#         "Case": {
#             "UsrSupportTier": {
#                 "type": "CustomStringField",
#                 "value": "Gold"
#             }
#         }
#     }
# }

6. Complete Example with CasesService

Here is a complete example of how to use the CaseBuilder to create a new case.

from easy_acumatica.models.case_builder import CaseBuilder

# 1. Build the case payload
case_to_create = (
    CaseBuilder()
    .class_id("HIGH")
    .business_account("INNOTECH")
    .subject("Urgent: Main website is down")
    .set("Description", "The main e-commerce site is returning a 503 error.")
    .set_custom_field("Case", "UsrSystemImpact", "Critical")
)

# 2. Use the payload with the CasesService to create the record
try:
    new_case = client.cases.create_case(
        "24.200.001",
        builder=case_to_create
    )
    print(f"Successfully created case: {new_case['CaseCD']['value']}")
except Exception as e:
    print(f"Failed to create case: {e}")