Configuring the Application Integration Framework (AIF) for Data Exchange

MicrosoftDynamics™AX

Configuring the Application Integration Framework (AIF) for Data Exchange

White Paper

Instructions for configuring AIF to exchange data using adapters or Web services.

Date: November 13, 2006

http://www.microsoft.com/dynamics/ax/
Table of Contents

Introduction 4

Overview of AIF Configuration 4

Setting up an Adapter-Based Exchange 6

Setting Up and Configuring an MSMQ Exchange 9

Install and configure MSMQ 9

Install and configure the MSMQ adapter 10

Setting up and Configuring a File System Exchange 13

Configure the file system directories 13

Install and configure the file system adapter 13

Setting up and Configuring an Outbound Web Service Exchange 16

Configure the Web service in IIS 16

Install and configure the Web services adapter 16

Configuring Global Settings 18

Configure the resource locking interval 19

Configure the Web methods global setting 19

Configure the default encoding format 19

Configure the outbound schema validation 19

Setting up and Configuring AIF Services 20

Sending and Receiving Documents Electronically 21

Sending documents automatically 22

Sending documents manually 23

Receiving documents 24

Managing Document Exchanges 27

View document history 27

View the exception logs 28

Manage the AIF queues 28

Setting Up an Inbound Web Service Exchange 29

Configuring AIF for Web Services 32

Set up the Web services environment 32

Install the AIF Web services 33

Configure IIS 34

Create the Web service 36

Configure AIF 37

AIF Resources 38

Introduction

This document provides instructions for configuring the Application Integration Framework (AIF) for data exchange in MicrosoftDynamics™AX.

Overview of AIF Configuration

The Application Integration Framework (AIF) provides an extensible framework that enables the exchange of documents in XML format from within MicrosoftDynamicsAX. The AIF replaces the Commerce Gateway for MicrosoftDynamicsAX 3.0 (formerly Microsoft Business Solutions—Axapta 3.0), and provides a more secure business-to-business and application-to-application integration between MicrosoftDynamicsAX and trading partners or other software systems.

In AIF, an exchange can be inbound or outbound.

·  Inbound exchange: One in which your MicrosoftDynamicsAX system accepts data as input.

·  Outbound exchange: An exchange in which your 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, MicrosoftDynamicsAX would receive the request, retrieve the requested information from the database, and return it to the requesting system with appropriate filtering and security.

Within AIF there are two types of exchanges, and each has different requirements for installation and configuration.

·  Adapter-based exchange: Asynchronous document exchanges that use adapters in MicrosoftDynamicsAX and do not require the installation of Microsoft®Internet Information Server (IIS). Adapter transports supported by AIF are:

·  Message queuing (also known as MSMQ)

·  File system

·  Microsoft®BizTalk® server

·  Outbound Web service

·  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 MicrosoftDynamicsAX 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 adapters for MSMQ, file system, and outbound Web service transports, as well as how to set up a Web service exchange. The process to set up and configure a BizTalk adapter is covered in the Microsoft Dynamics AX documentation available on MSDN.

An exchange starts with a document (based on a document class) defined using MicrosoftDynamicsAX 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 MicrosoftDynamicsAX 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 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 an Adapter-Based Exchange

A core installation of MicrosoftDynamicsAX includes the software to enable adapter-based connections. After a connection is configured and processing is initiated by starting the MicrosoftDynamicsAX 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.

To set up an adapter-based exchange you must first set up and configure the transport. The adapter transports available with MicrosoftDynamicsAX 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 MicrosoftDynamicsAX 4.0. The BizTalk adapter is part of MicrosoftDynamicsAX 4.0 Service Pack 1. This white paper can be used to configure AIF whether you have either version installed. Regardless of the adapter type, you must first configure the elements of the exchange, including:

·  Local endpoint

·  Actions

·  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 1.

Figure 1 – Required and optional steps to configure an adapter in MicrosoftDynamicsAX.

Setting Up and Configuring an MSMQ Exchange

The following steps explain how to set up MicrosoftDynamicsAX for data exchange using Message Queuing (MSMQ). This includes configuring the MSMQ adapter as well as MSMQ itself.

Install and configure MSMQ

An adapter for MSMQ is included with your Dynamics AX installation. Note that if you need to send signed messages, such as to other MicrosoftDynamicsAX installations, you must run the Application Object Server (AOS) service under a domain account. By default, the AOS service runs under the Network Service account. Using the default service account can be an issue when using AIF because when the AOS is running as Network Service it cannot send signed messages.

When sending a signed message, AIF will validate that the sending user is a current user in the Microsoft®ActiveDirectory®directory service. The Network Service account is not in Active Directory so the message signing process will fail. MicrosoftDynamicsAX requires that incoming messages be signed so if you want to send documents from one MicrosoftDynamicsAX installation to another, the messages must be signed. If the receiver of the documents doesn’t require a signature, you can send them unsigned and it won’t be an issue if the AOS runs under the Network Service account.

The rules for message signature and AOS accounts are as follows:

·  Unsigned messages can be sent whether the AOS is running as the Network Service account or a domain user.

·  Signed messages can only be sent if the AOS is running as a domain user.

To send documents using MSMQ, you must install MSMQ on a computer in your network and create at least one public queue. When sending documents, the queue can be on any computer in your network.

To receive documents using MSMQ, you must install MSMQ and create at least one queue. When running MicrosoftDynamicsAX 4.0, the queue used to receive documents must be located on the computer running the AOS that is configured to run the batch jobs that operate on the AIF queues. When running MicrosoftDynamicsAX 4.0 Service Pack 1, the queue used to receive documents can be located on any computer in your network. Use the following steps to set up and configure MSMQ for document exchange:

1.  Install MSMQ on a Windows Server 2003 computer.

a.  Click Start > Settings > Control Panel > Add or Remove Programs > Add/Remove Windows Components.

b.  Select Application Server.

c.  Click Details and select Message Queuing.

d.  Click Details, and select Active Directory Integration and Common.

e.  Click OK twice, and then click Next to install.

2.  Create a queue. A queue for inbound messages can be either private or public; a queue for outbound messages must be public.

a.  Click Start > Settings > Control Panel > Administrative Tools > Computer Management.

b.  Under Services and Applications, expand the Message Queuing folder.

c.  To create a new public queue, right-click the Public Queues folder and click New Public Queue.

d.  To create a new private queue, right-click the Private Queues folder and click New > Private Queue.

e.  Enter a name for the queue.

f.  Click the Transactional field and click OK.

3.  Configure the queue for sending or receiving documents.

AIF requires all inbound messages to be authenticated. When using MSMQ, authenticated messages are passed to AIF through authenticated or unauthenticated queues. AIF does not provide authentication for outbound messages, so you must configure outbound queues to be unauthenticated.

a.  Click Start > Settings > Control Panel > Administrative Tools > Computer Management.

b.  Under Services and Applications, expand the Message Queuing folder.

c.  Right-click the queue you created and click Properties.

d.  When configuring an inbound queue, on the General tab, select the Authenticated field. When configuring an outbound queue, clear the Authenticated field. Inbound messages must be authenticated for successful transfer to the local endpoint.

e.  On the Security tab, set the ACLs appropriately for all queues. When configuring the ACLs for newly created MSMQ queues, ensure that the current, logged-in user retains full control over each queue. If the currently logged-in user is denied certain privileges, they may be locked out of the queue and unable to make changes.

By default, the Everyone and Anonymous Logon users can send messages to any newly created queue. Only the creator of the queue and an administrator can receive messages from the queues.

f.  For inbound queues, select Allow on Receive Message and Peek Message for the AOS account (the domain account or Network Service account associated with the AOS instance). Select Allow on Send Message, Get Properties, and Get Permissions for endpoint users only.

g.  For outbound queues, set the ACLs to select Allow on Send Message, Get Properties, and Get Permissions for the Anonymous Logon user. Select Allow on Receive Message and Peek Message for endpoint users only.

h.  For outbound queues, set the ACLs to select Allow on Send Message, Get Properties, and Get Permissions for the Anonymous Logon user. Select Allow on Receive Message and Peek Message for endpoint users only.

i.  If the inbound queue is not on the same machine as the AOS, then two additional entries need to be added to the ACL. First, add the account for the AOS computer (for example, domain-name\computer-name$), and select Allow on Peek Message and Receive Message. Second, grant the Peek Message and Receive Message permissions for the Anonymous Logon user.

j.  On the Security tab, click Advanced.

k.  On the Owner tab, in the Current owner of this item field, enter the user name of the logged-in user who performs the document exchange.

l.  Click OK to exit the menus.

m.  Log off and then log back on to the computer.

Install and configure the MSMQ adapter

Once you have MSMQ configured, you must set up the MSMQ adapter in MicrosoftDynamicsAX.

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, MicrosoftDynamicsAX 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, MicrosoftDynamicsAX adds a new record by default.

c.  In the Adapter class field, select AifMSMQAdapter from the list. It may take a few moments while MicrosoftDynamicsAX scans for transport adapters. Note that you can have only one adapter for each Adapter class in MicrosoftDynamicsAX.

d.  In the Name field, enter a descriptive name.

e.  Select the Active check box. The Direction field defaults to Receive or Send.

4.  Create the channel. The channel associates the adapter with an MSMQ queue.

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, MicrosoftDynamicsAX adds a new record by default.

c.  In the Channel ID field, enter a short name with no spaces.