Blog |

How to build Dynamics AX2012 code/integrations while planning a migration to Dynamics 365 Finance and Supply Chain Management

We have many Microsoft Dynamics Partners who still have their customers on Dynamics AX 2009 or 2012, but are planning their migration to Dynamics 365 Finance and Supply Chain Management (formerly known as Finance and Operations). They may even have their current legacy codebase already analyzed and relevant customizations evaluated to be moved to Dynamics 365 Finance and Supply Chain Management. However, while the migration is being planned and budgeted, their technical teams are still supporting on-premises Dynamics AX implementations, and are still implementing fixes and change requests for their Dynamics AX applications.

As you may know, migrating Dynamics AX customizations to Dynamics 365 Finance and Supply Chain Management extensions usually requires extensive effort. Inevitably, these latest changes will also have to be added to the solution migration scope, potentially inflating the effort required to move the system to Dynamics 365 Finance and Supply Chain Management. This brings us to the question that our Dynamics Partners often come to us with: can Dynamics AX customizations be Dynamics 365 Finance and Supply Chain Management extension-friendly?

Through our extensive experience with Dynamics AX to Dynamics 365 Finance and Supply Chain Management migration projects, we have gathered tips and techniques for building Dynamics AX customizations that are as compatible with Dynamics 365 Finance and Supply Chain Management as the platform allows.

Building Dynamics AX2012 code

Code modifications in AX2012 can be generally split into two major categories:

  1. Custom Code (such as new classes and methods) in AX2012 is generally compatible with Dynamics 365 Finance and Supply Chain Management, so overall, you don‘t need to worry too much about it. Completely custom build classes in x++ can be directly transferred to Extension models in Dynamics 365 F&SCM. However, there are some exceptions. For instance, if the custom class is a child class for some standard class, and that class is customized to enable inheritance by adding intrusive modification (such as changing access modifier). There are also cases where unsupported frameworks may be used in custom code, which would require re-design when migrated to Dynamics 365. To avoid that, it is recommended that you avoid using code that has already been marked as obsolete in AX2012, and to adhere to best practices when building custom x++ code.
  1. Customized Standard Code that is customizing standard classes and tables. The general rule of building Dynamics 365 friendly code customizations is to avoid intrusive customizations. Intrusive customizations can generally be categorized as one of two types – type definition changes or breaks to encapsulation. More info on intrusive customizations can be found on the Microsoft Docs page.

Want some real-world examples of how these customizations can be avoided? When building code customizations, try to build your code extensions compatible with Dynamics 365. One way to do this is by creating dummy pre- and post-event handler methods that could host the customization code. Later, this code could easily be transferred to Dynamics 365 F&SCM event handlers. This should be quite easy to achieve in extension-friendly scenarios, such as modified field, insert, update, and validate methods. In more complex scenarios, such as in the middle of a standard code piece, it may require extra effort to incorporate the fake event handler – but it would also be hard to add an extension in Dynamics 365, so the effort will pay off later.

Data Structure customizations

Data Structure customizations in AX2012 are generally compatible with Dynamics 365 F&SCM. However, there are a few extra steps you may want to consider when implementing Data Structure customizations that will be upgraded to Dynamics 365 F&SCM:

  1. Avoid customizing individual fields. If you need to change the properties of a table field, it is always best to do these modifications on the Extended Data Type that the field is based on. This will come in handy when upgrading to Dynamics 365 F&SCM.
  2. Be careful with index modifications. Table index customizations are very limited in Dynamics 365 F&SCM. If you need to add indexes for performance tuning, always create new indexes instead of customizing existing ones. If you need to modify the primary index to add extra index fields, this is considered a breaking modification, and you should build a related table instead. Otherwise, it is likely that not only the index customizations be considered breaking changes, but so will all logic surrounding this modification, and the whole thing will have to be re-designed on Dynamics 365 F&SCM.

Building Dynamics AX 2012 integrations

 The general problem with AX2012 integrations is that they quite often rely on technologies and frameworks that are deprecated in Dynamics 365. These deprecations are caused by a couple of factors:

  • Dynamics 365 is a cloud-hosted system and all integration patterns that relied on on-premises deployment are now deprecated. These include file-based integrations relying on the on-premises or network storage and direct SQL integrations.
  • There are also integration patterns that rely on frameworks that are no longer supported, COM objects for Microsoft Office file integrations and AIF Document services being the most popular amongst those.

Let‘s see how such issues could be worked around to build Dynamics 365 compatible integrations already on AX2012:

API integrations
The most popular framework used to build AX2012 integrations is AIF Document services. Despite its popularity in previous versions, the support for it has been dropped in Dynamics 365 F&SCM, and all integrations based on it have to be re-designed while migrating the solution to Dynamics 365. Additionally, the integrating application or middleware must also be adjusted to accommodate changed integration protocol and message. To avoid this scenario, it is best to avoid using AIF Document services and use custom AIF services instead. It may require more effort to build these integrations compared to AIF Document services, but they have a tendency to provide better performance and they are still fully supported in Dynamics 365 F&SCM. It is also important to highlight that you should not redesign existing AIF Document services-based integrations, as you’ll probably be replacing those with ODATA API integrations in Dynamics 365, but in case you do need to build a new API for integration in AX2012, AIF custom services should be the technology of choice.

File-based integrations
In AX2012 you’re probably using either AIF Document services with some file transformation, or you’re using a custom batch job that periodically scans network location and works with files in these locations. Additionally, you may also be using COM object API to read and write Microsoft Excel files. Unfortunately, all of these popular integration patterns are no longer supported in Dynamics 365. To avoid rebuilding these types of integrations when migrating to Dynamics 365, the following integration patterns should be considered: for XML file import and export, custom X++ classes leveraging XML API could be used instead of AIF Document services. Migrating this code would be an almost copy-and-paste action. Custom periodic jobs to import from network location could ideally already be replaced or updated to utilize cloud storage, such as Azure BLOB storage. This will save the extra effort of completely rebuilding such integrations in Dynamics 365.

If there’s a need to handle Microsoft Excel files, a timeless alternative is .csv files. However, there may be specific requirements that require integration to use a specific Excel template, and working with .xls or .xlsx files is necessary. In that case it is generally advised to use OpenXML API – this is a supported pattern in Dynamics 365 and x++ code built consuming this API won’t have to be redesigned. Data import/export framework is also a popular integration platform used to load data into and extract it from the system. This framework has been replaced by data entities concept and data management in Dynamics 365, however, no coding can be saved as these techniques are completely different.

If you are considering moving to Dynamics 365 Finance and Supply Chain Management and would like to know how much time and effort will it take and what is the best possible approach for it, check out Companial’s (1ClickFactory’s) BestPath Assessment service that is available for all Microsoft Dynamics partners!

For more information you can watch my latest webinar and if you have any questions, don‘t hesitate to reach out to us at!

Paulius Brezgys