Monday, October 12, 2009

Taming the BizTalk AIF Adapter for Microsoft Dynamics AX 2009

Microsoft Dynamics AX 2009 is a new version of one of Microsoft ERP systems tailored for a specific market. The advantages of the new Dynamics AX 2009 version is that the technical integration of trading partner integration is much more robust and interfacing with other applications using BizTalk has now become even easier because the accompanied BizTalk AIF Adapter.

Dynamics AX 2009 exposes documents using an application platform called AIF. AIF enables the integration of Microsoft Dynamics AX through Web services, Microsoft Message Queuing (MSMQ), the file system (using a directory), or BizTalk Server.
The AIF framework uses documents wrapped in envelopes for processing. A downside to not using the BizTalk adapter is that the envelope processing has to be performed additionally while the BizTalk adapter will solve this for you. A colleague of mine has an article on how to do AIF processing without the AIF adapter (see:, this article will show you how to integrate with AIF using the BizTalk AIF Adapter.


  • Installed version of Dynamics AX 2009
    (All available service packs / fix packs must be installed, this is not easy to forget since the installation wizard forces you to install all service / fix packs before you can continue)
  • BizTalk environment
  • BizTalk AIF Adapter installed in the BizTalk environment
    (This can be found on the installation disc of Dynamics AX 2009)
  • Active directory account with access to Dynamics AX 2009
    (Used for authorization)
  • Active directory account (used for the proxy)
  • GOTCHA: Run the host instance under the active directory user with access to Dynamics AX 2009

Developing the BizTalk solution

Perform the following steps to develop a BizTalk solution using the BizTalk AIF Adapter;

1) Create a reference to the Dynamics AX DLL (used for the AX Documents)

C:\Program Files\Microsoft Dynamics AX\50\Client\Bin\Microsoft.Dynamics.BizTalk.Adapter.Schemas.dll

2) Walk through the ‘Add Generated Items wizard’ and select the process you want to implement

  • Right click the BizTalk project, add new item, add generated items

  • Select Adapter: Microsoft Dynamics AX 2009

Enter values for the following fields:
Set Server name = .
Set TCP/IP Port = .
  • Select the process that you want to implement

TIP: You can communicate Synchronous or A-Synchronous with the obvious pros and cons. I found however that for the initial setup when you are finding your way, synchronous is much more helpful when debugging the initial setup.

3) Configure Dynamics AX 2009 (it might post this in detail in a second blog post)

To be able to communicate with Dynamics AX 2009, the configuration of Dynamics has to be set up correctly. Since this is the non BizTalk point, this might not be of interest. The following steps must be performed and be found in a Microsoft whitepaper ‘Application Integration Framework(AIF) BizTalk adapter configuration for data exchange’;

  • Configure transport adapters (activate the dynamics side for send/receive)
  • Configure channels (configure one-way / bi-directional channels)
  • Configure services (configure what functionality to expose, used in the add generated items wizard)
  • Configure endpoint (this is used to configure how to expose the services, set authorization etc, e.g. a unique endpoint ID per service is configured so that the BizTalk orchestration can address this endpoint easily )

4) Set the context properties

When the orchestration is developed, some context properties must be set to be able to send/receive messages using the BizTalk AIF adapter as shown below;
PORequest = POCanonical;
PORequest(*) = POCanonical(*);

PORequest(DynamicsAx5.DestinationEndpoint) = "OrderEndpoint";
PORequest(DynamicsAx5.SourceEndpoint) = " OrderEndpoint ";
PORequest(DynamicsAx5.SourceEndpointUser) = @"activedirectory\axuser"; //a valid active directory user with access to dynamics
PORequest(DynamicsAx5.MessageId) = POCanonical(BTS.MessageID); //unique message id
PORequest(DynamicsAx5.Action) =
""; //action to identify the service that is required

5) Configure the port and specify the users

The final step is to configure the ports;

  • Active directory proxy account (port configuration) à used to authenticate to the AIF framework
  • Use an active directory account with access to Dynamics AX 2009 à used to authorize
    Configure the host instance with an user that is allowed to use Dynamics AX 2009.

This should do the trick!

Happy BizTalking…


toby_worth said...

Would be great if you made the blog entry for Configure Dynamics AX 2009 endpoint.

Anonymous said...

cannot find the "Microsoft.Dynamics.BizTalk.Adapter.Schemas.dll" in that folder, Any other software need to install, i've already installed biztalke and ax2009.please help.thx!