Creating a Document Inbound Service in Microsoft Dynamics AX 2012

Microsoft Dynamics AX exposes data for exchange with external systems through business logic exposed as services. 

The data and business logic together is called a document.

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 using AIF. 

As a group, these classes encapsulate the business logic for individual documents.

The XML Document Framework contains these types of classes:

• Document service classes (with data contracts)
• Axd <Document> classes (also known as Axd classes)
• Ax <Table> classes

A document service class is the top-level class that provides an external interface that represents the business logic. Document service classes include the service classes and their related data contract classes.

Document Service Classes

The service class is the top-level class that is exposed as a service through the Application Object Tree (AOT). You can view service classes in the Classes node in the AOT. The service classes are exposed as services, which you can view in Services node in the AOT. Each service class is derived 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 implements the methods that are needed to perform operations on the data. These methods are exposed as service operations by the service.

Data Object Classes

Data objects provide a data contract for the XML data that is exchanged through AIF. The data object classes reflect the data hierarchy of the query that 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 Classes node in the AOT.

The following table shows how the relationship between the data sources, XML elements, and data object classes is modeled in for a subset of the data sources included in the Customer service.

Object	XML element	Data object class
AxdCustomer query	<Customer>	CustCustomer
CustTable data source	<CustTable>	CustCustomer_CustTable
DirParty data source	<DirParty>	CustCustomer_DirParty

Document Data Object Class

The document data object class is the top-level data object and represents the whole XML document. The following list contains 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.
• Used as the 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. The CustCustomer_CustTable data object in turn depends on the CustCustomer_DirParty data object.

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 AifStronglyTypedDataContainer 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_DirParty class. The CustCustomer_CustTable class depends on the CustCustomer_DirParty class which models the relationship of this data in the database.

AIF Class Naming Conventions

Artifact type	Name description	Name generation rules	Example
Document name	Name of the document	User-defined name describing the document	SalesOrder
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 Windows Communication Foundation (WCF)	<Document Name> + "Service"	SalesOrderService
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 document name	AxdSalesOrder
Document class name	Name of the Axd <Document> class	Same name as the query	AxdSalesOrder

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.

Document services are XML documents that initiate transfer of data into or out of Dynamics AX. Any entity in AX can be represented as Documents, such as Customers or Sales Orders.

Document services are used when we have to execute complex CRUD (Create, Read, Update, Delete) operations on an entity.

1. Document service uses an AOT query to generate related artifacts. For this tutorial, InventTable query will be used

• Open Microsoft Dynamics AX Development workspace. Go to Tools à Application Integration Framework àCreate document service

• This will open the AIF Document Service Wizard. Click Next to proceed

• In this step, specify the Document parameters. Select the Query for which service has to be created. The Document name will default to Query name. Modify it as required and give a suitable Document label as shown below. Click Next

• Now specify the Code generation parameters. The wizard will use this to create the respective classes. Check the required Service operations you want to be automatically created by the wizard. Click Next
  Note: To allow Update/Delete/Create Service operations, the Update property must be set to Yes

• In the Generate code window, review the artifacts that will be generated. Click Generate to proceed

• The wizard will now generate all the artifacts. In the end, a Completed screen will display the list of artifacts it created. Click Finish to exit the wizard

• The next step is to create a service group and deploy the service to an Inbound Port

• Go to Service Groups, right click on it, and select New Service Group

• Name it InventServiceDemoGroup

• Set AutoDeploy to Yes (so the service will start automatically when AOS is started) and set the Description to Item Id service

• Right click the newly created service group and select New Service Node Reference

• In the newly created service node, set the Service property to InventTableDemoService. The Name property will automatically default to the Service name

• Now right click the service group and select Deploy Service Group

• A success message will appear if the service group is successfully deployed

• To verify, go to System administration à Setup à Services and Application Integration Framework à Inbound ports

• The Service group name InventServiceDemoGroup will appear here as Port name with a green tick mark. This shows that the service group is deployed and active. If a red cross mark is present, select Activate from the action pane to activate the port

• The WSDL URI is the URL of the service which can be used by external systems to access the service