Actions Service

The `ActionsService` is used to execute business logic actions on Acumatica records, such as "Confirm Shipment," "Release from Hold," or other custom actions defined in your instance. This service is the key to automating processes that would normally require user interaction in the Acumatica UI.

Importing Helpers

To identify the record on which to perform an action, you will typically use the `RecordBuilder`.


from easy_acumatica.models.record_builder import RecordBuilder

Service Methods

execute_action(...)

This method is for standard, straightforward actions that may have simple, flat parameters. It's the most common way to trigger business logic.

Example 1: Action with No Parameters

Reopening a Sales Order requires identifying the order by its key fields but needs no extra parameters.


# 1. Identify the Sales Order by its key fields
order_to_reopen = RecordBuilder().field("OrderType", "SO").field("OrderNbr", "000001")

# 2. Execute the action
client.actions.execute_action(
    api_version="24.200.001",
    entity_name="SalesOrder",
    action_name="ReopenSalesOrder",
    entity=order_to_reopen
)

Example 2: Action with Simple Parameters

Changing a Business Account ID requires identifying the account to change and providing the new ID as a simple parameter.


# 1. Identify the Business Account to change
account_to_change = RecordBuilder().field("BusinessAccountID", "CANDYY")

# 2. Define the action's parameters
new_id_params = {"BusinessAccountID": "CANDYYY"}

# 3. Execute the action
client.actions.execute_action(
    api_version="24.200.001",
    entity_name="BusinessAccount",
    action_name="ChangeBusinessAccountID",
    entity=account_to_change,
    parameters=new_id_params
)

execute_custom_action(...)

This method is for more complex actions that would typically open a dialog box in the UI and require nested parameters. The structure of the `custom_parameters` dictionary must exactly match the structure Acumatica expects for the dialog box.

Example: Closing a Case with a Reason

This action requires a `Reason` parameter, which is defined in the `FilterPreview` view within the UI dialog. We replicate this structure in our `custom_parameters`.


# 1. Identify the Case by its ID
case_to_close = RecordBuilder().field("id", "e3f46a39-1a14-e911-816f-bc920a5e0ac8")

# 2. Define the nested custom parameters
# The structure must match what Acumatica expects for the dialog box.
close_params = {
    "FilterPreview": {
        "Reason": {
            "type": "CustomStringField",
            "value": "Abandoned"
        }
    }
}

# 3. Execute the custom action
client.actions.execute_custom_action(
    api_version="24.200.001",
    entity_name="Case",
    action_name="Close",
    entity=case_to_close,
    custom_parameters=close_params
)