17.2 Bound and Unbound OData Actions with [ServiceEnabled]

17.2 Bound and Unbound OData Actions with [ServiceEnabled]

While standard RESTful operations on API pages handle basic CRUD activities (Create via POST, Read via GET, Update via PATCH, Delete via DELETE), enterprise integrations frequently require invoking complex server-side business routines—such as releasing a sales document, posting an invoice, recalculating customer credit limits, or canceling an order. In Business Central, developers implement these remote procedure calls (RPC) using OData Actions decorated with the [ServiceEnabled] attribute.

1. OData Actions Architecture & Execution Model

An OData Action is an operation exposed through the OData v4 metadata schema ($metadata) that can execute state-changing business logic on the Business Central Server tier.

+-------------------------------------------------------------------------+
|                         EXTERNAL REST CLIENT                            |
|               (HTTP POST /Microsoft.NAV.{actionName})                   |
+-----------------------------------┬-------------------------------------+
                                    │ (JSON Parameter Payload)
                                    ▼
+-------------------------------------------------------------------------+
|                   BUSINESS CENTRAL OData ACTION DISPATCHER              |
|                                                                         |
|   1. Locate Target Object (API Page / Codeunit Web Service)             |
|   2. Bind Entity Context (Fetch Rec for Bound; Skip for Unbound)        |
|   3. Deserialize Action Parameters from Request Body                    |
|   4. Initialize WebServiceActionContext Reference                       |
+-----------------------------------┬-------------------------------------+
                                    │ (Invoke AL Procedure)
                                    ▼
+-------------------------------------------------------------------------+
|                   AL BUSINESS LOGIC & TRANSACTION                       |
|                                                                         |
|   [ServiceEnabled]                                                      |
|   procedure ProcessAction(Params...; var ActionContext: ActionContext)  |
|   - Execute Business Logic (e.g., Post, Release, Validate)             |
|   - Configure ActionContext (SetResultCode, SetObjectId, AddKey)        |
+-----------------------------------┬-------------------------------------+
                                    │ (Construct HTTP Response)
                                    ▼
+-------------------------------------------------------------------------+
|                   HTTP RESPONSE STATUS & HEADERS                        |
|   - HTTP 200 OK (Updated / Returned Object)                             |
|   - HTTP 201 Created (Created Resource + Location Header)               |
|   - HTTP 204 No Content (None / Completed without Body)                 |
|   - HTTP 400 / 500 (AL Error Dialog converted to JSON Error)            |
+-------------------------------------------------------------------------+

Core Rules Governing OData Actions

1. HTTP Method: All OData Actions must be invoked using the POST HTTP verb. GET, PUT, or PATCH requests to an action endpoint will return 405 Method Not Allowed.
2. Attribute Decoration: The procedure in AL must be decorated with [ServiceEnabled].
3. Namespace Prefix: In the OData v4 metadata and endpoint URL, Business Central actions are always prefixed with the runtime namespace: Microsoft.NAV.<ProcedureName> (case-sensitive or matching exact AL procedure casing).
4. Transaction Boundary: The entire action procedure executes within a single database transaction. If an unhandled error occurs or an Error('...') statement is encountered, all database changes made during the action are automatically rolled back, and an HTTP 400 Bad Request or 500 Internal Server Error response is returned.

2. Implementing Bound OData Actions

A Bound Action is explicitly tied to a specific entity record instance. When the external client calls a bound action, the Business Central server automatically resolves the entity key in the URL and loads that specific record into the page's Rec buffer before executing the procedure.

AL Implementation of a Bound Action on an API Page

page 50130 "Custom Customer API"
{
    PageType = API;
    Caption = 'customCustomer';
    APIPublisher = 'custom';
    APIGroup = 'integrations';
    APIVersion = 'v2.0';
    EntityName = 'customCustomer';
    EntitySetName = 'customCustomers';
    SourceTable = Customer;
    DelayedInsert = true;
    ODataKeyFields = SystemId;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { }
                field(number; Rec."No.") { }
                field(displayName; Rec.Name) { }
                field(blocked; Rec.Blocked) { }
            }
        }
    }

    [ServiceEnabled]
    procedure BlockCustomer(ReasonCode: Code[10]; Comments: Text[100]; var ActionContext: WebServiceActionContext)
    var
        CustomerPostingMsg: Label 'Customer %1 was blocked via API. Reason: %2, Comments: %3', Locked = true;
    begin
        // The runtime has already loaded Rec matching the URL SystemId
        Rec.TestField(Blocked, Rec.Blocked::" ");
        Rec.Validate(Blocked, Rec.Blocked::All);
        Rec.Modify(true);

        // Configure the HTTP Response Context
        ActionContext.SetResultCode(WebServiceActionResultCode::Updated);
    end;
}

External HTTP Invocation (Bound Action)

To invoke this bound action, the client sends an HTTP POST to the specific customer entity URI, qualifying the action name with Microsoft.NAV.:

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/custom/integrations/v2.0/companies(12345678-1234-1234-1234-123456789abc)/customCustomers(d4f5a6b7-8901-2345-6789-abcdef012345)/Microsoft.NAV.blockCustomer
Content-Type: application/json

{
  "ReasonCode": "OVERDUE",
  "Comments": "Account placed on hold due to unpaid invoices exceeding 90 days."
}

HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal

{
  "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/.../$metadata#customCustomers/$entity",
  "id": "d4f5a6b7-8901-2345-6789-abcdef012345",
  "number": "C00010",
  "displayName": "Contoso Ltd.",
  "blocked": "All"
}

3. Implementing Unbound OData Actions

An Unbound Action is a global or collection-level operation not tied to a single existing record instance. Unbound actions can be declared on API pages (invoked at the entity set root) or inside Codeunits published as OData Web Services.

AL Implementation of an Unbound Action on an API Page

page 50130 "Custom Customer API"
{
    // ... (properties and layout) ...

    [ServiceEnabled]
    procedure RecalculateAllDiscounts(CustomerCategory: Code[20]; var ActionContext: WebServiceActionContext)
    var
        Cust: Record Customer;
        DiscountMgt: Codeunit "Cust-Order Discount";
    begin
        Cust.SetRange("Customer Disc. Group", CustomerCategory);
        if Cust.FindSet(true) then
            repeat
                DiscountMgt.UpdateCustomerDiscounts(Cust);
            until Cust.Next() = 0;

        ActionContext.SetResultCode(WebServiceActionResultCode::None);
    end;
}

External HTTP Invocation (Unbound Action)

Notice that the URI addresses the entity set root (customCustomers) rather than an individual entity GUID:

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/custom/integrations/v2.0/companies(12345678-1234-1234-1234-123456789abc)/customCustomers/Microsoft.NAV.recalculateAllDiscounts
Content-Type: application/json

{
  "CustomerCategory": "RETAIL"
}

HTTP Response:

HTTP/1.1 204 No Content

Unbound Actions on Web Service Codeunits

Developers can also publish a Codeunit as an OData Web Service. Every public procedure inside that codeunit becomes an unbound action callable over OData v4:

codeunit 50140 "Integration Service"
{
    procedure ProcessPendingShipments(WarehouseLocation: Code[10]): Integer
    var
        WarehouseMgt: Codeunit "Warehouse Management";
    begin
        exit(WarehouseMgt.ShipAllPendingOrders(WarehouseLocation));
    end;
}

4. Managing HTTP Response Context with WebServiceActionContext

The WebServiceActionContext data type gives AL developers precise control over the HTTP status codes, headers, and entity keys returned to the calling client.

Key Methods on WebServiceActionContext

Complete Example: Action Creating a New Resource (HTTP 201 Created)

When an action creates a new entity (such as posting an order and generating a Posted Sales Invoice), developers configure WebServiceActionContext so the client receives an HTTP 201 status and the URI of the newly created invoice:

[ServiceEnabled]
procedure CreateContractInvoice(ContractNo: Code[20]; var ActionContext: WebServiceActionContext)
var
    SalesHeader: Record "Sales Header";
    ContractMgt: Codeunit "Contract Management";
begin
    // Execute business routine that creates and inserts a new Sales Header
    ContractMgt.CreateInvoiceForContract(ContractNo, SalesHeader);

    // Build response context pointing to the newly created Sales Header API
    ActionContext.SetResultCode(WebServiceActionResultCode::Created);
    ActionContext.SetObjectType(ObjectType::Page);
    ActionContext.SetObjectId(Page::"Custom Sales Invoice API");
    ActionContext.AddEntityKey(SalesHeader.FieldNo(SystemId), SalesHeader.SystemId);
end;

WebServiceActionResultCode Status Code Mapping

• WebServiceActionResultCode::None -> 204 No Content (Request succeeded; no body returned).
• WebServiceActionResultCode::Updated -> 200 OK (Returns updated entity JSON in response body).
• WebServiceActionResultCode::Created -> 201 Created (Returns newly created entity JSON + Location response header).
• WebServiceActionResultCode::Deleted -> 204 No Content (Resource was successfully deleted).