Developing Mobile Apps for Microsoft Dynamics AX 2012 R3

Mobile architecture

The AX 2012 mobile architecture is designed to help developers overcome the following challenges that are inherent in developing mobile apps:

• How to facilitate communication between apps and on-premises installations
• How to authenticate users
• How to develop for multiple platforms

Because AX 2012 most often runs on-premises or is privately hosted, the average phone or tablet device does not have access to AX 2012 services, which are usually available only through a corporate network. To overcome this challenge, the mobile architecture uses the Microsoft Azure Service Bus Relay. The Service Bus Relay solves the challenges of communicating between on-premises applications and the outside world by allowing on-premises web services to project public endpoints. Systems can then access these web services, which continue to run on-premises, from anywhere.

The Service Bus Relay is based on a namespace that is set up for each company that deploys mobile apps for AX 2012. For example, an administrator from the Contoso company can create an Azure subscription and set up a unique namespace, such as contosomobapps. The namespace is a friendly identifier that end users enter into the mobile app to connect to their company’s AX 2012 instance.

The second challenge is authenticating users. AX 2012 has existing user accounts that are based on Active Directory accounts. Ideally, device users simply use their corporate identities (user IDs and passwords) to access AX 2012 from their devices. The mobile architecture accomplishes this by using Active Directory Federation Services (AD FS). AD FS is a Windows Server component that is used by users whose devices are not on the corporate network to authenticate themselves by using their existing corporate credentials.

Another challenge that mobile app developers face is providing apps for various device platforms, such as Windows 8.1, Windows Phone 8, iOS, and Android. By taking advantage of the mobile architecture, developers can create applications for the platform they choose, depending on customer requirements.

Mobile architecture components

The AX 2012 mobile architecture includes the following key components:

• AX 2012 services Apps communicate with AX 2012 through the AX 2012 services framework.
• Active Directory Users who access AX 2012 through mobile apps are authenticated against their existing corporate identities.
• AD FS AD FS facilitates authentication of Active Directory–based users who are accessing AX 2012 through mobile apps.
• Service Bus Relay The Service Bus Relay ferries messages from the mobile app to an on-premises listener through which the app can reach an on-premises instance of AX 2012.
• On-premises listener The listener listens for messages from mobile apps that are relayed through the Service Bus Relay. The listener then makes calls to AX 2012 and responds to the mobile app through the Service Bus Relay.
• Microsoft Azure Active Directory Access Control Access Control verifies that the user has been authenticated through AD FS and then allows messages to be sent through the Service Bus Relay.
• Mobile apps These apps can be for a phone or tablet on any of the prevailing mobile platforms—Windows, iOS, or Android. The architecture provides the means for these apps to communicate with AX 2012. The apps can then interact with AX 2012 as appropriate, based on the business scenario. Apps can also be designed to communicate with other systems, depending on the needs of the business scenario.

Figure 22-1 shows the components of the mobile architecture.

To become familiar with the mobile architecture, we recommend that you install and configure one or more of the AX 2012 mobile apps and the Microsoft Dynamics AX connector (on-premises listener) for mobile apps. Doing so will help you learn the configuration steps necessary for Azure, AD FS, AX 2012, and the listener. That familiarity will help you greatly in debugging and troubleshooting your apps. For more information about these components and their configuration, see the following white papers:

• Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps at http://www.microsoft.com/en-us/download/details.aspx?id=38413.
• Configure Microsoft Dynamics AX Connector for Mobile Applications at https://mbs.microsoft.com/downloads/customer/AX/ConfigureAXConnectorforMobileApplications.pdf. To access this paper, you must have CustomerSource or PartnerSource credentials.

You can download the AX 2012 expense app, which is used as an example throughout this chapter, at http://apps.microsoft.com/windows/en-us/app/dynamics-ax-2012-expenses/07aab6f9-c6ce-4b81-b04c-4b43c3f6de67.

Message flow and authentication

The following process outlines the flow of messages and describes how users are authenticated:

1. The user submits credentials to obtain a token from AD FS.
2. If the user’s credentials are verified, a token is returned that is based on Security Assertion Markup Language (SAML). The token contains a claim that indicates the user name and company domain, such as user@contoso.com. The claim is used to verify the user’s company affiliation and identity within the company.
3. The mobile app then presents the claim in the SAML token to Access Control. Access Control controls access to the Service Bus Relay; any app that calls the Service Bus Relay must have a token from Access Control.
4. Access Control validates the SAML token based on the previously established trust relationship between Access Control and AD FS for the Service Bus Relay namespace and company domain. Based on the claim in the SAML token, Access Control verifies that the user is from the company associated with the Service Bus Relay namespace. Access Control then provides a second token to the mobile app in Simple Web Token (SWT) format. The SWT token is then included in the request to the Service Bus Relay to send a message to AX 2012. The SAML token is also included and is used by the on-premises listener to authenticate the user.

5. The mobile app then sends the message (with associated tokens) through the Service Bus Relay to the on-premises listener. The Service Bus Relay ferries the message to the listener.

   The listener must also be authenticated to listen to the Service Bus Relay. This authentication is based on a Service Bus Relay namespace credential that is stored on the listener. The listener presents this credential as it starts to listen for messages coming from the namespace.

6. After a message is received from the Service Bus Relay, the listener validates the SAML token. The validation is based on a previously established trust relationship between the listener and AD FS. After verifying the token, the listener uses the claim to determine which AX 2012 user is using the mobile app making the call to AX 2012. The listener calls AX 2012 on behalf of the user identified in the claim.
7. The listener receives a response from AX 2012 and then returns the response message through the Service Bus Relay.
8. The Service Bus Relay sends the response message to the mobile app.

Figure 22-2 illustrates the message flow and authentication process. The numbering in the figure roughly corresponds to the numbers in the list.

Using AX 2012 services for mobile clients

To develop mobile apps, you must have an interface with AX 2012. The ideal approach is to use AX 2012 services for communication between mobile apps and AX 2012. For more information about AX 2012 services, see Chapter 12.

The AX 2012 services framework provides multiple types of services—system services, custom services, and document services—each with its own programming model. Custom services are the most likely to provide the exchange of messages that are appropriate for a mobile app.

To design an AX 2012 service that can be consumed by your mobile app, you will need to do the following:

1. Create AX 2012 services and data contracts, and deploy a basic inbound port to expose the service operations for consumption.
2. Implement the service methods in X++ classes to perform data operations in AX 2012.

The mobile client must communicate with the AX 2012 service, which is hosted on an Application Object Server (AOS) instance that is deployed behind a corporate firewall. Instead of configuring changes in the firewall, such as exposing an Internet Information Services (IIS) server externally to expose the on-premises service, the app makes use of a secured Service Bus Relay.

AX 2012 services are typically accessed by using Simple Object Access Protocol (SOAP). This approach might work well for some mobile applications. However, the trend in developing web and mobile applications is to interact by using RESTful services. (Representational state transfer [REST] is an architecture that allows developers to write asynchronous code that connects with cloud-based services more easily.) For information about RESTful services, see the article, “An Introduction To RESTful Services With WCF,” at http://msdn.microsoft.com/en-us/magazine/dd315413.aspx.

Currently AX 2012 does not expose custom services by using a RESTful approach. One option is for the on-premises listener to translate RESTful calls from a mobile app to SOAP calls to AX 2012 (and vice versa). The Microsoft Dynamics AX product group used this approach to develop the Microsoft Dynamics AX Windows Store apps (expenses, timesheets, and approvals). For more information about the Microsoft Dynamics AX Windows Store apps, see “What’s new: Companion apps for Microsoft Dynamics AX 2012 R2” at http://technet.microsoft.com/en-us/library/dn527182.aspx.

Developing an on-premises listener

As described earlier, you’ll need an on-premises service that acts as an intermediary between the Service Bus Relay and AX 2012 services. One approach is to use Windows Communication Foundation (WCF) to build a simple listener.

Beyond the listener’s primary purpose of passing messages between the Service Bus Relay and AX 2012, the listener can provide additional features that facilitate the development of mobile applications. For example, the listener can provide configuration information to the app, such as whether certain features of the app are enabled or disabled. The listener can expose RESTful calls to the client. The Microsoft Dynamics AX product group used WCF features to translate between the SOAP and JavaScript Object Notation (JSON) protocols for messaging to the Windows Store apps. This is a standard feature of WCF. The listener can also capture meaningful information in the event log and provide telemetry information.

Another approach is to use the Azure Service Bus adapter built into AX 2012 starting with AX 2012 R2 cumulative update 6. With this approach, you configure IIS as the listener. Depending on the requirements of your mobile app, you can choose the best approach. For a comparison of these approaches, see “Microsoft Dynamics AX White Paper: Developing Mobile Apps” at http://www.microsoft.com/en-us/download/details.aspx?id=38413.