Creating Country-Specific Features in AX 2012
Filed under: #daxmusings #bizapps
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!
There is no comment section here, but I would love to hear your thoughts! Get in touch!