Document Service

AX 2012: Create AIF document service

Posted on Updated on

Purpose:

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.

Assumptions:

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

Development:

  • 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;

AX 2012: Trigger AIF Document Service Outbound Message in X++

Posted on Updated on

Purpose:

The purpose of this document is to illustrate how we can trigger the generation of AIF document service outbound message in X++.

Business requirement:

Ability to generate an AIF outbound xml message on demand.

Assumptions:

Outbound port is configured using file system adapter.

Development:

Please find the job below to trigger an AIF document service outbound message in X++. The job uses the standard CustCustomerService class to generate outbound xml for customer data. Likewise the code can be used for any other valid document service class.

// Developed on 18 Feb 2016 by Muhammad Anas Khan
// Blog: dynamicsaxinsight.wordpress.com
// LinkedIn: pk.linkedin.com/in/muhammadanaskhan
// Description: Trigger AIF document service outbound message
static void sendElectronically(
    XMLDocPurpose _xMLDocPurpose,
    AifSendMode   _aifSendMode = AifSendMode::Async)
{
    AxdSendContext    axdSendContext = AxdSendContext::construct();
    AifEntityKey      aifEntityKey = AifEntityKey::construct();
    AifConstraintList aifConstraintList = new AifConstraintList();
    AifConstraint     aifConstraint = new AifConstraint();
    CustTable         custTable;
    Map               keyData;
    
    custTable = CustTable::find("1101");
    
    keyData = SysDictTable::getKeyData(custTable);
    aifEntityKey.parmTableId(custTable.TableId);
    aifEntityKey.parmRecId(custTable.RecId);
    aifEntityKey.parmKeyDataMap(keyData);
    axdSendContext.parmXMLDocPurpose(_xMLDocPurpose);
    axdSendContext.parmSecurity(false);
    aifConstraint.parmType(AifConstraintType::NoConstraint);
    
    aifConstraintList.addConstraint(aifConstraint);
    AifSendService::submitDefault(
        classnum(CustCustomerService),  //Service class goes here
        aifEntityKey,
        aifConstraintList,
        _aifSendMode,
        axdSendContext.pack());
}

AX 2012: AIF Document Service Invalid Data Container Type

Posted on

Error:

Invalid data container type.

Resolution:

Compile forward AfStronglyTypedDataContainer class.