Overview

Below is an architecture overview detailing the flow of information between a Client Application on an external network (the Internet) communicating with X++ services running on Microsoft Dynamics AX in a firewalled enterprise network. The major components and their behaviors are:

Architecture Visual Representation

Click for larger image

The authentication process is as follows:

1. The client app sends user credentials to ADFS. The client calls the ADFS Security Token System (STS) with the user credentials and requests a Security Assertion Markup Language (SAML) token.  The SAML token is signed but unencrypted. This is because the token is used by Microsoft Dynamics AX 2012 R2 to identify the user.
   
2. ADFS computer sends token A to the client.
   
3. The client app sends token A (the SAML token) to ACS.
   
4. ACS first verifies that the SAML token corresponds to a user with permissions to call the Service Bus, and then sends token B to the client app. Token B is a Single Web Token (SWT) that has the claim required to make the service call to the Service Bus.
   
5. The client app makes a call to the Service Bus and passes tokens A and B along with the service request. The Service Bus consumes the SWT (token B), but allows the SAML token (token A) stored in a custom header to pass through. The SAML token is intended for use by an authentication component hosted in IIS.
   
6. The Service Bus relays the SAML token and service message through to the Windows Communication Foundation (WCF) Routing service. Because the WCF Routing service has established an outbound connection to the Service Bus, messages from the Service Bus are allowed through the firewall.
   
7. The AOS receives the SAML token and the service message from the WCF Routing service.
   
   • An authentication component for the service is invoked by IIS as part of the authentication process. (he authentication component is detailed in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.
     
     The authentication component performs the following steps while processing the message:

   a. Reads the custom header from the message.

   b. Extracts the SAML token from the custom header.

   c. Validates the token by verifying that the signature of the token matches the signature expected
   by the ADFS STS.

   d. Extracts the claims from the token.

   e. Creates the claims identity and principal and sets them on the security context of the message.

   • An AIF extension gets the user identity from the message security context and sets it on the message being forwarded to the AOS. The AOS authenticates the caller specified in the headers set on the message by the AIF extension.
     
8. The AOS processes the service call, and sends the Response message to the WCF routing service hosted in IIS.
   
9. The WCF routing service sends the service response back through the Service Bus.
   
10. The Service Bus sends the service response back to the client app. 

Getting started with the AIF Windows Azure Service Bus Adapter

In order to get started using the AIF Windows Azure Service Bus Adapter you must first fulfill the following prerequisites as detailed in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

• Configure your Service Bus and ACS namespaces
  
• Configure a Microsoft ADFS
  OR
  Contact the administrator of your local Microsoft ADFS and request  that your ACS be added as a relying party application
  
• Verify the AX component Web Services on IIS 7.5 is installed
  
• Install the AIF Windows Azure Service Bus Adapter hotfix: https://support.microsoft.com/kb/2845539
  
• Create a service authentication component 

After fulfilling the prerequisites above you will be able to complete the following steps to make an AX service available through the Service Bus:

1. Create an X++ service from an existing X++ class
2. Expose an existing X++ method as an operation on the service
3. Register your Service Bus namespace with the AIF
4. Publish your X++ service to the Service Bus using the AIF Windows Azure Service Bus Adapter

 These steps are summarized below, and detailed in full in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

Create an X++ service from an existing X++ class

1. Open the Microsoft Dynamics AX MorphX Development Workspace
2. Open the X++ Class containing the X++ methods you wish to expose as services
1. Supply a SysEntryPointAttribute to each method
2. Save your changes

Expose an existing X++ method as an operation on the service

1. Open the Microsoft Dynamics AX MorphX Development Workspace 
2. Create a new service by right-clicking the Services node in the AOT and selecting New Service
1. Supply a name for the service
2. Set the Class property to the name of an X++ class containing methods with the SysEnrtyPointAttribute
3. Right-click the new service and add a new operation
1. Select all methods you wish to expose as operations on this service
4. Right-click the new service, click Add-Ins and then click Register Service

For more information on registering services and service operations, see:
https://technet.microsoft.com/en-us/library/gg731906.aspx

Register your Service Bus namespace with AIF

1. Open the Microsoft Dynamics AX Client
2. Click System administration > Setup > Services and Application Integration Framework > Windows Azure Service Bus Configuration
3. Complete the Windows Azure Service Bus Configuration form (this is complete only once for each Service Bus namespace)
1. Windows Azure service namespace: Supply the name your Service Bus namespace
2. Windows Azure service key issuer name: Supply the Access Key issuer name of your Service Bus
3. Windows Azure service key issuer secret: Supply the Access Key of your Service Bus
4. Deployment web site: Select the IIS website that will host the routing service
5. Class name: Select the authentication component registered while completing the prerequisites
6. Click Configure
1. Trusted Issuer Name: Supply the name of the X.509 certificate issuer as obtained while completing the prerequisites
2. Trusted Issuer Thumbprint: Supply the X.509 certificate thumbprint obtained while completing the prerequisites
7. RSA Key Container Name: Supply the name of the key container created while completing the prerequisites
8. Description: Supply a description of the Service Bus namespace being configured

Publish your service to the Service Bus using the AIF Windows Azure Service Bus Adapter

1. Click System Administration > Services and Application Integration Framework > Inbound Ports
2. Click New to create a new port
1. Port Name: Type the name of the port
2. Description: Provide a description of the services this port hosts
3. Adapter: Select Windows Azure Service Bus
4. Click the dropdown button beside the URI filed to open the Select Windows Azure Service Bus Namespace form
1. Select the namespace you registered
2. Click OK
   
5. Click the Service Operations button below Service Contract customizations
1. Locate the X++ service you wish to expose
2. Select all of the Operations on your service you wish to publish by highlighting each one and clicking the "<" button
3. Click Close
3. In the Inbound Ports window, highlight the port you created in the left-hand pane
4. Click the Activate button at the top

Your X++ service is now published to IIS 7.5 and listening to messages from the Service Bus. 

White papers:

• Selecting the Best Development Technology for Your Application Development Scenario: https://technet.microsoft.com/EN-US/library/hh272857.aspx
• Consuming Web Services: https://technet.microsoft.com/EN-US/library/hh272880.aspx
• Services: https://technet.microsoft.com/EN-US/library/hh272881.aspx 

Topics on Technet and MSDN: https://msdn.microsoft.com/en-us/library/gg731810.aspx):

• Services and AIF (includes Getting Started, Architecture, Planning, Operations, Troubleshooting): https://technet.microsoft.com/EN-US/library/gg731810.aspx
• Developer topics: https://technet.microsoft.com/EN-US/library/hh397321.aspx
• Troubleshooting: https://technet.microsoft.com/EN-US/library/aa548693.aspx

Training course 80416: Application Integration Framework and Services in Microsoft Dynamics® AX 2012

• PartnerSource: https://mbs.microsoft.com/partnersource/communities/training/trainingmaterials/student/course80416.htm?printpage=false
• CustomerSource: https://mbs.microsoft.com/customersource/training/trainingmaterials/student/course80416.htm?printpage=false

There are few workarounds for this limitation. If you want a field to be serialized irrespective of its value, you need to make it a “required” field. This can be done in two ways:

-          Make field mandatory at table level ie. In AOT , set the field property ‘Mandatory’ to Yes.

-          Make the field mandatory at service level.

Making a field mandatory at the table level affects all the consumers of the table such as forms. The second way is less intrusive since it only affects services stack. The tradeoff in this case is that both inbound and outbound exchanges for the document would need to include the required field or else the service operation would throw an error.

 This article demonstrates shows how to make a field mandatory at service level.

To demonstrate the outbound scenario, we are using BomBillsofMaterialsService document service already provided in Microsoft Dynamics AX and Contoso demo dataset available with product download.

Now let’s walk through this scenario

1.       Import Contoso dataset

2.       Register BomBillsofMaterialsService in AOT.

3.       Create an outbound port. Expose BomBillsofMaterialsService.* service operations on the port.

4.       Open Inventory and Warehouse Management à Common à Bills Of Materials form. This form already has AIF send API to generate outbound requests for AIF.

5.       Select an item and set ‘From qty = 0.00’ on the form. Click on “Send…”and select the outbound port. This sends an outbound BomBillsofMaterialsService.find request to the AIF.

6.       Run AifOutboundProcessingService and AifGatewaySendService batch jobs. For more information, see  the section “Configure and start the AIF batch services” in this topic on MSDN: https://msdn.microsoft.com/en-us/library/hh352313.aspx ..

7.       Check the resulting xml. The outbound xml in this case does not contain the tag ‘FromQty’ since its value is 0.00

As you would have observed that the ‘FromQty’ property is missing from the outbound xml. Let’s apply workaround #2 – of making FromQty mandatory for BomBillsofMaterialsService by following steps:

1.       Open the document class for BomBillsofMaterialsService service – AxdBillsOfMaterials . Override method initMandatoryFieldsMap() from the AxdBase in AxdBillsOfMaterials class

2.       Update method body as

 protected void initMandatoryFieldsMap()
 
 {
 
 super();
 
 this.setParmMethodAsMandatory(classNum(AxBOMVersion),methodStr(AxBOMVersion,parmFromQty));
 
 }
 

 For more information about the initMandatoryFieldsMap method, see https://msdn.microsoft.com/en-us/library/axdbase.initmandatoryfieldsmap.aspx .

3.       Here AxBOMVersion is the AxBC class for the table that contains the field and parmFromQty is the name of the field parm method.

4.       Compile the method.

5.       Generate Incremental IL

6.       Register the service again by right clicking the service node in AOT and selecting ‘Register Service’

7.       Stop and restart the AOS to flush all caches.

8.       Click on View Schema button on Document Data Policies form for the outbound port. The updated schema now shows ‘FromQty’ as a mandatory field.

9.       Send another request to the outbound port with FromQty = 0.00.

10.       Open the outbound xml and  this time you will see the FromQty property in the output xml.

Use of the sample code is covered by the license agreement included in the zipfile.

Introduction to the SysOperation Framework.zip

Images retrieved using OData query services are returned as base 64 encoded containers. The following code will decode the image container into a byte array that contains just the image.

string base64EncodedString = "<place your base64 encoded blob here>";

byte[] serializedContainer = Convert.FromBase64String(base64EncodedString);

byte[] modifiedSerializedContainer = null;

 if (serializedContainer.Length >= 7 &&

        serializedContainer.Take(3).SequenceEqual(new byte[] { 0x07, 0xFD, 0x30 }))

{

    modifiedSerializedContainer = serializedContainer.Skip(7).ToArray();

}

File.WriteAllBytes("<image file name here>", modifiedSerializedContainer);

This posting is provided "AS IS" with no warranties, and confers no rights. 

One big piece of news is that we now publish all the Services and AIF content on both TechNet and MSDN as a unified set of documentation. We hope that this will make the content easier to navigate and use. Whether you're a power user, system admin, or a developer, you can choose your favorite flavor of website.

See for yourself! 

This: https://msdn.microsoft.com/en-us/library/gg731810.aspx 

Is the same as this:  https://technet.microsoft.com/en-us/library/gg731810.aspx

-- Jim

Microsoft Dynamics AX 2012 hosts an OData Query Service that uses the Open Data Protocol (OData) protocol to execute queries that are modeled in the Application Object Tree (AOT). The OData protocol is a HTTP protocol for querying and updating data. Microsoft Dynamics AX 2012 supports data query scenarios (with some limitations listed below), but does not support data update scenarios. The following example describes how to read data from the Currency table. The sample assumes that the Application Object Server (AOS) is installed on a machine named ‘aoshost’.

Set up an AOT query that can be executed by the OData Query Service

1. Open the Microsoft Dynamics AX 2012 development environment.
1. Under AOT, click the Queries node, and then create a new query node. Either  (1) Select File > New or (2) Right-click the Queries node, and then select New Query.
2. Change the name the new query node to “CurrencyQuery”.
3. Under AOT, click Queries > CurrencyQuery > Data Sources node, and then create a new data source node. Either: (1) SelectFile > New. or (2) Right-click the Data Sources node, and then select New Data Source.
4. Select the new data source node Currency_1, and then on the Table property in the property sheet, select Currency
2. Open the Microsoft Dynamics AX 2012 Windows Client.
1. Click Organization Administration > Setup > Document management > Document data sources.
2. In the Document data sources form, click New or press CTRL+N to add a new document data source.

                                          i.    No specific value is required in the Module column.

                                        ii.    In the Data source type column, select Query.

                                       iii.    In the Data source name column, select or enter the CurrencyQuery.

                                       iv.    Select the Activated check box to activate the query as a document data source.

                                        v.    Close the Document data sources form.

Using the OData Query Service with Windows Internet Explorer

1. Open Internet Explorer.
2. Enter the following URL to return the OData Query Service definition: https://aoshost:8101/DynamicsAx/Services/ODataQueryService/. The service will display the name CurrencyQuery. The Application Object Server (AOS) host name and the services port are provided when installing and configuring each AOS and can be found in the AX32Serv.exe.config file created under the file system folder created for the AOS.
3. Enter the following URL to return the OData Query Service metadata definition: https://aoshost:8101/DynamicsAx/Services/ODataQueryService/$metadata
4. Enter the following URL to execute the CurrencyQuery query: https://aoshost:8101/DynamicsAx/Services/ODataQueryService/CurrencyQuery

Note: If Internet Explorer formats the results as a feed, then right-click on the HTML page, and select View source to open the result in Notepad.

 Using the OData Query Service with Microsoft PowerPivot

1. Install Microsoft Excel.
2. Install Microsoft PowerPivot.
3. Open Microsoft Excel.
4. Click the PowerPivot tab.
5. On the PowerPivot tab, in the Launch group, click the PowerPivot Window button. A PowerPivot window opens.
6. On the Home tab, in the Get External Data group, click the From Data Feeds button.
7. In the Data Feed Url field, enter the following URL:  https://aoshost:8101/DynamicsAx/Services/ODataQueryService/
8. Click the Next button to view the CurrencyQuery OData data source.
9. Click the Finish button to import the currency data into PowerPivot.
10. Click the Close button to view the currency data.

Using the OData Query Service with Microsoft Visual Studio

1. Install Microsoft Visual Studio.
2. Create a new Console Application.
3. Right-click the project References node in the Solution Explorer window, and then select the Add Service Reference… menu item.
4. Enter the following Url into the Address field and click Go: https://aoshost:8101/DynamicsAx/Services/ODataQueryService/
5. Click OK to add the service reference to the project.

OData Query Service paging

The OData Query Service returns data in pages that have a length specified in the AX32Serv.exe.config file created under the file system folder created for the AOS. The page size can be modified by editing the configuration file and by restarting the AOS. The default page size is shown in the following XML document fragment.

       <add key="ODataQueryPageSize" value="1000" />

OData Query Service limitations

• OData protocol filters are not supported.
• OData protocol create and update operations are not supported.
• Each record in an OData query response must have a unique primary key. AOT queries with View data sources are therefore not OData query candidates and will not be displayed in an OData metadata request.
• Only queries that support “Value-based paging” are executed. AOT queries whose FetchMode property value is “1:N” will generate an error message in the Windows Event Log

OData Query Service notes

• You may need to replace the AOS host machine name with an IP address in the OData Query Service Url when accessing OData Query Services remotely.
• Some applications require a slash mark (/) at the end of the service definition URL. For example: https://aoshost:8101/DynamicsAx/Services/ODataQueryService/
• Check the Application Windows Log in the Event Viewer if no results are returned from a query. Error messages generated by unsupported queries are written to this log.

 Known Bugs

• There is a bug in how we check for 1:N fetch mode in Microsoft Dynamics AX 2012 and this results in a windows event log message stating that the query is not supported because it specifies a fetch mode of 1:N. The problem is that the root data source's fetch mode defaults to 1:N and the query validation logic checks and throws an exception for this condition. The root data source fetch mode is not exposed in the AOT so the work around is to export the query as an XPO file and then to edit the query by adding the fetch mode for the root data source as shown in the following example:

     BLOCK #TrvExpTable
      PROPERTIES
        Name                #TrvExpTable
        Table               #TrvExpTable
        UniqueId            #1000
        FetchMode           #1:1
      ENDPROPERTIES

This posting is provided "AS IS" with no warranties, and confers no rights.

I'm Jim Travis, a Senior Technical Writer at Microsoft. I write documentation for services and Application Integration Framework (AIF) in Microsoft Dynamics AX.

Recently, I've been working on integration between Microsoft BizTalk Server 2010 (https://www.microsoft.com/biztalk/en/us/default.aspx) and Microsoft Dynamics AX 2012. If you have used BizTalk, then you know that BizTalk Server is a commonly used middleware product from Microsoft that is used for large-scale integration scenarios in the enterprise. While the Dynamics AX services and AIF features are very well suited to small-scale integrations, when BizTalk is in use in the enterprise, then AIF becomes more of a "spoke" to the BizTalk "hub."

In Microsoft Dynamics AX2009, we included a specialized BizTalk adapter. This component did a fair job of setting up the connections between Dynamics AX and BizTalk, but at the cost of creating some additional complications and requiring deployment of custom code and a superfluous component. In Dynamics AX 2012, we have removed the BizTalk adapter. Instead, we have chosen to favor standards-based communications, wherever possible. Because BizTalk and AIF both are built on Windows Communication Foundation (WCF), you can simply use the standard WCF adapters to manage communications across various transports and using various protocols. Typically, synchronous communications happen through standard Web services by using the HTTP or NetTCP adapters, while asynchronous communications simply use the file system or Message Queuing (MSMQ).

Now, if you've become accustomed to using the Dynamics AX 2009 BizTalk adapter, there will be some work to do to understand how to get the systems to communicate without the adapter. However, I assure you that it's very straightforward and you should be up and running in no time at all. If you're used BizTalk before, here are a few important points to understand:

• For simple scenarios, such as those requiring
  just transformation and communication of data to and from AX, there is no need
  to create an orchestration.  All the
  transformations and communication happen through the standard ports and
  pipelines. You will still need to add an orchestration if you have the need for
  additional processing in complex scenarios.
• You don't need to write any custom code. The
  BizTalk mapper can create the transformations for you and the BizTalk
  administration console can set up the entire integration.
• Microsoft Dynamics AX 2012 integration ports are
  much simpler to configure than earlier versions, yet provide the needed
  flexibility to enforce your data and authorization policies.

We've published a detailed white paper on this topic. The white paper provides a comprehensive FAQ and then walks you through two scenarios, step by step. The first scenario shows you how to create a sales order that starts out in a custom XML format, by using the file system adapter. The second scenario shows you how to read the sales order that you created in the first scenario, by using the NetTCP adapter.

You can download the white paper from this link: https://go.microsoft.com/fwlink/?LinkId=221937

I'll be posting a video, soon, that walks you through a bit of this scenario, as well.

Thanks,

Jim Travis [MS]

This posting is provided "AS IS" with no warranties, and confers no rights.

• Services in Microsoft Dynamics AX 2012 gives an overview of different types of services that are available in Microsoft Dynamics AX 2012 and provides guidance for developers and architects in deciding when to use a specific service type.
• Consuming Web Services describes how to reference a web service and provides example code that demonstrates how to use the service in X++.

In addition to exposing functionality through services that ship with Microsoft Dynamics AX 2012, Microsoft Dynamics AX 2012 also provides declarative language constructs (X++ attributes) and development tools so that you can quickly expose existing X++ business logic as services without additional coding.

This white paper provides an overview of the common development patterns, programming models, and development tool changes in Microsoft Dynamics AX 2012, including services:

• Selecting the Best Development Technology for Your Application Development Scenario

You may also be interested in the following resources for developers:

• What’s New in Microsoft Dynamics AX 2012 for Developers
• What’s New: Services and AIF (Microsoft Dynamics AX 2012) on Technet
• Developer Help on MSDN
• MSDN Developer Center- includes a link to the April 2011 beta code download

And finally, this white paper describes all the Microsoft Dynamics AX 2012 documentation currently available:

• Documentation Resources for Microsoft Dynamics AX 2012

To fix this problem, increase the binding properties maxBufferSize and maxReceivedMessageSize.  These properties are part of the <bindings> section in the app.config and web.config. Both parameters must be changed on the both the client side in the app.config and on the server side in the web.config. To change these properties, you can edit the config files directly or go to Basic > Setup > AIF > Services and click the Configure button to open the service configuration editor. Here are some links that cover this aspect of WCF:

MSDN: https://msdn.microsoft.com/en-us/library/ms733135.aspx

Blog: https://geekswithblogs.net/niemguy/archive/2007/12/11/wcf-maxstringcontentlength-maxbuffersize-and-maxreceivedmessagesize.aspx