Download pdf - AIF Stuff - iali.co.ukhide\AX5\AIF\AIF Stuff.pdf · AIF Stuff Table of Contents AIF Stuff

$Page 1: AIF Stuff - iali.co.ukhide\AX5\AIF\AIF Stuff.pdf · AIF Stuff Table of Contents AIF Stuff$
AIF Stuff

Table of Contents AIF Stuff .............................................................................................................................................................................................. 1

Creating Custom Dynamics AX Services ............................................................................................................................................ 2

How to: Add a Service Operation to a Service .................................................................................................................................... 5

Refresh the Service in the AOT .................................................................................................................................................. 6

Refresh the Service in the Services Form .................................................................................................................................. 6

Document Class Service Operations ................................................................................................................................................... 6

Document Services Classes ................................................................................................................................................................ 8

AIF Class Naming Conventions ......................................................................................................................................................... 11

About Service Classes ...................................................................................................................................................................... 12

Document Data Object Class ................................................................................................................................................... 14

Data Object Classes ................................................................................................................................................................. 14

Data Object Methods ................................................................................................................................................................ 14

About Axd<Document> Classes ........................................................................................................................................................ 15

Functions of Axd<Document> Classes ................................................................................................................................ 16

About Ax<Table> Classes ................................................................................................................................................................. 18

Schemas ........................................................................................................................................................................................... 20

Inbound Read Message ............................................................................................................................................................ 21

Inbound Update Message ......................................................................................................................................................... 22

Document XML Generation ............................................................................................................................................................... 24

String ........................................................................................................................................................................................ 26

Integer ...................................................................................................................................................................................... 27

Int64 .......................................................................................................................................................................................... 27

Real .......................................................................................................................................................................................... 27

Date .......................................................................................................................................................................................... 27

DateTime .................................................................................................................................................................................. 27

Enum ........................................................................................................................................................................................ 27

GUID ......................................................................................................................................................................................... 27

Container .................................................................................................................................................................................. 27

Guidelines for Adding Code to Document Service Classes ............................................................................................................... 28

Duplicates ................................................................................................................................................................................. 28

References ............................................................................................................................................................................... 28

Transaction Veracity ................................................................................................................................................................. 29

Outbound Exchange Business Logic ........................................................................................................................................ 29

Data Validation ......................................................................................................................................................................... 30

References ............................................................................................................................................................................... 30

Cache Methods ........................................................................................................................................................................ 30

AIF Messages ................................................................................................................................................................................... 30

Message Header ............................................................................................................................................................................... 31

Action and Data Policies ........................................................................................................................................................... 32

<Action> Tag: Service Class .................................................................................................................................................... 33

<Action> Tag: Service Operation .............................................................................................................................................. 33

Message Body ................................................................................................................................................................................... 34

Tags in the <Body> of Inbound ................................................................................................................................................. 34

Tags in the <Body> of Outbound .............................................................................................................................................. 35

<EntityKeyList> Tag.................................................................................................................................................................. 36

<EntityKey> Tag ....................................................................................................................................................................... 36

<serviceExternalName> Tag .................................................................................................................................................... 37

<entityName> Tag .................................................................................................................................................................... 37

<QueryCriteria> Tag ................................................................................................................................................................. 37

<CriteriaElement> Tag .............................................................................................................................................................. 37

General XSDs ........................................................................................................................................................................... 37

Entity-Specific XSDs ................................................................................................................................................................. 38

Query Criteria Overview .................................................................................................................................................................... 38

<DataSourceName> Value Aligned with Service ...................................................................................................................... 39

<Operator> Values ................................................................................................................................................................... 39

Example: Fault in an Outbound Message.......................................................................................................................................... 40

Message XSDs .................................................................................................................................................................................. 41

CreatingCustomDynamicsAXServicesOverview In certain scenarios, X++ classes need to be exposed for consumption by external applications, for example, through WCF web services or through MSMQ. Custom services, which have been introduced with Microsoft Dynamics AX 2009, are intended exactly for that purpose. However, since hardly any assumptions can be made about the purpose or semantics of these custom services or about the structure of the parameter types used by the published service operations, creating a custom service involves a little more work that creating a document-centric service with AIF’s Create document service wizard from a Dynamics AX query. In order to implement a custom service, you need to:

o Write a service implementation class o Create a service interface o Implement data objects – if necessary

The following sections walk you through a simple example of how you can build a Dynamics AX service from an X++ class named MyDataObjectService. Once you have encapsulated the business logic you would like to expose, you can use AIF’s standard tools and infrastructure to publish the service through the (supported) transport of your choice. Writing a Service Implementation Class A service implementation class is an X++ class; service implementation classes need not implement any X++ interfaces or extend any X++ super classes. The class definition of a sample service implementation class MyDataObjectService may look like this: public class MyDataObjectService { } One of MyDataObjectService’s service operations may look as shown in the following code snippet: public MyDataObject CreateMyDataObject(str _s) {

MyDataObject mdo; // see below for a definition of MyDataObject ; mdo = new MyDataObject(); mdo.parmMyString(_s);

// do something with ‘mdo’, for instance persist it...

return mdo;

} The input and return parameters of service operations must be either of primitive X++ types, or they must be instances of X++ classes that implement the X++ interface AifXmlSerializable. Creating a Service Contract In order to create a new service contract, we need to create a new AOT node under the AOT Services node. Let’s name the service contract MyDataObjectService, just like the service implementation class. The newly created service contract has a few properties that need to be initialized before the service can be consumed by external clients:

o Service implementation class: MyDataObjectService o Security key: Each service should have its own security key with the same name as the service, for example,

MyDataObjectService; should have parent key Services in a functional area (for example, Accounts Receivable) o Namespace (optional): XML namespace that should be used in the WSDL can be specified o External name (optional): External name of the service

Finally, the service operations need to be added to the service contract; see for instance product documentation for additional details. Implementing Data Objects Service operations can automatically use primitive X++ types (such as int, str, etc.) as types for input and return parameters. X++ classes that are intended to be used as data objects – as input or return parameters for service operations – must implement the interface AifXmlSerializable. See the following snippet for an example: public class MyDataObject implements AifXmlSerializable {

str myString; // more fields...

#define.MyDataObjectNS ('http://schemas.contoso.com/samples/MyDataObject') #define.MyDataObjectRoot (‘MyDataObject’)

}

Note that arrays or any other X++ data structures are not primitive types, even if they only contain data of primitive types; thus, data objects must be defined for such constructs as well. This is necessary to define the custom serialization to and the deserialization from XML for that class. Note that the methods serialize() and deserialize() must be inverse functions, since they use the same XML schema definition. In other words, it must be possible to deserialize an XML document that was created by serializing a data object and vice versa. The code snippets below are examples for the implementation of these methods. For additional information about any of the implemented methods refer to the product documentation. The method serialize() defines the serialization of the data object to XML. The code for serializing the class MyDataObject (as defined above) to XML may look similar to this: AifXml serialize() {

str xml; XmlTextWriter xmlTextWriter; ;

#Aif

xmlTextWriter = XmlTextWriter::newXml();

// turn off indentation to reduce file size xmlTextWriter.formatting(XmlFormatting::None);

// initialize XML document xmlTextWriter.writeStartDocument();

// write root element xmlTextWriter.writeStartElement2(#MyDataObjectRoot, #MyDataObjectNS);

// write custom data xmlTextWriter.writeElementString('MyString', myString); // more fields...

// serialize XML document into XML string xmlTextWriter.writeEndDocument(); xml = xmlTextWriter.writeToString();

xmlTextWriter.close();

return xml; } The method deserialize() defines the deserialization of a data object from XML. The code for deserializing an instance of the class MyDataObject (as defined above) from XML may look like this: void deserialize(AifXml xml) {

XmlTextReader xmlReader; ;

xmlReader = XmlTextReader::newXml(xml);

// turn off Whitespace handling to avoid extra reads xmlReader.whitespaceHandling(XmlWhitespaceHandling::None);

xmlReader.moveToContent(); while ((xmlReader.nodeType() != XmlNodeType::Element) && !xmlReader.eof())

xmlReader.read();

xmlReader.readStartElement3(#MyDataObjectRoot, #MyDataObjectNS); if (!xmlReader.eof() && xmlReader.isStartElement()) {

myString = xmlReader.readElementString3('MyString', #MyDataObjectNS); // more fields...

}

xmlReader.readEndElement(); xmlReader.close();

}

In X++, parm methods are used to define properties on a class. In data objects, all fields that are used for serialization or deserialization must be accessible through parm methods. Moreover, they must be optional and thus have a default value. Example: public str parmMyString(str _myString = ‘’) {

if (!prmisdefault(_myString)) {

myString = _myString; } return myString;

} The method getRootName() returns the root name used for deriving names for service artifacts. An example for the implementation: public AifDocumentName getRootName() {

return #MyDataObjectRoot; }

The method getSchema() returns the XML schema definition (XSD) that is used for serializing and deserializing the data object. public AifXml getSchema() {

str schema = @'<?xml version="1.0"?> <xsd:schema xmlns="http://schemas.contoso.com/samples/MyDataObject" targetNamespace="http://schemas.contoso.com/samples/MyDataObject" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xsd:complexType name="MyDataObjectType"> <xsd:sequence> <xsd:element name="MyString" type="xsd:string" />  </xsd:sequence> </xsd:complexType> <xsd:element name="MyDataObject" type="MyDataObjectType"/> </xsd:schema>'

;

return schema; }

XML schemas are used for validation, for example, to avoid the processing of invalid request messages. As a best practice, you should always use a modeling tool or an XML/XSD editor for generating the XML schema definitions rather than hand-crafting them. Discovering Custom Services

Open the form Services (by navigating to Basic > Setup > Application Integration Framework > Services) and click Refresh. Once the form has refreshed its contents, the MyDataObjectService service displays along with the other services. It’s ready for use and can now be published for consumption by external service clients (see product documentation for details).

Howto:AddaServiceOperationtoaService

This topic describes how to add a custom service operation to a service in Application Integration Framework (AIF). This topic

shows you how to add a service operation to one of the existing document service classes. However, you follow the same method

to add a service operation to any class that's exposed as a service in Microsoft Dynamics AX. An example of a custom method on

one of the document service classes that are included with Microsoft Dynamics AX is the TrvExpenseService.Submit method.

Each document service class can contain one or more of the following six methods.

create delete find findKeys read update

These methods support document functionality that enables you to perform create, read, update, and delete operations on data in

Microsoft Dynamics AX. For more information, see Document Class Service Operations.

Guidelines for Service Operations

When you add a custom service operation to a service in Microsoft Dynamics AX, the service operation must follow these rules:

The method that is exposed as a service operation must be public.

If the service operation takes an object as a parameter or returns an object, that object class must implement the

AifXmlSerializable interface.

Parameters or return values that are not objects must be one of the primitive types that include the following: str, date,

utcdatetime, guid, int, int64, enum, real, or void.

The service operation name should not be a .NET Framework language keyword, otherwise an error is generated. This is

because a .NET Framework Web services proxy class is generated for your service.

Add the Method to the Document Service Class

When adding a service operation, the first step is to add the method to the service class. As an example, we'll add a method to the

CustCustomerService class. The new method adds two integers and returns the result.

1. Open the AOT, expand the Classes node and navigate to the CustCustomerService class. 2. Right-click the class, and then select New Method. 3. In the Code Editor, enter the following code.

public int addIntegers(int _int1, int _int2)

{

return _int1 + _int2;

}

1. Press F7 to compile and press CTRL+S to save your changes. Expose the Method as a Service Operation 2. Open the AOT, expand the Services node, and navigate to the CustCustomerService service. 3. Expand the service, right-click Operations, and then select Add Operation. 4. In the Add service operations form, select the addIntegers method in the grid and select Add. 5. Click OK. 6. Press CTRL+S to save your changes.

Refresh the Service

After you have added the method and exposed it as a service operation, you must refresh the service. This can be one in the AOT

or in the Services form. Refreshing the service in the AOT is faster because the Services form refreshes service operations for all

the services.

Refresh the Service in the AOT

1. Open the AOT, expand the Services node, and then navigate to the CustCustomerService service.

2. Right-click the service, select Add-Ins, and then select Register actions.

Refresh the Service in the Services Form

1. On the Setup pane in the Basic module, expand Application Integration Framework, and then click Services.

2. Click Refresh. If you click Service Operations, you should see the new CustCustomerService.addIntegers method.

Generate the Web Service

If you are exposing the service as a Web service, you must regenerate the Web services.

1. On the Setup pane in the Basic module, expand Application Integration Framework, and then click Services.

2. Click Generate. For more information, see "Configure services" in the Server and Database Administration Help.

DocumentClassServiceOperations

This topic describes the default service operations in the document service classes in Application Integration Framework (AIF). AIF

exchanges data with external systems by sending and receiving XML documents. Each document being exchanged is represented

by a document service class.

The document service classes included with Microsoft Dynamics AX have six service operations as shown in the following table.

Method Parameters Returns Description

create Document object AIFEntityKeyList Takes a document object, creates records in the database, and returns a list of the IDs for the new records.

delete AifEntityKeyList Nothing Takes one or more IDs and deletes the specified records from the database.

find AifQueryCriteria Document object

Takes criteria, queries the database for matching records, and returns them in a document object.

findKeys AifQueryCriteria AifEntityKeyList Takes criteria, queries the database for matching records, and returns a list of corresponding IDs for those records.

read AifEntityKeyList Document object

Takes one or more IDs, reads the records from the database, and returns the records.

update AifEntityKeyList and document object

Nothing Takes one or more IDS and the data that corresponds to those IDs and updates the database.

Note

Each document service class may implement only a subset of these methods.

When a message comes into AIF or is sent out of AIF, the service and the service operation are referenced in the message header

in Action tags as shown in the following code.

<Header>

<MessageId></MessageId>

<SourceEndpointUser></SourceEndpointUser>

<SourceEndpoint></SourceEndpoint>

<DestinationEndpoint></DestinationEndpoint>

<Action>http://schemas.microsoft.com/dynamics/

2008/01/services/CustomerService/read</Action>

<ConversationId></ConversationId>

</Header>

The document service class contains a method for each service operation. The service class is exposed as a service in the AOT

Services node and each method is exposed as a service operation.

Note

A service operation is sometimes referred to as an action or a method. This is because the service operation is referenced in the message as an action, is a method off of the document service class, and is exposed externally as a service operation.

Service Operation Parameters

Each service operation takes one or more of the following objects as a parameter:

Document object - The top-level data object that represents an entire XML document. This object implements the

AifDocument interface and contains the data required by the method. For example, when you call the

SalesSalesOrder.create service operation, you must pass the sales order data in a document object. When you call a

service operation through Web services, you must pass a populated document object to the method. When you use one of

the other AIF transports, AIF takes the data in the XML message, populates a document object, and then passes it to the

method behind the scenes.

AifEntityKeyList - An object that represents one or more key/value pairs that specify a single record. The key contains the

table field name of the ID field and the value contains the table field value. For example, when you send in a message to

read a customer, the key field contains AccountNum and the value contains a value such as 5407. AIF uses this

information to return the specified record from the CustTable table.

AifQueryCriteria - An object that represents a query. This query is used by the find and findKeys service operations to

select the range of data that is returned by the method.

Each service operation may also return one of these objects. Each of these parameters implements the AifXmlSerializable

interface. This interface provides methods to get the schema of the class (getSchema), to serialize (serialize) the object data, and

to deserialize (deserialize) the object data.

Example

To see how service operations work, consider the CustCustomerService class. The create method (which is exposed as the create

service operation) signature resembles this:

public AifEntityKeyList create(CustCustomer _custCustomer)

The method takes a CustCustomer parameter which is an object that contains the customer data. The return value is an

AifEntityKeyList object that contains the IDs for the customers that were created. For more information, see About Service Classes.

Custom Service Operations

You can add custom service operations to the document service classes that are included with Microsoft Dynamics AX. The

procedure is the same as adding a service operation to any service within Microsoft Dynamics AX. The service operation must

follow these rules:

The method that is exposed as a service operation must be public.

If the service operation takes an object as a parameter or returns an object, that object class must implement the

AifXmlSerializable interface.

Parameters or return values that are not objects must be one of the primitive types that include the following: str, date,

utcdatetime, guid, int, int64, enum, real, or void.

For more information, see How to: Add a Service Operation to a Service.

Returning Large Data Sets

Calling the find service operation could potentially return a large data set because it takes a query and returns all the matching

records. When retrieving large result sets, it may be more efficient to use the findKeys and read methods instead. You can still pass

the query to the findKeys method, however, it will return only the IDs of the matching records instead of the data for each matching

record. The client system can then loop through those IDs and call the read method to return the data for each individual record.

DocumentServicesClasses

This topic describes the document services that are part of Application Integration Framework (AIF) and how they are used. In AIF

a document is a representation of the data model in Microsoft Dynamics AX, meaning that a document reflects the data as it exists

in the application. For example, the sales order document contains a sales order header with the sales order data and the

corresponding sales order lines. This document structure reflects the existing records in the application.

In AIF, data is exchanged in XML format. The AIF classes are responsible for serializing the data to or from XML for use by the

transport layer. These classes include the document services classes, the Axd<Document> classes, and the Ax<Table> classes.

The source of data for each document is a query (the Axd document query). The query controls the content and structure of the

data in the document.

Service Classes

The document services classes include the service class itself and the related data object classes.

Service class - Exposes the AIF business logic to external callers through these service operations: create, delete, find,

findKeys, read, and update. The service classes provide the interface for reading, creating, updating, and deleting data in

Microsoft Dynamics AX. Each service class has a corresponding service node in the AOT under the Services node. The

service in the AOT exposes the service class methods as service operations. The service operations take one or more

data object classes as parameters.

Data object class - Represents a class that can be serialized to and deserialized from XML. The data object class

encapsulates the XML data and provides an object interface to the data. This enables developers to work with the data by

using objects and properties instead of XML. The data object class that contains the data is passed as a parameter in the

service operations.

To see the relationship between the document service classes, you can examine the example of a sales order. The sales order

service class is named SalesSalesOrderService and can be found in the AOT Classes node. This service exposes a create

method that can be called to create a new sales order. The create method has the following signature:

public AifEntityKeyList create(SalesSalesOrder _salesSalesOrder)

The _salesSalesOrder parameter in this method is a data object class. This class contains the sales order data that is used to

create the sales order in the database. For more information, see About Service Classes.

Axd Document Classes

The Axd<Document> classes present XML data as an electronic document. Each class represents a single document in Microsoft

Dynamics AX. Axd<Document> classes also aggregate data from a number of internal Ax<Table> classes to form the document

content. Axd<Document> classes perform the actual serialization and deserialization of the inbound and outbound XML

documents, respectively.

The term Axd<Document> class is a general reference to specific classes that implement actual document logic. For example,

AxdSalesOrder is an instance of an Axd<Document> class. Each document class inherits from the AxdBase base class as shown

in the following AxdSalesOrder Class.

class AxdSalesOrder extends AxdBase

{

}

By default all the methods of the AxdBase class are enabled when a document class is created. To disable a method, you must

override it and return an error. For example, the AxdPurchaseInvoice.read method is disabled as shown in the following code.

public XML read(AifEntityKey _entityKey,

AifSchemaInfo _schemaInfo,

AifEndpointActionPolicyInfo _actionPolicyInfo,

AifConstraintList _constraintList,

AifPropertyBag _aifPropertyBag)

{

throw error(strfmt("@SYS94880"));

}

For more information about document classes, see About Axd<Document> Classes.

Ax<Table> Classes

The Ax<Table> classes (previously known as AxBC classes) manage data, manage access to and from the tables, encapsulate the

business logic that is available through the corresponding form, set default field values, and provide an object interface to the

individual tables.

The Ax<Table> class inherits from the AxInternalBase Class and represents a single table in the AOT. The term Ax<Table> class is

a general reference to specific classes that implement actual table logic. In the following code example, AxSalesTable is an

instance of an Ax<Table> class. Each Ax<Table> class inherits from the AxdInternalBase class as seen in the AxSalesTable Class.

class AxSalesTable extends AxInternalBase

{

SalesTable salesTable;

SalesIdBlanket salesIdBlanket;

int custAccount_CustTableIdx;

int invoiceAccount_CustTableIdx;

int projTableIdx;

int salesParametersIdx;

int custParametersIdx;

int addressIdx;

int paymTermIdx;

int zipCodeIdx;

int contactPersonIdx;

int axAddressIdx;

str state;

str county;

}

The Axd<Document> classes always use the Ax<Table> classes to read from or write to the underlying tables. For example, the

AxdSalesOrder document class uses the AxSalesTable class to access the SalesTable table. For more information about table

classes, see About Ax<Table> Classes.

Axd Document Queries

An Axd<Document> query describes the structure of the XML document and controls the data that is retrieved from Microsoft

Dynamics AX. The document query is a standard query found in the AOT under the Queries node, and it functions as a data

source just as a query does for a form or report. Fields that are disabled in the query are not retrieved from the database because

the query is run when the data is being serialized or deserialized in the document class.

The queries for the documents that that are included with Microsoft Dynamics AX have the same name as the Axd<Document>

class with which they are associated. For example, the query for the AxdPurchaseRequisition document class is also named

AxdPurchaseRequisition. In an Axd<Document> class, the document query is returned from the AxdBase.getQuery method. The

getQuery base class method is called because it is not overridden in the derived document classes. This method defaults the query

name to the name of the document class as shown in the following code. If you create your own document classes, this method

can be overridden.

public QueryName getQueryName() { ; if (!queryName) { queryName = classId2Name(classidget(this)); } return queryName; }

Within each document class, the query is stored and accessed by using the AifQueryCriteria class. It can store the query as an

existing Microsoft Dynamics AX query or as a list of criteria elements. However, the class can contain only one type of query. If the

AifQueryCriteria class represents a named query, you cannot add query criteria to it. If the class contains multiple criteria elements,

criteria on the same field will be ORed whereas criteria on different fields will be ANDed.

Schemas

The document schema defines what data elements can participate in a data exchange and the rules for those elements. The

document schema structure is based on the query that is associated with the document. The schema for the document is

generated by iterating through the document query that defines the structure of the document. The schema uses the names of the

Ax<Table> classes and their properties to name the XML elements. The document data is mapped directly from the query to the

XML schema, but with the following exceptions:

Hidden fields, disabled fields, and data sources in the document query are excluded from the schema.

The name of the root element in the schema is derived from the Axd<Document> class name by removing the Axd prefix.

The document query can have only one root data source.

All properties that are associated with the Axd<Document> class are included in the schema. Document properties contain

document-level data that is stored in the document class but is not part of the document query. For example, the

documentPurpose (original or copy) and the senderId (the sending company within the application) properties are included

in the document schema.

The document query field list always controls which fields are included in the schema and are therefore serialized.

However, if the Ax<Table> class is present, only fields that have a corresponding parm<Field> method on the Ax<Table>

class are serialized. Calculated fields (display fields) are always serialized.

For more information about document XML schemas, see Document Schema Overview.

AIFClassNamingConventionsThe following table lists the naming conventions for the Application Integration Framework (AIF) classes. If you are creating your

own services, it is a best practice to follow these naming conventions.

Note

The document class artifact is the top-level data object. It is referred to as the document class, but is also a data object.

Artifact type Name description Name generation rules Example

Service class

Name of the AIF service class

<Prefix> + <Document Name> + "Service"

SalesSalesOrderService

Document class

Name of the X++ class for the root data object

<Prefix> + <Document Name> SalesSalesOrder

Data objects Name of the X++ class for the child data objects of the document class

<Root data object name> + "_" + <Query data source Name>

SalesSalesOrder_SalesTable, SalesSalesOrder_DocuRefHeader, SalesSalesOrder_DocuRefLine, SalesSalesOrder_InventDim, SalesSalesOrder_MarkupTransHeader, SalesSalesOrder_MarkupTransLine, SalesSalesOrder_SalesLine

AOT service node

Name of the AOT node for the service

<Prefix> + <Document Name> + "Service"

SalesSalesOrderService

Service external name

Name of the service published to WCF

<Document Name> + "Service" SalesOrderService

Document class name

Name of the Axd<Document> class

Same name as the query AxdSalesOrder

Table class names

Name of the Ax<Table> classes

"Ax" + query data source table name

AxSalesTable, AxInventDim, AxDocuRef, AxMarkupTrans, AxSalesLine

Query Name of the query "Axd" + user-defined name AxdSalesOrder

AboutServiceClasses

This topic describes the Application Integration Framework (AIF) document service classes. AIF exchanges data with external

systems by sending and receiving XML documents. The document services classes provide an external application object interface

to the Microsoft Dynamics AX business logic.

The document service 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. You can also use this framework to create your own custom

documents that can be sent through the AIF transport layer. 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

The document service classes are the top-level classes that provide the external interface to the business logic. These classes

include the service class itself and the related data object classes. The following Unified Modeling Language (UML) diagram shows

the relationship between all the AIF classes.

A UML diagram that shows the relationship between the AIF document service classes

Service Class

The service class is the top-level class that is exposed as a service through the AOT. These classes are found in the AOT Classes

node. The service classes are exposed as services in the AOT under the AOT Services node. The service class inherits from the

AifDocumentService class. The service methods delegate their operations to the AifDocumentService class. For example, the

SalesSalesOrderService.read method calls the AifDocumentService.readList method as shown in the following code.

public SalesSalesOrder read(AifEntityKeyList _entityKeyList)

{

SalesSalesOrder salesSalesOrder = new SalesSalesOrder();

this.readList(_entityKeyList, salesSalesOrder);

return salesSalesOrder;

}

The service class contains the methods that are called to update, create, read, and delete data. These methods are exposed as

service operations by the service. The service class methods supported by the service classes are shown in the following table.

Method Parameters Returns Description

create Document object AIFEntityKeyList Takes a document object, creates records in the database, and returns a list of the IDs for the new records.

delete AifEntityKeyList Nothing Takes one or more IDs and deletes the specified records from the database.

find AifQueryCriteriaObject Document object Takes criteria, queries the database for matching records, and returns them in a document object.

findKeys AifQueryCriteriaObject AifEntityKeyList Takes criteria, queries the database for matching records, and returns a list of corresponding IDs for those records.

read AifEntityKeyList Document object Takes one or more IDs, reads the records from the database, and returns the records.

update AifEntityKeyList and document object

Nothing Takes one or more IDS and the data that corresponds to those IDs and updates the database.

Note

Each service class implements the methods that are necessary for the business requirements of the class. Therefore, each service may implement only a subset of the available methods.

The parameters that each service class method takes are one of three types:

A document object such as SalesSalesOrder

An AifEntityKeyList object

An AifQueryCriteria Object

Each of these parameter types implements the AifXmlSerializable interface. If you create your own custom services or service class

methods, the parameters can be of any type as long as they are objects that implement the AifXmlSerializable interface or are one

of the primitive types that include: str, date, utcdatetime, guid, int, int64, enum, real, or void.

Data Object Classes

Data objects are closely related to service classes and provide an object interface for the XML data that comes in and out of AIF.

The data object classes represent the data hierarchy of the query, which is the basis of an AIF document. These classes are used

only to work with data, they contain no business logic. The data object classes are found in the AOT under the Classes node.

The following table illustrates how the hierarchy of the query and the query data sources is modeled in both the XML and the data

objects that represent that XML.

Object XML element Data object class

AxdCustomer query <Customer> CustCustomer

CustTable data source <CustTable> CustCustomer_CustTable

CustAddress data source <CustAddress> CustCustomer_CustAddress

Document Data Object Class

The document data object class is the top-level data object and represents an entire XML document. The following are features of

the document data object classes:

Implement the AifDocument class.

Encapsulate data being exchanged with AIF.

Passed as parameters to the update and create methods.

Return value of the service class find and read methods.

For example, CustCustomer is the document data object and depends on the CustCustomer_CustTable data object which in turn

depends on the CustCustomer_CustAddress data object as shown in the previous diagram.

Although the document data object class implements the AifDocument class, it is still considered a data object. This is because the

AifDocument class implements the AfStronglyTypedDataContainer class just as the data object classes do.

Data Object Classes

The data object classes provide an object model for the service data. Data object classes implement the

AfStronglyTypedDataContainer class which in turn implements the AifXmlSerializable interface.

There is a data object class for each data source in the query. For example, the customer data objects are the

CustCustomer_CustTable class and the CustCustomer_CustAddress class. A customer can have one or more addresses. The

CustCustomer_CustTable class depends on the CustCustomer_CustAddress class which models the relationship of this data in the

database.

Data Object Methods

Both the document data object and the data objects have three types of methods:

Exists methods - Verify that data exists for a particular field.

Parm methods - Returns the value for a particular field.

Create methods - Creates and returns a list of data objects. For example, the CustCustomer document data object has a

method called CreateCustTable which creates and returns an instance of the CustCustomer_CustTable data object. Each

of the CustCustomer_CustTable data objects contains the data for a single customer record.

There are two types of parm methods: simple and complex. A simple parm method returns the value of a field. For example, the

CustCustomer_CustTable.parmAccountNum method returns the customer account number.

A complex parm method returns a list of data objects. For example, the CustCustomer document data object has a method called

parmCustTable that returns a list of CustTable objects. This is useful when there are multiple records in the XML; for example, if

you had an XML document that contains two customers, the data for each customer would be inside <CustTable> tags and there

would be two CustTable data objects.

AboutAxd<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.

Note

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.

Axd<Document> Class Characteristics

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.

Additional Characteristics of Axd<Document>Classes

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.

Axd<Document> Class Interfaces

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.

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.

AboutAx<Table>Classes

This topic describes the Ax<Table> classes in Application Integration Framework (AIF). The Ax<Table> classes (sometimes

referred to as AxBC classes) provide an object API on top of the database tables. These classes manage data, manage access to

and from the tables, encapsulate the business logic that is available through the corresponding form, create default field values,

and provide an object interface to the individual tables. Along with the Axd<Document> classes, the Ax<Table> classes provide the

business logic implementation for the AIF document services.

Note

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

Each Ax<Table> class has a one-to-one relationship with a database table. This relationship is reflected in the naming convention

for Ax<Table> classes. Names are constructed by prefixing the table name with Ax. For example, the Ax<Table> class for the

SalesTable table is AxSalesTable.

The Axd<Document>classes always use the Ax<Table> classes to read or write to the underlying tables. For example, the

AxdSalesOrder document class uses the AxSalesTable class to access the SalesTable table. The Axd<Document> classes access

the Ax<Tables> through the AxdBaseRead and AxdBaseCreate classes, depending on whether the data is being retrieved or

written. These classes are responsible for reading data from tables or writing records to tables respectively.

Ax<Table> Class Characteristics

The primary purpose of an Ax<Table> class is to contain any business logic that is associated with the creation and modification of

records in the related table. The Ax<Table> classes are responsible for the following operations:

Defaulting data – generating default values for fields that are not explicitly set by the calling code.

Sequencing – setting fields in the correct order to prevent explicitly set values from being overwritten by the default

procedures.

Validation – maintaining referential integrity in the database and making sure that any field-level business rules or record-

level business rules are adhered to, such as number sequences and application business logic.

Value mapping – translating the value of specific fields according to predefined business rules. Value mapping enables

external systems to interpret the value of specific fields.

Error processing – consolidating error messages when applying operations across fields so that the calling code has a list

of all errors that occur during an exchange.

The Ax<Table> classes eliminate the need for the calling application to set database fields in a specific order and to replicate any

table-specific business logic.

Additional Characteristics of Ax<Table> Classes

The following are additional characteristics of Ax<Table> classes:

Typically named with the name of the table that they access prefixed with Ax, such as AxPurchTable or AxPurchLine. The

table classes reside in the AOT Classes node.

Manipulate table records directly.

Read from and write to the underlying tables, except where the business logic in Microsoft Dynamics AX will be violated by

external updates, such as the TaxTrans table.

Are self-contained, and their operations are independent of the calling context.

Are independent of the structure of the document in Microsoft Dynamics AX and can be called individually.

Implement the AxInternalBase class.

Note

The code calling an Ax<Table> class authorizes data access. The Ax<Table> class does not validate whether the user that is calling the class is allowed to retrieve data from the database or create or update data in the database. For example, in an Axd<Document> class that is invoked from the AIF, the document class that calls the Ax<Table> classes is invoked by a service acting on behalf of the requesting user. This service must perform the necessary authorization.

The term Ax<Table> class is a general reference to specific classes that implement actual table logic. For example, AxSalesTable

is an instance of an Ax<Table> class. The Ax<Table> class inherits from the AxInternalBase class and represents a single table in

the AOT, as shown in the following code.

class AxSalesTable extends AxInternalBase

{

SalesTable salesTable;

SalesIdBlanket salesIdBlanket;

int custAccount_CustTableIdx;

int invoiceAccount_CustTableIdx;

int projTableIdx;

int salesParametersIdx;

int custParametersIdx;

int addressIdx;

int paymTermIdx;

int zipCodeIdx;

int contactPersonIdx;

int axAddressIdx;

str state;

str county;

}

Default Field Values

The Ax<Table> classes set default field values that are not set by the calling code. If you must bypass default fields when you

insert a record with the Ax<Table> class, the code that is calling an Ax<Table> class must explicitly set the defaulting procedures to

false. Table fields are defaulted in the Ax<Table> class by overriding the setTableFields method. This code example is from the

AxSalesTable.setTableFields Method.

protected void setTableFields()

{

SalesTableLinks salesTableLinks;

;

super();

useMapPolicy = false;

this.setCashDisc();

this.setCommissionGroup();

this.setContactPersonId();

this.setCurrencyCode();

this.setCustAccount();

this.setCustGroup();

this.setDeliveryAddress();

this.setDeliveryCity();

this.setDeliveryCountryRegionId();

this.setDeliveryCounty();

this.setDeliveryName();

this.setDeliveryState();

this.setDeliveryStreet();

this.setDeliveryZipCode();

this.setDimension();

this.setDlvMode();

this.setDlvReason();

this.setDlvTerm();

this.setEmail();

// Code ommitted.

}

Schemas

This topic describes the schemas in Application Integration Framework (AIF) and how they are used to define the format of the data

that is exchanged. When a document is transferred through the AIF transport layer, it does so as a message that is formatted in

XML.

Each message contains both metadata and data. The metadata is the data that is not document-specific and includes the

envelope, the header, entity keys, and so on. The message metadata is used by AIF to determine which service and action to call

as well as which endpoint to use. The message data is specific to a particular document.

There are various schemas that define the format and content of messages in AIF as shown in the following table.

Schema Description

Message Define the format and content of the message metadata. This includes elements such as the envelope, the

schemas header, query criteria, entity key lists, and so on. The message schemas are included with Microsoft Dynamics AX. For more information, see Message XSDs.

Document schema

Defines the format and content of the business data in a message. This schema contains all the fields that can participate in a data exchange. Any message that comes into AIF must validate against the document schema.

Endpoint schema

Further restricts the fields that can participate in a data exchange for a particular endpoint. The endpoint schema is defined by the data policy that you set for each endpoint action.

Example

Inbound Read Message

To illustrate how the different schemas are used in AIF, we will consider the scenario in which a client reads a customer record,

modifies that record, and then sends it back to AIF to update the database. The client application must first create a read request

message which is sent into AIF via any one of the supported transport methods.

In the message header, the Action tags must specify the CustomerService service and the read service operation. For more

information, see AIF Messages and Example: Read Action. The Action tag is used by AIF to identify the service and the service

operation that should be called as a result of the message.

The message metadata such as the envelope and the header must conform to the Message.xsd schema that is included with

Microsoft Dynamics AX. The CustomerService.read service operation takes an _entityKeyList parameter, so this information must

also be in the inbound message and conform to the EntityKeyList.xsd schema that is included with Microsoft Dynamics AX and

shown in the following code.

<?xml version="1.0" encoding="utf-8"?>

<Envelope xmlns="http://schemas.microsoft.com/dynamics/

2008/01/documents/Message">

<Header>








</Header>

<Body>

<MessageParts xmlns="http://schemas.microsoft.com/dynamics/


<EntityKeyList xmlns="http://schemas.microsoft.com/dynamics/

2006/02/documents/EntityKeyList">

<EntityKey xmlns="http://schemas.microsoft.com/dynamics/

2006/02/documents/EntityKey">

<KeyData>

<KeyField>

<Field>AccountNum</Field>

<Value>4507</Value>

</KeyField>

</KeyData>

</EntityKey>

</EntityKeyList>

</MessageParts>

</Body>

</Envelope>

Within the EntityKeyList tags in the message, there can be one ore more EntityKey tags that contain the IDs of the records to be

read. The EntityKey tags must conform to the EntityKey.xsd that is included with Microsoft Dynamics AX. When AIF receives the

correctly formatted message, it will send back a message containing the customer data. For more information about the message

schemas included with Microsoft Dynamics AX, see Message XSDs.

Inbound Update Message

The client system takes the customer data, makes modifications and then creates a message to send back to AIF. This message

specifies the updates that will be made in the database. In the message header, the Action tags must specify the CustomerService

service and the update service operation. Again, the update message metadata must conform to the Message.xsd schema. The

CustomerService.update service operation takes two parameters:

_entityKeyList - A list of IDs for the customers that are to be updated.

_custCustomer - One or more customer records to be updated.

The inbound update message will contain both the entity key list and the updated customer data. Just as in the read message,

message metadata and the data within the EntityKeyList tags must conform to the Message.xsd schema.

The data for each customer record and each customer address record to be updated is enclosed in Customer tags. The message

content in between these tags must conform to the document schema. The document schema defines the format for each specific

document. In this case, the document-specific XML must conform to the customer document schema. For more information, see

Document Schema Overview.

The following XML is an example of an inbound update message to update a customer and an address.

<?xml version="1.0" encoding="utf-8" ?>



<Header>






2008/01/services/CustomerService/update</Action>


</Header>

<Body>



<EntityKeyList xmlns="http://schemas.microsoft.com/

dynamics/2006/02/documents/EntityKeyList">

<EntityKey xmlns="http://schemas.microsoft.com/

dynamics/2006/02/documents/EntityKey">

<KeyData>

<KeyField>


<Value>4507</Value>

</KeyField>

</KeyData>

</EntityKey>

</EntityKeyList>

<Customer xmlns="http://schemas.microsoft.com/dynamics/

2008/01/documents/Customer">

<DocPurpose>Original</DocPurpose>

<SenderId>DAT</SenderId>

<CustTable class="entity" action="update">

<_DocumentHash>98bae208a7c43705aec9bcbb49687d2a

</_DocumentHash>

<AccountNum>4507</AccountNum>

<AccountStatement>Always</AccountStatement>

<Address>7212 9th Street Fargo,

ND 58102 US</Address>

<Blocked>No</Blocked>

<CashDisc>5D2%</CashDisc>

<City>Fargo</City>

<CountryRegionId>US</CountryRegionId>

<County>Cass</County>

<Currency>USD</Currency>

<CustGroup>30</CustGroup>

<ForecastDMPInclude>No</ForecastDMPInclude>

<GiroType>None</GiroType>

<GiroTypeCollectionletter>None

</GiroTypeCollectionletter>

<GiroTypeFreeTextInvoice>None

</GiroTypeFreeTextInvoice>

<GiroTypeInterestNote>None</GiroTypeInterestNote>

<GiroTypeProjInvoice>None</GiroTypeProjInvoice>

<InclTax>No</InclTax>

<InterCompanyAllowIndirectCreation>No

</InterCompanyAllowIndirectCreation>

<InterCompanyAutoCreateOrders>No

</InterCompanyAutoCreateOrders>

<InterCompanyDirectDelivery>No

</InterCompanyDirectDelivery>

<InvoiceAddress>InvoiceAccount</InvoiceAddress>

<LanguageId>en-us</LanguageId>

<MandatoryCreditLimit>No</MandatoryCreditLimit>

<Name>Northwind Traders</Name>

<NameAlias>NW Traders</NameAlias>

<OneTimeCustomer>No</OneTimeCustomer>

<PartyId>1318</PartyId>

<PartyType>Organization</PartyType>

<PaymTermId>D30</PaymTermId>

<RecId>5637144604</RecId>

<RecVersion>1280385480</RecVersion>

<RFIDCaseTagging>No</RFIDCaseTagging>

<RFIDItemTagging>No</RFIDItemTagging>

<RFIDPalletTagging>No</RFIDPalletTagging>

<ShipCarrierBlindShipment>No

</ShipCarrierBlindShipment>

<ShipCarrierFuelSurcharge>No

</ShipCarrierFuelSurcharge>

<State>ND</State>

<Street>7212 9th Street</Street>

<WebSalesOrderDisplay>WebEntered

</WebSalesOrderDisplay>

<ZipCode>58102</ZipCode>

<CustAddress class="entity" action="update">

<Address>111 5th Street Baltimore,

MD 21210 US</Address>

<AddrRecId>5637144604</AddrRecId>

<AddrTableId>77</AddrTableId>

<City>Baltimore</City>


<County>Baltimore</County>

<DlvMode>U11A</DlvMode>

<DlvTerm>TERMNA3RD</DlvTerm>

<Name>Jane Smith</Name>



<ShipCarrierAccount>234-4567

</ShipCarrierAccount>

<ShipCarrierAccountCode>UPS

</ShipCarrierAccountCode>



<ShipCarrierID>U11A</ShipCarrierID>

<ShipCarrierResidential>No

</ShipCarrierResidential>

<State>MD</State>


<TimeZone>GMTMINUS0800PACIFICTIME

</TimeZone>

<type>ShipCarrierThirdPartyShipping</type>


</CustAddress>

</CustTable>

</Customer>

</MessageParts>

</Body>

</Envelope>

DocumentXMLGeneration

This document describes how Application Integration Framework (AIF) serializes data into XML. In Microsoft Dynamics AX, data is

exchanged using documents, and each document is represented by a document service class. When a document is exchanged,

the XML data is contained in an envelope with a header that includes the message delivery information. The actual data is

contained in the <Body> tags of the message.

When a document is serialized into XML, a table element is created for each table in the query. The table is denoted by the

class="entity" attribute and value. Each table element contains a list of fields that is derived from all the properties of the

corresponding internal Ax<Table> class for which a parm<Field> get/set method exists. Within each table element is a series of

child table elements that represent the child data sources as defined in the query.

When the customer document is serialized into XML, it resembles the following XML which is the result of calling the read method

on the CustCustomerService document service class. Blank fields in the table are not returned.

<?xml version="1.0" encoding="utf-8" ?>



<Header>

<MessageId>{3B7C23AB-B0EF-4C35-8DC6-481574080F62}</MessageId>

<SourceEndpoint>Default</SourceEndpoint>

<DestinationEndpoint>Default</DestinationEndpoint>



<RequestMessageId>{C8111B69-9786-4BB4-9A03-

D0BE847F4C3C}</RequestMessageId>

</Header>

<Body>



<Customer xmlns="http://schemas.microsoft.com/dynamics/

2008/01/documents/Customer">

<DocPurpose>Original</DocPurpose>

<SenderId>DAT</SenderId>

<CustTable class="entity">

<_DocumentHash>98bae208a7c43705aec9bcbb49687d2a

</_DocumentHash>

<AccountNum>4507</AccountNum>

<AccountStatement>Always</AccountStatement>

<Address>7212 9th Street Fargo,

ND 58102 US</Address>

<Blocked>No</Blocked>

<Currency>USD</Currency>

<CustGroup>10</CustGroup>

<State>ND</State>


<WebSalesOrderDisplay>WebEntered

</WebSalesOrderDisplay>


<CustAddress class="entity">

<Address>111 5th Street Baltimore,

MD 21210 US</Address>

<AddrRecId>5637144604</AddrRecId>

<AddrTableId>77</AddrTableId>

<City>Baltimore</City>


<County>Baltimore</County>

<DlvMode>U11A</DlvMode>

<DlvTerm>TERMNA3RD</DlvTerm>

<Name>Jane Smith</Name>



<ShipCarrierAccount>234-456

</ShipCarrierAccount>

<ShipCarrierAccountCode>UPS

</ShipCarrierAccountCode>



<ShipCarrierID>U11A</ShipCarrierID>

<ShipCarrierResidential>No

</ShipCarrierResidential>

<State>MD</State>


<type>ShipCarrierThirdPartyShipping</type>


</CustAddress>

</CustTable>

</Customer>

</MessageParts>

</Body>

</Envelope>

Serialization Strategy

The serialization from Microsoft Dynamics AX to XML is as follows:

The parm<Field> methods on the Axd<Document> class are serialized to add the sending company and the document

purpose (original or copy) properties. These properties are stored at the document level and are not returned from the

query.

Empty data is not serialized so table fields that have no values are excluded from the XML.

When the Axd<Document> class serializes data (generates XML from the database), the Ax<Table> classes are used to

read data. If there are no Ax<Table> classes present, data is read directly from the tables.

When the Axd<Document> class deserializes XML (writes the data to the database), Ax<Table> classes are used to

validate data, ensure referential integrity of data, set default fields, and ensure the business logic compliance of the

inbound data.

The field list from the Axd<Document> query controls the fields that are included in the serialized XML. However, if the

Ax<Table>class is present, only fields that have a corresponding parm<Field> method on the Ax<Table> class are

serialized. Calculated fields (display fields) are always serialized.

Data Serialization

When a document class serializes data into XML, the field data types are dependent on the primitive data type of the fields in

Microsoft Dynamics AX.

String

The String field is serialized unchanged except for characters that are used as markup delimiters. These are converted to the

corresponding XML entities as shown in the following table.

Source character Output entity

< <

> >

& &

' '

" "

Integer

The Integer field value is converted to a string and serialized. If the field is based on an extended data type that derives from

timeOfDay, createdTime, or modifiedTime, the field represents a time value and is serialized using the rules described for

DateTime.

Int64

The Int64 field value is converted to a string and serialized.

Real

The Real field value is converted to a string and serialized based on the following rules:

Minimum length of 1 Decimal separator is a period No thousands separator Number of decimals defaults to 2

Date

The Date field value is converted to a string and serialized based on the following rules:

Format is YYYY-MM-DD Day always contains 2 digits Month always contains 2 digits Year, month, and day are separated by a hyphen

DateTime

The DateTime field value is converted to a string and serialized based on the following rules: Format is HH:MM:SS Hours, minutes, and seconds are separated by a colon Time is represented by 24 hours

Enum

The Enum field values are converted to a string that contains the Name property of the corresponding enum value. For example, if

the query returns a field based on the NoYes enum and the value of the field is "1," then the resulting XML element will contain

"Yes."

<TaxJournalTrans class="entity">

<EUROTriangulation>Yes</EUROTriangulation>

</TaxJournalTrans>

GUID

The GUID field value is converted to a string and serialized.

Container

When a container is serialized to XML, the field values are serialized based on their data types as described earlier. Container

values are not serialized if they are one of the following types:

Record

Class

UserType

AnyType

Rstring and VarString

The Rstring and VarString field values are serialized unchanged except for characters that are used as markup delimiters. These

are converted to the corresponding XML entities, as shown in the following table.

Source character Output entity

< <

> >

& &

' '

" "

BLOB

A BLOB field value is serialized as a stream of Base64 encoded binary data.

GuidelinesforAddingCodetoDocumentServiceClasses

This topic provides business logic concepts to keep in mind when coding the document classes for Application Integration

Framework (AIF) data exchange. You can use the AIF Document Service Wizard to generate the document service class,

Axd<Document> class and its associated Ax<Table> classes. Then you can add business logic code. For more information, see

Document Services Classes.

Axd<Document>Classes

Duplicates

The AxdBase class does not prevent duplicate documents from being received and created in the database. Duplicates may or

may not be acceptable, depending on the nature of the specific document and its business rules.

If you determine that duplicates pose a problem for a particular Axd<Document> class, then that class must include code to

prevent the creation of duplicates. For example, duplicate sales orders are accepted in the sales journal table only, which

reduces the impact of an incorrect or duplicate sales order document. You can add validation by overriding the document class

prepareForSave method and calling any custom methods to perform data validation.

References

When you enable the outbound methods Axd<Document>.read, Axd<Document>.readList,

Axd<Document>.findList, and Axd<Document>.findEntityKeyList for an Axd<Document> class and the

document class query includes the DocuRef table as a data source, ensure that only external notes are sent from the

application and that only documents of the type Note are sent. References of other types might contain viruses, worms, Trojan

horses, or other malicious code that can harm the system.

Transaction Veracity

Any Axd<Document> classes that expose methods, such as create and createList, and accept inbound documents must

include code to prevent the creation of malicious transactions or other data in the database. For example, we recommend that

you implement business logic code to prevent the creation of orders for large quantities of costly items by customers with limited

credit.

Many inbound documents are usually created as records in a journal so that no transactions are committed to the database until

a user has manually posted the journal. In these scenarios, the application data is not as vulnerable. For this reason, you should

consider designing custom Axd<Document> classes so that transactions are not posted automatically.

Some inbound documents can be inserted directly into a work table, which can pose an exploitable threat to the system that

must be mitigated. For example, an inbound exchange rates document that contains incorrect exchange rates can be accepted

directly into the exchange rates table. It is important to ensure that the endpoints are defined correctly, secure, and trusted.

Outbound Exchange Business Logic

In an outbound exchange, the initQueryFromEntityKey method in the document class is called. This method can be used

to implement any business logic for the document that is being retrieved from the database before it is sent. For example, the

following code in the AxdPurchaseRequisition document class checks to ensure that the purchase order being requested

has a status of Open order. If the purchase requisition does not have that status, an error is returned and the document is not

sent.

public void initQueryFromEntityKey(AifEntityKey _aifEntityKey = null, boolean _validateEntityKey = false) { VendPurchOrderJour vendPurchOrderJour; ; if(_aifEntityKey) { if (_aifEntityKey.parmTableId() == tablenum(VendPurchOrderJour)) { vendPurchOrderJour = SysDictTable::findFromKeyData(_aifEntityKey.parmTableId(), _aifEntityKey.parmKeyDataMap().pack()); if (vendPurchOrderJour) { if (PurchTable::find( vendPurchOrderJour.PurchId).PurchStatus != PurchStatus::Backorder) { throw error(strfmt("@SYS89370",vendPurchOrderJour.PurchId)); } } } } super(_aifEntityKey, _validateEntityKey); this.disableDataSources();

} Ax <Table> Classes Data Validation

By default, Ax<Table> classes do not validate data. Data validation is enabled by calling the Ax<Table>.validateInput

method with the parameter set to true.

References

We strongly recommend that you allow only references of the type Note. References of any other types might contain malicious

code that can harm the system. The calling code must validate document types (Note, File, Image, Document, and

Worksheet) that are permitted to be saved by the AxDocuRef class.

Cache Methods

When generating an Ax<Table> class, there are two cache methods that will compile with errors.

cacheObject method

cacheRecordRecord method

These two methods are templates that can be used to cache a record or an object in relation to the defaulting logic in the

Ax<Table> class for inbound services.

To cache <MyObject> in the created Ax<Table> class, you can use the cacheObject method as a template. Use search and

replace to search for cacheObject and replace it with <MyObject>. After you have updated the method, you should be able

to compile without errors. See the axSalesTable method in AxSalesLine class for an example of a cached object

method. For an example of how a cached object method is used in relation to defaulting logic in an Ax<Table> class, see the

setCustAccount method in the AxSalesLine class.

To cache a record of the type <MyTable> in the created Ax<Table> class, you can use the cacheRecordRecord method as

template. Use search and replace to search for cacheRecord and replace it with <MyTable>. After you have updated the

method, you should be able to compile without errors. For an example of a cached record method, see the

inventTableRecord method in the AxSalesLine class. For an example of how a cached record method is used in

relation to defaulting logic in an Ax<Table> class, see the setSalesUnit method in the AxSalesLine class.

AIFMessagesThis topic provides an overview of messages in Application Integration Framework (AIF). When AIF receives and processes an

inbound message, it generates an outbound message in response. AIF messages are in the form of XML.

All AIF messages have a <Header> tag section and a <Body> tag section. The XML tag names in the <Header> are mostly

the same across all messages.

The tag names in the <Body> section vary between different inbound messages, and vary between different outbound

messages. The tags that are required within the <Body> section depend on which service option is specified in the <Action>

tag within the <Header> section.

In This Section

The topics covered in this section discuss the <Header> tag schema and the <Body> tag schema for AIF messages of different

types. The formal XSD schemas are discussed. Several topics focus on a pair of messages. They contain an inbound message for

a different service operation, and they show the corresponding outbound message.

MessageHeader

This topic describes the <Header> tag section of inbound and outbound messages in Application Integration Framework (AIF).

XSD Schema Validation

In the message XML, the <Header> tag is nested one level under the <Envelope> tag. The <Header> section in inbound

and outbound messages must validate against the same XSD schema. The XSD is stored in the database in the

AifSchemaStore table. The XSD schema for the <Header> section is duplicated in the file Message.xsd that is included

with Microsoft Dynamics AX under the installation directory. Message.xsd might be located in the following path:

C:\Program Files\

Microsoft Dynamics AX\ <version> \Application\Share\Include\

For more information about this XSD schema, see Message XSDs.

Table of Contained Tags

The following table lists all the tags that can appear in the <Header> tag section. All tags are optional unless they are

described as required in the table. The tags must appear in the same sequence they are listed in the table.

Tag name Inbound description Outbound description

<MessageId> Uniquely identifies each message. The value is a GUID. The value is not case sensitive. As an option, the value can be bounded by braces (the two characters {}).

The value is replicated in the <RequestMessageId> tag of the corresponding outbound message.

By default, the inbound message is rejected if the system has seen this same <MessageId> value before. However, duplicate values are accepted if the EnableIdempotence property is set to Yes on the service operation. These are located under the Services node in the Application Object Tree (AOT).

The system generates a new unique GUID value for each outbound message.

<SourceEndpointUser> The user on whose authority the inbound request is being made. The format is TheDomain\TheUser. The default value is the Windows domain user who submitted the inbound message. For an inbound channel that is based on the FileSystemAdaptor, the default value can be the owner of the *.xml file that contains the message.

In some cases the default value is determined to be a general account to handle all messages from an external company.

The inbound value is repeated in the outbound message.

<SourceEndpoint> Identifies the organization that sent the inbound message to your Microsoft Dynamics AX installation. For example, this can be another company or a division within another company. The value must already have been entered into your system through the Endpoints form. In the installation that sends the inbound message, the value in this tag must be present in the Endpoints form of AIF.

If a value is specified for <SourceEndpoint>, then a value must also be specified for <DestinationEndpoint>, although the reverse is not true.

If an explicit value was given for the <DestinationEndpoint> in the inbound message, that value is reused for the <SourceEndpoint> in the corresponding outbound message.

<DestinationEndpoint> Identifies the organization to which the inbound message is sent. In the Microsoft Dynamics AX installation that sends the inbound message to another installation, the value in this tag must be present in the Local endpoints form.

The organization that sent the corresponding inbound message.

<Action> Required. A URL string that contains information that uniquely identifies the service operation to the system.

Required. The value is identical to the inbound value.

<ConversationId> A string value that several inbound messages have in common to force AIF to process only one message in the set at a time. The messages in the conversation are processed sequentially even when the channel is configured for parallel processing. Each message in the set is processed in the same order it was received. The maximum length of the string is 256 characters.

If no value is specified, a setting on the channel determines whether the messages are processed sequentially or in parallel.

The same value as was in the corresponding inbound message.

<RequestMessageId> Does not apply to inbound messages. AIF puts the <MessageId> value from the inbound message into this tag. This enables you to determine which outbound message corresponds to your inbound message.

The <SourceEndpoint> Tag

For an inbound message that specifies an explicit <SourceEndpoint> value, the value must be one that is listed in the

Endpoints form. To reach this form, use the Content Pane to locate Basic, Basic Area, Setup, Application Integration Framework, Endpoints, and then click Endpoints.

Action and Data Policies

In order for an inbound message to be processed, the Endpoint value must be configured to have action and data policies. The

Endpoints form provides buttons to begin to configure those policies.

The endpoint must be configured for the service that is specified in the <Action> tag. The endpoint must also be configured to

have permissions on all the data fields the message processing will involve.

The <Action> Tag

The following is an example <Action> tag and value (with line breaks added to improve the display):

<Action>http://schemas.microsoft.com/dynamics/2008/01/

services/CustomeService/Read</Action>

The example is for the CustCustomerService class. More directly, this example is for the service that has the same name

of CustCustomerService (the names do not have to match).

The example value comes from combining three pieces of information. These pieces can be found in the AOT. The details are

described in the following table.

Portion of the <Action> value Location in AOT

http://schemas.microsoft.com/ dynamics/2008/01/services/

Under the Services node, on the CustCustomerService node, the Namespace property.

CustomerService Under the Services node, on the CustCustomerService node, the ExternalName property.

Read Under the Services node, under the CustCustomerService node, under the Operations node, on the Read node, the Name property. Another property is the name of the Method on the service class. Usually the Name and Method properties have exactly the same value.

The items specified in the <Action> tag determine the XSD schemas that the <Body> tag contents must comply with.

<Action> Tag: Service Class

The form AIF Services lists all the valid services that you can select from. The form has a column named ExternalName, and

that is the value that you must use in the <Action> tag. Every item listed in this form is also listed in the AOT under the

Services node.

The AIF Services form can be reached by using the Content Pane to locate Basic, Basic Area, Setup, Application Integration Framework, Services.

<Action> Tag: Service Operation

In AIF terminology the method is called the service operation. The following table lists the service operations that are available.

The names are not case sensitive.

Service operation name Description

Create Inserts new records into the database.

Delete Deletes records from the database.

Find Reads complete data from records that match the specified fields and values.

FindKeys Reads the key values from records that match the specified fields and values.

Read Reads complete data from records that match the specified key values. Read is a subset of the Find functionality, with slightly less verbose syntax.

Update Modifies data in existing records, which are selected by the specified key values.

Each type of <Action> message can affect zero, one, or many records.

For more information about service operations, see Document Class Service Operations.

The <ConversationId> Tag

A conversation is a group of messages. The value for the <ConversationId> tag is only one criteria that is used to uniquely

identify each conversation. For an inbound message, the AIF system combines the conversation ID with endpoint and the

channel. These three values combined together help ensure that no two legal entities might have their two conversations mixed

together by AIF.

MessageBody

This topic describes the <Body> tag section of inbound and outbound messages in Application Integration Framework (AIF). The

<Body> tag must follow the closing </Header> tag.

The <MessageParts> Tag

The first tag nested under <Body> must be the <MessageParts> tag. There is no need to specify the xmlns attribute on

the <MessageParts> tag because the correct value is already specified on the outer <Envelope> tag.

Tags Required for <Action> Values

The <Action> tag is nested under the <Header> tag. The values in the <Action> tag determine the XSD schema

validations that are applied to the contents of the <Body> tag.

For more information about actions, see Document Class Service Operations.

Tags in the <Body> of Inbound

For inbound messages, the following table shows the XML tags that must be in the <Body> tag section.

The outermost tag in each table cell occurs immediately after the <MessageParts> tag, and is nested directly under the

<MessageParts> tag. For instance, in an inbound Find message, the nesting relationship between the <MessageParts>

tag and the tags in the following table is:

<Body>

<MessageParts>

<QueryCriteria>

<CriteriaElement>

...

</CriteriaElement>

</QueryCriteria>

</MessageParts>

</Body>

Here is the table.

Service operation in <Action> Tags in the inbound <Body>

Create <serviceExternalName>

<entityName> Examples could be as follows:

<Customer>

<CustTable>

Delete <EntityKeyList>

<EntityKey>

Find <QueryCriteria>

<CriteriaElement>

FindKeys <QueryCriteria>

<CriteriaElement>

Read Same as Delete.

Update The following tags must come first: <EntityKeyList>

<EntityKey>

The following tags must come next:

<serviceExternalName>

<entityName>

The tags <EntityKeyList> and <serviceExternalName> are at the same level of nesting under <MessageParts>. Both tags are nested one level deeper than <MessageParts>, which is their parent tag.

The <EntityKey> tag sequence must align with the <entityName> tag sequence.

Tags in the <Body> of Outbound

For outbound messages, the following table shows the XML tags that are in the <Body> tag section.

Service operation in <Action> Tags in the outbound <Body>

Create <EntityKeyList>

<EntityKey>

Delete The <MessageParts> tag section is empty.

Find <serviceExternalName>

<entityName>

FindKeys <EntityKeyList>

<EntityKey>

Read Same as Find.

Update Same as Delete.

Details About Each Tag in the <Body> Section

The following sections discuss the tags in more detail.

<EntityKeyList> Tag

The <EntityKeyList> tag section contains one or more <EntityKey> tags. The following is the correct syntax for the

<EntityKeyList> tag (with a line break added to improve this display).

<EntityKeyList xmlns = "http://schemas/microsoft.com/

dynamics/2008/01/documents/Message">

<EntityKey> Tag

Each record in a table is uniquely identified by its value in the key field. In some tables the key is a set of two or more fields. The

<EntityKey> tag section specifies the name and value for each key field. Each <EntityKey> section identifies at most one

record.

The service class specified in the <Action> tag determines the table (or data source) that contains the records targeted by the

<EntityKey>.

<EntityKey> Example

The following XML code is an example of the <EntityKey> tag section. It identifies therecord that has a value of 4507 in its

AccountNum field. Not shown is XML code elsewhere in the message that relates this <EntityKey> to the CustTable

table.

<EntityKey xmlns = "http://schemas.microsoft.com/

dynamics/2006/02/documents/EntityKey">

<KeyData>

<KeyField>


<Value>4507</Value>

</KeyField>

</KeyData>

</EntityKey>

<serviceExternalName> Tag

This tag is named for the document service that is specified in the <Action> tag.

<entityName> Tag

This tag is the name of the table (or data source) that the inbound message operates against. Nested under this tag are tags for

each field in the table (or a subset of those field tags).

Also, nested under this tag could be another <entityName> tag for a child table. This can occur for create and update

<Action> operations. For example, under the <CustTable> tag there can be a <CustAddress> tag.

<QueryCriteria> Tag

The <QueryCriteria> tag section contains one or more <CriteriaElement> tags. The <QueryCriteria> tag offers

more flexibility than does the <EntityKeyList> tag. Unlike the <EntityKeyList> tag, the <QueryCriteria> tag

never occurs in an outbound message.

For more information, see Query Criteria Overview.

<CriteriaElement> Tag

For matching records, the <CriteriaElement> tag section can specify field-value pairs that are not limited to key fields.

The <CriteriaElement> tag also offers several operators beyond the equals operator.

XSD Validations

The XSD schemas that are used to validate all parts of each message are stored in the database.

For more information about XSD schema, see the following topics:

Document Schema Overview

How to: Generate a Document Schema

Message XSDs

General XSDs

All schemas are stored in the database in the AifSchemaStore table. A few XSD schemas are reused in several types of

inbound or outbound messages. The common schemas are duplicated in files that are included with each Microsoft Dynamics AX

AOS installation. The files might be in a directory path that resembles the following:

C:\Program Files\Microsoft Dynamics AX\ <version> \Application\

Share\Include\

The general schema files are as follows:

EntityKey.xsd

EntityKeyList.xsd

Message.xsd

QueryCriteria.xsd

Entity-Specific XSDs

The XSDs for entity external name tags, and for entity name tags, are stored in the database table named AifSchemaStore.

QueryCriteriaOverview

This topic describes the <QueryCriteria> tag in inbound messages for Application Integration Framework (AIF). The

<QueryCriteria> tag occurs in the <Body> tag section of an inbound message. The <QueryCriteria> tag never

occurs in outbound messages. For more information, see Message Body.

The purpose of the <QueryCriteria> tag is to provide a flexible way to control which records are returned from an inbound

message. The <QueryCriteria> tag is valid only in messages that have Find or FindKeys specified in their <Action>

tag. The <QueryCriteria> section is more flexible than the <EntityKeyList> section.

Example <QueryCriteria> Section

The following XML code example is taken from an inbound message. The message has an <Action> tag (not shown) which

contains the CustomerService service, and the FindKeys service operation. The code shows a <QueryCriteria>

section that contains two <CriteriaElement> tags.

The system uses Boolean OR logic to connect the all the <CriteriaElement> tags. This means that the record information

returned in the outbound message comes from records that satisfy any one of the <CriteriaElement> conditions.

<QueryCriteria xmlns = "http://schemas.microsoft.com/

dynamics/2006/02/documents/QueryCriteria">

<CriteriaElement>

<DataSourceName>CustTable</DataSourceName>

<FieldName>Street</FieldName>

<Operator>Range</Operator>

<Value1>1</Value1>

<Value2>5</Value2>

</CriteriaElement>

<CriteriaElement>

<DataSourceName>CustTable</DataSourceName>

<FieldName>Name</FieldName>

<Operator>Equal</Operator>

<Value1>Northwind Traders</Value1>

<Value2/>

</CriteriaElement>

</QueryCriteria>

Tags in the <CriteriaElement> Section

The following table lists the tags that occur in the <CriteriaElement> section.

Note

All the tags are required except for <Value2>, which is required only when the Range operator is used.

Tag name Description

<DataSourceName> The name of the table that is targeted for the search. The table must be the one that is targeted by the service that is specified in the <Action> tag.

<FieldName> The name of a field in the table.

<Operator> One of several recognized operators, such as GreaterOrEqual or Range.

<Value1> The string representation of any value that is appropriate for the type of field specified.

<Value2> The second operand, used only when the Range operator is used.

The following sections provide more details about some of the tags in the previous table.

<DataSourceName> Value Aligned with Service

You can determine the correct XML tag name for any service that is specified in the <Action> tag. The determination process

is described by the following steps, which use the service CustomerService as a specific example.

1. In the Content Pane, locate Basic, Setup, Application Integration Framework, and then click Services.

2. Click the row that contains CustomerService, to highlight it with focus.

3. Click the Service operations button, to display the Service operations form.

4. Highlight one row, such as the row for the Method name of create.

5. Click the Parameter schema button, to display the Parameter schemas form.

Note

Your inbound message must have one XML tag for each parameter that is displayed in the form. Each of these tags must have <Body><MessageParts> as its immediate parent. These tags must occur in your message in the same sequence that they are displayed in the form.

6. Highlight the first row that has a Direction value of Inbound. In this example, we highlight the row for the

Parameter name of _custCustomer.

7. Click the View schema button.

8. In the Schema window that is displayed, the name attribute of the first element is the name you must use for the first

tag under <Body><MessageParts> in your inbound message. The name of the first element in our example is

Customer, as is shown in the following schema code.

<xs:element name="Customer" type="AxdCustomer" />

<Operator> Values

The following table shows all the operators that are recognized as valid <Operator> tag values.

<Operator> value Analogous X++ operator

Equal ==

NotEqual !=

Greater >

GreaterOrEqual >=

Less <

LessOrEqual <=

Range >= && <=

Note

The Range operator cannot be used to query hidden or locked ranges for a data source or field. For more information about the status property on a query range, see Query Properties.

XSD Validations

The <QueryCriteria> section is validated against an XSD schema. The schema is stored in the table AifSchemaStore,

in the record that has the value QueryCriteria in its SchemaRootElementType field.

The XSD schema that is duplicated in file QueryCriteria.xsd that is included with Microsoft Dynamics AX. In some

installations, the file can be found under the following directory path:

C:\Program Files\Microsoft Dynamics AX\ <version> \

Application\Share\Include\

Example:FaultinanOutboundMessage

This topic describes the <Fault> tag that occurs in outbound messages that report an error in the corresponding inbound

message.

Outbound <Fault> Example

The following XML code example shows a <Body> tag section that contains a <Fault> tag. The <Text> tag contains the

textual information that you can use to diagnose the problem.

<Body>

<MessageParts xmlns = "http://schemas.microsoft.com/

dynamics/2008/01/documents/Message">

<Fault xmlns = "http://schemas.microsoft.com/dynamics/

2008/01/documents/Fault">

<Code>RequestFailed</Code>

<Reason>

<Text xml:lang = "EN-US"

>Request Failed. See the Exception Log for details.</Text>

</Reason>

</Fault>

</MessageParts>

</Body>

View the Exception Log

The <Text> tag in the previous example instructed the user to view the Exceptions log. The log can be started from the

Content Pane.

1. In the address bar for the Content Pane, select Basic.

2. In the Content Pane, locate the Periodic section.

3. Expand Application Integration Framework.

4. Click Exceptions.

5. Read the message in the Exception message column.

XSD Validations

The <Fault> tag section is validated against the Fault XSD.

MessageXSDsThis topic describes the XML schema definitions (XSDs) that are common to many or all Application Integration Framework (AIF)

messages. This topic does not include XSDs that are specific to a particular service (such as CustomerService) that is

specified in the <Action> tag of the message.

The system checks all AIF messages against the appropriate XSDs. Messages that fail these validation tests are rejected.

Location of XSDs

All AIF related XSDs are stored in the database table named AifSchemaStore. Some of the common XSDs are also stored in

files under the Microsoft Dynamics AX installation directory. These files are useful duplicates of their corresponding records in the

AifSchemaStore table. These files are installed in the following directory path:

<InstallationDirectory> \Microsoft Dynamics AX\ <version> \

Axapta Application\Share\Include\.

List of Common AIF XSDs

The following table lists the common AIF XSDs that are available XSDs.

XSD Description

EntityKey.xsd Defines the <EntityKey> tag and all tags that can appear nested underneath it.

EntityeKeyList.xsd Defines the <EntityKeyList> tag. It specifies the <EntityKey> tag, but it leaves the more deeply nested tags for the EntityKey.xsd file to specify.

Fault.xsd Defines the <Fault> tag. This is the valid format for a SOAP fault.

Message.xsd Defines the <Envelope> tag, which is the outermost tag in an AIF message. It specifies the whole <Header> section. It also specifies the <Body> tag and the

<MessageParts> tag that is always nested immediately under <Body>.

QueryCriteria.xsd Defines the <QueryCriteria> tag and the nested <CriteriaElement> tag. It also specifies tags at the level of <Operator>, and it lists all the valid values for the <Operator> tag (such as GreaterOrEqual).