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

Microsoft Dynamics AX 2012 Connector

Introduction

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.

Example Apps Using Connectordynamics-ax-2012-samples.zip

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:

Windows Gateway Services for Anypoint Platform

The Windows Gateway Services agent performs 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

Installing the Connector

You can install the connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Configuring the Connector

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://myserver.com:9333/router.

    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.

    Microsoft Dynamics AX 2012 Connector Global Element < v1.0.0

    v1 and below

    Microsoft Dynamics AX 2012 Connector Global Element v1.1.0 and above

    v1.1.0 and above

  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 the Order By dropdown, select ProjId.

    8. From the Direction dropdown, select DESCENDING.

  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"}]

Using the Connector

Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

If you are manually coding the Mule application in Studio’s XML editor or other text editor, paste these into the header of your Configuration XML, inside the <mule> tag.
<mule xmlns:dynamicsax="http://www.mulesoft.org/schema/mule/dynamicsax"
  ...
  xsi:schemaLocation="http://www.mulesoft.org/schema/mule/dynamicsax http://www.mulesoft.org/schema/mule/dynamicsax/current/mule-dynamicsax.xsd">
  ...
  <flow name="yourFlow">
  ...
  </flow>
</mule>

Using Call Context

The connector supports providing a fixed Call Context within each call that can be setup at the configuration tab with the same name.

Within the configuration section you can set the following:

Setting Description

Company

This is the Microsoft Dynamics AX company for the data on which the service operation is performed. If Company is not specified then the calling user’s default company is used.

Language

This is the Microsoft Dynamics AX LanguageID for the language that is used to display messages. The default value for Language is 'en-us'.

Logon As User

This is the Microsoft Dynamics AX user who performs the service operation. It uses the submitting user (calling user) in the format 'domain\user'. If LogonAsUser is not specified then the user who makes the service operation call is used. The default user depends on the adapter that is selected. For example, when you use the file system adapter the default user is the owner of the folder where the file resides.

Message ID

This is the GUID that uniquely identifies each document. If you do not specify a message ID, the system generates one. However, if you want to identify a particular message for debugging, you must specify the message ID as part of the call context.

Partition Key

This value identifies the partition that contains data that is referenced by the service operation. The default value for PartitionKey is the default partition set for the calling user.

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.

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.


          
       
1
2
3
4
5
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-module-dynamics-ax-2012</artifactId>
  <version>1.1.2</version>
</dependency>

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version. The available versions to date are:

  • 1.1.2

  • 1.1.1

  • 1.1.0

  • 1.0.0

Demo Applications Using the Connector

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: