Setting up AIF to use web services

In some cases, setting up a filesystem transport adapter, as we did in the previous post, can satisfy simple document exchange needs. However, most document exchange methods utilize web services to transfer documents. Most web services utilize the Simple Object Access Protocol (SOAP) to transfer XML messages.
For more information on web services and what they are, refer to: http://en.wikipedia.org/wiki/Web_service.
This post provides the process of how to set up AIF to exchange documents using web services. Much of the process is the same as using and setting up the filesystem adapter since we must also specify both local and external endpoints and channels. We can even reuse the settings we already created for
the filesystem adapter without having to reconfigure for web services. However, additional steps are required for specifically using web services as a means of document exchange.

Creating an AIF website
Before we install the AIF web service extension, a website in IIS must be created to successfully run the installer. This allows you to also determine which port the AIF web service will listen on. The process of creating a website for the AIF is no different than creating a generic website in IIS. For more information on creating websites in IIS,
refer to: http://technet.microsoft.com/en-us/library/cc772350(WS.10).aspx.

Installing the AIF web service extension
By now you should be accustomed to the process of installing the extended components for Dynamics AX. The following steps will guide you through the process of installing the AIF integration component:
1. Run the Microsoft Dynamics AX Setup wizard to add new components. In the Add or modify components screen of the wizard, mark the AIF Web services checkbox, as shown in the following screenshot and then click on the Next button.

2. In the following screen of the wizard, specify the password for the .NET Business Connector, and then click on the Next button when complete.

3. In the next section, you can select which website you want to install the AIF web service component into. Select the website that you recently created the AIF web service for. Additionally, you have the option to specify the application pool and virtual directory name if desired, but its not required.
When the parameters have been set with the appropriate settings, click on the Next button.

Hint:

During this step, the installer prepares to update Dynamics AX with the settings provided. However, this may not fully complete in Windows Server 2008 or 2008 R2.

4. In the following screen, you ensure that the AOS service account is provided in order for the wizard to properly assign permissions to allow the AOS to access the AIF web service.

5. In the following step, you are prompted to complete the installation of the AIF by clicking on the Finish button.

6. Once installed, you will be prompted with the final screen. The final screen will display the result of the installation of the Dynamics AX 2009 AIF system. If the installation was successful, you will see a green box next to
the installed component. Otherwise, if the box is orange or red, you will want to open the log file after you close the wizard by marking the checkbox at the bottom. It is recommended that IIS be restarted after AIF has been
successfully installed.

If any warnings or errors appeared during the installation of the AIF, review the log file that was generated to find and isolate the issue. In Windows Server 2008 and 2008 R2, it is possible that permissions were not appropriately set on folders that were generated in Dynamics AX. Additionally, the website for the AIF may have not
been updated in Dynamics AX. In the following Link, we will cover the process to manually set these up.

Managing and troubleshooting AIF document exchanges

We will cover the process of common management and troubleshooting tasks on the AIF.

Managing AIF document exchanges

In Dynamics AX, we can check document logs, view document messages, or manually import messages. We can also peak at which documents are in the pipeline
for Dynamics AX to process. This can all be accomplished using the AIF Queue manager form. To access the Queue manager form in Dynamics AX, go to Basic |
Periodic | Application Integration Framework | Queue manager.

To view a history of document exchanges in Dynamics AX, go to Basic | Periodic | Application Integration Framework | Document history. The Document history
form contains detailed information on documents and how they are to be processed.

Methods for troubleshooting
When attempting to diagnose issues with the AIF, there are a couple of methods at your disposal that will assist in isolating issues. The following is a list of possible
methods:
• Consult the AIF Exception Log
• Consult the Windows Event Log
• Consult endpoint's logs
The AIF exception log can be accessed in Dynamics AX by going to Basic | Periodic | Application Integration Framework | Exceptions.

For additional AIF troubleshooting tips refer to: http://technet.microsoft.com/en-us/library/aa548693.aspx

Setting up AIF to use a filesystem adapter

At times, data is exchanged between two systems using a filesystem. In other words, files are placed in a directory and read from a directory. For Dynamics AX to process documents in a filesystem, the AIF must be set up to use a filesystem adapter. To set up a filesystem adapter, perform the following steps:
1. First, we must create a filesystem adapter. To specify the transport adapter, go to Basic | Setup | Application Integration Framework | Transport  adapters. In this example, we will be using the filesystem adapter. Create a
new record and select the AifFileSystemAdapter class.

Hint:

When you create a new record in the Transport adapters form,the system scans for any classes in the AOT that implements the interface class AifIntegrationAdapter. In this example, we will be using the filesystem adapter.

2. Now that you have created the transport adapter, the next step is to activate the transport adapter. To do this, mark the Active field for the AifFileSystemAdapter record.

Specifying channels
Since we have activated the transport adapter that implements the AifFileSystemAdapter, a channel must also be created. A channel defines the transport method for processing documents. Depending on the type of adapter in
use, an address or location is specified for document exchanges. To create a channel, perform the following steps:
1. Before we can set up the channel, we must create the appropriate inbound and outbound folders since we are using the filesystem adapter. Open Windows Explorer and create a new folder called AIF (for example: C:\AIF).

2. Within the newly created AIF folder, create two folders: one called Inbound, which will contain documents received for Dynamics AX to process, and another called Outbound for Dynamics AX to place documents that will
be sent.

3. Now that the folders have been created, we need to set permissions for the AIF folder to allow the AOS service account to be able to modify the folder contents. To do this, right-click on the AIF folder and click on Properties.

4. In the AIF Properties window, go to the Security tab.

5. Click on the Edit… button to modify the permissions on the folder.

6. Click on Add… to add the AOS service account. When complete, click on the OK button.

7. Now that the AOS service account has been added, we need to allow Full Control permissions. When completed click on OK to save the changes.

8. Now that the folders are created and the permissions are set, we can specify the folders as appropriate channels for the filesystem adapter. Go to Basic | Setup | Application Integration Framework | Channels. Create a new record and then click on the General tab and fill in the appropriate fields. In this step, we will create an Inbound Channel, which is the channel that will handle incoming documents.

9. In order to process data and send data to be processed by other systems, we must now create an Outbound Channel. The process is the same as when configuring an Inbound Channel, as shown in the following screenshot:

10. In order to associate the Outbound Channel to the Inbound Channel, we must explicitly specify that relation. To do this, select the Inbound Channel previously created in the Channel form and specify the Response channel
to the newly created Outbound field, as shown in the following screenshot. Therefore, the system can respond independently to the Inbound Channel after incoming requests.

Hint: In a multi-AOS environment such as a clustered or load-balanced setup, any AOS can process documents if they are available to do so. To enable this feature, mark the Parallel processing checkbox. This method allows
documents to be processed more quickly.

11. After one or more channels have been set up, you must define actions that can be utilized by the AIF service. To do this, go to Basic | Setup | Application Integration Framework | Action. You have the flexibility to
enable up to six actions per service (create, read, find, findKeys, update, and delete). To enable an action, simply mark the action's Enabled field.

Specifying external endpoints
External endpoints in Dynamics AX are simply referred to as Endpoints. When an endpoint is set up, you can control various options, such as which services and actions are available to external systems. There can be multiple endpoints for a single transport method of document exchange. In this section, we will cover the process of
setting a simple endpoint.
1. In Dynamics AX, go to Basic | Setup | Application Integration Framework | Endpoints to load the Endpoints form.

2. In the Endpoints form, create a new record. Specify the local endpoint that we previously created and save the record.

3. Before we can proceed, we must disable or enable constraints. Constraints are used to control which data is available to specific warehouses, vendors, customers, and so on. In this example, we will disable constraints.

4. Now we can enable actions that will be available for use to an external system. To create an action, click on the Action policies button.

Hint: Endpoint actions will be available only if they are enabled on the specified service in Basic | Setup | Application Integration Framework | Services.

5. In this example, we will simply allow a read action on a specific service. To do this, click on the lookup button on the Action ID field and select a read action on an available service (for example: CustCustomerService.read).

6. By default, the action is disabled. To enable the action, so that it is available to an external system, change the Status field value to Enabled.

7. With the endpoint's action now enabled, we can specify further restrictions or policies, such as which fields are permitted. To do this, click on the Data policies button. This will open the Parameter Data Policies form.

8. Click on the Data policies button to open the Endpoint action data policies form.

9. To make a field available on the service for an endpoint, it must be enabled. To enable a field for access, mark the Enabled field (to quickly enable all fields click on Set | Enable all). To make a field as a required field when
inserting a new record or querying a service, mark the Required field. Some fields may already be marked Required if they are mandatory fields because on the table level, the fields have been specified as mandatory fields.

10. In the General tab, specify an Outbound channel ID and mark the Active
field to enable the endpoint.

Now that we have specified all the steps necessary for creating a file adapter for document exchange, documents can now be created and placed in the Inbound folder. Dynamics AX will then read the documents in the Inbound folder in the order they are created, process them, and output results in the Outbound folder for access. If this process does not work as expected, the following section will show you how to troubleshoot such issues.