{"title":"Creating and interacting with an OData V4 bound action","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-bound-action/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-bound-action, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-bound-action","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Create an OData V4 bound action in AL, publish its page, and call it with an authenticated POST request to copy an existing sales invoice in Business Central.","date":"2026-10-29","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Creating and interacting with an OData V4 bound action","slug":"creating-and-interacting-with-an-odata-v4-bound-action","at":0,"chars":8919},{"level":2,"title":"Prerequisites for the invoice-copy example","slug":"prerequisites-for-the-invoice-copy-example","at":298,"chars":1051},{"level":2,"title":"Declare the OData bound action","slug":"declare-the-odata-bound-action","at":1349,"chars":3686},{"level":2,"title":"Publish the custom page as a web service","slug":"publish-the-custom-page-as-a-web-service","at":5035,"chars":543},{"level":2,"title":"Retrieve an invoice and its OData key","slug":"retrieve-an-invoice-and-its-odata-key","at":5578,"chars":1135},{"level":2,"title":"Invoke the bound action with POST","slug":"invoke-the-bound-action-with-post","at":6713,"chars":1862},{"level":3,"title":"Expected response","slug":"expected-response","at":7250,"chars":747},{"level":3,"title":"Troubleshoot action requests","slug":"troubleshoot-action-requests","at":7997,"chars":578},{"level":2,"title":"Related information","slug":"related-information","at":8575,"chars":344}],"text":"# Creating and interacting with an OData V4 bound action\nUse an OData V4 bound action to run an AL procedure for a specific record through a web service. This article shows how to copy an existing unposted sales invoice to a new unposted invoice, publish the custom page, and call its Copy action.\n## Prerequisites for the invoice-copy example\n An AL extension project that references the Business Central application. Include object ID 50110 in the project's app.json ID ranges.\n A sandbox or test company with Sales & Receivables Setup, invoice number series, posting number series, and a valid unposted sales invoice with a customer. Start with a simple invoice whose data supports the standard copy-document operation.\n Permission to publish web services. The calling identity also needs access to the custom page, the copy-document codeunit, sales documents, setup, and number series. Publishing the page doesn't grant these permissions.\n An HTTP client and authentication for your environment. For Business Central online, use an OAuth access token. See Using OAuth to authorize Business Central web services<../webservices/authenticate-web-services-using-oauth>.\n For on-premises environments, enabled OData V4 services. See Business Central Server instance settings<../administration/server-instance-settings#expose-odata-and-api-services>.\n## Declare the OData bound action\nDeclare a procedure on the page and add the `[ServiceEnabled]` attribute. Use WebServiceActionContext to identify the new invoice and set `WebServiceActionResultCode::Created`.\nThe page exposes SystemId through the Id control and uses it as the OData key. The action result must use the same table field, SystemId, when it identifies the new record.\n> NOTE\n> Declare the procedure on the page object itself. Adding a procedure through a pageextension doesn't expose it as an OData bound action. You can define the new page in an AL extension.\n```al\nusing Microsoft.Sales.Document;\nusing Microsoft.Sales.Setup;\nusing Microsoft.Utilities;\n\npage 50110 SalesInvoiceCopy\n{\n    Caption = 'Sales invoice copy';\n    PageType = Card;\n    SourceTable = \"Sales Header\";\n    SourceTableView = where(\"Document Type\" = const(Invoice));\n    ODataKeyFields = SystemId;\n    InsertAllowed = false;\n    ModifyAllowed = false;\n    DeleteAllowed = false;\n\n    layout\n    {\n        area(Content)\n        {\n            group(General)\n            {\n                Caption = 'General';\n\n                field(Id; Rec.SystemId)\n                {\n                    ApplicationArea = All;\n                    Caption = 'Id';\n                    ToolTip = 'Specifies the unique identifier of the sales invoice.';\n                }\n\n                field(\"No.\"; Rec.\"No.\")\n                {\n                    ApplicationArea = All;\n                    Caption = 'No.';\n                    ToolTip = 'Specifies the sales invoice number.';\n                }\n\n                field(\"Sell-to Customer No.\"; Rec.\"Sell-to Customer No.\")\n                {\n                    ApplicationArea = All;\n                    Caption = 'Sell-to Customer No.';\n                    ToolTip = 'Specifies the customer who receives the sales invoice.';\n                }\n            }\n        }\n    }\n\n    [ServiceEnabled]\n    procedure Copy(var ActionContext: WebServiceActionContext)\n    var\n        FromSalesHeader: Record \"Sales Header\";\n        ToSalesHeader: Record \"Sales Header\";\n        SalesSetup: Record \"Sales & Receivables Setup\";\n        CopyDocumentMgt: Codeunit \"Copy Document Mgt.\";\n    begin\n        FromSalesHeader.Get(Rec.\"Document Type\", Rec.\"No.\");\n        FromSalesHeader.TestField(\n            \"Document Type\", FromSalesHeader.\"Document Type\"::Invoice);\n        FromSalesHeader.TestField(\"Sell-to Customer No.\");\n\n        SalesSetup.Get();\n        CopyDocumentMgt.SetProperties(\n            true, false, false, false, true,\n            SalesSetup.\"Exact Cost Reversing Mandatory\", false);\n\n        ToSalesHeader.Init();\n        ToSalesHeader.\"Document Type\" :=\n            ToSalesHeader.\"Document Type\"::Invoice;\n        ToSalesHeader.SetHideValidationDialog(true);\n        ToSalesHeader.Insert(true);\n\n        CopyDocumentMgt.CopySalesDoc(\n            \"Sales Document Type From\"::Invoice,\n            FromSalesHeader.\"No.\", ToSalesHeader);\n\n        ToSalesHeader.Get(\n            ToSalesHeader.\"Document Type\", ToSalesHeader.\"No.\");\n\n        ActionContext.SetObjectType(ObjectType::Page);\n        ActionContext.SetObjectId(Page::SalesInvoiceCopy);\n        ActionContext.AddEntityKey(\n            Rec.FieldNo(SystemId), ToSalesHeader.SystemId);\n        ActionContext.SetResultCode(WebServiceActionResultCode::Created);\n    end;\n}\n```\nThe page settings prevent direct inserts, edits, and deletes through the page. The Copy procedure creates the new invoice through AL code. The sample suppresses standard dialogs. Permissions and applicable validation still run, but availability warnings and interactive credit-limit notifications don't run through this web-service path.\n## Publish the custom page as a web service\n1. Build and publish the extension to your test environment.\n1. In Business Central, use Search to find and open the Web Services page.\n1. Select New.\n1. Set Object Type to Page, Object ID to 50110, and Service Name to SalesInvoiceCopy.\n1. Select Published.\n1. Copy the OData V4 URL for the service.\nPublish page 50110, not the standard Sales Invoice page, which has object ID 43. The service name alone doesn't associate the custom action with another page. See ../webservices/publish-web-service.\n## Retrieve an invoice and its OData key\nUse the copied URL to retrieve invoices before you invoke the action. In the following requests, replace `<BaseUrl>` with the URL prefix before `/ODataV4`. Replace `<CompanyName>` with your actual company name, URL-encoded and escaped as an OData string.\nFor Business Central online, `<BaseUrl>` is `https://api.businesscentral.dynamics.com/v2.0/<TenantId>/<EnvironmentName>`. Replace `<TenantId>` and `<EnvironmentName>` with your tenant ID and environment name. For on-premises environments, use the prefix from the copied service URL.\nFor OAuth authentication, replace `<AccessToken>` with an access token for your environment.\n```http\nGET <BaseUrl>/ODataV4/Company('<CompanyName>')/SalesInvoiceCopy\nAuthorization: Bearer <AccessToken>\nAccept: application/json\n```\nIn the returned collection, find the source invoice and copy its Id value. This property exposes the record's SystemId, not its invoice number.\nThe GUID `aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb` in the next example is an illustrative record ID. Replace it with the retrieved Id. Don't enclose the GUID in single quotation marks.\n## Invoke the bound action with POST\nSend a POST request to the invoice's URL followed by `/NAV.Copy`. Use the same `<BaseUrl>` and `<CompanyName>` values that you used to retrieve the invoice.\n```http\nPOST <BaseUrl>/ODataV4/Company('<CompanyName>')/SalesInvoiceCopy(aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb)/NAV.Copy\nAuthorization: Bearer <AccessToken>\nContent-Length: 0\n```\nThis action has no request body. The platform supplies ActionContext; don't send it as a JSON parameter. A GET request retrieves data but doesn't invoke the action.\n### Expected response\nOn success, the action returns `201 Created` with a Location header that identifies the new invoice. It doesn't return an invoice JSON body.\n```http\nHTTP/1.1 201 Created\nLocation: <BaseUrl>/ODataV4/Company('<CompanyName>')/SalesInvoiceCopy(<NewInvoiceGuid>)\n```\nRetrieve the URL in the Location header to inspect the new invoice. Replace `<NewInvoiceGuid>` only if you're constructing the URL yourself; the actual response supplies the new record's GUID.\nOpen the new invoice in Business Central and review its header and lines. The standard copy-document operation can skip lines, including lines with blocked items. A `201 Created` response confirms that the new invoice was created, not that every source line was copied.\n### Troubleshoot action requests\n If the key count or type is incorrect, confirm that you published page 50110 and that its ODataKeyFields property is SystemId. Use the returned Id GUID, not the document number. Inspect `<BaseUrl>/ODataV4/$metadata` to check the published entity's key definition.\n If the action isn't found, use the exact service name and `/NAV.Copy` suffix with POST. Confirm that the installed page declares the `[ServiceEnabled]` procedure.\n If copying fails, check the calling identity's permissions, number series, company setup, and source invoice data.\n## Related information\nattributes/devenv-serviceenabled-attribute\nmethods-auto/webserviceactioncontext/webserviceactioncontext-data-type\nproperties/devenv-odatakeyfields-property\ndevenv-table-system-fields\n../webservices/publish-web-service\nCreate and call an OData V4 unbound action<devenv-creating-and-interacting-with-odatav4-unbound-action>"}