Configure document exchanges with Web services in AIF

In Application Integration Framework (AIF), the following steps are used to set up and manage a document exchange using Web services:

  • Install the prerequisites.

  • Configure the exchange.

  • Configure other AIF settings, if required.

  • Maintain the integration.

Prerequisites

If you are setting up a data exchange that uses Web services, you must first perform these steps:

  1. Install the Web services on the application integration server. This is the gateway computer that sends and receives AIF messages and communicates with one or more AOSs. For more information, see "Install AIF Web Services" in the Microsoft Dynamics AX Installation Guide.

  2. Use the Web sites form to configure the AIF Web site that hosts the Web services. For more information, see Configure Web sites for document exchange

Configure the exchange

To quickly configure a document exchange, follow the steps in the minimal configuration. If you want to customize or modify the document exchange, follow the steps in the extended configuration.

Minimal configuration

To set up a document exchange with the minimal configuration, perform the following steps:

  1. Generate the Web services. In this step, you publish the Web services for external consumption. See Configure services. This step is required.

    This step is the only task that you need to do to enable the AIF Web services. AIF ships with a default endpoint that is used to send or receive data so no endpoint is necessary in the message header. By default, all service operations (for services that have been generated) are enabled for the default endpoint.

    Note

    If the default endpoint is used and records are created in Microsoft Dynamics AX, those records will be associated with the default company of the user that submitted the request.


  2. Grant permissions to the Web service. See Grant permissions to a service. This step is required.

    After you have completed these steps, you can exchange messages with the Web services that you have enabled.

  3. Create the XML message. The message you send to AIF through the Web service will vary in format depending on which service operation you are calling. If you want to create a sales order, then the XML message will contain the create action and the data required to create a sales order in Microsoft Dynamics AX. If you want to request a sales order, then the XML message will contain the read action and the ID of the sales order that you want to retrieve. For more information about messages, see "AIF Messages" in the Microsoft Dynamics AX SDK Help.

  4. Get the Web service URL and call the service. Follow these steps to get the service URL:

    1. Click Start > Administrative tools > Internet Information Services (IIS) Manager.

    2. Expand the Default Web Site node or the Web site node that contains the AIF Web services virtual directory.

    3. Navigate to the virtual directory MicrosoftDynamicsAXAif50. The services appear in the pane on the right side of the screen and have a file name extension of .svc.

    4. Right-click the .svc file and select Browse. An Internet Explorer browser window appears with the service name at the top. The URL to which Internet Explorer points is the URL of the service, for example, http://localhost/MicrosoftDynamicsAXAif50/salesorderservice.svc (you will need the fully-qualified URL without the localhost path in order to successfully call the service).

You must create a program to call the appropriate Web service and pass the message to the service.

Extended configuration

The extended configuration provides more flexibility and options for configuring the AIF components that make up a document exchange. This configuration allows you to create your own endpoints, configure action policies for those endpoints, and specify endpoint action data policies. To set up a document exchange with the extended configuration, perform the following steps:

  1. Generate the Web services. This step publishes the Web services for external consumption. See Configure services. This step is required.

  2. Grant permissions to the Web service. See Grant permissions to a service. This step is required.

  3. Create a local endpoint. See Create and configure local endpoints. This step is required if you are going to create an endpoint in the following step.

  4. Create and configure an endpoint for the external system that will consume the Web services. This is only necessary if you do not use the default endpoint that ships in AIF. See Creating and configuring endpoints. This step is required if you are not going to use the default endpoint.

  5. Configure the endpoint action policy to associate the desired actions with the endpoint. See Configure endpoint action policies. This step is required if you are not going to use the default endpoint.

  6. Configure data policies. See Configure endpoint action data policies. This step is required if you are not going to use the default endpoint.

  7. Create the XML message. The message you send to AIF through the Web service will vary in format depending on which action you are calling. If you want to create a sales order, then the XML message will contain the create action and the data required to create a sales order in Microsoft Dynamics AX. If you want to request a sales order, then the XML message will contain the read action and the ID of the sales order that you want to retrieve. For more information about messages, see "AIF Messages" in the Microsoft Dynamics AX SDK Help.

  8. Get the Web service URL and call service. Follow these steps to get the service URL:

    1. Click Start > Administrative tools > Internet Information Services (IIS) Manager.

    2. Expand the Default Web Site node or the Web site node that contains the AIF Web services virtual directory.

    3. Navigate to the virtual directory MicrosoftDynamicsAXAif50. The services appear in the pane on the right side of the screen and have a file name extension of .svc.

    4. Right-click the .svc file and select Browse. An Internet Explorer browser window appears with the service name at the top. The URL to which Internet Explorer points is the URL of the service, for example, http://localhost/MicrosoftDynamicsAXAif50/salesorderservice.svc.

You must create a program to call the appropriate Web service and pass the message to the service.

Other AIF settings

The following forms can be used when configuring a data exchange regardless of whether you are using the minimal configuration or the extended configuration:

  • Use the Global settings form to configure global defaults for configuring adapters, actions, resource locks for batch processing, and schema validation, as well as the default encoding format for documents. For more information, see Configure global settings for document exchange.

  • Use the Pipeline components form to configure optional document transformations, including XSLT style sheet mapping or value substitutions. For more information, see Creating and configuring a pipeline.

  • Use the Value Mapping form to set up optional predefined value mapping that is available for certain documents. For more information, see About value mapping.

Maintain integration with external software systems

After you have configured a document exchange using AIF, you will need to maintain that integration and possibly troubleshoot any errors that occur. This may include the following tasks:

  • Checking error logs and message queues to monitor traffic.

  • Stopping and restarting the framework when necessary.

  • Reconfiguring the channel and endpoint if conditions change.

  • Viewing the document history and deleting old messages.

For more information, see Manage document exchanges in AIF.

See Also

Web services-based exchanges in AIF

Configure Web sites for document exchange