Tuesday, January 24, 2012

Microsoft Dynamics AX 2012 Services and (Application Integration Framework) AIF architecture

Hi there!

In this post I would like to discuss, in detail, the Application Integration Framework (AIF) and its capability to integrate Microsoft Dynamics AX 2012 with other systems inside and outside an organization.

So what is the AIF and why is important?

The AIF provides capability to integrate Microsoft Dynamics AX 2012 with other systems inside and outside an organization by enabling the exchange of data through XML.

This formatted XML is referred to as a document, and each document contains data and business logic. Documents are based on a document class and defined by using Microsoft Dynamics AX.

Further, AX 2012 ships together with standard document services that support common business processes. As in AX 2009, in AX 2012 we can also customize existing services or create our services.

How documents are exchanged?

The AIF provides an extensible framework for the exchange of XML documents with external systems. The framework supports both synchronous and asynchronous transports.

In synchronous mode, requests are tightly coupled to responses, which means that the submitter of the request must wait for a response from AIF before proceeding.  In this case, AIF does process the request immediately and then sends a response.

In asynchronous mode, however, requests are placed into a queue, called the gateway queue. Queued messages are processed at a later time and AIF sends a response when processing is completed. In this case, responses are delayed, but note that large volumes of messages can be processed more efficiently, and message processing can be controlled by changing various configuration settings. Further, the AIF can be used to send and retrieve data into/from AX.

Inbound / Outbound Exchanges

Inbound exchange, an external system may send a sales order so that the sales order can be saved to the Microsoft Dynamics AX database.
Outbound exchange, an external system may send a request for a purchase order and receive the purchase order.

The inbound and outbound exchanges can be categorized in the following ways:

  • Send data – AX sends documents to an external system.
  • Send data in response to requests – AX receives requests for documents from another authorized system, and retrieves the requested information, such as a document or a list of documents, from the AX database. Then AX returns the information to the requesting system.
  • Receive and create data – AX receives documents from another authorized system and creates new records in the Microsoft Dynamics AX database.

AIF Architecture

AX 2012 exposes its functionality through services that are based on Windows Communication Foundation (WCF) and hosted on Application Object Server (AOS).

External applications and client applications on the local area network consume AX services by accessing them directly from AOS. These clients and applications include AX components such as the AX client, Office Add-, and Enterprise Portal.

The following diagram illustrates the services and AIF architecture.

Application Integration Framework Process
  • Internet-based external applications and clients access the AX services through Internet Information Services (IIS).
  • IIS routes the incoming requests for AX services to AOS. All services requests, regardless of their origin, are handled by the WCF runtime that is hosted on AOS.
  • The AIF request pre-processor, if it is configured, can intercept the inbound request messages for custom preprocessing, such as message transforms or value substitutions.
  • The AX service invokes the necessary business logic to process the inbound request message.
  • Similarly, the AIF response post-processor, if it is configured, can intercept the outbound response messages for custom post-processing, such as message transforms or value substitutions.
  • The AIF response post-processor then returns the response to the client.

NOTE:  Microsoft Dynamics AX 2012 no longer includes a BizTalk adapter. For more information about how to use Microsoft BizTalk Server together with Microsoft Dynamics AX 2012, see Exchanging documents between BizTalk Server and AIF.

Services in AX 2012

Application Object Server (AOS) is the Windows Communication Foundation (WCF) service host for Microsoft Dynamics AX 2012 services that are exposed to users and applications on an intranet.
  • To consume services over the Internet, you must host services on Internet Information Services (IIS).
  • Services that are hosted on IIS use the WCF message routing service. IIS routes all service requests to AOS.
  • All service requests are processed on AOS, regardless of whether they originate on the Internet or an intranet. AOS then returns a response to the service consumer via IIS.
  • Exchanges that are configured to use Web services are processed synchronously and therefore are not queued.
  • AX deploys the service that is based on Web Services Description Language (WSDL) to a subfolder of the virtual directory that is associated with the Web site that you provide.

NOTE: In general when dealing with the AIF, keep in mind that the AIF user names and passwords are encrypted in the Application.Host configuration file located in C:\Windows\System32\Inetsrv\Config. Therefore, DO NOT copy files from other environments into this location when the AIF and/or Workflow are running in the same machine.

AX 2012 supports the following three kinds of services:
  • Document services are query-based services that can be used to exchange data with external systems by sending and receiving XML documents. These documents represent business entities, such as customers, vendors, or sales orders.
  • Custom services can be used by developers to expose any X++ logic, such as X++ classes and their members, through a service interface.
  • System services are provided by Microsoft Dynamics AX. System services include the Query service, the Metadata service, and the User Session service.
Further, system services are not customizable, and they are not mapped to any query or X++ code. For more information about system services, see AIF System Services.

Integration ports in AX 2012

In Microsoft Dynamics AX 2012, integration ports provide simplified administration of services and Application Integration Framework (AIF). Integration ports replace the AIF endpoints and related concepts that were used in previous releases of Microsoft Dynamics AX.

  • Each integration port can expose one or more services, and each integration port has a unique Uniform Resource Identifier (URI) that identifies the address of the port.
  • Each integration port also has a direction. An integration port can be either an inbound integration port or an outbound integration port.
  • An inbound integration port is a destination for messages that originate from outside Microsoft Dynamics AX.
  • An outbound integration port is a destination for messages that originate from your Microsoft Dynamics AX system. Inbound integration ports can be one of two types: basic or enhanced. Outbound integration ports are always enhanced ports.

Basic integration ports

Basic integration ports are exposed at a specific Windows Communication Foundation (WCF) endpoint on the Application Object Server (AOS) host. Only a developer can create a new basic integration port.

Enhanced integration ports

If you want advanced integration capabilities that you can use to customize the behavior of an integration port, you must create an enhanced integration port.

Enhanced integration ports provide the following capabilities that basic integration ports do not provide:
  • A variety of protocols are supported through WCF adapters. These protocols include HTTP, NetTCP, and Message Queuing, which is also known as MSMQ.
  • Enhanced integration ports also support a file system adapter that lets you use file paths as addresses.
  • You can perform pre-processing and post-processing of service requests and service responses.
  • You can create customizations for data contracts by specifying service operations and policies for document data.
  • You can specify advanced security and troubleshooting settings.


In AX 2012 services and AIF, integration ports use adapters. These adapters enable AX to communicate by using various transport protocols.

AX 2012 provides the following four adapters that represent predefined bindings:

HTTP adapter – This adapter provides for synchronous message exchanges by using an HTTP or HTTPs transport.

NetTCP adapter – This adapter provides for synchronous exchanges by using WS-* standards support over the Transmission Control Protocol (TCP) transport.

This adapter corresponds to the WCF-NetTcp binding in Windows Communication Foundation (WCF).

MSMQ adapter – This adapter provides support for queuing by using Message Queuing as a transport. Message Queuing is also known as MSMQ.

Message Queuing is a type of asynchronous communication. This adapter corresponds to the WCF-NetMsmq binding in WCF.

File system adapter – This adapter provides support for the asynchronous exchange of documents through file system directories.

Messages and transforms in AIF

In AX 2012 services and AIF, a message corresponds to a Windows Communication Foundation (WCF) message. A message is a self-contained unit of data that can consist of several parts. These parts include a body and headers. When AIF receives and processes an inbound message, it generates an outbound message in response.

Although AIF supports the transfer of data in any arbitrary format, most information exchanges with AIF services use XML documents.

In order to create an XML document that adheres to a standard for a particular exchange of information, AIF requires XML documents to follow an XML style definition (XSD). XSD files (which have a .xsd file name extension) are meta-documents that describe the format, or schema, of XML documents that declare the namespace of the XSD.

Each schema includes rules about the hierarchical arrangement of XML elements, which elements must be present in the document, and other such requirements.


1-Document service schemas: Each document service has a unique schema that describes the fields that can be added, read, updated, and so forth, by using the particular document service.

2-Message schema: Asynchronous exchanges require XML messages to be contained by the AIF message envelope. The namespace for the message schema is:

3-Message-set schema: AIF uses the message-set, or batch, schema to contain batched AIF messages in asynchronous exchanges. The namespace for the message-set schema is:


4-Entity key schemas: AIF uses entity key schemas to contain name-value pairs, such as those used to query for a particular item during a read operation or when sending a response to a create operation. The namespaces for entity keys and entity key lists are:


5-Shared types schema: AIF aggregates common property types in the shared-types schema. The namespace for the shared-types schema is:


6-Fault schema: AIF uses the fault schema to contain response messages about error conditions. The namespace for the fault schema is:


Schema locations

You can save XSDs for particular document services, including their imported schemas (such as the shared-types schema) and any port-specific customizations, when you configure data policies for an integration port.

You can retrieve XSDs for common schemas from the following directory where you installed Microsoft Dynamics AX:
Program files\Microsoft Dynamics AX\60\Server\MicrosoftDynamicsAX\bin\Application\Share\Include

Processing messages

When you use an enhanced integration port for services and AIF, you can perform custom processing of data, such as XML documents, as each message passes through the integration port. Enhanced integration ports use the following two concepts to process messages during inbound or outbound exchanges:
  • Extensible Stylesheet Language Transformations (XSLT)
  • .NET-based transforms to messages.

In addition, transforms are run for inbound exchanges before they are run for outbound exchanges. Transforms process the whole message. Headers are included in the processing.

NOTE: Transforms apply only to asynchronous exchanges.

.Net-based transforms can convert messages to or from any proprietary format. AX services and AIF can process XML documents only if the documents comply with the service XSD.

If an incoming document is based on XML but uses a different schema, you can use Extensible Stylesheet Language (XSL) to transform the document to the AIF schema.

If an incoming document is not based on XML, such as a comma-delimited file, you can use a .NET Framework assembly to convert the file to the AIF schema.
Pipelines use components to enable the processing of requests for service operations. These components include custom components that are written in X++ code.

For example, if an inbound message contains customer records, your AIF pipeline can contain an XSLT component that updates an element in the XML, based on the value of the customer status element.

Further, your AIF pipeline can contain one or more of any available transformation component. Alternatively, your AIF pipeline can contain no transformation components.

Processing that occurs in pipelines, including XML transformation, applies to both synchronous and asynchronous exchanges.

For inbound exchanges, pipelines are run after transforms. For outbound exchanges, pipelines are run before transforms.

The following diagram shows how data moves through an enhanced inbound integration port.

That's all for now.


  1. This is excellent... Thanks for posting this. Cheers!!

  2. Keep up d good work!!!!

  3. Can you please guide on how to consume services in AX 2012?

  4. Hi,

    Take a look at the following:


    The above links will give uou a good direction.

    I hope this helps!

    1. Just like the way AX2012 can work with MSMQ, is there a way AX2012 can work with third party Message Queuing transports like IBM WebSphere MQ which supports a WCF interface? My intention is to configure AX2012 to receive web service request messages via IBM MQ transport and send responses back via the same transport. MQ WCF interface is in C#.

    2. Hi,

      Yes, it is possible. You can create a AIF service in AX that will be consume by WESB. In addition, AX AIF will be able to consume a service from WESB. I did work with WESB not long ago where we would consume flat files that were coming from PeopleSoft via WESB. The same was tru to send information back to PeopleSoft via WESB (flat file).

      I'm not sure if WESB will be a middle tier for what you need to do. If so, just make sure to understand if the target system can handle WESB service calls. PeopleSoft didn't, thus the need to do it through flat files.

      The good news though is that AX 2012 AIF can read any type of files now, not only XML documents. If this is your case, you can create a WCF service and use the .NET file classes to read the file contents. However, if you don't need flat files (or any other file) for your integration, then it will be really easy to create and consume a service through c#.

      Please see the above response for links on how to achieve this,

      Thanks for reading my blog and I hope this helps!

  5. Hi colleagues, nice paragraph and nice arguments commented
    at this place, I am genuinely enjoying by these.
    Also see my site - acls pretest

  6. Hello,

    When creating an inbound port in Dynamics AX 2012, we can specify a URI where the WSDL is hosted for NetTCP adapters. Using that WSDL file application can generate service references. Is it possible to have a WSDL defined for an inbound port that uses MSMQ adapter?

    1. Hi,

      I'm not sure if that would work, Sashi. It would be great if you could let us know the outcome of this to have it available for the community.


    2. Sorry for delayed response. AX Port configuration panel does not provide a way to set WSDL URL for MSMQ adapter. So it can't be done.

    3. Shashi, thank you very much for sharing this with us.

  7. I'm really impressed with your writing skills and also with the layout on your weblog. Is this a paid theme or did you modify it yourself? Anyway keep up the excellent quality writing, it's rare to see a great
    blog like this one today.
    My web-site :: bd web searh

    1. Hi,

      I did everything myself. It is a simple blogger layout. Thanks for your comments and I'm glad you liked my blog.

  8. This comment has been removed by the author.

  9. You have been of great help for me. The new question is about AifGatewayMessage class. Is it possible to set some custom data to to an instance of this class, say some tag or something similar and put that message to AX Gateway queue and indicate to AX to return the same tag on the response message?

    1. Hi,

      This is an interesting question that I don't have an answer to. Let me poke around and I'll try to get back to you as soon as I can with a good answer.

      Thanks for sharing your thoughts with us.

  10. Excellent post, Neet & clean one, keep it up

  11. Neat & clean post, Keep it up

  12. Hi,
    I am new into the Dynamics AX 2012 world and I have a question about integrating a (Visual Studio 2010) custom asp.net web app with Dynamics AX 2012. What is the best practice to do this integration: using services or .NET business connector? I nee to CRUD Dynamics AX 2012 objects from the custom ASP.NET application. Do you have or can you advice about some sample code or how can I achieve this, and what's the best solution?

    Thank you!

    1. Hi,

      I would recommend using services instead of the .NET nusiness connector as the latter will be eliminated in the next release.

      As for sample code, what do you need? I understand that you are trying to integrate an ASP.NET page, but if you use services, the code used is the same that for any service layer in .NET.

      Let me know what you need (specificaly).


    2. Hi,

      First thank you for your replay and willingness to help. This is the scenarios: I need tho integrate an asp.net application with Dynamics AX 2012. The application should be able to read invoices from DAX, users should make different operations on the invoice(s) and than save it(them) back to DAX. As I am new to DAX I have no idea what services to call and where you can find them exposed. The integration has to be done with Visual Studio 2010. I will appreciate some sample code operations on DAX services: create, read, write. It's not difficult to add the references and call the services... what about authentication from external app? DAX services are REST or SOAP?

      Thnak you very much!

  13. Hi

    when i active a service in ax 2012 i was get the below mentioned error

    Faulted: System.OperationCanceledException: AIF service group not activated. Service group: AifServices. Error: Duplicate type with name 'Dynamics.Ax.Application.PrintMyName' in assembly 'Dynamics.Ax.Application, Version=6.0.947.0, Culture=neutral, PublicKeyToken=null'. ---> System.BadImageFormatException: Duplicate type with name 'Dynamics.Ax.Application.PrintMyName' in assembly 'Dynamics.Ax.Application, Version=6.0.947.0, Culture=neutral, PublicKeyToken=null'.

    please provide the solution for this error

    1. Hi Naresh,

      As the error says it, you need to activate the AIF service group for the service you are trying to use.

      Take a look at the following link. It is a discussion of your problem with an answer on how to solve it.


      I hope this helps.


  14. Hi,

    I am creating outbound port with msmq adapter to send sales order details but message is not generated in queue. Please help me.

    Do you have any MSMQ Outbound port example that i can follow?

    1. Hi,

      This post helped me solve the problem you have. http://dynamics-ax-developer.blogspot.com/

      I hope this helps and let me know.

  15. Hi ,
    I want fetch data from XMl format in ax table.can u pls guide me?

  16. hi,
    I am getting following error when generating incremetal CIL.. previously i ws able to use AIF services without any issue.. Possible solutions like Full CIL generation, AOS restart have already been done.. i have also deleted all the generated objects which are created when created AIF service using wizard....please suggest any permanent solution for this
    Duplicate type with name 'Dynamics.Ax.Application.Dev_PostCode' in assembly 'Dynamics.Ax.Application, Version=6.0.947.0, Culture=neutral, PublicKeyToken=null'.

    1. Hi,

      Have you followed these steps by any chance? http://axwonders.blogspot.com/2013/04/solving-error-cil-generator-found.html

      There is a problem in AX 2012, and it has to do with the generated XppIl files for asseblies. Try it (if you haven't already so) and let me know.

      Also, is your kernel and application version the same?

  17. Hifnd,

    i want small help from you ?
    am working on some customization in Ax 2012,but i didn't get the result..
    do u know how we send sms to customer from Ax 2012 ?
    if u know the details please send me the complete process of the same...

    Thank u....

  18. Hi,

    I am conducting a one day workshop training program on "MSD AX 2012 - AIF Integration" for AX Technical Consultants with different experience levels. I am feeling very difficult to create the content for this particular workshop program. Would you please help me out in creating the syllabus.

    Principal Consultant : Training & Development
    Locus IT!!!

  19. Your article is good.

    I am develop a outbound service it's work fine and get xml of single records I want that generate a single xml with multiple records plz help me out


Thank you for your thoughts. Your comment will appear in my blog shortly after review.

Have a great day!