Dynamics 365 Business Central/NAV provides two web services: SOAP and OData web services. Compared to the SOAP web service, the OData web service is lightweight as it is a REST-based data service that supports JSON format while the SOAP web service always works with XML format. Previously we have written a blog post that demonstrates Working with Dynamics 365 Business Central/NAV Codeunit in SSIS, in which we talked about calling Dynamics 365 Business Central/NAV Codeunit functions with SOAP web services using our Web Service components. In this blog post, we will look at consuming Business Central/NAV Codeunit functions through OData web services by using OData Connection Manager and Premium OData components offered in our SSIS Productivity Pack product.
Our Premium OData components are primarily designed to work with OData v4 services, so we would need to work with Dynamics BC/NAV OData v4 endpoints.
Configure OData Connection Manager
To consume the Dynamics BC/NAV Codeunit function through the OData web service, the first step is to configure the OData Connection Manager to establish the connection to the Dynamics BC/NAV server.
Connecting to Dynamics Business Central/NAV On-Premises
Dynamics BC/NAV On-Premises ODataV4 Base URL should have an address in the following format:
- https://Server:ODataWebServicePort/ServerInstance/ODataV4/Company('CompanyName')
The company name can be specified as part of the URI as shown above, or it can be specified the company as part of the query parameters like this:
- https://Server:ODataWebServicePort/ServerInstance/ODataV4/?company='CompanyName'
A Dynamics BC/NAV server installed on a local computer can have an OData base URL like this: https://localhost:7048/BC160/ODataV4/Company('CRONUS%20Canada%2C%20Inc.')
After you have specified the Base URL, the next step is to configure the authentication method to connect to the Dynamics BC/NAV OnPrem server. This can be done in the Authentication tab. You would use the Credentials authentication method and provide the domain, username, and password values in order to access your on-premises Business Central installation.
Connecting to Dynamics Business Central Online
The OData v4 base URL for Dynamics BC Online is a little different from the on-premises one, it should have a format like this: https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/Production/ODataV4/?company='CRONUS Canada, Inc.'
Both Basic and OAuth2 authentication modes can be used to connect to Dynamics Business Central Online. However, OAuth2 will be the preferred option, as it offers better security, and it will be future-proof.
When using Basic authentication mode, Business Central user’s Web Service Access Key would be the password to be used in the Basic authentication.
When authenticating Dynamics BC using the OAuth authentication, it’s required to register an Azure Active Directory application in the same Azure AD Directory tenant. Once the app has been created, you would need to grant the app with the necessary API permissions to have access to Dynamics 365 Business Central data. The permission configuration should be something below.
Once you have the Microsoft AAD app registered and configured, you can come back to the connection manager, and set the authentication mode to OAuth 2 in OData Connection Manager, from where you should be able to launch the OAuth Token Generator. You should already have all the required information to put into the OAuth Token Generator, which is a tool shipped within the SSIS Productivity Pack product, and it can be launched from with the OData or HTTP connection manager provided by Microsoft. Based on Microsoft OAuth documentation, we should configure the OAuth Token Generator as something below:
|
Parameter |
Value |
|
Sign In Url |
https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize |
|
Client Id |
The application ID of the AAD app. |
|
Client Secret |
The application secret in the AAD app. |
|
Scope |
https://api.businesscentral.dynamics.com/.default offline_access |
|
Redirect URI |
The redirect_uri configured in the AAD app |
Click the Next button to go to the next page and click either the Authorize In App… or Authorize In Browser… button to open the authorization page, login and consent to the permissions the app requested. You will be redirected to the redirect_uri web page that you set up in the Microsoft AAD app with an authorization code in the code parameter. Copy the entire URL to the pop-up dialog if you are using the Authorize In Browser mode, then you will be navigated to the Request Tokens page in OAuth Token Generator.
The Request Token URL is “https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token” for Microsoft OAuth authentications. Fill in the Request Tokens URL and click the Get Tokens button to request an access token, once the OAuth access_token and refresh_token are successfully retrieved, save the token file to your local file system with a password. All sensitive information will be encrypted with the provided password in the token file.
When the OAuth2 token file is successfully generated and used in OData Connection Manager, the Connection Manager automatically refreshes the access_token using the refresh_token upon expiry in the future, this includes your runtime execution, provided that the token file is made available to the server.
Consume Codeunit Web Service
When Codeunit is published as a web service in Dynamics BC/NAV, it is exposed as an OData unbound action in OData web service. OData unbound actions don’t bound to any object or entity type and they are also referred as static operations. OData unbound actions are supported in Premium OData Destination component.
As shown in the screenshot above, all the published Codeunit functions in Dynamics BC/NAV are available as OData unbound actions.
In this blog post, we are working with CustomerMgt_GetTotalSales unbound action which takes custNo as the input parameter and returns a decimal value with the total sales amount for the given customer. We use Data Spawner and Premium Derived Column to generate our test data, we are getting the total sales amount for customer "10000". Our Premium OData Destination component supports returning the key information from the response of the OData requests that are sent. For this CustomerMgt_GetTotalSales unbound action, the result is available in the @Result default output column in the Premium OData Destination component's Error Handling page.
Let's set up a dummy component and enable the Data Viewer to check the result returned from the Codeunit function.
Conclusion
It is important to note that the same connection can be used to consume any other NAV services including those Page objects/entities. It can be useful if you have to consume such services using the OData connection.
In conclusion, working with Dynamics BC/NAV Codeunit function through OData web service in SSIS can be extremely easy using KingswaySoft Productivity Pack components without writing a single line of code. Compared with consuming SOAP web service to call Codeunit functions, OData usually has a better performance as it supports JSON formats. And users can work with all published Codeunit functions in the OData web service, while in SOAP each Codeunit function has its own WSDL document therefore it requires to create separate connections when interacting with Codeunit through SOAP web service. We hope you find this blog helpful.