Title: BizTalk 2013 and AX2012 R2 Receive Services Interface:

Author: Toraj Khavari

Date: January 29 2015

Objective: Use the Microsoft BizTalk’s Send ports to interface with Microsoft Dynamics AX 2012 R2 Application Interface Framework (AIF) receive services. No file drop, directly uses the AX services.

Article Body: Microsoft Dynamics AX AIF services support files drop and direct web service interfaces. BizTalk can support file drops to communicate with Dynamics AX. Interface with the AIF services directly, unwaveringly, have significant advantages. Such as, no need of file drop location, added file location security, disk storage, another server to depend on, etc. As long as the BizTalk server, Dynamics AX Application Object Server (AOS), and Network are available, we have interfaces.

When I started on the BizTalk and Dynamics AX R2 services interface, I had a steep learning curve. I encourage you to put the AX file interface knowledge behind you and look at the interface in a pure Service Oriented Architect (SOA) methodology. Let us review some basics together. All web services interfaces have fundamental Address, Binding, and Contract, also known as, ABC.

·         "A" stands for Address: Where is the service?

·         "B" stands for Binding: How do I talk to the service?

·         "C" stands for Contract: What can the service do for me?

Dynamics AX R2, and higher version, in addition to ABC take full advantage of the web services namespace. The namespaces uniquely identify a set of names so that there is no ambiguity when objects having different origins but the same names are mixed together.

1-      When you receive the Microsoft Dynamics AX AIF services URI, take your favorite browser, paste the URI in the address bar, and study the services. You can get the URI from the AX System Admin or start an AX GUI > Select System administration > Services and Application Integration Framework > Inbound ports (in my case). Find your service. Select it and verify that it is Active. Copy the WSDL URI.  E.g., in my case, the URI as follows.

http://<<Server Name:Port>>/DynamicsAx/Services/PurchInvoice810

I am interested in creating an invoice and using NetTcp BizTalk Adapter. Copy both information.

2-      Write a short C#, or your preferred language, project program and create the Microsoft Dynamics AX AIF services. Study the project’s configuration app.config file and take note of the “userPrincipalName”. You can add Service References to your project in Visual Studio. Select Project > Add Service Reference > Paste the AX Service URI in the Address field > Press OK.

Now that you have done your homework, let us focus on BizTalk project.

3-      Studying and understanding the Ax Services generated schemas are paramount for the next steps successful implementation. Take the time needed to discover the services provided. There are limited documentations available. Because, the AX services and ability to customize them are unbounded. If you invest time in this step, you will save yourself a lot of time for the subsequent steps, deployment, and debugging.

Add an Empty BizTalk Server Project to your solution. In my case, I called it “Adec.VendorsEDI.InboundAdecSchema”. The Microsoft Dynamics AX AIF services are rich and provide significant services. Add a sub folder “AXPurchInvoice810SvcSchema” in the “Adec.VendorsEDI.InboundAdecSchema” to collect all generated schemas in one folder. Select the “AXPurchInvoice810SvcSchema” folder > Right Mouse Click > Select Add Generate Items … > Consume WCF Service > Next > select Metadata Exchange (MEX) endpoint > Next > Paste the URI (step 1) in the Metadata Address (URL) Field > Next > Import. At this point the wizard adds a few schemas to the “AXPurchInvoice810SvcSchema” folder. Take a while and study the schemas. Start with Services schema and get a clear direction of the soap envelop and body constructions. My business requirements were around creating invoices, in this case. Therefore, I focused around Purchase Invoice Service Create Request and its Response.
Delete the default created Orchestration (.odx) file.

4-      Create the first map.  I refer to it as the web services soap’s “Body”. Use the standard BizTalk mapping technologies. However, the key and utmost importance is, use the correct and published schema created in step 3. There is no need of anything else, or other schemas.

5-      The web services require soap envelop. Create the envelop map using the standard BizTalk mapping technologies. The inbound schema, in this case, is the outbound of step 4. The outbound schema is the create service envelop. Use mass copy functoid and copy the entire inbound schema, soap’s “Body”.

6-      In the BizTalk orchestration create the Messages required. A) Cascade two Transform functoids to map the soap’s “Body” and “Envelope”, respectively. Outcome of step 4 and 5. B) Configure a send port and connect it to a Send functoid to expose the soap envelop with embedded body. The Dynamics AX services support request and response ports. I will leave the request and response port handling for another article.

7-      The send port Identifier will play an important role in the BizTalk. In my case it is called “CreateOperation”. No space and no special characters, Select the send port operation and take a note of your Identifier. It will be used in the BizTalk send port “Action”.

8-      At this point, the Visual Studio project is ready. Compile the solution and verify all the Schemas and Maps. Deploy the solution. Validate that the components are deployed in BizTalk, and the server’s GAC (Global Access Cache).

9-      Open the BizTalk Admin tool and the solution in the BizTalk Group. A) Add an WCF-NetTcp Send port. Select the Configure button. B) Copy and paste the Dynamic AX net.tcp UNI in the Address (URI). Result of step 1. C) Create an Action that reflect the Visual Studio orchestration send port Identifier (Result of step 7) and the desired Operation URI (Result of step 1).

<BtsActionMapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <Operation Name="CreateOperation" Action="http://schemas.microsoft.com/dynamics/2008/01/services/PurchaseInvoiceService/create" />

</BtsActionMapping>

D) Select the Edit and enter the User Principal Name. The result of step 2.

10- I increased the WCF-NetTcp Binding timeouts and message size.

11- The Security worked for me only if the Security mode is set to “Transport”, The Transaction client credential type is “Windows”. The “EncyptAndSign” is selected for Transport protection level.  Dynamics AX has its own security. Make sure the User Principal Name and BizTalk runtime service ids are registered in the AX and have appropriate Dynamics AX security credential.

12- The WCF-NetTcp Messages is setup to Body. Apply and save the port.

13- Start the new WCF-NetTcp port and bind it to the Orchestration Outbound port. Start the orchestration.

14- Refresh the BizTalk application and restart the Host Instances.

The solution collection and BizTalk ports are ready for testing. Enjoy new discoveries and have fun debugging.

Hints:

-          Dynamics AX has History and Exceptions logs. Use them in addition to BizTalk events. They are great debugging resources. Start an AX GUI > Select System administration > Services and Application Integration Framework.

-          If you get the following error message, check the port’s Action.

Entity action cannot be specified. Or

‘cannot be processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a contract mismatch (mismatched Actions between sender and receiver) or a binding/security mismatch between the sender and the receiver.  Check that sender and receiver have the same contract and the same binding (including security requirements, e.g. Message, Transport, None).

-          If you see the following error message, check the envelope and body schemas. Most likely, incorrect schemas are used.

The value in field <<Schema Field>> is invalid. Or

Invalid document schema. The following error was returned:  The 'http://schemas.microsoft.com/dynamics/2008/01/documents/<<Schema Name:Node>>' element is not declared.

-          Do not waste too much time doubting the BizTalk Adapters and AX Services. When in absolute doubt, use Network sniffers to validate BizTalk and AX ports communications. There are a few free downloads available on-line.

-          The XML message between BizTalk and Dynamic AX are standard Soap messages. Nothing more or less. There is no need to add or take away from the published schemas. Example is as follows. I encourage you, forget about file drop communication with Dynamics AX, it will help you. Rely on pure soap and SOA.

The interface between BizTalk 2013 and AX 2012 R2 proves to be extremely rewarding.  At times, I wish error messages were more meaningful, and straight forward. The BizTalk and AX proved, once more to me, they are solid, scalable, reliable, and good technologies. I encourage you, if you ever faced system interface challenges, do not compromise and do not listen to unsubstantiated accusations. Learn the sand boxes. Significant knowledge and technologies are invested in the enterprise products such as BizTalk and Dynamics AX. SOA Works!

Happy coding, Toraj

References:

-          Introduction to Building Windows Communication Foundation Services - https://msdn.microsoft.com/en-us/library/aa480190.aspx

-          How to integrate Dynamics AX 2012 R3 AIF Document Service with BizTalk server – Very Good Reference - http://tech.alirazazaidi.com/how-to-integrate-dynamics-ax-2012-r3-aif-document-service-with-biztalk-server/

-          Walkthrough: Consuming WCF Services with the WCF-BasicHttp Adapter - http://msdn.microsoft.com/en-us/library/bb246019.aspx

Version 1.0.0203.01