AX 2012 Code Promotion & Environment Refresh

This article is intended for AX Administrators mostly, but new Developers can benefit from this as well. Understand the standard practices for promoting code and refreshing environments will save you lots of problems in the future. Following these practices will make future upgrades much easier with less time spend merging code & troubleshooting conflicts.  

Code Management:  

TFS or VSTS should be used for change control. This is more for developers to be able to manage their code. Some benefits of TFS/VSTS are included below with a description of its uses.  

Version control:  

Multiple developers can work on their own project, in their own workspace and check code in to version control on TFS or VSTS so that it becomes part of the same version for a model. The Check in process also checks for best practices and conflicts.  

Automation: 

You can automate many of the manual processes. For example, Compile, CIL and deploy a model into TEST instance automatically. There are scripts you can download from Microsoft to get you started and other resources which I have included links for. I have also included additional links to articles that cover automation for more details.  

Build and deploy scripts for Microsoft Dynamics AX 2012 

Great article by Martin Dráb 

Dynamics AX Admin scripts for 2009 and 2012  

Instances required:  

Your AX environment should at minimum consist of the instances listed below, I have included the intended use of these instances. These instances should be used for their intended purposes only. Otherwise you cannot ensure the reliability of the code be promoted and the testing process.  

DEV: 

This is used as the master development server where code can be developed and where models can be exported out of. This Server would be synced with TFS or VSTS.  

TEST: 

Models get promoted into this environment for user testing. A Pass or Fail checklist should be filled out. This checklist should include all modifications needed to be tested by the user requesting the change, or the person effected by the change. If any code doesn’t pass testing the Developer reworks the code in DEV and delivers a new model to be installed and retested. If all tests pass, you install the same model  exported from DEV into STAGING.  

PLAYGROUND: 

This instance is not necessary however, very useful in organizations with functional or financial analysts. This instance allows these users to have System Administrator rights, with current business data from PROD, to accomplish testing otherwise not allowed in PROD, in order to assist users with certain issues. This environment is fully disposable and can be refreshed regularly. This instance is not included in the model promotion process.  

STAGING: 

This is an exact copy of PROD with the exception of setup. This instance is refreshed right before the model gets promoted to it. This is where you do your compile and CIL for PROD and confirm no Compile errors or errors in the CIL. You can start promoting your model here during business hours. Once you have done your Compile and your CIL and no errors have occurred. You export out a modelstore to go into PROD. This saves you at lease 1 hour, because you don’t have to compile or do a CIL in PROD.The Compile and CIL are included in the modelstore.   

PROD: 

This is your live instance.  

AX Layers and their intended uses:  

This Image is taken from Microsoft TechNet. You can see full details at https://msdn.microsoft.com/en-us/library/aa851164.aspx 

The more code modifications you have on deferent layers, the more complex code merges become in future upgrades.  

The Layers mainly used for modifications are ISV, VAR and CUS. each one of these layers has a model which is automatically crated once a modification is made in the layer. Each one if these layers also has a patch layer. The patch layer is used in the case a conflict occurs in your model installation. You can push your conflicts into the Patch layer, then create a project from this layer and perform a code comparison and merges as needed to clear the conflicts.  

This Image is taken from Microsoft TechNet. You can see full details at https://msdn.microsoft.com/en-us/library/aa891248.aspx 

Models: contain the elements in a layer. If you want to move just the modification in the CUS layer. You would export out the model for that layer.  

Modelstores: Contains all layers, their elements, element ID & element handles, CIL & Compilations.  

XPO files: Contain Projects within the layer.  if you are working on a project to create a new security role in the CUS layer. You can export this project as an XPO file. Never import XPO files into an environment that you plan on using to export out models and model stores out of. This can result in ID conflicts.  

The only scenario I would use an XPO file would be in a PLAYGROUND environment. If a developer wanted to load a project, to test with fresh data from a refresh from PROD. The XPO can be imported into PLAYGROUND and would be used as proof of concept so that it can be moved as a model later.   

This Image is taken from Microsoft TechNet. You can see full details at https://technet.microsoft.com/en-us/library/hh335184.aspx 

Model Promotion Steps:  

Steps to Promote your models 

Microsoft Dynamics AX 2012 White Paper: Deploying Customizations Across Microsoft Dynamics AX 2012 Environments:

https://www.microsoft.com/en-us/download/confirmation.aspx?id=26571

Keeping your Instances in Sync:  

It is extremely important to keep you instances in sync. This is the only way you can guaranty the code to work in PROD. For example, let's say in between a model promotion, one of your Developers or Security Admin decided to test something really quick in TEST. The plan was to pull it out once they were done, but as all humans do, they forgot. Now you are ready to promote a model into TEST for users to Pass or Fail. The model actually passes, but only because of the additional changes made only to this instance. The possible result of this is, it goes into PROD and breaks a critical business process. Now, you're doing an emergency maintenance to resolve the issue.  Most importantly, it keeps all your Layers, element ID's & element handles in sync with PROD. That way any ID conflicts can be detected in TEST rather than later in STAGING.  

Procedure to keep your instances in Sync: 

Once you have promoted your modelstore into PROD. Your DBA needs to back up the Business database & put it in a location accessible by the AX Admin. Restore the Business data so that the environments have updated transactions for testing. 

You can restore Business data by utilizing the Test Data Transfer tool (beta). Since this tool is in beta it is not supported by Microsoft. This tool works great, however there are possibilities that not all data will come over to the target environment. This is ok for environments used for DEV purposes. However, it can cause a problem in environments being used for user expectance. The main problem is if data needed for user acceptance didn't transfer the user cant perform their testing. Most of the time this is due to references being lost in the transfer process. Data will appear on the SQL table due to the references being lost the data will not show up on the Form.

Another method is to backup and restore your Business data and model database using SQL. This would be an exact copy of Production. Some additional SQL Scripts will need to be used to clean up some of the tables. for example confidential information will need to be wiped or scrambled. Batch jobs should be put on withhold. Print Management settings should be set to defaults. Credit Card processing parameters need to be wiped or set to test parameters and any other parameters that are specific to PROD need to be adjusted.  Below I have included some additional parameters that might need updating after a refresh using SQL Backup and restore.

Document Management Parameters

E-mail Parameters

EP Web sites

Report Servers

System parameters

System Service Accounts

Server Configuration

You can download the TDTT from:  

Test Data Transfer Tool Download 

You can read the TDTT instructions at: 

Instructions to use TDTT 

If you have followed these steps then the model database at this point is exactly the same in TEST, STAGING and PROD. If your developers don’t have System Administrator rights in TEST, STAGING and PROD (Which they shouldn’t) then you are all set.  

If they do have System administrator in any other environment other than DEV. You will have to refresh the model database, before your next model promotion. This is the only way you can guaranty the code matches PROD and no other development has occurred since the last model promotion.  

In turn guarantying that the testing truly passes and new code can move to PROD without the chance of failure. Assuming code was fully tested in TEST.  

Refreshing Model Database: 

The best practice in dealing with the model database is to import the .modelstore file. This is the file used for deploying from STAGING to PROD in your last code promotion. This insures that all layers are the same as they should be. It also validates and protects against possible conflicts with Element IDs.   

Environment Refresh Steps:  

Your DBA backs up the PROD database > the .bak file is placed in a location accessible by AX Admin > TDTT is used to refresh Business data to lower environments> Modelstore is imported to lower environments to insure no code changes are present that don’t exist in PROD.  

Environment Refresh Using SQL Scripts:

If you would like to refresh using SQL backup and restore see links below to get an idea of how you should build your scripts. At the bottom of the article there is a link to a document called 112013_AX2012-TechDomain_M05_MoveEnvironment_edited.docx that has examples of SQL scripts and lots of good information. Make sure to download this document and look it over.

https://blogs.msdn.microsoft.com/axsupport/2011/11/07/moving-between-microsoft-dynamics-ax-2012-environments/

Environment Refresh Using Powershell:

You can also use Powershell to refresh your lower environments. You still would need to specify tables you would like to exclude from coming over from PROD. Below is a great article by Bruno Ferreti (MSFT). He shared his Powershell scripts and detailed instructions on how to use them. At the bottom of the article he has included a link to download the scripts for your own use.

https://blogs.msdn.microsoft.com/axinthefield/ax-data-refresh-with-powershell/

As you can see there are some options available to refreshing your environment. In either case it takes a little time to initially build and test your scripts. You have to find what works best for your environment and what you are most comfortable with using. You can always consult your Microsoft partner to find out which method fits your environment best.