Dynamics AX: Generating an AIF web service

Now that we have configured the AIF web service in Dynamics AX, we can generate services right from Dynamics AX that will be available for use. Services can be created by developers but Dynamics AX 2009 comes pre-packaged with several services, depending on your licensing scheme. In this section, we will go over the process of generating services.

1. In Dynamics AX, services are specified in the AOT under the Services node.

2. To enable the use of the services in the AOT, go to Basic | Setup |Application Integration Framework | Services.

3. In the AIF Services form, click on the Refresh button. This may take a while because the form will query Dynamics AX for the available services.

4. To choose which services will be available as a web service, select the appropriate service and mark the Enable field.

5. Now that the desired services have been selected to be enabled, the next step
is to automatically generate the web services. To generate these services, click
on the Generate button.

Specifying the authentication method for an AIF web service

Since an AIF web service is a WCF service, all the same rules apply when it comes to specifying authentication methods and many other settings. Such settings allow
greater flexibility when customizing web services to enhance security, performance, and compatibility. When you generate a web service for the AIF, the default method
for authentication is basicHttpBinding. However, in most scenarios, the binding method for authentication should be wsHttpBinding. For more information on
wsHttpBinding, refer to http://msdn.microsoft.com/en-us/library/ms751418.aspx. To change the authentication binding method, we must edit the configuration
file of a web service that was created when the service was generated.

The following steps describe the process of editing the AIF web service configuration file:
1. In Dynamics AX, go to Basic | Setup | Application Integration Framework| Services to load the Services form.

2. Select the service to change the authentication binding method and click on the Configure button. This will load the Microsoft Service
Configuration Editor.

Hint: The Microsoft Service Configuration Editor comes with the Microsoft .NET 3.5 Framework SDK or Windows Server 2008 SDK. This must be
installed in order to properly edit the web service configuration. Although you can use a text editor to make modifications to the configuration file,
it is not best practice, nor is it recommended. The configuration editor ensures that configuration settings are properly formatted.

3. In the Microsoft Service Configuration Editor, collapse the Bindings node to view the current binding. Notice that the default binding method is
basicHttpBinding.

4. We will need to create a wsHttpBinding method for authentication. To create a new binding, right-click on the Bindings folder and click on New Binding
Configuration…. In the Create a New Binding window that pops up, select wsHttpBinding and click on the OK button.

5. A new binding method of type wsHttpBinding, will be created under the Bindings folder. In this example, we will rename it to wsHttpBindingAif.

6. Now that we have created an appropriate binding method for an AIF service, we must associate the binding to the service that was generated,
so that it may be used as a binding method. In the Services folder, collapse the appropriate service (for example: Microsoft.Dynamics.
IntegrationFramework.Service.CustomerService) and collapse the Endpoints folder. Select the listed endpoint, and change the Binding
property to wsHttpBinding. Then in the Binding Configuration property, select the wsHttpBindingAif that we created.

7. Now that the correct binding is set, close the Microsoft Service Configuration Editor and save the modifications that were made. To ensure
that the settings take immediate effect, open the Windows Command Prompt and run iisreset on the web server.

 

Setting the appropriate authentication binding method will ensure that developers, external servers, and end users will be able to access the service appropriately.
Additional methods can be implemented to ensure a stronger security implementation such as SSL.

Creating and configuring an AIF website

The processes of installing AIF already explained in another's spots in this blog such Up to this point, the installer will have created and installed the appropriate libraries. However, in Windows Server 2008 and 2008 R2, the permissions and website setup in Dynamics AX may not have completed. The following process is what is required, so that the AIF website is properly set up for use:
• Apply appropriate permissions
• Specify an AIF website
• Generate an AIF web service
• Specifying the authentication method for an AIF web service
• Accessing the AIF web service

Applying appropriate permissions
During the installation of the AIF web service extension in the Installing the AIF web service extension post, a Content directory was specified in step 3. That directory was created to store the AIF web service files. The installation wizard went ahead and automatically created a network share of the folder. However, due to imitations of the installers in a Windows Server 2008 or 2008 R2 environment, the permissions will not work. The AOS will need access to this directory in order to create, modify, or delete AIF services. To allow this functionality, we need to permit the AOS service account to be able to do this. The following steps outline this process:
1. In Windows Explorer, navigate to the Content directory that was specified in step 3 of the Installing the AIF Web Service Extension section (for example: C:\Program Files\Microsoft Dynamics AX\50).

2. Right-click on the AifWebServices folder and go to Properties.

2. Go to the Security tab and click on the Edit button to edit the permissions on this directory.

Hint: The installer originally created a group Microsoft Dynamics AX Web Service Administrators on the server and assigned the AOS service account as a member of that group.Regardless, you will still have to manually add the AOS service account and apply the appropriate permissions.

3. In the Permission for AifWebServices window, click on the Add… button and then add the AOS service account and click on the OK button.

4. Now we must specify the permission level for the AOS services account. In the Permissions for AifWebServices window, ensure that the newly added AOS service account is selected and allow Full Control. When complete,
click on the OK button to save the modifications.

Specifying an AIF website
Now that we have applied the appropriate permissions to the AIF web service directory, the AOS will now be able to access and modify the directory and contents. This is necessary if you want to use AIF for web services. When services are created in AX, the AIF will be able to generate standard WCF web services and place them in the Content directory. In this section, we will cover the process of specifying this directory.
1. In Dynamics AX, go to Basic | Setup | Application Integration Framework | Web sites.

2. In the Web sites form, create a new record and specify the network share location of the AIF Content directory (it may be easier to go into the General tab and browse the folder manually).

Hint: The Web sites form automatically validates the directory upon creating  the record. If the validation fails and the record cannot be created, verify that the permissions are correct and that the directory exists and is shared.

 

3. Now that the record with the AIF Content directory location has been provided, click on the Validate button to ensure that the AOS will be able to access and modify it appropriately. An Infolog window will display whether the validation was successful or not.

You can follow up links below for rest of this post:

• Generate an AIF web service
• Specifying the authentication method for an AIF web service
• Accessing the AIF web service

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.