Chapter 2: Architecture

CHAPTER 2: ARCHITECTURE
Objectives
The objectives are:

Review high level flows in Services and Application Integration

Framework (AIF).

Discuss the topology of the Services and AIF model.

Describe moving service configurations by using integration ports in

AIF.

Discuss the new process of change tracking.

Review the transforms that are available for customization in

banking.

Demonstrate Excel Document Service Registration.

Review support data model changes in Microsoft Dynamics AX

2012.

Introduction
Application Integration Framework (AIF) helps companies integrate Microsoft
Dynamics AX with external business processes and partners through the
exchange of XML over various transport media.
As mentioned in the "Architecture lesson" of Chapter 1: Introduction to Services
and Application Integration Framework all services are WCF based and hosted
on AOS. When intranet communication is needed for services that are using IIS,
the requests are routed to AOS for processing. Inbound and outbound messages
can take advantage of message transforms or value substitutions when they are
configured to do this.

2-1

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
The following diagram illustrates the services and AIF architecture.

FIGURE 2.1 SERVICES AND AIF ARCHITECTURE

High Level Features and Concepts

The process flows in Microsoft Dynamics AX2012 are managed by integration
ports, simplifying the administration of services and the AIF. This replaces AIF
endpoints and related concepts that were used in previous releases of Microsoft
Dynamics AX. This lesson will review those high level processes and illustrate
the following flowing features and concepts.

2-2

Synchronous and asynchronous transports

Basic and enhanced ports

Inbound and outbound message exchanges

Service types

Chapter 2: Architecture

Service operations

Service groups

Synchronous and Asynchronous Transports

AIF supports synchronous and asynchronous transports for exchanging XML
documents with external systems. In synchronous mode, requests are tightly
coupled to responses, and the same connection is used for the request and the
response. In this case, AIF immediately processes the request and then sends a
response. In asynchronous mode, requests are sent through a queue, called the
gateway queue. Queued messages are processed at a later time. In this case,
responses are delayed, but large volumes of messages can be processed more
efficiently, and message processing can be controlled by changing various
configuration settings.

Basic Integration Ports

Basic integration ports are exposed through a specific Windows Communication
Foundation (WCF) endpoint on the Application Object Server (AOS) host. Only
a developer can create a new basic integration port. When a developer creates a
service group in the Application Object Tree (AOT), a basic inbound integration
port is also automatically created if the autoDeploy property is set to yes. The
basic inbound integration port is then associated with the service group. Some
basic integration ports, such as those that are used for system services, are auto
deployed and enabled by default.

Enhanced Integration Ports

If you want advanced integration capabilities that you can use to customize the
behavior of an integration port, you must create an enhanced integration port.
Enhanced integration ports provide the following capabilities that basic
integration ports do not provide:

Services can be hosted on either AOS or Internet Information

Services (IIS).

A variety of protocols are supported through WCF adapters. These

protocols include HTTP and NetTCP. Enhanced integration ports
also support a file system adapter that lets you use file paths as
addresses and a MSMQ adapter.

You can configure pre-processing and post-processing of service

requests and service responses, for instance through configurable
transformations.

You can customize service and data contracts by selecting the set of
service operations that are exposed when you create the data policies.

You can specify advanced security and troubleshooting settings.

Change tracking is supported

2-3

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
Inbound and Outbound
Inbound ports are used by external systems to call Microsoft Dynamics AX AIF
and services. This kind of exchange is called an inbound exchange. For example,
during an inbound exchange, an external system can send a sales order so that the
sales order can be saved to the Microsoft Dynamics AX database.
AIF can also be used by Microsoft Dynamics AX to call external systems. For
example purchase orders can be sent electronically to an external system by using
an outbound exchange. Some outbound exchanges can be triggered by an
inbound message. For example, an external system might send an inbound
request for information about a specific product and receive product information
from an outbound message. This kind of exchange is called an outbound
exchange.

How Documents are Exchanged

AIF provides an extensible framework for the exchange of XML documents with
external systems. The framework supports synchronous and asynchronous
transports. In synchronous mode, requests are tightly coupled to responses. This
means that the submitter of the request must wait for a response from AIF before
proceeding. In this case, AIF immediately processes the request and then sends a
response. In asynchronous mode, requests are placed into a queue, called the
gateway queue. Queued messages are processed at a later time and AIF sends a
response when processing is completed. In this case, responses are delayed, but
large volumes of messages can be processed more efficiently, and message
processing can be controlled by changing various configuration settings.
AIF can be used to send data into Microsoft Dynamics AX. This kind of
exchange is called an inbound exchange. For example, during an inbound
exchange, an external system might send a sales order so that the sales order can
be saved to the Microsoft Dynamics AX database. AIF can also be used to
retrieve data from Microsoft Dynamics AX. This kind of exchange is called an
outbound exchange. For example, during an outbound exchange, an external
system might send a request for a purchase order and receive the purchase order.
The inbound and outbound exchanges can be categorized in the following ways:

Send data Microsoft Dynamics AX sends documents to an

external system.

Send data in response to requests Microsoft Dynamics AX

receives requests for documents from another authorized system, and
retrieves the requested information, such as a document or a list of
documents, from the Microsoft Dynamics AX database.

Microsoft Dynamics AX then returns the information to the requesting

system, and the appropriate filtering and security are applied. The request
message contains the entity keys or a query that specifies the data that
the external system is requesting.

2-4

Chapter 2: Architecture

Receive and create data Microsoft Dynamics AX receives

documents from another authorized system and creates new records
in the Microsoft Dynamics AX database.

Parallelism
To improve performance for data exchange by using asynchronous adapters, AIF
supports parallelism. Parallelism specifies that inbound messages are processed
by one or more AOSs without regard to the order in which they are received or
produced. This helps you scale out message processing by adding multiple
AOSs. Note that you can enable parallelism only for inbound channels.
Parallel processing in AIF is implemented on a channel-by-channel basis. Follow
these steps to implement parallel processing.
1. Click System Administration > Setup > Services and Application
Integration Framework > Inbound Port or System
Administration > Setup > Services and Application Integration
Framework > Outbound Port.
2. Select a channel and select the Process requests in parallel check
box.
Conversational parallelismalso known as ordered parallelismmeans that you
can specify certain messages to be processed sequentially in a channel, even
when parallelism is enabled for that channel. This is done by including a special
XML element called <ConversationId> in the messages that require sequential
processing. All messages with the same ConversationId will then be processed
sequentially.
NOTE: If you do not select the Parallel processing field in the Channels form,
all inbound messages for a particular endpoint will be processed sequentially
and the <ConversationId> element in a message is ignored.

2-5

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
Service Types
Microsoft Dynamics AX, together with AIF, enables building integrations with
other systems. By using the programming model for Microsoft Dynamics AX
services, you can customize the document services that are included with
Microsoft Dynamics AX 2012, create new custom services. To support a range of
option for customization and programmability, Microsoft Dynamics AX provides
the following types of services:

Document Services - Services that represent data and business logic

within Microsoft Dynamics AX. You can use or customize the over
70 standard Axd document services that are included with Microsoft
Dynamics AX. If none of the standard document services meet your
needs, you can create a new document service by using the AIF
Document Service Wizard. Each document is represented by a class;
the name of a document class is preceded by Axd. For example,
AxdSalesOrder is the name of the document and also the name of the
document class.

Custom Services - Services that you create to expose X++ logic

through a service interface. You can use the business logic with
inbound or outbound transfers.

System Services - Services that cannot be customized. The Query

Service, Metadata Service, and User Session Service are Windows
Communication Foundation (WCF) services that are included with
Microsoft Dynamics AX. They provide access to data that is returned
in queries, metadata for AOT objects such as tables and extended
data types (EDTs), and data about the calling user such as default
language and default company.

Document Service Operations

A service operation is a named set of functionality that is offered by a service. A
service can expose multiple service operations. The service operations that a
service exposes can include custom service operations.
For example, the sales order document services service operation that creates a
new sales order is named SalesSalesOrderService.create. Service operations
include: create, delete, find, findkeys, getkeys, getchangedkeys, read, and update
NOTE: When you configure an integration port, you must know which service
operations have to be exposed from the port.

2-6

Chapter 2: Architecture
Service Groups
Developers can group services and service operations that are managed and
consumed together into a service group. All the services in a service group are
published through a basic port, in a single WSDL file. The WSDL contains all
service and data contracts for the service operations of the service group, which
simplifies developing the code that consumes services.
NOTE: A Web Service Description Language (WSDL) file defines the operations
that are available for a service.
Developers can create a service group in the Application Object Tree (AOT).
Developers can use the AutoDeploy property to specify whether the service
groups that they create are automatically deployed and activated when they are
created. Developers must manually deploy and activate any service groups that
are not automatically activated.
NOTE: Service groups are associated only with basic integration ports.

Topology
There are certain factors to consider when you plan the topology of services and
Application Integration Framework (AIF).

Adapters
In Microsoft Dynamics AX 2012 services and Application Integration
Framework (AIF), integration ports use adapters. These adapters enable
Microsoft Dynamics AX to communicate by using various transport protocols.
Microsoft Dynamics AX 2012 provides the following four adapters that represent
predefined bindings:

HTTP adapter - This adapter enables synchronous exchanges

through web services on Internet Information Services (IIS), which
can expose services on a network or the Internet.

NOTE: Web Services should in general never be deployed by using basic HTTP
binding. HTTPS bindings or similar, should be selected even for internal use.
When you use the HTTP binding, all data will travel unencrypted and can be
read by anyone on the same segment on the network.

NetTCP adapter - This adapter enables synchronous exchanges by

using support for WS-* standards over the Transmission Control
Protocol (TCP) transport.

2-7

Application Integration Framework and Services in

Microsoft Dynamics AX 2012

MSMQ adapter - This adapter enables asynchronous exchanges

through message queues. To use this adapter, you must install
Message Queuing, which is also known as MSMQ, on a network
computer. You must also create at least one public queue to
configure the MSMQ Adapter for Microsoft Dynamics AX.

File System adapter - This adapter enables asynchronous exchanges

through file system directories. You must enable and configure at
least one file system directory, or folder, for messages. Inbound
messages and outbound messages require separate folders.

NOTE: Microsoft Dynamics AX 2012 no longer includes a BizTalk adapter.

Earlier versions of Microsoft Dynamics AX required a BizTalk adapter for
integration with Microsoft BizTalk Server. However, BizTalk Server can now
connect to AIF through standards-based adapters. For more information, see
Exchanging documents between BizTalk Server and AIF
(http://go.microsoft.com/fwlink/?LinkID=247431&clcid=0x409 ) and the Using
Microsoft BizTalk Server 2010 to Exchange Documents with Microsoft Dynamics
AX (http://go.microsoft.com/fwlink/?LinkID=247479&clcid=0x409 )whitepaper.

Performance Improvements
The following list describes enhancements in services and AIF that result in
improved performance:

To achieve scale and redundancy, you can configure AOS servers

with the Network Load Balancing (NLB) for Microsoft Dynamics
AX services. The AOS-clustering solution affects only the RPCbased connections and does not allow you to load balance Microsoft
Dynamics AX services. For more information, refer to Configuring
network load balancing for services
(http://go.microsoft.com/fwlink/?LinkID=247480&clcid=0x409 ).

Client applications can access services directly on AOS; IIS-hosted

services use the WCF routing service and no longer depend on the
.NET Business Connector, which was required for services and AIF
in previous releases of Microsoft Dynamics AX.

The services framework uses connection pooling to reduce the

overhead of creating and destroying a session on service calls.

When to Use IIS Hosting

To consume services over the Internet, you must host services on Internet
Information Services (IIS). IIS uses the message routing service to route all
service requests to AOS where all service requests are processed.. AOS then
returns a response to the service consumer through IIS.
Microsoft Dynamics AX deploys services that are hosted on IIS to a subfolder of
the virtual directory that is associated with the web site that you provide.

2-8

Chapter 2: Architecture

Usability
New usability features of services and Application Integration Framework (AIF)
are added to Microsoft Dynamics AX 2012. The following are components of the
new features.

Moving service configurations by using integration ports in AIF

Change tracking based on date and time of changes

Templates for the transforms for Banking

Configure services for Office add-ins

Office Add-ins
The new add-in for Microsoft Excel and Microsoft Word help users to view,
analyze, and update information in Microsoft Dynamics AX. The Microsoft
Excel add-in has built-in support for consuming document services for updating
data.

Excel Document Service Registration

Data in Microsoft Excel can be modified by using any document service that has
a Create or Update service operation, and that uses a file adapter or net.tcp.
Before using a document service, you must register it, add it to an inbound
integration port, activate the port, and then expose the service.
Only the following document services from Microsoft Dynamics AX 2012 are
supported without modification in the Excel Add-in:

BudgetTransaction

EMSMeterReading

EMSSubstanceFlow

GeneralJournal

ProductionPickingList

ProjectHourJournalS

SysImportBusSector

VendGroup

VendRequestSignup

Additional services can be constructed to extend the scenarios in which Excel can
be used to update, create, and delete business data in Microsoft Dynamics AX.
NOTE: The configuration of integration ports for Excel import is a specific
example of the procedures that are used to configure any integration port.

2-9

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
Moving Service Configurations
Microsoft Dynamics AX 2012 uses integration ports to manage integration
scenarios in services and AIF. To move service configurations from test
environments to production environments, you must meet specific prerequisites
and complete the following tasks:

Export the service metadata from the source environment, which is

the test environment. This metadata includes AOT code, service
details, and so on.

Export configuration data about integration ports from the source

environment. The data is exported as a .dat file.

Import the exported metadata into the destination environment,

which is the production environment.

Import the integration port data into the destination environment.

Prerequisites to Export/Import Configuration Data

Before you migrate configuration data from a test environment to a production
environment, ensure that you meet the following prerequisites:

2-10

Create a file share.

For file-based integrations, the account for the AOS must have
read/write permissions for the file share. The file share must not be
an administrative share, such as shares that contain a dollar sign ($).

The user who is importing the port configurations into the

destination environment must have privileges as an AIF
administrator. This means that the user must have the AifAdmin
privilege.

All customizations must first be added to the source environment,

and the application must compile without errors.

All ports must be activated and tested. For ports that are based on
NetTCP and HTTP, the Web Service Description Language (WSDL)
files must be published. Additionally, a client must be able to start
the service through service calls. For ports that are based on the file
system adapter or the MSMQ adapter, the corresponding scenario
must be tested.

Chapter 2: Architecture
Procedure: Export the Integration Port Configuration Data
Use the following procedure to export the integration port configuration data.
1. Create a new definition group for exports. Click System
administration > Common > Data export/import > Definition
groups.
a. Click New.
b. Enter a unique name for the group into the Definition group
field.
c. Optionally enter a description.
d. Click the Options tab and clear all the check boxes.
e. Click the Include table groups tab and clear all the check boxes.
f. Click OK.
2. Select tables for the definition group by clicking Select tables.
a. Click Add, and then for inbound ports, select AifInboundPort
in the Name of table field.
b. Select Include document references and Specify related tables
check boxes.
c. Click the Select related tables button. On the Select related
tables form, select the desired related tables to include and then
click Close.
d. Optionally, add export criteria by selecting the Apply criteria
check box, and then click Export criteria. Enter the desired
filter criteria and then click OK.
e. Close the Select tables form.
3. Export the data to a local or network file share by clicking Export to
on the Definition groups form. Select the file name and path, and
then select the file type. Click OK to export the data to the specified
file.
4. Close the Definition group form.
5. Repeat steps 1 through 4, using AifOutboundPort in the Name of
table field in step 2.a instead of AifInboundPort.
NOTE: During export, you might receive the following message:
"TableDirPartyCollection was not found." If you receive this message, add
export criteria, which is described in Step 3 of the "Export the Integration Port
Data" procedure, to export only new and customized ports.

2-11

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
Procedure: Import the Integration Port Configuration Data
In the destination environment, use the following steps to import the file for the
integration port data that you exported from the source environment.
1. Open the Import options form. Click System administration >
Common > Data export/import > Import.
2. If you exported only selected ports by using export criteria, select
Update existing record on the Advanced tab. Otherwise, existing
ports in the destination environment are deleted.
When you have finished importing the data, you must deactivate the imported
ports, register services, register basic ports, and update the configuration details
for each port. For example, you would update URIs based on paths in the
production environment, and then activate the ports. For more information on
completing these steps, refer to Exporting and importing AIF integration port
configurations (http://go.microsoft.com/fwlink/?LinkID=247481&clcid=0x409 ).
NOTE: This process will need to be completed once for each exported file in the
Export the Integration Port Data procedure.

IMPORTANT: If the production environment is part of a cluster, you must

restart all AOS instances to guarantee that all configurations are updated.

Change Tracking
In Microsoft Dynamics AX 2012, you can configure the database to keep track of
when changes happen at the table level. When so configured, you can use the
getChangedKeys service operation to retrieve entity keys for only those
documents that have changed based on certain criteria, such as a specified date
and time.
Change tracking must be enabled in the database for the database tables that are
used by the document service. To do this, you will need to configure change
tracking. To retrieve the entity keys for documents that were changed, you must
publish the getChangedKeys service operation through an integration port.
Additionally, you will need to create a document filter and add filtering criteria.
NOTE: You can use change tracking only if the document service is exposed
through an inbound enhanced integration port.

IMPORTANT: You must create at least one document filter. Otherwise, no entity
keys are returned from the getChangedKeys service operation.

2-12

Chapter 2: Architecture
Once enabled, you can use change tracking in two ways:

Submit an XML document to AIF that specifies the getChangedKeys

action in the message header.

Call the getChangedKeys method on a document service class.

Only the entities that are changed on or after the _changedDateTime

parameter are returned.
The response message contains a list of entity keys. These keys represent the
documents that have been changed according to the criteria that you specified,
such as documents that were changed after a certain date and time.
NOTE: For more information on configuring change tracking refer to
Configuring AIF for change tracking
(http://go.microsoft.com/fwlink/?LinkID=247482&clcid=0x409 ).

Templates for Banking

Application Integration Framework (AIF) provides framework that can help you
generate payment files by using document services. This is an advantage over the
previous system where the base classes were extended and customized to select
appropriate data from transactional tables. If the parameters changed, then there
would need to be recoding. Document services now help you to exchange data
with external systems by sending and receiving data in XML documents.
There are two primary areas of functionality in this process: the transport
components and the business logic components. The transport components
handle the transfer of business logic in and out of the system by using XML
documents. The elements of the transport layer define how data is exchanged,
including the source of the data, the destination of the data, and how it is
transported.
The business logic component of document exchange consists of the data, its
format, and the business rules that govern the data. This business logic is exposed
by two sets of classes: the base classes and the document service classes in the
XML Document Framework. To provide framework for current and future
payment formats, you can create a single query that exposes all the fields that are
required for all the outbound payment formats. Use the AIF Document query
wizard to generate the service and document object, data object, and Axd
document classes.
To enable payment generation by using AIF, use the customer and vendor
payment services to expose the payment generation data for AIF outbound
processing service. These services are based on Microsoft Dynamics AX queries.
Customer/Vendor payment query captures all the necessary data to generate
customer/vendor electronic payment files. Use the AIF document service wizard
to generate the service document and data object classes. An XSLT can be
applied on this master data to transform the AIF XML file to the payment file for
a specific payment format.

2-13

Application Integration Framework and Services in

Microsoft Dynamics AX 2012
For every payment format that you intend to generate by using AIF, you need to
have a corresponding XSLT file. This XSLT is based on the format that is
specified by the bank. These XSLTs can be can be created by using a simple text
or XML editor. You can also use visual studio and BizTalk mapper. For payment
files that are not XML, you need to apply an outbound transformation to convert
the XML results to flat file. Outbound transforms can be of any type and they
post-process the generated XML file to obtain the desired payment file.
For the Microsoft Dynamics AX administrator, he or she has access to outbound
port setup and can create an outbound port and define payment processing data
for a payment format. The administrator can chose the outbound folder and the
XSLT for the specific payment format. For a end user, the experience is quite
similar to generating the payments by using file I/O. The user only needs to
choose payment format and the format specific data that is required for the
specific instance of payment creation process.
Generating payments by using services provides flexible and extensible
framework helps you to effortlessly easily plug and remove payment formats.
The application integration framework provides capabilities, like outbound
transforms, to help you plug in additional XSL or binary transformations to
generate the desired payment files. In the event of any change to payment
formats, the XSLT can be modified outside of Microsoft Dynamics AX. Any
new payment formats can be added by creating the XSLT and adding it to the
outbound port.

Support for Data Model Changes

In Microsoft Dynamics AX 2012, the services framework is enhanced to use
several of the infrastructure features that are added in Microsoft Dynamics AX.
Each document service is built on top of a query that is used to produce the data
contract for that service as a document. The services framework handles
scenarios to produce more user-friendly data contracts. These scenarios include
the following:

Replacing a surrogate foreign key with the natural key for a specific
table relationship so that the final service contract has user-friendly
readable fields instead of Surrogate Foreign Keys (SFK).

Handling the queries that contain tables with dimension columns in

the data sources. The framework has support to serialize or
desterilize the dimension columns across the service boundary.

Understanding table inheritance.

Handling tables with date effective fields.

The create and update document service wizards have been updated to generate
code that includes the previous changes.

2-14

Chapter 2: Architecture

Summary
Application Integration Framework (AIF) helps companies integrate Microsoft
Dynamics AX and communicate with external business processes and other
enterprise applications within and outside the boundaries of the business through
the exchange of XML over various transport media.

2-15

Application Integration Framework and Services in

Microsoft Dynamics AX 2012

Test Your Knowledge

Test your knowledge with the following questions.
1. Which of the following can not be a basic port?
( ) Outbound
( ) Inbound
( ) Endpoint
( ) Startpoint
2. Which of the following Axd document service operations are available in
AIF? (Select all that apply)
( ) Create
( ) Read
( ) Update
( ) keysFind
3. Which of the following is not a service type?
( ) Custom services
( ) Document services
( ) NetTCP services
( ) System services
4. Which of the following best describes synchronous and asynchronous
transports? (Select all that apply)
( ) Requests are tightly coupled to responses.
( ) Requests are placed into a queue, called the gateway queue.
( ) Invoke business logic by using preprocessing options.
( ) Requests develop new file links by using post-processing.

2-16

Chapter 2: Architecture

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this
chapter
1.

2.

3.

2-17

Application Integration Framework and Services in

Microsoft Dynamics AX 2012

Solutions
Test Your Knowledge
1. Which of the following can not be a basic port?
() Outbound
( ) Inbound
( ) Endpoint
( ) Startpoint
2. Which of the following Axd document service operations are available in
AIF? (Select all that apply)
() Create
() Read
() Update
() keysFind
3. Which of the following is not a service type?
( ) Custom services
( ) Document services
() NetTCP services
( ) System services
4. Which of the following best describes synchronous and asynchronous
transports? (Select all that apply)
() Requests are tightly coupled to responses.
() Requests are placed into a queue, called the gateway queue.
( ) Invoke business logic by using preprocessing options.
( ) Requests develop new file links by using post-processing.

2-18