Customizing a Microsoft Dynamics AX 2012 and Microsoft Dynamics CRM 2011 Integration

If you need to expose a custom table in Microsoft Dynamics AX 2012 for integration to a custom entity in Microsoft Dynamics CRM 2011, then this post is for you!  Let's say that you will be creating a custom entity in Microsoft Dynamics CRM 2011 and that entity really doesn't integrate to one of the out of the box tables in Microsoft Dynamics AX 2012 or that you would like to integrate to a staging table in Microsoft Dynamics AX 2012 and then have your custom Microsoft Dynamics AX 2012 code pick up the data from that table and process it.  For the purposes of this post, we will be creating a "Feature Request" entity in both systems for tracking feature requests from customers. 

This post will outline how to create the table in Microsoft Dynamics AX 2012, how to create the entity in Microsoft Dynamics CRM 2011, how to expose both of those customizations to Connector for Microsoft Dynamics, and finally how to map them together.  This post also assumes that you would like these records to be bi-directionally synced, that is creates and updates in either system will be reflected in the other integrated system.  It should be noted that this post does NOT describe how to support the deletion of custom records in either system.  Currently the integration of deletes for custom records or entities in either Microsoft Dynamics CRM  or Microsoft Dynamics AX is not supported by Connector for Microsoft Dynamics.  If you have already created your custom Microsoft Dynamics AX 2012 artifacts as well as your Microsoft Dynamics CRM 2011 artifacts, then you can skip to this section of this post.

Prerequisites

This post assumes that you have the following set up and installation steps have been completed (more information on Connector for Microsoft Dynamics installation can be found in this post)

1. Microsoft Dynamics CRM Online or Microsoft Dynamics CRM 2011 installed with Update Rollup 11 or above
2. Microsoft Dynamics AX 2012 Cumulative Update 2 or Microsoft Dynamics AX 2012 R2 with change tracking enabled on the Microsoft Dynamics AX 2012 database
3. Connector for Microsoft Dynamics with Microsoft Dynamics AX 2012 and Microsoft Dynamics CRM 2011 Adapters configured
4. An Integration and site for a Microsoft Dynamics AX 2012 Company and a Microsoft Dynamics CRM 2011 Organization have been created

This post also assumes that you are using a user account (s) that can perform the following functions:

1. Microsoft Dynamics CRM customization
2. Microsoft Dynamics AX customization in the AOT
3. Microsoft Dynamics AX AIF document service creation
4. Microsoft Dynamics AX AIF Inbound Port creation and activation

And finally this post assumes that you are comfortable in performing customization actions in both Microsoft Dynamics CRM 2011 and Microsoft Dynamics AX 2012 including the following:

1. Microsoft Dynamics AX custom table
2. Microsoft Dynamics AX AIF Document Service creation
3. Microsoft Dynamics AX custom queries
4. Microsoft Dynamics CRM custom entities
5. Microsoft Dynamics CRM solutions

Customizing Microsoft Dynamics AX to Support Bi-Directional Data Integration

Create Custom Components

 The first step in this guide to customize Microsoft Dynamics AX to support bi-directional data integration is to determine what data you want to integrate in Microsoft Dynamics AX. For the purpose of this guide we will be creating the following components:

Execute the AIF Document Service Wizard

 Execute the AIF Document Service Wizard to create a new Document Service. 

 Notes:   You may need to either implement the cacheObject method or delete the cacheObject method from the AxFeatureRequest class. Also you will need to delete the cacheRecordRecord or implement that method as well from the AxFeatureRequest class.

Create an Inbound Port for Your Service Operations

After the wizard is complete we must expose our service via an Inbound Port. This can be done within the Microsoft Dynamics AX client in the System Administration -> Services and Application Integration Framework -> Inbound ports area. Create a new port with the following settings 

Customizing Microsoft Dynamics CRM to Support Bi-Direction Data Integration 

Create Custom Components

Now that the Microsoft Dynamics AX side of things is customized we need to focus on the Microsoft Dynamics CRM customizations that are needed. We will need to create the following components in Microsoft Dynamics CRM

Configuring the Microsoft Dynamics CRM 2011 Adapter

In order to map the custom entity in the Connector for Microsoft Dynamics client we must configure the Microsoft Dynamics CRM 2011 Adapter. This is requires executing that adapter’s configuration utility.

1. Launch the Connector for Microsoft Dynamics Client
2. Click the settings node in the tree view for the already existing Microsoft Dynamics AX 2012 to Microsoft Dynamics CRM 2011 integration
3. Click the link on the right under the Microsoft Dynamics CRM 2011 Settings for the Configure Microsoft Dynamics CRM utility
4. Once the configuration utility has started click “Next”
5. Enter the credentials for a Microsoft Dynamics CRM Administrator account
6. Click Get Organizations
7. Select the Organization where your custom entity exists
8. Click Next
9. Scroll down the tree view of check boxes until you find the “Feature Request” entity. Check the box
10. Check the box for “Skip complete configuration and only generate entity configurations”
11. Click Next
12. Click Configure
13. Click Finish
14. The utility will close

Configuring the Microsoft Dynamics AX 2012 Adapter

In order map the custom AIF document service in the Connector for Microsoft Dynamics client we must configure the Microsoft Dynamics AX 2012 Adapter. This requires executing the adapter configuration utility.

1. Launch the Connector for Microsoft Dynamics Client
2. Click the settings node in the tree view for the already existing Microsoft Dynamics AX 2012 to Microsoft Dynamics CRM 2011 integration
3. Click the link on the right under the Microsoft Dynamics AX 2012 Settings for the Configure Microsoft Dynamics AX utility. (You must run this utility as a Windows user that is in the admin group within Microsoft Dynamics AX 2012)
4. Once the configuration utility has started click Refresh services
5. Check the check box in the tree view for the FeatureRequestDocumentService
6. Click Configure
7. Click the OK button on the message box that is shown
8. Close the Microsoft Dynamics AX 2012 Configuration utility

Important Note:

Due to a limitation that is currently being worked on you must change the QueryName attribute in the object provider configuration file that is generated for your Document Service. You must change the QueryName attribute from the Query your Document Service is based upon to the class name which represents your document. Usually this will be something like Axd<Class Name>. In this case it will be AxdFeatureRequestDocument.

This file can be located in %ProgramFiles(x86)%\Microsoft Dynamics\Microsoft Dynamics Adapter\Adapters\Microsoft.Dynamics.Integration.Adapters.Ax2012\ObjectConfig\<AOSServerName_DocumentPort>\

In this example the file should be called FeatureRequestPort_FeatureRequestDocumentService.config

The XML that needs to be adjusted would look like this before and after the change:

Before:

<RootDefinition Name="AxdEntity_FeatureRequest_1" TypeName="AxdEntity_FeatureRequest_1" DisplayName="Feature Request Document Service" IsRequired="false" IsReadOnly="false" QueryName="FeatureRequestQuery" ID="478ef2fe-b623-4f2f-8460-845df5720444" ServiceName="FeatureRequestDocumentService" PortName="FeatureRequestPort" SupportedOperations="Create, Delete, FindKeys, GetChangedKeys, Read, Update" RootDataSourceName="FeatureRequest_1" KeyInfo="RecId">

After:

<RootDefinition Name="AxdEntity_FeatureRequest_1" TypeName="AxdEntity_FeatureRequest_1" DisplayName="Feature Request Document Service" IsRequired="false" IsReadOnly="false" QueryName="AxdFeatureRequestDocument" ID="478ef2fe-b623-4f2f-8460-845df5720444" ServiceName="FeatureRequestDocumentService" PortName="FeatureRequestPort" SupportedOperations="Create, Delete, FindKeys, GetChangedKeys, Read, Update" RootDataSourceName="FeatureRequest_1" KeyInfo="RecId">

Creating Bi-Directional Maps for Your Microsoft Dynamics AX Document Service and Microsoft Dynamics CRM Custom Entity

In order to get data to flow you must create new maps for your custom document service and custom entity.

Microsoft Dynamics AX 2012 Document Service to Microsoft Dynamics CRM 2011 Custom Entity Map

The first step is to create a map that flows data from Microsoft Dynamics AX to Microsoft Dynamics CRM.

1. Open the Connector for Microsoft Dynamics Client
2. Expand the Integration and Site for your existing Microsoft Dynamics CRM and Microsoft Dynamics AX integration
3. Click Maps nodes
4. Click New Map on the tool bar
5. A dialog window will be shown
6. On the Source Entity list select Feature Request Document Service under Microsoft Dynamics AX 2012 \ <Company Name>
7. On the Destination Entity list select Feature Request under the Microsoft Dynamics CRM 2011 \ <Organization Name>
8. Click Create
9. Perform the following mappings

* CreateGuid is a function in the mapping it will show as =CreateGuid(DAX Integration ID) 

10.   Change the map settings as followings

11.   Save the map

Microsoft Dynamics CRM 2011 Custom Entity to Microsoft Dynamics AX 2012 Document Service Map

Now we must create the map in the other direction.

1. Open the Connector Client
2. Expand the Integration and Site for your existing Microsoft Dynamics CRM and Microsoft Dynamics AX integration
3. Click Maps nodes
4. Click New Map on the tool bar
5. A dialog window will be shown
6. On the Destination Entity list select Feature Request Document Service under Microsoft Dynamics AX 2012 \ <Company Name>
7. On the Source Entity list select Feature Request under the Microsoft Dynamics CRM 2011 \ <Organization Name>
8. Click Create
9. Perform the following mappings

* Concatenate is a function in the mapping it will show as =Concatenate(“{“, Feature Request, “}”)

10.   Change the map settings as followings

11.   Save the map

Testing the Integration

Now that the maps are created we can activate them. 

1. Open the Connector for Microsoft Dynamics Client
2. Expand the Integration and Site for your existing Microsoft Dynamics CRM and Microsoft Dynamics AX integration
3. Click Maps nodes
4. Locate the maps we created and for each map right click the map and click Activate Map
5. Then click the Save button on the tool bar

The final test is to enter some data. For Microsoft Dynamics AX we did not create a form to enter data, but we can do so quickly to make an easy way to enter a record. You can follow the MSDN article on “How to: Create a Simple List Form [AX 2012]” here: msdn.microsoft.com/EN-US/library/hh538488.aspx

For Microsoft Dynamics CRM we can customize the Microsoft Dynamics CRM form to add the fields we want to add.  The data should now be able to flow in both directions.

I would like to personally thank our support engineers for developing this post as well as for assisting all of our customers! Stay tuned for an in-depth video series on this topic as well.