Integrating with Microsoft Dynamics AX 2009 using BizTalk Adapter

Carl Darski

August 2011


Microsoft BizTalk 2010: Line of Business Systems Integration

Microsoft BizTalk 2010: Line of Business Systems Integration

A practical guide to integrating Line of Business systems with BizTalk Server 2010

        Read more about this book      

(For more resources on BizTalk, see here.)


What is Dynamics AX?

Microsoft Dynamics AX (formally Microsoft Axapta) is Microsoft's Enterprise Resource Planning (ERP) solution for mid-size and large customers. Much like SAP, Dynamics AX provides functions that are critical to businesses that can benefit from BizTalk's integration. Microsoft Dynamics AX is fully customizable and extensible through its rich development platform and tools. It has direct connections to products such as Microsoft BizTalk Server, Microsoft SQL Server, Exchange, and Office.

Often Dynamics AX is compared to SAP All in One. Those who are familiar with SAP are also familiar with high cost of implementation, maintenance, and customization associated with it. A Microsoft Dynamics AX solution offers more customizability, lower maintenance costs, and lower per-user costs than SAP. ERP implementations often fail in part due to lack of user acceptance in adopting a new system. The Dynamics AX user interface has a similar look and feel to other widely used products such as Microsoft Office and Microsoft Outlook, which significantly increases the user's comfort level when dealing with a new ERP system. For more information on Dynamics AX 2009 and SAP, please see


Methods of integration with AX

Included with Dynamics AX 2009, Microsoft provides two tools for integration with Dynamics AX:

  • Dynamics AX BizTalk Adapter
  • .NET Business Connector

The BizTalk adapter interfaces via the Application Interface Framework Module (AIF) in Dynamics AX 2009, and the .NET Business Connector directly calls the Application Object Tree (AOT) classes in your AX source code.

The AIF module requires a license key, which can add cost to your integration projects if your organization has not purchased this module. It provides an extensible framework that enables integration via XML document exchange. A great advantage of the AIF module is its integration functionality with the BizTalk Dynamics AX adapter. Other adapters include a FILE adapter and MSMQ, as well as Web Services to consume XML files are included out of the box. The AIF module requires a fair amount of setup and configuration. Other advantages include full and granular security, capability of synchronous and asynchronous mode integration mode, and full logging of transactions and error handling.

The Microsoft BizTalk AX 2009 adapter can execute AX actions (exposed functions to the AIF module) to write data to AX in both synch and asynch modes. Which mode is used is determined by the design of your BizTalk application (via logical ports). A one-way send port will put the XML data into the AIF queue, whereas a two-way send-receive port will execute the actions and return a response message. Asynch transitions will stay in the AIF queue until a batch job is executed. Setting up and executing the batch jobs can be very difficult to manage. Pulling data from AX can also be achieved using the BizTalk adapter. Transactions pushed into the same AIF queue (with an OUTBOUND direction in an async mode) can be retrieved using the AX adapter which polls AX for these transactions.

The .NET Business connector requires custom .NET code to be written in order to implement it. If your business requirements are for a single (or very small amount) of point-to-point integration data flows, then we would recommend using the .NET Business Connector. However, this often requires customizations in order to create and expose the methods. Security also needs to be handled with the service account that the code is running under.


Installing the adapter and .NET Business Connector

The Microsoft BizTalk adapter for Dynamics AX 2009 and the .NET Business Connector are installed from your Dynamics AX Setup install setup under Integration on the Add or Modify components window. Each component is independent of one another; however the BizTalk adapter leverages components of the business connector. You are not required to install the Dynamics AX client on the BizTalk server. When installed in BizTalk adapter, you can simply select all the defaults from the install wizard. For the .NET business connector, you'll be prompted for the location of your Dynamics AX instance. This will be used only as a default configuration and can easily be changed.


Configuring Dynamics AX 2009 Application Integration Framework for BizTalk Adapter

Configuration of the AIF module involves several steps. It also goes a long way to increasing your understanding of the granularity of Dynamics AX setup and security considerations that were taken into account for integration of what can be highly sensitive data.It is recommended that this setup be done with Admin level security, however, only full control of the AIF module is required. This setup is almost identical in version prior to Dynamics AX 2009; minor differences will be noted.

  1. All AIF setup tables can be found in Dynamics AX under Basic | Setup | Application Integration Framework.
  2. The first step is rather simple, however critical. In the Transport Adapters form, add in a new entry selecting Adapter Class drop down AifBizTalkAdapter, select Active, and Direction will be Receive and Respond. You also notice there are two other out-of-the-box adapters: FILE and MSMQ. This is a one-time setup that is effective across all companies.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  3. Next, using the Channels form, set up an active channel for your specific BizTalk server. Select a meaningful and identifiable Channel ID and Name such as BizTalkChannelID and BizTalkChannel. Select the Adapter to BizTalk Adapter, check Active, set Direction to Both, Response channel equal to the Channel ID of BizTalkChannelID. Set the Address to your BizTalk Server (I2CDARS1 as shown below).

    (Move the mouse over the image to enlarge.)



        Read more about this book      

(For more resources on BizTalk, see here.)

  1. Then, click Configure to bring up the BizTalk Adapter configuration form. Again, set the Server name to the name of your BizTalk Server instance.

  2. This configuration is required for secure connectivity during runtime. It is also required in order for Visual Studio to connect to your Dynamics AX 2009 instance when using the schema import wizard. This is also a one-time setup across all companies.
  3. Now, in this step, we will set up a local endpoint from the Local endpoints form. Each company that your BizTalk application requires connectivity with will require a local endpoint. Select the Company you want to configure (CDF in our case) and type in CDFLocalEndpoint as shown.

    We recommend using this type of naming convention (Company + 'LocalEndpoint'), as often your BizTalk applications will need to specify this value. Often, the incoming message will contain data to determine which company it is intended for, thus, you'll need to dynamically determine the local endpoint during runtime.

    Microsoft BizTalk 2010: Line of Business Systems Integration

  4. Next, we need to create an endpoint from the Endpoints form. The endpoint links together our local endpoint, BizTalk channel, BizTalk service account, and active Dynamics AX actions. Again, each company will require a local endpoint and thus we'll use the same naming conversion.
  5. We'll start by typing in the Endpoint ID to CDFEndpoint and select the Local endpoint ID to CDFLocalEndpoint.

  6. On the General tab, specify the Outbound channel ID to BizTalkChannelID, which we created above. This will also allow asynchronous outbound messages to be retrieved from Dynamics AX 2009 using the BizTalk adapter.

  7. On the Constraints tab, we'll check No constraints. If required, you can specify constraints such as Customer and Vendor. Now, set the record to Active from the General tab and save.

  8. On the Users tab, we'll add the AX BizTalk user (linked to the Active Directory account that our BizTalk host instance is running under) by selecting User type to User, and then selecting the AX BizTalk (cdar in the example shown) user. Thus, all the records in AX will have this account as created by user. Depending on your integration requirements, this user may also need other associations such as employee.

  9. The next thing to do (after we have the AIF base configuration setup complete in AX) is to determine which AIF Services we are going to use. This will allow us to know what services to and thus which we need to enable. Each service has several actions associated with it. If there are no services out of the box with actions that meet our needs, we can either customize existing services or create our own. This is where the speed and ease of customizations in Dynamics AX are of great advantage.

    Note: Prior to AX 2009 actions were not grouped in services, thus no AIF Services table existed.

  10. For this example, we must use the out-of-the-box service LedgerExchangeRatesService. So, we will enable this service in the AIF services form as shown in the following screenshot:

  11. On the AIF Services form, we can examine the AX schema(s) for each by highlighting a Service name, clicking Service operations, selecting a specific Action, and then clicking Parameter schema. Actions include create, delete, find, findkeys, read, and update. Select the SalesOrderService and notice that there is no outbound schema for delete and update actions because these do not return a message.



        Read more about this book      

(For more resources on BizTalk, see here.)

A basic record in the Exchange Rates table only requires three fields: (1) Currency code, (2) Exchange Rate, and (3) From Date. We don't typically specify an end date as AX logic handles this when the next day's rate is entered.

Each AIF service will have its own security key associated with it. You must give the DynamicsAX BizTalk user account that access by assigning user permission to the required security keys in Dynamics AX 2009. In prior versions of Dynamics AX 2009, (where the AIF did not have services) security permissions had to be handled manually. This can be done by creating a security group with the permission needed to execute each AIF action and associating the Dynamics AX BizTalk user with the group.

  1. Now that the AIF service is enabled, we can go over to the Actions form and see the four actions that are enabled. These are the actions that are a part of the AIF LedgreExchangeRatesService service. Notice we can't enable any default action individually without enabling the service (in previous versions of Dynamics AX each individual action was required to be enabled).

  2. For each Dynamics AX company, you'll need to enter a currency relative to the base currency. Thus if you have one company whose currency is USD based, and another that's CAD based, then you'll need to enter a rate in each company for each currency. The USD-based company will require a USD/CAD rate to be entered, and the CAD-based company will need a CAD/USD rate entered. Thus, you'll need to repeat the following AIF Actions setup for each company's Endpoint if you're using the LedgerExchangeRatesService AIF Service.
  3. Now, we go back to the Endpoints form and click on Action policies to bring up the Endpoint Action Policies form. Although we have activated the LedgerExchangeRatesService, the Endpoint Action Policies are action specific, thus we need to create a record for each. Here, we'll select the Action ID to LedgerExchangeRatesService.create from the drop down; set the Status to Enabled, and Logging Mode to Log All. Now, we need to save the record. This will enable the Configure button on this form as shown in the following screenshot:

  4. Next, click Configure to bring up the Parameter Data Policies window.

  5. Click on Data policies; that will bring up the Endpoint Action data policies form. You'll notice that only the required fields are enabled. Here, we can get very granular in our security and data policies; however, with more complex AX actions this can get very tedious. Thus, simply click Set and then click Enable all.

    If you add customization to any Dynamics AX services, adding a new field for example, you need to (1) update the AIF Services by hitting the Refresh button (as in the figure above) and (2) enable the field in the Endpoint action data policies table.
    Typically, an integration policy would be not to override the value in the Exchange Rate table (based on currency & date) if it already exists. In fact, if we attempt to send a duplicate rate, AIF will throw an error. We could simply catch and ignore this error; however, this would be introducing unnecessary clutter in the AIF exception log. Since we can expose this table to AX business users, we want to limit as much as possible the amount of errors that are thrown from the AIF module.
  6. So, before we attempt to push an exchange rate we want to query AX so as to see if a particular rate already exists. To do this, we can use the out-of-the-box action LedgerExchangeRates.find. Note that the schema for the action will return a list of exchange rates. So now we'll need to repeat the above steps to enable this Action in the AIF Actions form, add it to the Action policies of our AIF Endpoint, and enable all the fields in the Endpoint Action data policies form. This completes the configuration of the AIF module in Dynamics AX.


In this article, we discussed the advantages of using the BizTalk Dynamics AX 2009 adapter for our BizTalk integration applications. We went through the required configuration setup of the Application Integration Framework module in Dynamics AX 2009.

Further resources on this subject:

You've been reading an excerpt of:

Microsoft BizTalk 2010: Line of Business Systems Integration

Explore Title