1. Integrated
Microsoft Dynamics™ AX
Configuring the Application
Integration Framework (AIF)
BizTalk Adapter for Data
Exchange
White Paper
Instructions for configuring the AIF BizTalk adapter to exchange data in
Microsoft Dynamics AX.
Date: March 26, 2007
http://www.microsoft.com/dynamics/ax/
2. Table of Contents
Introduction ....................................................................................................................... 4
Overview of AIF Configuration ........................................................................................ 4
Inbound and Outbound Exchanges .......................................................................................................................................... 5
Synchronous Versus Asynchronous Mode ............................................................................................................................. 7
Documents in AIF ............................................................................................................................................................................. 8
Setting up a BizTalk Document Exchange ...................................................................... 8
Configuring a BizTalk Exchange .............................................................................................................................................. 11
Step 1: Set up the AIF environment ...................................................................................................................................11
Step 2: Install the BizTalk adapter .......................................................................................................................................12
Step 3: Configure the BizTalk adapter ...............................................................................................................................12
Send a Document Asynchronously to BizTalk (internal request) ................................................................................ 15
Create the BizTalk assembly ..................................................................................................................................................15
Configure the BizTalk application .......................................................................................................................................23
Send the sales invoice from Microsoft Dynamics AX...................................................................................................29
Send a Document Synchronously to BizTalk (external request) ................................................................................. 30
Create the BizTalk assembly ..................................................................................................................................................31
Configure the BizTalk application .......................................................................................................................................42
Send the sales order ID to Microsoft Dynamics AX......................................................................................................50
Send a Document Asynchronously to BizTalk (External Request) .............................................................................. 51
Create the BizTalk assembly ..................................................................................................................................................52
Configure the BizTalk application .......................................................................................................................................65
Send the sales order ID to Microsoft Dynamics AX......................................................................................................75
Create a Document Synchronously (External Request) .................................................................................................. 76
Create the BizTalk assembly ..................................................................................................................................................77
Configure the BizTalk application .......................................................................................................................................89
Send the sales order to Microsoft Dynamics AX ...........................................................................................................97
Managing AIF and Documents ....................................................................................... 98
Configuring Global Settings ...................................................................................................................................................... 98
Resource locking interval global setting ..........................................................................................................................98
Web methods global setting ................................................................................................................................................99
Default encoding format global setting ...........................................................................................................................99
Outbound schema validation global setting ..................................................................................................................99
Setting Up and Configuring AIF Services ........................................................................................................................... 100
Sending and Receiving Documents Electronically ......................................................................................................... 101
Sending documents automatically .................................................................................................................................. 102
Sending documents manually ........................................................................................................................................... 102
2
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
3. Receiving documents ............................................................................................................................................................ 103
Managing Document Exchanges .......................................................................................................................................... 107
View document history ........................................................................................................................................................ 107
View the exception logs ....................................................................................................................................................... 108
Manage the AIF queues ....................................................................................................................................................... 108
AIF and BizTalk Resources ............................................................................................ 109
3
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
4. Introduction
This document provides instructions for configuring the Application Integration Framework (AIF) BizTalk
adapter for data exchange in Microsoft Dynamics™ AX. The BizTalk adapter is part of
Microsoft Dynamics AX 4.0 Service Pack 1, which must be installed to (be able to) use this white paper.
Note: Throughout this document, you’ll see frequent use of the terms document and message. This is
because when data is transferred in AIF, it’s referred to as a document. When data is transferred in BizTalk,
it’s referred to as a message. These terms are used interchangeably and both refer to the XML as it is being
transferred from system to system.
Overview of AIF Configuration
The Application Integration Framework (AIF) provides an extensible framework that enables the exchange
of documents in XML format from within Microsoft Dynamics AX. AIF replaces the Commerce Gateway for
Microsoft Dynamics AX 3.0 (formerly Microsoft Business Solutions—Axapta 3.0), and provides a more
secure business-to-business and application-to-application integration between Microsoft Dynamics AX
and trading partners or other software systems.
This framework includes adapters and Web services that enable document exchange. The BizTalk adapter
uses the .NET Business Connector in Microsoft Dynamics AX to send messages to and receive messages
from Microsoft® BizTalk® Server.
Figure 1 – Overview of the Application Integration Framework (AIF) components.
Trading Partners
3rd Party Systems
BizTalk Server 2006
Microsoft Dynamics
BizTalk Adapter for
BizTalk Adapter for
XML XML
Direct
X++ API
Calls Web Services Asynchronou
s
Transports
.NET Business
CLR Interop AIF
Connector
AOS
Microsoft Dynamics AX
4
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
5. Inbound and Outbound Exchanges
AIF is the mechanism through which data transfer is automated. The AIF infrastructure provides the ability
to implement loosely coupled transfer of data through XML documents. A document exchange can be
inbound or outbound.
Inbound exchange: One in which your Microsoft Dynamics AX system accepts data as input.
Figure 2 – Overview of how a document enters Microsoft Dynamics AX through AIF.
External Web Services BizTalk Server 2006
File
MSMQ System
Web Service Gateway
Service 1
1
Web Services Framework (.NET) Messaging Gateway (X++)
Gateway
2 Queue
11
Supporting Components
Endpoint Policy
User Validation 5 Request 10 Inbound
Enforcement
4 Processor 3 Processing Service
Document Services (X++)
Transformation Schema Validation Idempotency
Enforcement
Value
Substitution
Document 9
Logging/History
6
Document Processing Pipeline
Document
Configuration (X++)
Broker
Integration Layer (X++)
8 7 AxdBase
Business Logic (X++)
Read/Create
Microsoft Confidential
5
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
6. Outbound exchange: An exchange in which your Microsoft Dynamics AX system sends data to
another system. An outbound exchange can originate from within the system, such as configuring AIF
to send out a price list to your customers each time it is updated. Or, an outbound exchange can
originate as a request from another authorized system. In this case, Microsoft Dynamics AX would
receive the request, retrieve the requested information from the database, and return it to the
requesting system with appropriate filtering and security.
Figure 3 – Overview of how a document leaves Microsoft Dynamics AX through AIF.
External Web Services BizTalk Server 2006
File
MSMQ System
Gateway
Service
Web Services Framework (.NET) Messaging Gateway (X++)
12
12
Gateway
Queue
Supporting Components 11
Endpoint Policy
Enforcement 9 Request 10
Processor 4
Outbound 3
Transformation Processing
Document Services (X++)
Schema Validation Service
Value
Substitution
Document Outbound
Logging/History 8 Processing
5 Queue
Document Processing Pipeline
Configuration (X++)
Document
Broker Integration Layer (X++)
AifSend Service 2
7 6 AxdBase Read
Business Logic (X++) 1 X++ Code
Microsoft Confidential
AIF comprises both synchronous Web services as well as adapters that support a variety of asynchronous
transports. Within AIF there are two types of exchanges, and each has different requirements for
installation and configuration. Understanding the types of exchanges that are available allows you to
better match the functionality in AIF with your data transfer requirements and environment.
Adapter-based exchange: Asynchronous document exchanges that use adapters in
Microsoft Dynamics AX and do not require the installation of Microsoft® Internet Information Services
(IIS). Adapter transports supported by AIF are:
Message queuing (also known as MSMQ)
File system
Microsoft BizTalk Server
Outbound Web service
6
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
7. Web service exchange: Synchronous document exchanges that use Web services, and require the
installation and configuration of IIS to either send or receive data. The Web services are generated
automatically from the Microsoft Dynamics AX business logic so that developers with limited Web
experience can easily create their own Web services. The Web service exchange differs from the
outbound Web service adapter exchange in that it is synchronous and it can accept requests while the
outbound Web service adapter cannot.
This document details how to set up and configure an adapter for the BizTalk transport. The process to set
up and configure MSMQ, file system, and outbound Web service adapter transports as well as configure
Web services is covered in the white paper Configuring the Application Integration Framework (AIF) for
Data Exchange. For more information about Microsoft BizTalk Server 2006, see MSDN.
Synchronous Versus Asynchronous Mode
The BizTalk adapter supports two modes when sending or receiving documents: synchronous and
asynchronous.
Synchronous mode – BizTalk sends a message to AIF and waits to receive a response. In
synchronous mode, messages sent into AIF bypass the gateway queue in AIF and go directly into
Microsoft Dynamics AX. Similarly, the responses from AIF to BizTalk also bypass the AIF queues
and go directly to BizTalk.
Asynchronous mode – Messages sent from BizTalk to AIF and responses from AIF to BizTalk are
sent asynchronously. Messages going into AIF are sent to the gateway queue in AIF. When the
batches run, AIF retrieves the messages from the inbound gateway queue. Responses that are sent
back to BizTalk use the AIF outbound gateway queue. Because the response is sent
asynchronously, you must use correlation in BizTalk to relate a response with its original message.
This white paper covers the following scenarios:
AIF sends a sales invoice asynchronously to BizTalk and BizTalk writes the sales invoice to a
file.
AIF receives a request for a sales order synchronously from BizTalk and the sales order is
sent to BizTalk synchronously.
AIF receives a request for a sales order asynchronously from BizTalk and the sales order is
sent back as a response asynchronously through the AIF queues. This scenario
demonstrates how to use correlation to relate the sales order response with the request in
BizTalk.
AIF receives a request to create a sales order synchronously from BizTalk and the new sales
order ID is sent back as a response synchronously.
When to use asynchronous or synchronous processing depends on your message volume and particular
data transfer scenario. If you have a high volume of messages being exchanged between AIF and BizTalk,
you may want to implement your exchanges asynchronously. Asynchronous exchanges provide more
control, via batch jobs and other configurations, over the load placed on Microsoft Dynamics AX for
processing documents. Synchronous exchanges place immediate load on Microsoft Dynamics AX, thereby
requiring sufficient hardware capacity to handle the load. If you need an immediate response—from a
user-initiated request, for example—you may want to use synchronous mode.
7
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
8. Documents in AIF
An exchange starts with a document (based on a document class) defined using Microsoft Dynamics AX
business logic. The document is serialized into XML, and header information is added to create a message
that can then be transferred into or out of the Microsoft Dynamics AX system (called the local endpoint in
AIF). The other entity taking part in the exchanges is called the endpoint. The document and the direction
of the exchange is called an action in AIF. For example, selecting the readPurchaseRequisition action means
that you are sending Microsoft Dynamics AX purchase requisition data to another system.
AIF includes out-of-the-box support for sending and receiving commonly used documents, including:
ASN (Advance shipping notice) (outbound)
Exchange rates (outbound and inbound)
Free text invoice (inbound)
Inventory balances (outbound)
Inventory counting journal (inbound)
Inventory profit and loss journal (inbound)
Inventory transactions (outbound)
Inventory transfer journal (inbound)
Ledger chart of account (outbound and inbound)
Ledger dimensions (outbound and inbound)
Packing slip update (inbound)
Picking list (outbound)
Price discount agreement journal (inbound)
Price list (outbound)
Purchase invoice (inbound)
Purchase order (outbound)
Sales invoice (outbound)
Sales order (inbound)
EDI 820 remittance advice (inbound)
Setting up a BizTalk Document Exchange
A core installation of Microsoft Dynamics AX includes the software to enable adapter-based connections.
After a connection is configured and processing is initiated by starting the Microsoft Dynamics AX batch
jobs, messages are exchanged between the local endpoint and the endpoint using the channel that you
define. The XML messages consist of the document and a header, and can be viewed during the exchange
as they appear in the queues (in asynchronous mode).
To set up an adapter-based exchange, you must first set up and configure the transport. The adapter
transports available with Microsoft Dynamics AX 4.0 Service Pack 1 are MSMQ, file system, BizTalk, or
outbound Web services. Note that MSMQ, file system, and outbound Web service adapters are included in
Microsoft Dynamics AX 4.0. The BizTalk adapter is part of Microsoft Dynamics AX 4.0 Service Pack 1 so you
must have this version installed to use this white paper. Regardless of the adapter type, you must first
configure the elements of the exchange, including:
Local endpoint
Actions
8
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
9. Endpoints
Endpoint action policy
Endpoint action data policy (or simply ―data policy‖)
Once the exchange elements are set up, you configure the transport adapter and channel. Next, you
configure the batch job that controls the initiation of the transfer. Optionally, you can select global settings
for the exchange, configure pipeline components, and set up value mapping for the individual fields in the
document being exchanged. For a diagram of the steps involved in setting up an adapter-based exchange,
see Figure 4 in this document.
9
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
10. Figure 4 – Required and optional steps to configure an adapter in Microsoft Dynamics AX.
10
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
11. Configuring a BizTalk Exchange
The following steps explain how to set up Microsoft Dynamics AX for data exchange using the BizTalk
adapter. To configure a document exchange using the BizTalk adapter, you must have Microsoft BizTalk
Server 2006 installed and you must install the AIF BizTalk adapter itself.
Step 1: Set up the AIF environment
Before installing and configuring the BizTalk adapter, first install the prerequisite software and configure
the Business Connector Proxy. To install the BizTalk adapter, you must be at the application integration
gateway computer. The application integration gateway is typically a separate computer from the AOS.
This computer acts as a proxy between systems that are sending or receiving data and the AOS server.
After you install the BizTalk adapter services, you must finish configuring and deploying it within
Microsoft Dynamics AX.
Setting up a computer as an application integration gateway installs the following components on the
computer:
BizTalk adapter for Microsoft Dynamics AX
.NET Business Connector
1. Check for prerequisites. The following software must be installed to enable a BizTalk document
exchange in Microsoft Dynamics AX:
Microsoft BizTalk Server 2006. For more information on installing BizTalk, download the BizTalk
Installation Guide.
Make sure the following are available in the domain:
A core Microsoft Dynamics AX Service Pack 1 installation. This installation must be completed
before you install the BizTalk adapter.
Microsoft® Active Directory® directory service configured in native mode.
2. Set up the Business Connector Proxy. The Business Connector Proxy is a Microsoft® Windows® domain
account that is used to connect to Microsoft Dynamics AX for applications that require ―act-on-behalf-
of‖ functionality for external users or users who have an intermittent network connection. The Business
Connector Proxy account should not be set up as a Microsoft Dynamics AX user account. If you have
already set up the Business Connector Proxy account, you don’t need to set it up again.
a. Have the domain administrator create a unique user in Active Directory using the format
domainusername. This domain account should have the following characteristics:
User cannot have the same name as an existing Microsoft Dynamics AX user.
Password does not expire.
No interactive logon rights.
3. Associate the proxy account with Business Connector in Microsoft Dynamics AX. This step adds the
proxy account to the database. Storing the proxy account in the database ensures that multiple AOS
instances can access the proxy.
a. Click Administration > Setup > Security > Business Connector Proxy.
b. In the Alias field, enter the name of proxy user created in Active Directory.
c. In the Network domain field, enter the domain name.
d. To propagate the change to the Microsoft Dynamics AX database, you must restart the AOS
service. To restart the AOS service, click Start > Programs > Administrative Tools > Services.
e. Right-click the Microsoft Dynamics AX service and click Restart. The service will have a name
similar to Dynamics Server$01-Company1.
11
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
12. Step 2: Install the BizTalk adapter
1. Run the setup. To install the AIF BizTalk adapter, you must be at the application integration gateway
computer. Ensure that you are logged on with an account that is a member of the Administrators
group on the computer on which you are running setup.
a. Insert the Microsoft Dynamics AX 4.0 Service Pack 1 DVD into your drive. If the setup wizard
doesn’t launch automatically, double-click the Autorun.hta file in the root directory of the DVD. If
you are installing from a network location, share the installation files and connect to the location
from the computer on which you want to install the BizTalk adapter.
b. Under Install, select Microsoft Dynamics AX.
c. The Microsoft Dynamics AX Setup Wizard appears. Click Next.
d. If you are updating an existing installation, a summary of roles that are already configured on the
computer appears. Click Next and skip to Step i below.
e. On the Prerequisites check page, setup validates that the software required for the installation is
present. If software is missing, click Install. To continue after the update completes, click Next.
f. On the Welcome page, click Next to continue.
g. On the License agreement page, click I accept the terms in the license agreement to accept
the licensing terms and conditions, and then click Next.
h. Click Custom installation, and then click Next.
i. On the Select Computer Role page, under Application integration gateway, select BizTalk
adapter, and then click Next. Installing the BizTalk adapter automatically installs the .NET Business
Connector.
j. A screen appears with a summary of roles that will be installed. Click Install.
k. Click Finish.
Step 3: Configure the BizTalk adapter
Once you have installed BizTalk Server and the BizTalk adapter, you must configure the BizTalk adapter in
Microsoft Dynamics AX.
1. Configure global settings.
a. Click Basic > Setup > Application Integration Framework > Global settings.
b. Modify the configuration settings as needed. For more information about configuring global
settings, see the section Configuring Global Settings later in this document.
2. Create the local endpoint.
a. Click Basic > Setup > Application Integration Framework > Local endpoints.
b. Create a new record by selecting File > New > New. If there are currently no local endpoints
configured, Microsoft Dynamics AX adds a new record by default.
c. In the Company field, select the company account that contains the data.
d. In the Local endpoint field, enter a descriptive name for the endpoint.
3. Create the adapter.
a. Click Basic > Setup > Application Integration Framework > Transport adapters.
b. Create a new record by selecting File > New > New. If there are currently no adapters configured,
Microsoft Dynamics AX adds a new record by default.
c. In the Adapter class field, select AifBizTalkAdapter from the list. It may take a few moments
while Microsoft Dynamics AX scans for transport adapters. Note that you can have only one
adapter for each Adapter class in Microsoft Dynamics AX.
d. In the Name field, enter a descriptive name.
12
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
13. e. Select the Active check box. The Direction field defaults to Receive And Respond.
4. Create the channel. This establishes a relationship between the BizTalk adapter and one or more
BizTalk servers.
a. Click Basic > Setup > Application Integration Framework > Channels.
b. Create a new record by selecting File > New > New. If there are currently no channels configured,
Microsoft Dynamics AX adds a new record by default.
c. In the Channel ID field, enter a short name with no spaces.
d. In the Name field, enter a descriptive name.
e. Click the Active check box.
f. In the Adapter field, select the BizTalk transport adapter that you created.
g. The Direction field defaults to Both specifying that this channel can be used to send or receive
messages. This field cannot be updated.
h. In the Address field, enter a name. Enter the name of the BizTalk group that contains the servers
with which the adapter communicates. This group name does not need to correspond to a BizTalk
group name; however, if all your servers are in the same BizTalk group, you may want the AIF
group to match the BizTalk group for convenience.
i. The Response Channel defaults to the current channel that you are configuring. This specifies that
any responses in synchronous transfers are sent using the same channel that received the request.
This field cannot be updated.
j. Click the Configure button.
k. Create a new record by selecting File > New > New. If there are currently no BizTalk servers
configured, Microsoft Dynamics AX adds a new record by default.
l. In the Server name field, enter the name of the BizTalk server that can connect to this channel.
This is the machine name of the BizTalk server. You can enter multiple BizTalk servers in the grid
and associate them with the new channel.
5. Enable the actions.
a. Click Basic > Setup > Application Integration Framework > Action.
b. Click the Scan and Register button. This step generates the available, out-of-the-box actions. It
may take a few moments while Microsoft Dynamics AX scans the AOT and generates actions.
c. Select the Enabled field for each action that you want to use. An action must be enabled in order
to use the associated document in AIF. For example, if you want to send a sales invoice, select the
Enabled field for the readSalesInvoice action. Actions only need to be enabled once for use by
AIF.
6. Create the endpoint. The endpoint is the external entity that participates in the document exchange in
addition to the local endpoint.
a. Click Basic > Setup > Application Integration Framework > Endpoints.
b. Create a new record by selecting File > New > New. If there are currently no endpoints
configured, Microsoft Dynamics AX adds a new record by default.
c. In the Endpoint ID field, enter a short name with no spaces.
d. In the Name field, enter a descriptive name for the endpoint.
e. On the Constraints tab, select the No Constraints check box. Selecting this check box allows data
to be exchanged regardless of any association.
f. Back on the Overview tab, select the Active check box.
g. In the Local endpoint ID field, select the local endpoint that you created. The local endpoint is the
local Microsoft Dynamics AX installation that participates in a document exchange.
13
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
14. h. On the General tab, ensure that the Outbound channel ID is set to the correct BizTalk channel
that you created.
i. On the Users tab, add users or user groups by selecting a value in the User type field and
selecting the user name or group name in the Application user or group field. This specifies
which users and groups can submit or receive documents for the endpoint.
7. Create the endpoint action policy. This step associates an endpoint with an action.
a. Click Basic > Setup > Application Integration Framework > Endpoints.
b. Click the Action policies button. You must have at least one endpoint created for this button to
be enabled.
c. Create a new record by selecting File > New > New. If there are currently no endpoint action
policies configured, Microsoft Dynamics AX adds a new record by default.
d. In the Action ID field, select an action such as readSalesInvoice.
e. In the Status field, select Enabled. The Class name defaults to the class associated with the action
you selected in the Action ID field.
f. In the Logging Mode field, select Log All.
g. On the General tab, select the Automatically respond to errors field. This ensures that you can
see in BizTalk any AIF errors that occur.
8. Create the endpoint action data policy.
a. Click Basic > Setup > Application Integration Framework > Endpoints.
b. Select an endpoint in the grid and click the Action policies button.
c. Select an endpoint action policy and click the Data Policies button.
d. Click the Enabled field for each of the elements that you want to include in the data exchange.
Use the Set button to enable or disable all of the elements.
9. Configure the AIF services. If you have not already set up the AIF services for inbound and outbound
document transfer, see the Setting up and Configuring AIF Services section later in this document. If
the AIF document processing components are already configured, continue to the next step below.
10. Send or receive documents. See one of the following scenarios below:
Scenario Description
Send a Document Asynchronously to BizTalk Sends a sales invoice asynchronously from AIF to
(internal request) BizTalk where the request originates from inside
Microsoft Dynamics AX. BizTalk saves the sales
invoice to a file.
Send a Document Synchronously to BizTalk Sends a sales order synchronously from AIF to
(external request) BizTalk. The request for the sales order originates as
a message from BizTalk containing the sales order
ID of the order being requested. BizTalk saves the
sale order to a file.
Send a Document Asynchronously to BizTalk Sends a sales order asynchronously from AIF to
(external request) BizTalk. The request for the sales order originates
as a message from BizTalk containing the sales
order ID of the order being requested. Both the
request and the response use the AIF gateway
queues. BizTalk uses correlation to match the
response to the requesting instance of BizTalk and
14
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
15. saves the sale order to a file.
Create a Document Synchronously (external Creates a sales order inside Microsoft Dynamics AX.
request) The request for the sales order originates as a
message from BizTalk containing the sales order
information. AIF sends the sales order ID of the
newly created sales order as a response to BizTalk
synchronously. BizTalk saves the new sales order ID
to a file.
11. Once you have sent documents electronically you may need to research exceptions or edit and
resubmit a message. To find out more about the tools that are available for managing document
exchanges in Microsoft Dynamics AX, see the Managing Document Exchanges section later in this
document.
You have completed configuration of the BizTalk exchange.
Send a Document Asynchronously to BizTalk (internal request)
In this scenario, AIF sends a sales invoice to BizTalk asynchronously. BizTalk receives the sales invoice and
saves it to a file. The sales invoice request originates from within Microsoft Dynamics AX (as opposed to an
external request from BizTalk). To enable a document exchange between AIF and BizTalk, you must first
create a BizTalk assembly in Visual Studio.
Create the BizTalk assembly
1. Open Visual Studio and click File > New > Project.
2. Under Project types, click the BizTalk Projects node.
3. Select Empty BizTalk Server Project.
a. In the Name field, enter a name for the BizTalk project such as ReceiveSalesInvoice.
b. In the Location field, enter a directory location for the project.
c. In the Solution Name field, keep the default solution. You can enter an alternate name if you
want the solution name to be different from the project name.
4. Click OK.
5. Add a reference to the Microsoft Dynamics AX schemas assembly.
a. In the Solution Explorer, right-click the References node and select Add Reference.
b. Click the Browse tab.
c. Browse to the default install location of Program FilesMicrosoft Dynamics AX40ClientBin
Microsoft.Dynamics.BizTak.Adapter.Schemas.dll.
d. Double-click the assembly (.dll file). It will appear in the Selected projects and components grid.
e. Click OK. The assembly reference appears under the References node in the Visual Studio Solution
Explorer.
6. Import the sales invoice schemas.
a. In the Solution Explorer, right-click the project and select Add > Add Generated Items.
b. Under Categories, the Add Adapter Metadata node should be selected. In the Templates pane,
select Add Adapter Metadata.
c. Click Add. The Add Adapter Wizard appears.
15
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
16. d. Select the Microsoft Dynamics AX adapter and click Next.
e. In the Server name field, enter the name of the server running the AOS. The name entered in this
field should be the machine name of the server.
f. In the TCP/IP Port field, enter the port of the AOS server and click Next.
To find the server port, open the Microsoft Dynamics AX Server Configuration Utility by clicking
Start > Administrative Tools > Microsoft Dynamics AX Server Configuration Utility. Select a
configuration in the Configuration field and you will see the port number in the TCP/IP port field
in the Settings frame.
g. In the Schema Import Wizard, you see a list of the document schemas for documents that are
enabled in AIF. Expand the Sales Invoice node and select readSalesInvoice():SalesInvoice
[async]. The other schemas, readSalesInvoice(EntityKey):SalesInvoice [sync] and
readSalesInvoice(EntityKey) [async], apply to the external request scenarios discussed later.
16
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
17. h. Click Finish. A sales invoice schema called SalesInvoiceService_SalesInvoice.xsd can be seen in
the Solution Explorer. An orchestration has also been created. An orchestration is created in Visual
Studio and graphically models a workflow process. Orchestrations are the primary mechanism in
BizTalk for automating a workflow process.
When using automatically generated orchestrations containing message and port types to
implement the actions for a project, you may encounter naming conflicts. To avoid these conflicts,
it’s recommended that you create an orchestration containing the message and port types, and
reference those types from the generated orchestration.
7. Modify the BizTalk orchestration.
a. In the Solution Explorer, double-click the new orchestration called BizTalk Orchestration.odx.
b. Drag a Receive action from the Toolbox to the orchestration. This is the first step in the
orchestration.
c. Drag a Message Assignment action from the Toolbox to be the second step in the orchestration.
d. Drag a Send action from the Toolbox to be the third step in the orchestration.
8. Create a port to receive the sales invoice from AIF.
17
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
18. a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard.
b. Click Next.
c. In the Name field, enter the name of the port such as ReceiveSalesInvoicePort.
d. Click Next.
e. Select Use an existing Port Type and under Available Port Types, select
ReceiveSalesInvoice.SalesInvoiceAsyncResponse.
f. Click Next.
g. In the Port direction of communication field, keep the default of I’ll always be receiving
messages on this port and click Next.
h. Click Finish.
i. Connect the port ReceiveSalesInvoicePort to the receive action by dragging from the green
arrow on the port to the incoming green arrow of the Receive_1 action.
9. Rename the message being received from AIF.
a. In the Orchestration View, expand the Messages node and click the message named Message_1.
b. In the Properties pane, set the Identifier property to a meaningful name such as SalesInvoiceIn.
10. Create a new message to be saved to the file system.
a. In the Orchestration View, right-click the Messages node and select New Message.
18
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
19. b. Select the new message and set the Identifier property to a meaningful name such as
SalesInvoiceOut.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesInvoice.SalesInvoice.
11. Set the message.
a. In the orchestration, click the ConstructMessage_1 shape.
b. Set the Messages Constructed property to SalesInvoiceOut.
c. Click the MessageAssignment_1 shape found within the ConstructMessage_1 shape.
d. In the Expression property, click the ellipses to open the BizTalk Expression Editor.
e. In the BizTalk Expression Editor, set the value of the outbound message to the inbound
message.
f. Click OK.
12. Modify the send action message.
a. Click the Send_1 shape.
b. Set the Message property to SalesInvoiceOut.
13. Create a port to save the sales invoice to a file.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard.
b. Click Next.
19
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
20. c. In the Name field, enter the name of the port such as SaveSalesInvoicePort.
d. Click Next and select Create a new Port Type.
e. In the Port Type Name field, enter a name such as SaveSalesInvoicePortType and click Next.
f. In the Port direction of communication field, select I’ll always be sending messages on this
port and click Next.
g. Click Finish.
h. Connect the port SaveSalesInvoicePort to the send action by dragging from the green arrow on
the port to the outgoing green arrow of the Send_1 action.
14. Activate the receive action.
a. Click the Receive_1 shape.
b. Set the Activate property to True.
15. Set the assembly key file. The BizTalk project assembly must be strong named in order to compile the
project. To create a strong-named assembly, you must specify the key pair file in the project. To create
a key pair file for strong naming, use the Strong Name tool.
a. In the Solution Explorer, right-click the project and select Properties.
20
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
21. b. In the Assembly Key File property, click the Browse button.
21
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
22. c. In the Assembly Key File dialog box, navigate to the path of the key file (.snk) and click Open.
22
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
23. 16. In the project property pages, specify the name of the BizTalk application by expanding the
Configuration Properties node, selecting Deployment, and setting the Application Name property.
17. Click OK to exit.
18. Rebuild the project by right-clicking the project and selecting Rebuild.
19. Deploy the project by right-clicking the project and selecting Deploy. This deploys the assembly to the
specified BizTalk application. If the BizTalk application doesn’t exist, deployment creates the
application.
Configure the BizTalk application
1. Open the BizTalk Server 2006 Administration Console by clicking Start > All Programs >
Microsoft BizTalk Server 2006 > BizTalk Server Administration. If the BizTalk Server 2006
Administration Console is already open, select Action > Refresh to refresh the tree.
2. Expand the Applications node. The BizTalk application is called ReceiveSalesInvoice. Right-click it
and select Configure.
23
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
24. 3. In the navigation pane, click Orchestration_1.
4. In the Host field, select BizTalkServerApplication.
5. In the Receive Ports field, select New receive port.
24
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
25. 6. In the Name field, enter a name such as AxReceivePort. This is the port that receives messages from
AIF.
7. In the navigation pane, click Receive Locations. This is where the messages for this orchestration will
be received.
8. Click New.
9. In the Name field, enter a name such as AxReceiveLocation.
10. In the Type field, select Microsoft Dynamics AX.
25
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
26. 11. In the Receive pipeline field, select XMLReceive.
12. Click the Configure button.
13. Set the Authentication Type property. This specifies the credentials that BizTalk uses to connect to
AIF.
a. If your BizTalk application is already running under the credentials of the Business Connector Proxy
account, set the Authentication Type property to Host User. To verify the Business Connector
Proxy account in Microsoft Dynamics AX, go to Administration > Setup > Security > Business
Connector Proxy.
b. If the BizTalk application is running under the credentials of a user other than the Business
Connector Proxy account, do the following:
i. Set the Authentication Type property to Proxy User.
ii. Set the Proxy User property to the Business Connector Proxy account in domainusername
format.
iii. Set the Proxy Password property to the password of the Business Connector Proxy account.
26
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
27. 14. Set the Gateway User property to the account of a Microsoft Dynamics AX user who has access to the
AIF gateway queues. The property should be in domainusername format.
15. Set the AOS Server property to the name of the AOS server.
16. Set the AOS Port property to the port of the AOS server. You can find the AOS server port by clicking
Start > Administrative Tools > Microsoft Dynamics AX Server Configuration Utility. Instead of
setting the AOS Server and AOS Port properties, you can specify a configuration file in the
Configuration property. For more information about managing server configurations, see the topic
Managing configurations (server) in the Microsoft Dynamics AX Help.
You can modify the Polling Interval property depending on how frequently you want BizTalk to check
this location for messages.
17. Close out of the open dialog boxes by clicking OK.
18. In the Configure Application screen, in the Send Ports/Send Port Groups field, select New send
port. This is the port that saves the sales invoice to a file.
19. In the Name field, enter a name such as SendFilePort.
20. In the Type field, select FILE.
21. In the Send pipeline field, select PassThruTransmit.
22. Click the Configure button.
23. In the Destination folder field, enter the directory path or browse to the folder where you want to
save the sales invoice file.
27
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
28. 24. Click OK to close the FILE Transport Properties dialog box.
28
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
29. 25. Click OK to close the Send Port Properties dialog box. You should now see a receive port named
AxReceivePort and a send port called FileSendPort in your orchestration.
26. Click OK to exit the Configure Application dialog box.
27. In the BizTalk Server 2006 Administration Console, right-click the ReceiveSalesInvoice application
and select Start.
28. Click the Start button. This starts the BizTalk application so that it can send and receive messages.
Send the sales invoice from Microsoft Dynamics AX
1. Open Microsoft Dynamics AX and click Accounts receivable > Sales order.
2. Click Advanced and select an invoice in the grid.
3. Click Inquiries > Invoice > Copy (select Original to send the original invoice). The Invoice menu
option is only available after the sales order has been posted.
The sales invoice can now be seen in the Queue Manager. If the AIF batch services have been started,
the next time those services run, the sales invoice in the queue will be processed.
29
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
30. 4. Verify that BizTalk has received the sales order by checking the directory you specified in the previous
procedure in step 23. You should see an XML document with a name such as {18F819BD-2A3C-4865-
A884-34D2F1CA51E0}.xml. The XML for the sales order will look similar to the following illustration.
There may be a delay from the time the document goes into the queue and when it appears in the
directory depending on how often the AIF batch services run and the value of the polling interval for
the BizTalk receive port.
For more information about sending and receiving documents, see the Sending and Receiving Documents
Electronically section later in this document.
Send a Document Synchronously to BizTalk (external request)
In this scenario, AIF sends a sales order to BizTalk synchronously from a request made by BizTalk. In
synchronous document exchanges using the BizTalk adapter, documents bypass the AIF queues and are
sent directly through the .NET Business Connector. This scenario contains the following steps:
1. BizTalk reads a sales order ID from a file. Reading the sales order ID from a file is arbitrary for the
purposes of this scenario. BizTalk could receive the sales order ID in another manner such as
another BizTalk message or from a Web service.
2. BizTalk sends the sales order ID (also called an entity key in general terms) to AIF and waits for a
response.
3. AIF receives the entity key request and sends the sales order to the waiting BizTalk adapter.
4. BizTalk receives the sales order and saves it to a file.
Note: In Microsoft Dynamics AX, the term entity key refers to the key of a particular entity whether it is a
sales order, invoice, purchase order, and so on. In scenarios where we are sending and receiving sales
orders, the term entity key is interchangeable with the term sales order ID.
To enable a document exchange between AIF and BizTalk, you must first create a BizTalk assembly in
Visual Studio.
30
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
31. Create the BizTalk assembly
1. Open Visual Studio and click File > New > Project.
2. Under Project types, click the BizTalk Projects node.
3. Select Empty BizTalk Server Project.
a. In the Name field, enter a name for the BizTalk project such as ReceiveSalesOrder.
b. In the Location field, enter a directory location for the project.
c. In the Solution Name field, keep the default solution. You can enter an alternate name if you
want the solution name to be different from the project name.
4. Click OK.
5. Add a reference to the Microsoft Dynamics AX schemas assembly.
a. In the Solution Explorer, right-click the References node and select Add Reference.
b. Click the Browse tab.
c. Browse to the default install location of Program FilesMicrosoft Dynamics AX40ClientBin
Microsoft.Dynamics.BizTak.Adapter.Schemas.dll.
d. Double-click the assembly (.dll file). It will appear in the Selected projects and components grid.
e. Click OK. The assembly reference appears under the References node in the Visual Studio Solution
Explorer.
6. Import the sales order schemas.
a. Right-click the project and select Add > Add Generated Items.
b. Under Categories, the Add Adapter Metadata node should be selected. In the Templates pane,
select Add Adapter Metadata.
c. Click Add. The Add Adapter Wizard appears.
d. Select the Microsoft Dynamics AX adapter and click Next.
e. In the Server name field, enter the name of the server running the AOS. The name entered in this
field should be the machine name of the server.
f. In the TCP/IP Port field, enter the port of the AOS server and click Next.
To find the server port, open the Microsoft Dynamics AX Server Configuration Utility by clicking
Start > Administrative Tools > Microsoft Dynamics AX Server Configuration Utility. Select a
configuration in the Configuration field. You will see the port number in the TCP/IP port field in
the Settings frame.
31
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
32. g. In the Schema Import Wizard, you’ll see a list of the document schemas for documents that are
enabled in AIF. Expand the Sales Order node and select readSalesOrder(EntityKey):SalesOrder
[sync].
h. Click Finish. A sales order schema called SalesOrderService_SalesOrder.xsd can be seen in the
Solution Explorer. An orchestration has also been created.
When using automatically generated orchestrations containing message and port types to
implement the actions for a project, you may encounter naming conflicts. To avoid these conflicts,
it’s recommended that you create an orchestration containing the message and port types, and
reference those types from the generated orchestration.
7. Select the schema for the entity key message.
a. In the Solution Explorer, double-click BizTalk Orchestration.odx to open the orchestration.
b. In the Orchestration View, expand the Types node and then expand the Multi-part Message
Types node.
c. Expand the EntityKey node, click the Body node and open the Type property list.
d. In the drop-down list, expand the Schemas node and click Select from referenced assembly.
The Select Artifact Type dialog appears.
32
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
33. e. Expand the Microsoft.Dynamics.BizTalk.Adapter.Schemas node, click the { } Dynamics node,
and then in the Type Name field, select EntityKey.
f. Click OK.
8. Modify the BizTalk orchestration.
a. In the Solution Explorer, double-click the new orchestration called BizTalk Orchestration.odx.
b. Drag a Receive action from the Toolbox to the orchestration to be first step in the orchestration.
This step reads in the entity key from a file.
c. Drag a Message Assignment action from the Toolbox to be the second step in the orchestration.
This step creates the message that is sent to AIF containing the entity key.
d. Drag a Send action from the Toolbox to be the third step in the orchestration. This step sends the
entity key to AIF.
e. Drag a Receive action from the Toolbox to be the fourth step in the orchestration. This step
receives the sales order from AIF.
f. Drag a Message Assignment action from the Toolbox to be the fifth step in the orchestration.
This step creates the sales order to be saved.
33
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
34. g. Drag a Send action from the Toolbox to be the sixth step in the orchestration. This step saves the
sales order as a file.
9. Create a port to read in the sales order ID (entity key).
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port, ReceiveEntityKeyPort for example. Click Next.
c. Select Create a new Port Type.
d. In the Port Type Name field, enter a name for the port such as ReadEntityKeyPortType.
e. Click Next.
f. In the Port direction of communication field, keep the default of I’ll always be receiving
messages on this port and click Next.
g. Click Finish.
10. Create a new message.
a. In the Orchestration View, right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
EntityKeyIn.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrder.EntityKey.
34
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
35. 11. Set the receive action message.
a. Click the Receive_1 shape.
b. Set the Message property to the message you just created, for example, EntityKeyIn.
c. Connect the port ReceiveEntityKeyPort to the receive action by dragging from the green arrow
on the port to the incoming green arrow of the Receive_1 action.
12. Create a port to send the sales order ID (entity key) to AIF and receive the sales order back from AIF.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port such as ReadSalesOrderPort. Click Next.
c. Select Use an existing Port Type and under Available Port Types, select
ReceiveSalesOrder.SalesOrderSync. Click Next.
d. In the Port direction of communication field, keep the default of I’ll be sending a request and
receiving a response and click Next.
e. Click Finish. You’ll now see the new port ReadSalesOrderPort that contains both a Request
operation and a Response operation has been created in the orchestration.
f. Connect the port ReadSalesOrderPort to the first send action by dragging from the operation
labeled Request on the port to the green arrow operation of the Send_1 action.
35
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
36. g. Connect the port ReadSalesOrderPort to the second receive action by dragging from the
operation labeled Response on the port to the incoming green arrow of the Receive_2 action.
13. Create a port to save the sales order to a file.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port such as SaveSalesOrderPort. Click Next.
c. Select Create a new Port Type.
d. In the Port Type Name field, enter a name such as SaveSalesOrderPortType and click Next.
e. In the Port direction of communication field, select I’ll always be sending messages on this
port and click Next.
f. Click Finish.
14. Rename the message containing the sales order coming from AIF.
a. Expand the Messages node and click the message named Message_1.
b. In the Properties pane, set the Identifier property to a meaningful name such as SalesOrderIn.
15. Create a new message containing the sales order ID (entity key) to be sent to AIF.
a. Right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
EntityKeyOut.
36
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
37. c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrder.EntityKey.
16. Create a new message containing the sales order to save to the file system.
a. Right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
SalesOrderOut.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrder.SalesOrder.
17. Set the message for the entity key being sent to AIF.
a. In the orchestration, click the ConstructMessage_1 shape.
b. Set the Messages Constructed property to EntityKeyOut.
c. Click the MessageAssignment_1 shape found within the ConstructMessage_1 shape.
d. In the Expression property, click the Browse button to open the BizTalk Expression Editor.
e. In the BizTalk Expression Editor, set the value of the outbound entity key message to the
inbound entity key message.
f. Click OK.
18. Modify the first send action message.
a. Click the Send_1 shape.
37
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
38. b. Set the Message property to EntityKeyOut
19. Set the message for the sales order being saved to a file.
a. In the orchestration, click the ConstructMessage_2 shape.
b. Set the Messages Constructed property to SalesOrderOut.
c. Click the MessageAssignment_2 shape found within the ConstructMessage_2 shape.
d. In the Expression property, click the ellipses to open the BizTalk Expression Editor.
e. In the BizTalk Expression Editor, set the value of the outbound sales order message to the
inbound sales order message. Click OK.
20. Modify the second send action message.
a. Click the Send_2 shape.
b. Set the Message property to SalesOrderOut.
38
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
39. 21. Connect the save sales order port to the send action to save the sales order to a file.
a. Connect the port SaveSalesOrderPort to the second send action by dragging from the Request
operation on the port to the outgoing green arrow of the Send_2 action.
22. Activate the receive action.
a. Click the Receive_1 shape.
b. Set the Activate property to True.
23. Set the assembly key file. The BizTalk project assembly must be strong named in order to compile the
project. To create a strong-named assembly, you must specify the key pair file in the project. To create
a key pair file for strong naming, use the Strong Name tool.
a. In the Solution Explorer, right-click the project and select Properties.
39
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
40. b. In the Assembly Key File property, click the Browse button.
40
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
41. c. In the Assembly Key File dialog box, navigate to the path of the key file (.snk) and click Open.
41
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
42. 24. In the project property pages, specify the name of the BizTalk application by expanding the
Configuration Properties node, selecting Deployment, and setting the Application Name property.
25. Click OK to exit.
26. Rebuild the project by right-clicking the project and selecting Rebuild.
27. Deploy the project by right-clicking the project and selecting Deploy. This deploys the assembly to the
specified BizTalk application. If the BizTalk application doesn’t exist, the deployment process creates
the application.
Configure the BizTalk application
1. Open the BizTalk Server 2006 Administration Console by clicking Start > All Programs >
Microsoft BizTalk Server 2006 > BizTalk Server Administration. If the BizTalk Server 2006
Administration Console is already open, select Action > Refresh to refresh the tree.
2. Expand the Applications node. The BizTalk application is called SendSalesOrderSync. Right-click it
and select Configure.
42
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
43. 3. In the navigation pane, click Orchestration_1.
4. In the Host field, select BizTalkServerApplication.
5. In the Receive Ports field, select New receive port. This is the port that receives the sales order ID
(entity key).
43
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
44. 6. In the Name field, enter a name such as AxFileReceivePort.
7. In the navigation pane, click Receive Locations. This is where the receive port looks for the XML file
containing the entity key to send to AIF.
8. Click New.
9. In the Name field, enter a name such as AxEntityKeys.
10. In the Type field, select FILE.
44
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
45. 11. In the Receive pipeline field, select XMLReceive.
12. Click the Configure button.
45
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
46. 13. In the Receive folder field, enter the directory path or browse to the folder that contains the entity
key to be sent to AIF.
14. Click OK to close out of the open dialog boxes.
15. In the Configure Application screen, in the Outbound Logical Ports field, select
ReadSalesOrderPort.
16. In the Send Ports/Send Port Groups field, select New send port.
17. In the Name field, enter a name such as AxSyncSendPort.
18. In the Type field, select Microsoft Dynamics AX.
19. In the Send pipeline field, select XMLTransmit.
20. In the Receive pipeline field, select XMLReceive.
21. Click the Configure button.
22. Set the Authentication Type property. This specifies the credentials that BizTalk uses to connect to
AIF.
a. If your BizTalk application is already running under the credentials of the Business Connector Proxy
account, set the Authentication Type property to Host User. To verify the Business Connector
Proxy account go to Administration > Setup > Security > Business Connector Proxy.
b. If the BizTalk application is running under the credentials of a user other than the Business
Connector Proxy account, do the following:
46
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
47. i. Set the Authentication Type property to Proxy User.
ii. Set the Proxy User property to the Business Connector Proxy account in domainusername
format.
iii. Set the Proxy Password property to the password of the Business Connector Proxy account.
23. Set the Gateway User property to the account of a Microsoft Dynamics AX user who has access to the
AIF gateway queues. The property should be in domainusername format. This property needs to be
set even though the AIF queues aren’t used in synchronous document exchange.
24. Set the AOS Server property to the name of the AOS server.
25. Set the AOS Port property to the port of the AOS server. You can find the AOS server port by clicking
Start > Administrative Tools > Microsoft Dynamics AX Server Configuration Utility. Instead of
setting the AOS Server and AOS Port properties, you can specify a configuration file in the
Configuration property. For more information about managing server configurations, see the topic
Managing configurations (server) in the Microsoft Dynamics AX Help.
You can modify the Polling Interval property depending on how frequently you want BizTalk to check
this location for messages.
26. Click OK to close out of the dialog boxes.
27. In the Configure Application screen, in the Outbound Logical Ports field, select
SaveSalesOrderPort.
47
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
48. 28. In the Send Ports/Send Port Groups field, select New send port. This is the port that saves the sales
order to a file.
29. In the Name field, enter a name such as FileSendPort.
30. In the Type field, select FILE.
31. In the Send pipeline field, select PassThruTransmit.
32. Click the Configure button.
33. In the Destination folder field, enter the directory path or browse to the folder where you want to
save the sales order file.
34. Click OK to close the FILE Transport Properties dialog box.
48
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
49. 35. Click OK to close the Send Port Properties dialog box. You should now see a receive port named
AxFileReceivePort, a send port called AxSyncSendPort, and a send port called FileSendPort in your
orchestration.
36. Click OK to exit the Configure Application dialog box.
37. In the BizTalk Server 2006 Administration Console, right-click the SendSalesOrderSync application
and select Start.
38. Click the Start button. This starts the BizTalk application so that it can send and receive messages.
49
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
50. Send the sales order ID to Microsoft Dynamics AX
1. Create an XML file containing the sales order ID of the sales order to be returned from
Microsoft Dynamics AX. The source endpoint user, source endpoint, destination endpoint, and other
elements of information are contained in the message envelope as seen in the following screen shot.
Following is the sample XML that you can use to create your request message.
<?xml version="1.0" encoding="utf-8"?>
<Envelope xmlns="http://schemas.microsoft.com/dynamics/2006/02/documents/Message">
<Header>
<MessageId>{D0522EFC-A7A3-4E86-855B-7406A6FD0747}</MessageId>
<SourceEndpointUser>contosomclark</SourceEndpointUser>
<SourceEndpoint>EP</SourceEndpoint>
<DestinationEndpoint>LocalEP</DestinationEndpoint>
<Action>ReadSalesOrder</Action>
<RequestMessageId></RequestMessageId>
</Header>
<Body>
<EntityKey
xmlns="http://schemas.microsoft.com/dynamics/2006/02/documents/EntityKey"><KeyData><KeyField><Fie
ld>SalesId</Field><Value>00016_036</Value></KeyField></KeyData></EntityKey>
</Body>
</Envelope>
2. Copy this file to the directory specified previously in step 13.
3. Verify that BizTalk has sent the request and received the sales order by checking the directory you
specified previously in step 38. You should see an XML document with a name such as {B264E9B5-
50
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
51. 15E0-41EC-9667-782D67B774F1}.xml. This is the sales order returned by the request as shown in the
following illustration.
Send a Document Asynchronously to BizTalk (External Request)
In this scenario, AIF sends a sales order to BizTalk asynchronously from a request made by BizTalk. This
scenario is the same concept as the previous scenario, however, the request containing the sales order ID
and the response sales order are sent asynchronously. In asynchronous document exchanges using the
BizTalk adapter, the documents use the AIF queues in Microsoft Dynamics AX. You must use correlation in
the BizTalk orchestration to send the sales order back to the instance of BizTalk that requested it. This
scenario contains the following steps:
1. BizTalk reads a sales order ID from a file. Reading the sales order ID from a file is arbitrary for the
purposes of this scenario. BizTalk could receive the sales order ID in another manner such as
another BizTalk message or from a Web service.
2. BizTalk sends the sales order ID (also called an entity key in general terms) asynchronously to AIF
through the AIF queue.
3. AIF receives the entity key request and sends the sales order asynchronously to BizTalk through
the AIF queue.
4. BizTalk retrieves the requested sales order from the AIF queue and saves it to a file. Through
correlation, the sales order returned to BizTalk is related to the BizTalk instance that requested it.
51
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
52. To enable a document exchange between AIF and BizTalk, you must first create a BizTalk assembly in
Microsoft® Visual Studio®.
Create the BizTalk assembly
1. Open Microsoft Visual Studio and click File > New > Project.
2. Under Project types, click the BizTalk Projects node.
3. Select Empty BizTalk Server Project.
a. In the Name field, enter a name for the BizTalk project such as ReceiveSalesOrderAsync.
b. In the Location field, enter a directory location for the project.
c. In the Solution Name field, keep the default solution. You can enter an alternate name if you
want the solution name to be different from the project name.
4. Click OK.
5. Add a reference to the Microsoft Dynamics AX schemas assembly.
a. In the Solution Explorer, right-click the References node and select Add Reference.
b. Click the Browse tab.
c. Browse to the default install location of Program FilesMicrosoft Dynamics AX40ClientBin
Microsoft.Dynamics.BizTak.Adapter.Schemas.dll.
d. Double-click the assembly (.dll file). It will appear in the Selected projects and components grid.
e. Click OK. The assembly reference appears under the References node in the Visual Studio Solution
Explorer.
6. Import the sales order schemas.
a. Right-click the project and select Add > Add Generated Items.
b. Under Categories, the Add Adapter Metadata node should be selected. In the Templates pane,
select Add Adapter Metadata.
c. Click Add. The Add Adapter Wizard appears.
d. Select the Microsoft Dynamics AX adapter and click Next.
e. In the Server name field, enter the name of the server running the AOS. The name entered in this
field should be the machine name of the server.
f. In the TCP/IP Port field, enter the port of the AOS server and click Next.
To find the server port, open the Microsoft Dynamics AX Server Configuration Utility by clicking
Start > Administrative Tools > Microsoft Dynamics AX Server Configuration Utility. Select a
configuration in the Configuration field and you’ll find the port number in the TCP/IP port field
in the Settings frame.
52
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
53. g. In the Schema Import Wizard, you’ll see a list of the document schemas for documents that are
enabled in AIF. Expand the Sales Order node and select readSalesOrder(EntityKey) [async] (for
sending the sales order ID to AIF) and readSalesOrder( ):SalesOrder [async] (for sending the
response back to BizTalk).
h. Click Finish. A sales order schema called SalesOrderService_SalesOrder.xsd can be seen in the
Solution Explorer. An orchestration has also been created.
When using automatically generated orchestrations containing message and port types to
implement the actions for a project, you may encounter naming conflicts. To avoid these conflicts,
it’s recommended that you create an orchestration containing the message and port types, and
reference those types from the generated orchestration.
7. Select the schema for the entity key message.
a. In the Solution Explorer, double-click BizTalk Orchestration.odx to open the orchestration.
b. In the Orchestration View, expand the Types node and then expand the Multi-part Message
Types node.
c. Expand the EntityKey node, click the Body node and open the Type property dropdown list.
d. In the dropdown list, expand the Schemas node and click Select from referenced assembly. The
Select Artifact Type dialog appears.
53
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
54. e. Expand the Microsoft.Dynamics.BizTalk.Adapter.Schemas node, click the { } Dynamics node,
and then in the Type Name field, select EntityKey.
f. Click OK.
8. Modify the BizTalk orchestration.
a. In the Solution Explorer, double-click the new orchestration called BizTalk Orchestration.odx.
b. Drag a Receive action from the Toolbox to the orchestration to be first step in the orchestration.
This step reads in the entity key from a file.
c. Drag a Message Assignment action from the Toolbox to be the second step in the orchestration.
This step creates the message that is sent to AIF containing the entity key.
d. Drag a Send action from the Toolbox to be the third step in the orchestration. This step sends the
entity key to AIF.
e. Drag a Receive action from the Toolbox to be the fourth step in the orchestration. This step
receives the sales order from AIF.
f. Drag a Message Assignment action from the Toolbox to be the fifth step in the orchestration.
This step creates the sales order to be saved.
54
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
55. g. Drag a Send action from the Toolbox to be the sixth step in the orchestration. This step saves the
sales order as a file.
9. Create a port to read in the sales order ID (entity key).
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port, ReceiveEntityKeyPort for example. Click Next.
c. Select Create a new Port Type.
d. In the Port Type Name field, enter a name for the port such as ReadEntityKeyPortType. Click
Next.
e. In the Port direction of communication field, keep the default of I’ll always be receiving
messages on this port and click Next.
f. Click Finish.
10. Create a new message.
a. In the Orchestration View, right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
EntityKeyIn.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrder.EntityKey.
55
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
56. 11. Set the receive action message.
a. Click the Receive_1 shape.
b. Set the Message property to the message you just created, for example, EntityKeyIn.
c. Connect the port ReceiveEntityKeyPort to the receive action by dragging from the green arrow
on the Request operation to the incoming green arrow of the Receive_1 action.
12. Create a port to send the sales order ID (entity key) to AIF.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port, SendEntityKeyPort for example. Click Next.
c. Select Create a new Port Type.
d. In the Port Type Name field, enter a name such as SendEntityKeyAxPortType and click Next.
e. In the Port direction of communication field, keep the default of I’ll always be sending
messages on this port and click Next.
f. Click Finish. You’ll now see the new port SendEntityKeyPort that contains a Request operation.
13. Create a port to receive the sales order back from AIF.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port, for example, ReceiveSalesOrderPort. Click Next.
c. Select Create a new Port Type.
56
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
57. d. In the Port Type Name field, enter a name such as ReceiveSalesOrderAxPortType and click
Next.
e. In the Port direction of communication field, keep the default of I’ll always be receiving
messages on this port and click Next.
f. Click Finish. You’ll now see the new port ReceiveSalesOrderPort that contains a Request
operation has been created in the orchestration.
14. Create a port to save the sales order to a file.
a. Double-click the Port action in the Toolbox to open the Port Configuration Wizard. Click Next.
b. In the Name field, enter the name of the port, for example, SaveSalesOrderPort. Click Next.
c. Select Create a new Port Type.
d. In the Port Type Name field, enter a name such as SaveSalesOrderPortType and click Next.
e. In the Port direction of communication field, select I’ll always be sending messages on this
port and click Next.
f. Click Finish.
15. Create a new message containing the sales order ID (entity key) to be sent to AIF.
a. Right-click the Messages node and select New Message.
57
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
58. b. Select the new message and set the Identifier property to a meaningful name such as
EntityKeyOut.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrderAsync.EntityKey.
16. Create a new message containing the sales order coming from AIF.
a. Right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
SalesOrderIn.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrderAsync.SalesOrder.
17. Create a new message containing the sales order to be saved to the file system.
a. Right-click the Messages node and select New Message.
b. Select the new message and set the Identifier property to a meaningful name such as
SalesOrderOut.
c. In the Message Type property, expand the Multi-part Message Types node and select
ReceiveSalesOrderAsync.SalesOrder.
18. Set the value of the message for the entity being sent to AIF.
a. In the orchestration, click the ConstructMessage_1 shape.
b. Set the Messages Constructed property to EntityKeyOut.
c. Click the MessageAssignment_1 shape found within the ConstructMessage_1 shape.
d. In the Expression property, click the ellipses to open the BizTalk Expression Editor.
58
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
59. e. In the BizTalk Expression Editor, set the value of the outbound entity key message to the
inbound entity key message.
f. Click OK.
19. Modify the first send action message.
a. Click the Send_1 shape.
b. Set the Message property to EntityKeyOut.
20. Modify the second receive action message.
a. Click the Receive_2 shape.
b. Set the Message property to SalesOrderIn.
21. Set the value of the message for the sales order being saved to a file.
a. In the orchestration, click the ConstructMessage_2 shape.
b. Set the Messages Constructed property to SalesOrderOut.
c. Click the MessageAssignment_2 shape found within the ConstructMessage_2 shape.
d. In the Expression property, click the ellipses to open the BizTalk Expression Editor.
59
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
60. e. In the BizTalk Expression Editor, set the value of the outbound sales order message to the
inbound sales order message.
f. Click OK.
22. Modify the second send action message.
a. Click the Send_2 shape.
b. Set the Message property to SalesOrderOut.
23. Connect the port SendEntityKeyPort to the first send action by dragging from the operation labeled
Request on the port to the green arrow operation of the Send_1 action.
60
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
61. 24. Connect the port ReceiveSalesOrderPort to the second receive action by dragging from the
operation labeled Request on the port to the incoming green arrow of the Receive_2 action.
25. Connect the port SaveSalesOrderPort to the second send action by dragging from the Request
operation on the port to the outgoing green arrow of the Send_2 action.
26. Create the correlation to correlate the response message (the sales order) with the request message
(the entity key).
a. In the Orchestration View, click Correlation Types and select New Correlation Type.
b. In the Available Properties tree, expand the Dynamics node and select RequestMessageId.
c. Click Add.
d. Click OK.
27. Rename the new correlation type by clicking it and setting the Identifier property, for example,
RequestMessageIdCorType.
28. Create a new correlation set.
a. Click Correlation Sets and select New Correlation Set.
b. Set the Identifier property to something meaningful like RequestMessageIdCorSet.
c. Set the Correlation Type property to ReceiveSalesOrderAsync.RequestMessageIdCorType.
61
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE
62. 29. Rename the new correlation set by clicking it and setting the Identifier property,
RequestMessageIdCorSet for example.
30. Implement the correlation set in the orchestration.
a. Click the Send_1 shape and set the Initializing Correlation Sets property to
RequestMessageIdCorSet.
b. Click the Receive_2 shape and set the Following Correlation Sets property to
RequestMessageIdCorSet.
31. Set the RequestMessageId of the message sending the entity key to AIF. The RequestMessageId is set
to the original MessageId so that when the sales order response is returned to BizTalk, the message
can be correlated through the RequestMessageId values of the original message and the response
message.
a. Click the MessageAssignment_1 shape found within the ConstructMessage_1 shape.
b. In the Expression property, click the ellipses to open the BizTalk Expression Editor.
c. In the BizTalk Expression Editor, set the value of the RequestMessageId.
d. Click OK.
32. Activate the receive action.
a. Click the Receive_1 shape.
b. Set the Activate property to True.
62
CONFIGURING THE APPLICATION INTEGRATION FRAMEWORK (AIF) BIZTALK ADAPTER FOR DATA EXCHANGE