AIF Stuff - iali.co.ukhide\AX5\AIF\AIF Stuff.pdf · AIF Stuff Table of Contents AIF Stuff ...
Transcript of 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" /> <!-- more fields... --> </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>
<MessageId></MessageId>
<SourceEndpointUser></SourceEndpointUser>
<SourceEndpoint></SourceEndpoint>
<DestinationEndpoint></DestinationEndpoint>
<Action>http://schemas.microsoft.com/dynamics/
2008/01/services/CustomerService/read</Action>
<ConversationId></ConversationId>
</Header>
<Body>
<MessageParts xmlns="http://schemas.microsoft.com/dynamics/
2008/01/documents/Message">
<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" ?>
<Envelope xmlns="http://schemas.microsoft.com/dynamics/
2008/01/documents/Message">
<Header>
<MessageId></MessageId>
<SourceEndpointUser></SourceEndpointUser>
<SourceEndpoint></SourceEndpoint>
<DestinationEndpoint></DestinationEndpoint>
<Action>http://schemas.microsoft.com/dynamics/
2008/01/services/CustomerService/update</Action>
<ConversationId></ConversationId>
</Header>
<Body>
<MessageParts xmlns="http://schemas.microsoft.com/dynamics/
2008/01/documents/Message">
<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>
<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>
<CountryRegionId>US</CountryRegionId>
<County>Baltimore</County>
<DlvMode>U11A</DlvMode>
<DlvTerm>TERMNA3RD</DlvTerm>
<Name>Jane Smith</Name>
<RecId>5637145089</RecId>
<RecVersion>1</RecVersion>
<ShipCarrierAccount>234-4567
</ShipCarrierAccount>
<ShipCarrierAccountCode>UPS
</ShipCarrierAccountCode>
<ShipCarrierBlindShipment>No
</ShipCarrierBlindShipment>
<ShipCarrierID>U11A</ShipCarrierID>
<ShipCarrierResidential>No
</ShipCarrierResidential>
<State>MD</State>
<Street>111 5th Street</Street>
<TimeZone>GMTMINUS0800PACIFICTIME
</TimeZone>
<type>ShipCarrierThirdPartyShipping</type>
<ZipCode>21210</ZipCode>
</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" ?>
<Envelope xmlns="http://schemas.microsoft.com/dynamics/
2008/01/documents/Message">
<Header>
<MessageId>{3B7C23AB-B0EF-4C35-8DC6-481574080F62}</MessageId>
<SourceEndpoint>Default</SourceEndpoint>
<DestinationEndpoint>Default</DestinationEndpoint>
<Action>http://schemas.microsoft.com/dynamics/
2008/01/services/CustomerService/read</Action>
<RequestMessageId>{C8111B69-9786-4BB4-9A03-
D0BE847F4C3C}</RequestMessageId>
</Header>
<Body>
<MessageParts xmlns="http://schemas.microsoft.com/dynamics/
2008/01/documents/Message">
<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>
<Street>7212 9th Street</Street>
<WebSalesOrderDisplay>WebEntered
</WebSalesOrderDisplay>
<ZipCode>58102</ZipCode>
<CustAddress class="entity">
<Address>111 5th Street Baltimore,
MD 21210 US</Address>
<AddrRecId>5637144604</AddrRecId>
<AddrTableId>77</AddrTableId>
<City>Baltimore</City>
<CountryRegionId>US</CountryRegionId>
<County>Baltimore</County>
<DlvMode>U11A</DlvMode>
<DlvTerm>TERMNA3RD</DlvTerm>
<Name>Jane Smith</Name>
<RecId>5637145089</RecId>
<RecVersion>1</RecVersion>
<ShipCarrierAccount>234-456
</ShipCarrierAccount>
<ShipCarrierAccountCode>UPS
</ShipCarrierAccountCode>
<ShipCarrierBlindShipment>No
</ShipCarrierBlindShipment>
<ShipCarrierID>U11A</ShipCarrierID>
<ShipCarrierResidential>No
</ShipCarrierResidential>
<State>MD</State>
<Street>111 5th Street</Street>
<type>ShipCarrierThirdPartyShipping</type>
<ZipCode>21210</ZipCode>
</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>
<Field>AccountNum</Field>
<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).