AX 2012: Create AIF document service


The purpose of this document is to illustrate how we can develop AIF document service, what are the important methods available that can be overridden to do the customization and finally how we can consume/unit test the document service through an external .NET application.

Business requirement:

Ability to integrate Dynamics AX with external systems.


Application Integration Framework (AIF) has been configured to process inbound and outbound messages.


  • Create an AOT query. Prefix it with Axd to follow the naming convention for document service.
  • Run AIF document service wizard to generate/regenerate:
    • Document class (Axd class).
      • Represents whole business document.
      • Used to perform cross-table validations.
      • Serializes/deserializes the document to/from XML.
    • Document object class
      • Object interface to whole business document.
    • Data object classes
      • Object interface to underlying tables involved in the document.
    • AxBC classes, if chosen
      • Wrapper classes for underlying tables involved in the document.
      • Used to perform table-level validations.
        • For example, AxSalesLine.validateWrite method.
        • It then calls validateWrite method of SalesLine table.
      • Used by Axd class to create, read, update, delete data in tables.
    • Service class
      • Contains the service operations in the form of methods.
    • Service node
      • Exposes service operations to inbound/outbound ports
  • Change namespace property of service node (optional).
  • Generate incremental CIL.
  • Register the service
  • Create security privilege for each service operation (optional).
  • Create an enhanced inbound port
  • Choose an adapter
    • File system adapter
    • HTTP
    • ISABEL SEPA credit transfer
    • MSMQ
    • NetTcp
    • Windows Azure Service Bus
  • Choose service operations
  • Activate

Important methods:

  • Axd class
    • prepareForSave/prepareForSaveExtended method
      • Validation code goes here.
      • For example¬†checkSalesTable method in AxdSalesOrder class.
    • updateNow method
      • Business logic to be executed post insert/update of document.
      • For example, post receipt in II7.
    • expandSurrogateForeignKeys method
      • To automatically resolve surrogate foreign keys to natural keys.
    • getSurrogateForeignKeyValue method
      • To manually resolve surrogate foreign keys to natural keys.
  • AxBC class
    • initMandatoryFieldsExemptionList method
      • To make a¬†field optional which is mandatory at the table level.
    • initMandatoryFieldsMap method
      • To make a field mandatory which is optional at the table level.
    • set<Field> method
      • To set default value of a field in service.
      • This method calls parm method to set the default value.
      • For example, setLineNum method of AxSalesLine class.
      • It calls parmLineNum method of AxSalesLine class.

Consuming service:

  • Create console application in Visual Studio
  • Add service reference
  • Sometimes, setting some fields doesn’t work in C#. We use “<Field>Specified” parameters for them.
  • For example:
    • Course.Name = “Name”;
    • Course.NameSpecified = true;
    • Course.Description = “Desc”;
    • Course.DescriptionSpecified = true;