Wednesday, July 25, 2012

Creating Country-Specific Features in AX 2012

One of the new features in Dynamics AX 2012 is the country-specific features. In previous releases, country-specific features were available through configuration keys. Configuration keys however are global, meaning when turned on those features appear in all companies in your Dynamics AX environment.

In Dynamics AX 2012 these configuration keys are still there, and you still can disable/enable these configuration keys. However, to avoid confusion in legal entities that are in other countries, a new feature will make the user interface "adapt" to the country your legal entity is in, or, depending on the setup, the country of the data you are working with.

Let's create some code to illustrate this functionality and how it works.
First, my setup here is using the Contoso Demo Data. I'm the "CEU" legal entity. Since the country features will look at that entity's primary address country by default, let's make sure we know what it is.
Go to Organization Administration > Setup > Organization > Legal Entities. In the Addresses FastTab, select the primary address and click More Options > Advanced.

On the Country/region field, right-click and select "View Details". The reason we go through all of this is that the country-specific features use the country ISO codes, so you want to make sure you capture the correct ISO code for the address. In my case here, the address uses "USA" as the country, but the ISO code is "US".

Let's dive into the code. We're going to create a table with 2 string-type fields. One regular field, one field that is tied to the country features. To shorten the exercise I won't bother with data types or labels, but of course you should always use those in your code! :-)

Right-click the Country_US field and select "Properties". On the properties window enter US in the CountryRegionCodes property. Note that you can specify a comma-separated list of ISO country codes in case you need the field in multiple regions.

Next, we'll create a form for this table. I just added a grid and put the two fields on it. I dragged my table onto the "data sources" node, and from there dragged the two fields onto the grid. You gotta love MorphX drag and drop.

Now when I open the screen in my US company, as expected, here's what it looks like:

However, when we open this screen in for example CEUF, which is a French demo company, here's what the screen looks like:

In this case, the field we added uses the legal entity's country ISO code to determine visibility of the field. However, we can make this a bit more dynamic by explicitly specifying what is called a "Context Field". By default, the context is the legal entity (and it's primary address' country) the form is running under, however, we can create a field on the table that will indicate the context on a record-by-record basis.
To demonstrate this, let's add a field indicating a "party" (yes, global address book!) the record is for, and a second country-specific field, this time for France.

First, add an Int64 (recid) field to indicate the "entity" (aka party) and a new field that will be France-specific.

On the Party field, select the extended data type "DirPartyRecId" (make sure your field is Int64 type). This will also prompt you to add the relation to your table. Say yes, as this will enable the alternate key lookup.

For the new Country_FR field, make sure to set the "CountryRegionCodes" property to "FR" and select our new Party field as the "CountryRegionContextField".

Next, change our original Country_US field to use the new CountryRegion field as the context, by setting the "CountryRegionContextField" property on that field to "Party".

Finally, we'll need to add both fields on our form. First, you need to refresh the form to pick up the newly added fields on the table. In case you don't know, the quickest and easiest way to accomplish that is to right-click the form and select "restore". This will also reload the table and make the new fields available. Open the Data Sources node and expand the DMCountryExample table... drag the new fields onto the grid in the design. By dragging the Party field, you will automatically get the ReferenceGroup added. If you are manually adding controls to the grid, make sure to add the reference group for the Party so you get the alternate key lookup correctly.

So now for the grand finale... Let's open the form and add two records, one with a US party, one with an FR party. You may have to go through your parties and find USA and FRA records, or perhaps add a primary address to one of the parties and set them so you know they work.

This is what that looks like in a US company:

If you would blank out the Name for one, both fields will show the n/a symbol.

And of course, in the French company, this screen looks exactly the same, as the fields are now tied to the party and no longer to the default of legal entity!


  1. This comment has been removed by the author.

  2. Good job joris! I didn't know about this feature..

  3. Prima zoals je dit even uitlegt!

  4. Hi Joris

    We seem to have problems with these country specific fields when we are using virtual companies. That is when the table is in the table collection and the company is part of a virtual company.

    Do you know if there is any way to fix this problem?


    1. Sounds like it's resolving the legal entity based on the dataareaid, which is bad. I would open a case with Microsoft support on this, they will either have a fix or should make one for you!

  5. Hi joris,
    Thank you for informative post,i am having a different scenario I want Company specific customization in same country under same environment.


    1. There is no framework for that per se. You either create parameters an then people can turn it on or off in a specific company (you do have to hide/show the fields yourself using code). Or you can use security settings which would hide/show the fields based on security settings. That requires a bit more work on your customization to have enough security settings, but it will simplify the hiding and showing part for sure.

  6. Hi Joris,

    Thank you for the topic.

    Just want to add some info.

    If form main data source has the CrossCompanyAutoQuery property set to Yes then the Country specific feature is not working.
    It is because such form can have data from different companies.

    Example of such forms: CustOpenTrans

    So this form contains all fields for all countries and User can not hide ones through setup.

    Sincerely this Country specific approach is inconvenient and raw.