Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Microsoft Dynamics AX 2012 Connector

Select

Latest version: 1.2.0

The Microsoft Dynamics AX 2012 Connector enables Mule applications to interact with the Microsoft Dynamics AX Query Service. Microsoft Dynamics AX is an enterprise resource planning (ERP) application.

The Microsoft Dynamics AX 2012 Connector supports these operations:

Operation Description

Query table

Run a query against an Application Object Tree (AOT) Table. For more information, see the Microsoft AOT table site. 

Static query

Run an AOT static query

Document Service

Call an AIF Document Service

Prerequisites

The following prerequisites must be satisfied before running the Dynamics AX connector:

  • Install the Windows Gateway Services. Just go through the wizard by clicking the Install button if you plan to use this connector alone, otherwise take a look at its reference documentation for settings that apply to other connectors as well.

Windows Gateway Services for Anypoint Platform

The Windows Gateway Services perform protocol translation when calling the Dynamics AX System Services. The Dynamics AX System Services (Metadata Service, Query Service) use the net.tcp protocol which is not implemented in Java.

To execute requests, the connector routes the requests through the Windows Gateway Services as follows:

  1. The connector sends an HTTP request to the Windows Gateway Services.

  2. The Windows Gateway Services receives the HTTP request.

  3. The Windows Gateway Services executes the request against the Dynamics AX System Services using the net.tcp protocol.

  4. The Windows Gateway Services receives the response from the Dynamics AX System Services.

  5. The Windows Gateway Services sends the response to the connector over HTTP.

  6. The connector receives the response.

All communication between the Anypoint Platform and Windows Gateway Services is authenticated and secured by SSL.

protocol-translation

Installation

To install the Microsoft Dynamics AX 2012 Connector in Anypoint Studio:

  1. Under the Help menu in Anypoint Studio, click Install New Software.

  2. From Work with drop down, click Anypoint Connectors Update Site.

  3. Expand the Select category and click the checkbox for Microsoft Dynamics AX 2012 Connector. Click  Next.

  4. Review the details of the item you selected, and click Next.

  5. Select I accept the terms of the license agreement and click Finish.

  6. Click Restart Now to complete the installation.

  7. After Studio restarts, expand the Connectors palette group to see your recently added Microsoft Dynamics AX 2012 Connector.

Getting Started

Step 1: Create a New Mule Project

Open Anypoint Studio and create a new project:

  1. From the menu, select File > New > Mule Project.

  2. In the New Mule Project window, enter ax-demo as the Project Name.

  3. Click Finish.

Step 2: Create and Configure a New Microsoft Dynamics AX Global Element

Configure the connector’s connection:

  1. Click the Global Elements tab.

  2. Click Create to bring up Global Type dialog box.

  3. In the Search text box, enter ax.

  4. Select Microsoft Dynamics AX: Gateway Connection and click OK.

  5. Fill in the required parameters:

    Parameter Description

    Username

    The username to connect to Dynamics AX.

    Password

    The password to connect to Dynamics AX.

    AOS Server Name

    The name or IP of the server on which the Application Object Server is running.

    AOS Services WSDL Port

    (v 1.1.0 and newer) The port number that the WSDL Services runs on. The default port number is 8101.

    Gateway Router Service Uri

    The address (host and port) of the Windows Gateway Services. This address is usually similar to https://[server_with_windows_gateway_services].com:9333/router (refer to Prerequisites) if you haven’t changed the Windows Gateway Services routing service configuration, otherwise use the port you have chosen.

    AOS Services Endpoint Port (Optional)

    (v 1.1.0 and newer) Use this configuration to override the service endpoint that is specified in the Services' WSDL document.

    Connection timeout (Optional)

    Use this setting to configure the timeout to use while establishing a connection with the Windows Gateway Services. If you want to configure an infinite timeout then set it to zero (value is in milliseconds).

    Reception timeout (Optional)

    Use this setting to configure the timeout to use when sending/receiving data through the Windows Gateway Services. If you want to configure an infinite timeout then set it to zero (value is in milliseconds).

  6. Click Test Connection to make sure the connection works correctly.

  7. Once the connection is successful, click OK.

Step 3: Create a Flow to Query Dynamics AX

Creating a Mule flow to query the "ProjTable".

query-table-flow

To create the Mule flow, follow these steps:

  1. Click the Message Flow tab.

  2. Search for http and drag an HTTP connector onto the canvas. This creates a new flow.

  3. Search for ax and drag the Microsoft Dynamics AX 2012 connector next to the HTTP connector, in the Process area.

  4. Search for json and drag an Object to JSON transformer next to Microsoft Dynamics AX 2012.

  5. Double-click the HTTP connector. Click the plus sign (+) beside the Connector Configuration list.

  6. In the HTTP Listener Configuration window, make sure Protocol is set to HTTPHost is set to All Interfaces [0.0.0.0] (Default) and Port is set to 8081. Click OK.

  7. Under Basic Settings, set the Path to /query.

  8. Double-click  Microsoft Dynamics AX 2012 and update the following configuration values:

    1. From the Connector Configuration list, select the Microsoft Dynamics AX 2012  Connector configuration that was previously created.

    2. From the Operation list, select Query table.

    3. From the Language list, click DataSense Query Language.

    4. Click Query Builder…

    5. From the list of Types, select ProjTable.

    6. From the list of Fields, select ProjId and ProjGroupId.

    7. From Order By list, select ProjId.

    8. From Direction list, select DESCENDING.

      query-table-config

  9. Click OK.

Step 4: Running the Flow

  1. In Package Explorer, right click demo-ax and select Run As > Mule Application.

  2. Check the console to see when the application starts. You should see the following message if no errors occurred:

    
                 
              
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    + Started app 'ax-demo'                                    +
    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    [main] org.mule.module.launcher.DeploymentDirectoryWatcher:
    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    + Mule is up and kicking (every 5000ms)                     +
    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    [main] org.mule.module.launcher.StartupSummaryDeploymentListener:
    **********************************************************************
    *              - - + DOMAIN + - -               * - - + STATUS + - - *
    **********************************************************************
    * default                                       * DEPLOYED           *
    **********************************************************************
     
    *************************************************************************************
    * - - + APPLICATION + - -            *       - - + DOMAIN + - -      * - - + STATUS *
    *************************************************************************************
    * ax-demo                          * default                       * DEPLOYED       *
    *************************************************************************************
  3. Open an Internet browser and visit http://localhost:8081/query

  4. The list of accounts ordered by descending name should be returned in JSON format (results vary according to your AX instance).

    [{"ProjId":"DAT-000009","ProjGroupId":"Group-2"},{"ProjId":"DAT-000008","ProjGroupId":"Group-1"},{"ProjId":"DAT-000007","ProjGroupId":"Group-0"}]

Use Case Example

Starting the Demo

  1. Import the project folder in Studio.

  2. Update the Microsoft Dynamics AX connection parameters in /src/main/app/mule-app.properties.

  3. Click Test Connection to make sure the connection works correctly.

  4. Run the application.

Running the Demo

The demo includes the following operations:

Datasense

When inbound/outbound ports are not configured over the net.tcp adapter their metadata is not retrieved and, in consequence, they are not shown through Datasense. In addition, net.tcp services that are not deployed within the AOS are not shown either.

Operations

Query Table

Run a query on an AOT table.

Static Query

Run an AOT static query.

Static Query Input

The following table details the operation’s input parameters.

Parameter Description

staticQueryName

The name of the static query to execute.

fetchSize

The size of the page for paging the results.

Message Payload

For static queries that accept input parameters, a Map<String, Object> with the parameter names and values.

Static Query Output

A list with the results of the static query.

Document Service

Document Service Input

The following table details the operation’s input parameters.

Parameter Description

serviceAndSoapActionUri

The Document Service name and the SOAP action URI, concatenated in the format:
service-name soapActionUri

Message Payload

The XML document that is sent to the operation.

Output

The result of invoking the Document Service operation.

Troubleshooting

In case of errors while executing AX operations through the connector, there are a number of steps that you can follow depending on the nature of the issue.

Timeouts

If you receive a timeout while executing any operation using the connector, then you should properly set the Connection timeout & Reception timeout parameters described at the connector’s settings table shown above (Step 2: Create and Configure a New Microsoft Dynamics AX Global Element). In addition to the connector’s timeout settings, there are timeouts that you should check/set at the Windows Gateway Services (who is the responsible of routing your requests to the AX server). For more information please refer to the Windows Gateway Services reference documentation.

Other issues

For other issues it is recommended to see the troubleshooting section at the Windows Gateway Services reference documentation. There are message size related settings (AX configuration) that you can increase if you suspect the issue might be related with the response’s payload of the operation you are executing. In addition, within that section, there are many helpful tips on tracing/debugging that could give you insights on what could be causing the problem.