About Axd<Document> Classes

This topic describes the Axd<Document> classes that are part of the XML Document Framework in Application Integration Framework (AIF). The Axd<Document> classes contain implementation details that support the document service classes.

NoteNote

If you are using AIF to exchange data, you do not have to know how the Axd<Document> classes interact with the other AIF objects. However, if you are creating custom services, this information may be helpful when coding your own classes.


AIF exchanges data with external systems by sending and receiving XML documents. This XML is sent or received by the document services class which provides an external application object interface to Microsoft Dynamics AX. The Axd<Document> class contains the business logic for each electronic document.

In addition, the document classes encapsulate any business logic that applies across tables and ensure that the business rules that govern the life cycle of the document are followed. These classes represent data as business entities so that the calling application can exchange data with Microsoft Dynamics AX without any knowledge of the underlying tables.

The Axd<Document> classes are part of the XML Document Framework. This framework consists of the classes that implement the business logic for individual documents in Microsoft Dynamics AX. As a group, these classes encapsulate the business logic for individual documents.

The XML Document Framework contains these types of classes:

  • Document service classes

  • Axd <Document> classes (also known as an Axd class)

  • Ax <Table> classes

Within AIF, the terms Axd<Document> class, Axd class, and document are often used interchangeably.

The Axd<Document> classes have the following characteristics and functions:

  • Implement the AifServiceable interface.

  • Shield users from the complexity of the underlying table structures and associated business logic.

  • Elevate the error handling from the individual database tables or fields to the document level.

  • Provide methods for serializing to XML and for deserializing Axd<Document> class instances from XML. During serialization and deserialization, these classes can also perform value mapping and data filtering.

  • Generate an XML Schema Definition (XSD) schema that describes the equivalent XML document.

  • Access Ax<Table> classes. Axd<Document> classes call Ax<Table> classes and use them when serializing to XML and deserializing from XML to ensure that business logic within Microsoft Dynamics AX is always followed. Axd<Document> classes can invoke business logic internally, but the document classes that are supplied in the application typically do not invoke business logic.

Functions of Axd<Document> Classes

The Axd<Document> class is responsible for maintaining the internal data for the document and for creating XML from that data or populating itself with XML data. The responsibilities of the Axd<Document> class include the following:

  • Document structure – the document structure allows the Axd document classes to perform operations on an entire document such as:

    • Reading an entire document in one logical operation by reading all elements that are defined by the associated Axd document query and then serializing them into a single XML file. The read operation is invoked, for example, when the AIF processes a send action. This is because the document data must be read from the database before the document can be sent to another system.

    • Creating a new document in the database in one operation by saving each element of the document to the database. The create operation is invoked, for example, when AIF processes a receive action.

  • XML serialization and deserialization – the document structure makes it possible for an Axd document class to perform the following:

    • Generate an XSD schema that is a one-to-one representation of itself.

    • Serialize itself into Microsoft Dynamics AX-specific XML.

    • Deserialize itself from Microsoft Dynamics AX-specific XML.

  • Document life cycle – ensure that operations on the document do not violate the business rules that govern the document life cycle, such as ensuring that a change order is not accepted if the original order has already shipped.

  • Document properties – maintain document-level information through properties. Properties provide information that pertains to the specific instance of a document, such as document status (whether it is an original or a duplicate).

  • Cross-table dependencies – conform to business logic that applies to a document across tables.

  • Error handling – consolidate errors that occur in the Ax<Table> classes to provide the calling code with a consolidated list of all the errors in a document.

The following are additional characteristics of Axd<Document> classes:

  • Typically, Axd document classes in Microsoft Dynamics AX have descriptive names that are prefixed with Axd, such as, AxdPurchaseRequisition or AxdSalesOrder. The document classes reside in the AOT Classes node.

  • There is a one-to-one correspondence between an Axd<Document> class and the corresponding document. For example, the AxdSalesOrder document class corresponds to the sales order document.

    • For inbound documents, the Axd<Document> class typically corresponds to one or more forms in Microsoft Dynamics AX, with associated journals or worktables. For example, the AxdSalesOrder class corresponds to the SalesTable form.

    • For outbound documents, the Axd<Document> class represents the electronic equivalent of the corresponding report. For example, the AxdPurchaseRequisition class represents a document that is equivalent to the PurchPurchaseOrder report.

  • If an Axd<Document> class supports both inbound and outbound documents, it must read data from the same tables, Ax<Table> classes, that it writes to.

  • Axd <Document> classes provide access to all public properties that map to the fields of the underlying database tables of the corresponding Ax<Table> classes.

  • Axd <Document> classes provide access to the fields of the underlying internal Ax<Table> classes without renaming them. By using the original field names, you can ensure that the serialized XML representation through the Axd<Document> and the Ax<Table> classes is consistent with the data model. Using the original field names also helps when you debug and ensures that the serialized XML representation through the Axd<Document> and the Ax<Table> classes can be traced because the same fields are not renamed in the various elements.

  • Axd <Document> classes work with data in the application indirectly through Ax<Table> classes.

  • An Axd<Document> class has the following document-level properties. These properties are part of the document schema in addition to the properties that are exposed from the Ax<Table>classes as shown in the following table.

Property

Type

Description

docPurpose

XMLDocPurpose

Identifies whether the document is an original or a duplicate. Possible values are XMLDocPurpose::Original, XMLDocPurpose::Duplicate, or XMLDocPurpose::Proforma. These values are found in the XMLDocPurpose enum. Proforma designates a document that is not yet posted, such as an unposted invoice being sent with an international shipment for tax declarations.

senderId

senderId

Identifies the company from which the document originates. It is populated with the DataAreaId of the sender in all outbound documents.

The Axd<Document> class follows the standard security model in Microsoft Dynamics AX, including security keys and record-level security. Access to system tables, including kernel tables, is restricted.

The Axd<Document> classes inherit from the AxdBase class, which in turn implements the AifServiceable interface. This interface enables the derived Axd<Document> class to be serviced by AIF. A document class must implement the AIFServicable interface to be recognized as an Axd<Document> class. The relationship between derived classes and the AifServiceable interface is shown in the following illustration.

Derived Classes and the AifServicable Interface

Axd<Document> class hierarchy object model

The AifServiceable interface contains methods that must be implemented by any document class that will be exposed using AIF. The following table shows these methods.

Interface method

Description

AifDocumentName getName()

Returns the name of the document. This must match the root element name in the document's XML schema. Not localized.

LabelString getLabel()

Returns the friendly name of the document. Localized.

AifDocumentSchemaXML getSchema()

Returns the XML schema that represents the document.

AifActionInfoList getActionList()

Returns a list of actions that are implemented by the document. An action is implemented if it has a method that matches the signature type of a particular action.

Community Additions

Show: