{"id":769,"date":"2023-03-07T20:54:32","date_gmt":"2023-03-07T20:54:32","guid":{"rendered":"http:\/\/fredborg.org\/?p=769"},"modified":"2023-03-08T06:27:16","modified_gmt":"2023-03-08T06:27:16","slug":"become-a-business-central-api-superhero","status":"publish","type":"post","link":"https:\/\/fredborg.org\/?p=769","title":{"rendered":"Become a Business Central API Superhero"},"content":{"rendered":"\n

We are living in a very connected world, all our devices have the ability to talk together and the same goes for our IT systems, so one of the things that pretty much every BC developer will face at one time or another is that someone needs to connect to a BC, luckily this is easy in BC so let us take a look at how we can accomplish this.<\/p>\n\n\n\n

Exposing data<\/h2>\n\n\n\n

The first thing that we will cover is how to expose data in BC, you have two ways of exposing data in BC the first way is to publish either a page, query or XMLPort as a web service, to do this create the object that you wish to expose and go to web services in BC and add it.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

However, there is a better way, and that is using API pages an API page is a regular page with some extra properties and it is created with the only goal of exposing data, another great thing about API pages is that you do need to publish API pages as web services because all pages of type API will automatically be exposed in BC, although we can also automatically publish web services we will get back to that later.<\/p>\n\n\n\n

A simple API page could look like this:<\/p>\n\n\n

\npage 50100 "API Items"\n{\n    APIGroup = 'demo';\n    APIPublisher = 'fredborg';\n    APIVersion = 'v1.0';\n    ApplicationArea = All;\n    Caption = 'apiItems';\n    DelayedInsert = true;\n    EntityName = 'apiItem';\n    EntityCaption = 'apiItem';\n    EntitySetName = 'apiItems';\n    EntitySetCaption = 'apiItems';\n    PageType = API;\n    SourceTable = Item;\n    ODataKeyFields = SystemId;\n    Editable = false;\n    DataAccessIntent = ReadOnly;\n\n    layout\n    {\n        area(content)\n        {\n            repeater(General)\n            {\n                field(systemId; Rec.SystemId)\n                {\n                    Caption = 'SystemId';\n                }\n                field(no; Rec."No.")\n                {\n                    Caption = 'No.';\n                }\n                field(description; Rec.Description)\n                {\n                    Caption = 'Description';\n                }\n            }\n        }\n    }\n\n}\n\n<\/pre><\/div>\n\n\n
Besides setting the PageType to API the properties that you need to add are APIGroup, APIPublisher, APIVersion, EntityName, EntitySetName<\/strong>, and ODataKeyFields<\/strong>. All of these properties are used to call your API page except the ODataKeyFields, which is used as the unique key for your record, it is recommended to always use the SystemId as ODataKeyFields, because it will always be unique and the value will never change, another thing that is a good idea when creating API pages is to set the DataAccessIntent <\/strong>this will improve the performance of your application DataAccessIntent Property – Business Central | Microsoft Learn<\/a><\/p>\n\n\n\n
Bound and UnBound Actions<\/strong><\/h2>\n\n\n\n
Many times when we expose services to the world we also need to expose some functions, this can be done in two ways in BC we have what we call bound actions, which are actions that are bound to a certain record, these are the ones that we have on our API pages to add a bound action to our API page you must add [ServiceEnabled]<\/strong> above your function so a function could look like this.  <\/p>\n\n\n
\n[ServiceEnabled]\n procedure UpdateUnitPrice(var actionContext: WebServiceActionContext; unitPrice: Decimal)\n    begin\n        rec."Unit Price" := unitPrice;\n        Rec.Modify();\n        actionContext.SetResultCode(WebServiceActionResultCode::Updated);\n    end;\n\n<\/pre><\/div>\n\n\n
 An UnBound action is a procedure in a codeunit that can be called without having to do so on a record, so a simple UnBound action could look like this.<\/p>\n\n\n
\ncodeunit 50100 MyApiDemo\n{\n    procedure myUnbound(itemDescription: text[50]; itemNo: Code[20])\n    var\n        Item: Record Item;\n    begin\n        Item.Get(itemNo);\n        Item.Description := itemDescription;\n        Item.Modify();\n    end;\n}\n\n<\/pre><\/div>\n\n\n
Which looks like any other function, however when working with UnBound actions we must expose the codeuint as a web service, and this can be done by manually setting it up like I showed earlier or we can create an XML file that will automatically publish our web service when the extension is installed you can call the XML file anything you want I have called mine WS.xml and added this to the file.     <\/span> <\/p>\n\n\n
\n<?xml version="1.0" encoding="utf-8"?>\n<ExportedData>\n    <TenantWebServiceCollection>\n        <TenantWebService>\n            <ObjectType>CodeUnit<\/ObjectType>\n            <ObjectID>50100<\/ObjectID>\n            <ServiceName>MyApiDemo<\/ServiceName>\n            <Published>true<\/Published>\n        <\/TenantWebService>\n    <\/TenantWebServiceCollection>\n<\/ExportedData>\n\n<\/pre><\/div>\n\n\n
  <\/p>\n\n\n\n
Setting up OAuth<\/strong><\/h2>\n\n\n\n
We have now created some API endpoints next we need to be able to call them, this is done by using Rest calls with OAuth as authentification, to set up OAuth, you must log in to your Azure Portal and go to App Registrations and create a new one: <\/span> <\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
 <\/p>\n\n\n\n
Choose a name for your App registration choose single tenant and choose web as redirect and enter a redirect URL I have entered https:\/\/businesscentral.dynamics.com\/OAuthLanding.htm in mine.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
 <\/p>\n\n\n\n
Press register, then go to API permissions and add a permission<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And here you must add both business central permissions Delegated and Application, and under these also add all permissions.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Next press Grant admin consent<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Now go to Certificates & secrets and create a new client secret<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
This will generate a new value and Secret ID copy the value and store it somewhere because you will not be able to see it again; next, go Overview and copy the Application (client) ID<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Head over to BC and go to the page Azure Active Directory Applications<\/strong> and press new enter your Application (client) ID as the Client ID set the state to Enabled and set permissions I have given mine D365 ADMINISTRATOR and D365 BUS FULL ACCESS and then press Grant Consent.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Once this is done we can now start calling your API’s so head over to Postman create a GET request and enter the following URL https:\/\/api.businesscentral.dynamics.com\/v2.0\/{enviromentName}<\/strong>\/api\/microsoft\/automation\/v2.0\/companies next head over to Authorization and choose OAuth 2.0<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Then head down to Configure New Token and enter your information:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Access Token URL<\/strong>: https:\/\/login.microsoftonline.com\/{TeantID}<\/strong>\/oauth2\/v2.0\/token
Client ID<\/strong>: Is the Application (client) ID from Azure Portal
Client Secret<\/strong>: is the value of the Client secrets that you generated in Azure Portal (the one that you have to copy because you could only see it once )
Scope<\/strong>: Enter URL https:\/\/api.businesscentral.dynamics.com\/.default
And press Get New Access Token<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And choose Use token:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
You should now be able to press send in Postman and get a list of your companies<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Copy the id and try to change your URL so it looks like the following https:\/\/api.businesscentral.dynamics.com\/v2.0\/dev\/api\/fredborg\/demo\/v1.0\/companies({companyID}<\/strong>)\/apiItems this should give you a list of all your items using your new API page<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Next Copy the systemId of one of your items, and change the URL to the following https:\/\/api.businesscentral.dynamics.com\/v2.0\/dev\/api\/fredborg\/demo\/v1.0\/companies({CompanyId}<\/strong>)\/apiItems({systemId}<\/strong>)\/Microsoft.NAV.updateUnitPrice and change the type to Post, and add the following to your body { “unitPrice”: 123456 } and press send:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And this will update the Unit Price of your Item OBS you might have noticed that my function name has been changed to start with lowercase, this is very important because even if your function starts with an uppercase in BC it will automatically be converted to lowercase in the API<\/strong><\/p>\n\n\n\n
Next, let us try to call our UnBound action to do this change the URL to this https:\/\/api.businesscentral.dynamics.com\/v2.0\/{teantId}<\/strong>\/dev\/ODataV4\/MyApiDemo_myUnbound?company={companyId}<\/strong> and set the body to {  “itemDescription”: “My Item”,  “itemNo”: “1896-S” } and press send.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
And this will update the Item Description of your Item.<\/p>\n\n\n\n
And that is all there is to working with API’s in BC, until next time stay safe.<\/p>\n\n\n\n
\n