This guide covers the ActionsService, which 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.

1. Accessing the Service

The ActionsService must be added to your AcumaticaClient and is then available as an attribute.

Assuming 'client' is an initialized AcumaticaClient

actions_service = client.actions

2. Standard Actions vs. Custom Actions

The ActionsService provides two methods for executing actions, which correspond to the two ways Acumatica handles them:

1. execute_action(...): For standard, straightforward actions that may have simple parameters (e.g., changing an ID).
2. execute_custom_action(...): For more complex actions that would typically open a dialog box in the UI and require nested parameters.

3. Executing a Standard Action

execute_action(api_version, entity_name, action_name, entity, parameters=None)

This method handles actions with no parameters or with simple, flat parameters.

Example 1: Action with No Parameters (Reopening a Sales Order)

from easy_acumatica.models.record_builder import RecordBuilder

# 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 an ID)

# 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  
)

4. Executing a Custom Action

execute_custom_action(api_version, entity_name, action_name, entity, custom_parameters)

This method is for actions that require parameters to be structured in a nested custom object, mimicking the dialog boxes seen in the Acumatica UI.

Example: Closing a Case with a Reason

This action requires a Reason parameter, which is defined in the FilterPreview view within the UI dialog.

# 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  
)  
print("Case has been closed.")