Azure App Service: Building an API for Dynamics AX Fabio Filardi

Technical Consultant - Microsoft Dynamics™ AX

As part of the "mobile first, cloud first" strategy, Microsoft announced early this year its new fully managed cloud integration platform: Azure App Service. The idea is to offer services to build scalable enterprise-level applications to run seamlessly across any device and platform, turning the barrier that separates what is on cloud and what is on premises even more transparent.

There are four types of applications that can be create as part of Azure App Services: Web, Mobile, Logic and API Apps. They can be part of a single solution, allowing the users to easily build apps targeting both web and mobile clients, sharing the same back-end and integrated with others Software-as-a-service (SaaS) systems or on-premises applications via virtual network or Hybrid connections.

Web Apps

Used to host websites and web applications, supports multiple languages and frameworks (.NET, Java, Python, PHP and more) with capabilities such as cloud debugging, hybrid connectivity, authentication, support for continuous deployment and easily auto-scalable, offering high-availability through several geo-locations.

Mobile Apps

Mobile application platform based on Azure Mobile Services, offers a set of client SDKs including Windows, iOS, Android and multi-platform environments (Xamarin and Cordova). Push notifications, authentication and offline sync and cloud based back-end are some of the others capabilities available.

Logic Apps

Used to automate business process execution and create enterprise-grade workflows using a visual web-based tool. The logic apps can be triggered on a schedule with automatic recurring option, manually or by messages received by the connectors. It is possible integrate SaaS apps (Dynamics CRM, Office 365, SharePoint, Salesforce, Dropbox and others) with platform-as-a-service (PaaS)applications, apply message validation/transformations, create hybrid connectivity with enterprise applications and use a few built-in connectors available in the marketplace or create your own APIs and connectors.

API Apps

API Apps can be considered the core of the platform. Used to create, host and manage RESTful APIs that run in a public or private context (to be used only by Logic, Web or Mobile apps). Accepts any supported language (.NET, Java, Python, PHP, Node.js), offers enterprise grade credential management with Active Directory, single sign-on and social identity using Google, Twitter, Facebook and Microsoft accounts. It's a tightly integrated development experience, offering also automatic SDK generation support and easy integration with Logic Apps. Also known as "connectors", API Apps can be used as a connection end point for other resources or applications. Using hybrid connectivity, it can be used to seamlessly expose on-premises data on the cloud.

BizTalk Hybrid Connection As part of BizTalk Services, Hybrid Connections offer an easy and secure way to connect cloud applications to on-premises resources, using Shared Access Signature (SAS) authorization and a pair of connection keys created for the application. It can connect to any resource that uses a static TCP port, requiring only outbound TCP/HTTP connectivity from your private network, not being necessary to open any firewall ports or change your network security setup. Hybrid connections can be used by any framework supported by App Services (.NET, Java, Python, PHP, Node.js).

Demo: Building a Dynamics AX cloud application In this demo we'll create a very simple API App that extracts data from AX through an AIF Inbound port and is exposed via REST Service, connecting to the AOS via BizTalk Hybrid connection.

Pre-Requirements:

Windows Azure subscription (Free trial available for 1 month and $260 credit at https://azure.microsoft.com/pricing/free-trial/)

Visual Studio 2013 or later with Azure SDK 2.7;

Access to a Dynamics AX server (local demo VM with internet access works fine for this);

1. Create a new API App on Azure

Login to https://portal.azure.com, click on New > Web + Mobile > API App, then select the app name and the service plan (create one if you don't have yet).

After creation, on your application window, click All Settings > Applications Settings and set API access level to Public (anonymous). Save and close.

2. AIF Inbound Port on AX

For the sake of simplicity, we'll use the existing TimesheetServices port to expose some existing sample data created manually.

Check if the service is active - if not just activate it - and copy the WSDL URI address.

3. Creating and publish the Visual Studio project

In Visual Studio, create a new project and select the Azure API App template.

After the project has been created, add a Service Reference and paste the WSDL URI address from your Inbound Port (above). Set the namespace to "TimesheetServices".

In the Controllers folder in your solution, delete the default ValuesController, then right click on the folder, select Add > Controller, and select the template "Web API 2 Controller - Empty". Set the new controllers name as TimesheetController.

Open the TimesheetController and write the code as shown in the screenshot below.

The idea here is to create a method to process a simple GET action on the specified route on line 9. The {id} parameter is sent as part of the URL. The credential sets which user will run the call, must be a valid AD user with the necessary permissions granted in AX. The context is used to specify some other details, including which company should be used to retrieve the data.

The TSTimesheetClient object offers many different methods to interact with the timesheets service - get, create, delete, recall, submit - and its related data, including periods, lines, entries, settings, etc.

We'll use the getTimeSheetDetailsByNumber() method, where we need to specify the timesheet number and the method returns all the detailed data for the header and lines as TSTimesheetDetails.

Save your project, right click on the Project node and select "Publish". Choose the "Microsoft Azure API Apps (Preview)" profile, enter your Microsoft account credentials (same as those used on Azure), select the API App previously created and click on Publish button.

4. Setup the Hybrid connection

Open your API App blade, and click on "API app host" link in the Essentials box. Roll down on API app host blade and click on the “Networking” box. Select "Configure your hybrid connection endpoints".

Select the connection name, hostname and port. Usually I enter the connection name as "hostname-port" to make it easier to read, but this is not a mandatory pattern. For the BizTalk service configuration, you can select an existing one or create a new one (free).

The host name must be the server name where you're running your service. The port 8201 is the default AOS services endpoint port, specify it based on the instance that you want to connect into.

Now the connection is created, but not connected yet. The next step is to install the listener, and we have two options. If you're using the portal on the service host machine (that you previously specified as the host name), then you can click on the Hybrid connection, then on Listener Setup, and select "Install and configure now". Azure will automatically install the listener to the host.

If you are not connected from the host machine or if you had some problem installing the listener automatically, you can select "Download and configure manually". An installer will be downloaded, just run and when prompted for the Connection String, use the "Primary On-Premises Gateway Connection String" listed on your hybrid connection properties window.

If you installed the listener successfully, after a few seconds your connection will be established and ready.

5. Testing the results

You can use a browser (Chrome recommended) to call your API, or use some tool (Postman or Fiddler are highly recommended) to help you build the requests and check the results.

The full URL for your API can be checked on the Azure Portal, the default address is:

https://{your-api-id}.azurewebsites.net/

In this sample we manually defined a relative route for our controller action, the final address composition can be checked below.

https://microsoft-apiappfcf6dcb8888943b5a011f2f88faba423.azurewebsites.net/timesheet/00201

That will send a GET request to the timesheet controller, sending "00201" as the timesheet id parameter. The results can be presented in XML or Json, ready to be parsed and consumed by any application, device and platform.

Conclusion With its powerful set of features and a competitive new pricing model, the Azure App Service platform opens a range of possibilities. It's a platform in constant development and progress, there is still room for improvement, but integrating your cloud solutions with on-premises resources and development of multi-platform solutions is becoming easier and more accessible.