The Neuron ESB Dynamics AX Connector (adapter) provides direct access to Microsoft Dynamics AX 2012 and later.  Using this adapter, organizations can easily integrate their business applications such as SAP, NetSuite or Marketo with Dynamics AX.  This adapter operates in both subscribe as well as solicit/response (or query) mode.  Organizations can use the adapter to execute any service exposed by the Application Integration Framework (AIF).  When developing applications that utilize this adapter, developers will be able to use the Adapter Metadata Generation Wizard to provide XML schemas and samples that describe the request and/or response documents that are exchanged with Dynamics AX.

Note – This adapter supports only on-premises versions of Dynamics AX 2012, Dynamics AX 2012 R2 and Dynamics AX 2012 R3.

Before reading this

If you are not familiar with Neuron ESB Adapters, take a moment to consult our online help.

This document assumes you have the following knowledge:

1. What adapters are and how they are leveraged in Neuron ESB
2. Register a Neuron ESB Adapter within a Neuron ESB Solution
3. Create an Adapter Endpoint in a Neuron ESB Solution
4. Set a Neuron ESB Adapter Endpoint Properties
5. Invoke a Neuron ESB Adapter Endpoint

This adapter provides a bridge between Neuron ESB and the services exposed by the Dynamics AX Application Integration Framework (AIF).  The AIF can be configured to expose services over multiple protocols – Http, NetTcp, MSMQ and Files.  This adapter support integration with AIF services exposed over Http and NetTcp.

• For an overview of the Application Integration Framework: https://technet.microsoft.com/en-us/library/gg731810.aspx
• Here is a walkthrough for setting up a service exposed via Http: https://technet.microsoft.com/en-us/library/hh496418.aspx
• Here is a walkthrough for setting up a service exposed via NetTcp: https://technet.microsoft.com/en-us/library/hh352231.aspx

Supported Modes

The Dynamics AX Adapter only supports Solicit Response mode which is used to send request-reply calls to Dynamics AX.  All calls to Dynamics AX will return a response.  The response will match exactly what is returned by the AIF service call.  The response returned is based on the configuration of the service operation in AIF

Dynamics AX Adapter Properties

Every Neuron ESB Adapter has design time properties that can be configured within a standard Microsoft property grid (as shown below). These properties are used to determine the behavior of the adapter at runtime.  The group of Connection properties is used to configure the Dynamics AX Application Object Server name and port numbers, along with the security credentials used when sending requests to Dynamics AX.

AOS Server Name

This is the DNS name or the IP address of the Dynamics AX Application Object Server.

AOS Services Port Number

This is the port number for the services hosted by the Dynamics AX Application Object Server.  The default port number is 8201.  All NetTcp services are hosted by the Application Object Server.  Http services can be hosted either by the Application Object Server or IIS.  You should contact your Dynamics AX administrator for the appropriate services port number.

AOS WSDL Port Number

This is the port number where the WSDLs for NetTcp-based services can be retrieved.  You should contact your Dynamics AX administrator for the appropriate services port number.

Security Method

There are two choices for which security model to use – the Neuron service account or a set of configured security credentials.  To use the Neuron service account, just select ServiceAccount from the Security Method dropdown list:

Figure 1: ServiceAccount

To use a different set of credentials for authentication to Dynamics AX, select Windows from the Security Model dropdown list:

Figure 2: On-Premises with Windows Credentials

When you select Windows, four additional properties are displayed:

• Stored Windows Credentials – In Neuron ESB you can create pre-configured credentials in the Neuron ESB Repository. The Store Windows Credentials dropdown list will display any Windows Credentials that have been added.
• Domain – The domain of the Windows credentials that should be used for authentication.
• Username – The user name of the Windows credentials that should be used for authentication.
• Password – The password of the Windows credentials that should be used for authentication.

Service URL

This is the URL that will be used for sending requests to Dynamics CRM.  This property is an editable dropdown list.  In you click the down arrow, Neuron will connect to the AOS server at the AOS Services port number defined in the properties and return a list of services available on that AOS instance.  If you have been provided a URL to call, you can instead just paste that URL into the Service URL text box.

Send Timeout

This is the amount of time in seconds the Dynamics AX Adapter will wait for a reply from Dynamics AX.  The default value is 60 seconds and should be long enough for most calls.  However, if you performing complex queries you may want to extend the timeout.

Max Message Size

This is the maximum size of the response message that will be returned by the service call.

Subscribe Mode Properties

When calling AIF service, a Call Context object can be used to provide information that is used in the execution of the service call such as a unique message ID and the Microsoft Dynamics AX user and company.  These properties are not required.  Any property that you do not provide a value for will default to the system value.

Company

The 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

The Microsoft Dynamics AX LanguageID for the language that is used to display messages. If Language is not specified, then default value is “en-us”.

Logon As User

The Microsoft Dynamics AX user who performs the service operation. Provide the user in the format “domain\user”.  If Logon As User is not specified then either the Neuron ESB service account or the “Run As” credential configured for the adapter endpoint is used.

Message Id

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

The partition that contains data that is referenced by the service operation. The default value for Partition Key is the default partition set for the calling user. This option is available only with Microsoft Dynamics AX 2012 R2 or later.

Using the Dynamics AX Adapter

The Dynamics AX Adapter can be used to make any NetTcp or Http service call exposed by the Application Integration Framework including:

• Document Services
  • Create
  • Read
  • Update
  • Delete
  • Find
  • findkeys
  • getKeys
  • getChangedKeys
• System Services
  • Metadata Service
  • Query Service
  • User Session Service
• Custom Services

The message formats for the above services can be retrieved using the Metadata Generation Wizard.

For more information about the above operations: https://msdn.microsoft.com/en-us/library/mt607901.aspx

When making calls to Dynamics AX using the adapter, creating the request messages can be done in many different ways.  You can use a C# or C# Class step in a process or workflow.  You can also use the Transform – XSLT process step.  You can also pass-thru a SOAP request received by a client connector and route it to a Dynamics AX Adapter endpoint.  This document focuses on creating the requests with a C# step in a process.

Security

As noted previously, the adapter supports using Windows credentials when calling Dynamics AX services.  The adapter handles all the security requirements at runtime.  When you’re constructing a request message to send to Dynamics AX you do not need to worry about setting credentials.

Call Context

You also don’t need to worry about creating the Call Context as part of the request message send to Dynamics AX.  The adapter will automatically create the Call Context based on either the values set in the Dynamics AX adapter endpoint or based on dynamic message properties if they are present.  See Dynamic Message Properties below for more information.

Walk-through: Creating an Adapter Endpoint

This walkthrough has the following requirements:

• An instance of Dynamics AX 2012, 2012 R2 or 2012 R3
• The Dynamics AX demo data loaded
• Follow the steps listed under To create a service group and deploy the basic inbound port located here – https://technet.microsoft.com/en-us/library/jj710374.aspx. This will create the ReadCustomerSG service that the adapter endpoint will be configured to use
• Neuron ESB 3.5.4.1080 or later installed
• A new Neuron Configuration with the following items already created:
  • 1 Topic – Customer
  • 1 Subscriber – CustomerSubscriber
  • 1 Publisher – CustomerPublisher
• The Neuron ESB runtime is configured and started with the above solution
  1. In Neuron ESB Explorer, navigate to Connections->Adapter Registration and click New. Set the name of the adapter to Dynamics AX Adapter and select Dynamics AX Adapter from the Adapter drop-down list.  Click Apply.
     
  2. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to AX Customer Endpoint, select Dynamics AX Adapter from the Adapter drop-down list and select CustomerSubscriber from the Party Id drop-down list.
     
  3. Click on the Properties tab. Enter the Dynamics AX Application Object Server name or IP address and verify the service and WSDL port numbers.  Select Windows as the Security Method and enter the Domain, Username and Password that will be used when making calls to Dynamics AX:
     
  4. In the adapter endpoint properties grid, click on the drop-down arrow for the Service URL property and select the URL for the service you created in Dynamics AX – ReadCustomerSG:
     
  5. Finally, set the Company property to BRMF. The is a Company in the demo data that has valid customers.  Click Apply:
     

In the next walk-through, you will use this adapter endpoint in the Metadata Generation Wizard to retrieve schemas and sample XML messages.

Request and Response Message Formats

The Dynamics AX adapter only supports XML content for request and response messages.  The request and response message formats depends on the service operation being called.  You can retrieve request and response message schemas, as well as XML samples, using the Metadata Generation Wizard described below.

Dynamic Message Properties

The Dynamics AX Adapter supports several message properties that can be used to dynamically change the behavior of the adapter at runtime.  All the message properties have the prefix “dynamicsax”.  For example, if you want to change which Company you are setting in the Call Context on a per-message basis, you could use the following code in a C# step:

context.Data.SetProperty(“dynamicsax”, “Company”, “BRMF”);

These messages properties can control which Dynamics AX AOS Server service requests are sent to.  If the message property ServiceUrl contains a value, then that value will be used and ServerName and PortNumber will be ignored.  If the message property ServiceUrl is not set, then the ServerName and PortNumber properties will be used if they contain a value.

ServiceUrl	This property overrides the Web Service URL to call
ServerName	This property overrides the Dynamics AX AOS Server Name set in the endpoint properties
PortNumber	This property overrides the Dynamics AX AOS Services Port Number set in the endpoint properties

These message properties can be used if you want to dynamically control the credentials used to secure the request message sent to Dynamics AX:

Domain	This property overrides the domain name of the Windows credentials used when calling the Dynamics AX Web service
Username	This property overrides the username of the Windows credentials used when calling the Dynamics AX Web service
Password	This property overrides the password of the Windows credentials used when calling the Dynamics AX Web service

These message properties are used to dynamically control which values are set in the Call Context:

Company	This property overrides the Company for the data on which the operation is performed
Language	This property overrides the LanguageID for the language used to display messages
LogonAsUser	This property overrides the user that is logged for having performed the service operation. Provide the user in the format “domain\user”.
MessageId	This property sets the MessageId that is used to uniquely identify the message.  For end-to-end tracking, you can set this value to the Neuron ESB Message Id:context.Data.SetProperty(“dynamicsax”, “MessageId”, context.Data.Header.MessageId);
PartitionKey	This property overrides the partition key that contains the data that is referenced by this service operation

Walk-through: Using the Metadata Generation Wizard

The Metadata Generation Wizard is a tool that is used to generate sample messages and schema definitions for certain adapters and their operations.  The Metadata Generation Wizard can be used to generate sample XML request and response messages for the Dynamics AX Adapter.  The following guide assumes you have already completed the first walk-through – Creating an Adapter Endoint.

1. First, in Neuron ESB Explorer navigate to Repository->Xml Documents:
   
2. Next, click the Generate button:
   

The Generate button can be accessed from any of the following menus:

In the “Repository” tab in:
– XML Schemas
– XSL Transformations
– XML Documents
– Text Documents
– JSON Documents
– Swagger Documents

In the Connections tab in:
– Adapter Registration
– Adapter Endpoints

3. On the Welcome Page, click Next:
   
4. On the Connect to Data Source page choose an adapter and adapter endpoint. In this case, choose the Dynamics AX Adapter and the adapter endpoint created in the first walk-through.  Click Next:
   
5. For the Dynamics AX adapter, the Category represents all the services that are available at the Service URL that was set in the adapter endpoint. Select a Category (i.e. CustomerService) and then select the Operation (i.e read) you want to perform and add them to the list of Chosen Operations by clicking the Add  More than one operation can be added by choosing each operation and adding it to the list.  Click Next:
   
6. Choose whether to generate sample XML messages (chosen by default) and whether to overwrite the existing documents, if they have already been added, by clicking on the appropriate boxes. Click Next:
   
7. Finally, click Finish to generate the documents:
   

To see the sample request and response messages, navigate to the XML Documents Repository and select the document ReadCustomerSG_CustomerServiceReadRequest.  This is an example of a read request:

<CustomerServiceReadRequest xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance” xmlns=”https://schemas.microsoft.com/dynamics/2008/01/services”> <!–Set the action to https://schemas.microsoft.com/dynamics/2008/01/services/CustomerService/read–> <EntityKeyList xmlns=”https://schemas.microsoft.com/dynamics/2006/02/documents/EntityKeyList”> <EntityKey xmlns=”https://schemas.microsoft.com/dynamics/2006/02/documents/EntityKey”> <KeyData> <KeyField> <Field>Field1</Field> <Value>Value1</Value> </KeyField> </KeyData> </EntityKey> </EntityKeyList> </CustomerServiceReadRequest>

Inside the XML sample there is a comment that tells you which action must be used when calling this particular operation.  To set the action, in a C# step you can use the code:

context.Data.Header.Action = "https://schemas.microsoft.com/dynamics/2008/01/services/CustomerService/read";

You can use these XML samples to guide your development when creating integrations to Dynamics AX.

Walk-through: Testing the Dynamics AX Adapter

This walk-through will show you how to test the Dynamics AX Adapter at runtime.  This assumes you completed the previous walk-throughs and the Neuron ESB Service is configured to host the Neuron configuration you’ve been working on.

1. If you haven’t already done so, save your Neuron Configuration.
2. Open a Neuron Test Client by clicking on the Test Client icon in the Neuron ESB Toolbar and select 1 Test Client:
   
3. When the Neuron Test Client open, select CustomerPublisher form the Party Id drop-down list and click the Connect button:
   
4. In Neuron ESB Explorer, navigate to Repository->XML Documents, and select the document ReadCustomerSG_CustomerServiceReadRequest that you added with the Metadata Generation Wizard in the previous Walk-through. Click on the XML tab and copy the entire contents to the clipboard.
5. In the Neuron Test Client, click on the send tab. Set the Semantic to Request and paste the contents of the clipboard to the  Message text area:
   
6. There is a comment in the XML sample you pasted into the text area. This comment contains the SOAP Action that needs to be used when calling the CustomerService read operation.  Copy this action and past it into the Action text box on the Test Client:
   
7. Finally, you need to set the Key Field and Value. Set the Field to AccountNum and set the Value to BRMF-000001:
   
8. Click the Send button. If everything works correctly, you should see the Recv: counter at the bottom of the Test Client increase by one.  Navigate to the Receive tab to see the response message:
   
9. To format the XML data, right-click in the text area and select Format:
   

If you receive a fault message indicating that the customer does not exist, you may have to search for a customer on Dynamics AX and use that account number instead.