Tool: User preferred startup menu for Dynamics AX 2009

In AX 2009, the user has no control over which menu is opened in the navigation pane and address bar when AX client is started. Most of the time you simply get the Home page, which is frustrating for a number of users. Another thing that is frustrating for them is the company account the application opens with. The latter can actually be setup using standard application functionality in the User options form. Just set the 'Start company accounts' to the account you want for the user by default. I wrote a small tool, that allows the user to select a preferred startup menu, ensuring that this menu is the one open every time AX client is started. Something similar existed in Axapta 3.0 application. You can download the xpo for this tool from my SkyDrive. Note, that it contains minor changes to a number of existing application objects. I suggest that you compare the xpo from the import dialog and ensure that you don't override any of your changes during import - the best thing would be to re-implement these minor changes manually. Below is a list of changes that I am referring to above:

• SysUserInfo table - 1 new field was added
• SysUserSetup form - 1 new control was added. Lookup method on datasource field overridden
• Info class - startupPost method changed

In order to enable the functionality, simply select one of the menus in the User options, as shown in the below screenshot. Next time you start AX, the selected menu will be open by default. Below is a short listing of "code patterns" used in the project, that can serve as examples for your future projects:

• SysTableLookup - for displaying a lookup form with a list of menus
• infolog.globalCache() - for storing a global reference to the navigator class
• TreeNode iteration - for finding all menu references in MainMenu
• QueryBuild classes - for constructing and filtering a list of menu references in MainMenu, used in the lookup form
• infolog.addTimeOut() method - for scheduling execution of another method in a set period of time

Tutorial: refresh, reread, research, executeQuery - which one to use?

X++ developers seem to be having a lot of trouble with these 4 datasource methods, no matter how senior they are in AX.
So I decided to make a small hands-on tutorial, demonstrating the common usage scenario for each of the methods. I have ordered the methods based on the impact on the rows being displayed in the grid.
You can download the xpo with the tutorial on my SkyDrive.

1. Common mistakes

Often, developers call 2 of the mentioned methods in the following order:
formDataSource.refresh()
formDataSource.research()
or
formDataSource.reread()
formDataSource.research()
or
formDataSource.research()
formDataSource.executeQuery()
or
formDataSource.research()
formDataSource.refresh() / formDataSource.reread()
All of these are wrong, or at least partially redundant.
Hopefully, after reading the full post, there will be no questions as to why they are wrong. Leave a comment to this post if one of them is still unclear, and I will try to explain in more detail.

2. Refresh

This method basically refreshes the data displayed in the form controls with whatever is stored in the form cache for that particular datasource record. Calling refresh() method will NOT reread the record from the database. So if changes happened to the record in another process, these will not be shown after executing refresh().

refreshEx

Does a redraw of the grid rows, depending on the optional argment for specifying the number of the record to refresh (and this means the actual row number in the grid, which is less useful for AX devs). Special argument values include -1, which means that all records will be redrawn, and -2, which redraws all marked records and records with displayOptions. Default argument value is -2.
This method should be used sparingly, in cases where multiple rows from the grid are updated, resulting in changes in their displayOptions, as an example. So you should avoid using it as a replacement for refresh(), since they actually have completely different implementations in the kernel.
Also, note, that refreshEx() only redraws the grid, so the controls not in the grid might still contain outdated values. Refresh() updates everything, since this is its intention.

3. Reread

Calling reread() will query the database and re-read the current record contents into the datasource form cache. This will not display the changes on the form until a redraw of the grid contents happens (for example, when you navigate away from the row or re-open the form).
You should not use it to refresh the form data if you have through code added or removed records. For this, you would use a different method described below.

How are these 2 methods commonly used?

Usually, when you change some values in the current record through some code (for example, when the user clicks on a button), and update the database by calling update method on the table buffer, you would want to show the user the changes that happened.
In this case, you would call reread() method to update the datasource form cache with the values from the database (this will not update the screen), and then call refresh() to actually redraw the grid and show the changes to the user.

Clicking buttons with SaveRecord == Yes

Each button has a property SaveRecord, which is by default set to Yes. Whenever you click a button, the changes you have done in the current record are saved to the database. So calling reread will not restore the original record values, as some expect. If that is the user expectation, you as a developer should set the property to No.

4. Research

Calling research() will rerun the existing form query against the database, therefore updating the list with new/removed records as well as updating all existing rows. This will honor any existing filters and sorting on the form, that were set by the user.

Research(true)

The research method starting with AX 2009 accepts an optional boolean argument _retainPosition. If you call research(true), the cursor position in the grid will be preserved after the data has been refreshed. This is an extremely useful addition, which solves most of the problems with cursor positioning (findRecord method is the alternative, but this method is very slow).

5. ExecuteQuery

Calling executeQuery() will also rerun the query and update/add/delete the rows in the grid. The difference in behavior from research is described below.
ExecuteQuery should be used if you have modified the query in your code and need to refresh the form to display the data based on the updated query.

formDataSource.queryRun().query() vs formDataSource.query()

An important thing to mention here is that the form has 2 instances of the query object - one is the original datasource query (stored in formDataSource.query()), and the other is the currently used query with any user filters applied (stored in formDataSource.queryRun().query()).
When the research method is called, a new instance of the queryRun is created, using the formDataSource.queryRun().query() as the basis. Therefore, if the user has set up some filters on the displayed data, those will be preserved.
This is useful, for example, when multiple users work with a certain form, each user has his own filters set up for displaying only relevant data, and rows get inserted into the underlying table externally (for example, through AIF).
Calling executeQuery, on the other hand, will use the original query as the basis, therefore removing any user filters.
This is a distinction that everyone should understand when using research/executeQuery methods in order to prevent possible collisions with the user filters when updating the query.

Highlighting your code on Blogger

A couple of people have now asked me for the tool that I use for pasting the source code on my blog.
In order to use the same, you will have to change the template of your blog and include the following scrips:

<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shCore.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushCpp.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushCSharp.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushSql.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushXml.js' type='text/javascript'/>
<link href='http://amalafe.googlecode.com/svn/trunk/Styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://amalafe.googlecode.com/svn/trunk/Styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>
<script type='text/javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://amalafe.googlecode.com/svn/trunk/Scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>

After that, you will be able to create code by specifying the following:

<pre class="brush: c-sharp;">
Your code goes here...
</pre>

Casing and text search/comparison tutorial

I have recently received a question from one of my blog readers.
He was asking about the possibility of doing case-sensitive search in AX.

I would like to reply to that by creating a small tutorial on search in AX. It is definitely not going to cover all the scenarios, but will give beginners a basic understanding of their options.

Download the tutorial xpo from my Skydrive

The tutorial consists of 1 form with 3 tab pages.

1.
Comparing two strings in AX is very simple: You can basically use the equality operator "==". As you can see from the tutorial, this is the case-insensitive operations, so "vanya" is equal to "Vanya".
AX also supports case-sensitive comparison. Kernel function strCmp() compares two strings taking into account the casing of the symbols in the string.

2.
Searching for a substring is a common operation in AX.
For that you have a number of options, as usual:
strScan() function ignores casing and allows you to specify from which position to search, and how many symbols. This is very basic, and a method like this is present in any programming language.
TextBuffer.find() is a more advanced use of the search mechanism. First of all, it allows to ignore or take into account the casing in the source text. Similar to strScan, it allows to specify the start position for the search.
What it also has is support for Regular Expressions, as well as the ability to, for example, paste the text to Windows clipboard.
Lastly, there is the match() function. The main purpose of it is to find a match based on the specified pattern using regular expressions, but nothing prevents using it for a simple search operation. It has a rather limited output though. You only get a boolean value stating whether a match was found or not, while with the previous 2 methods you also get the position of the substring.

Interesting
An interesting discovery that I made when writing the tutorial was about the speed of the different search operations. I have included this into the tutorial, so you can go in and try it yourself on your specific setup.
On my box, strScan() was the slowest operation of all, while TextBuffer, which I considered to be a very heavy class, was performing rather well.

Of course, single operation time compared to database operations is very low, so you won't notice it in your daily work. But it is something to think about.

3.
Finding a symbol in a string based on a specified set of symbols is also possible.
You have 2 functions at your disposal for that: strFind and strNFind. The difference is that strNFind searches for any symbol NOT present in the provided set, compared to strFind.


This is not an extensive list, so I would be interested in hearing which functions you use or what your results for performance comparison would be.

UtcDateTime in Dynamics AX 2009

In Dynamics AX 2009, Microsoft introduced a new data type, UtcDateTime, that is going to eventually replace the 2 existing types, Date and Time, which are still present in the application right now.
Obviously, the introduction of this new type requires a tutorial on how it can be used on forms, how you can filter on fields of this type, as well as what functions are available out of the box for it.
So I have made such a tutorial, and I hope it will be useful for developers upgrading to AX 2009.

Download the xpo for the tutorial from my SkyDrive

The tutorial consists of a single form, containing the following elements:

• a grid, displaying data from CustTable
• 4 buttons for various filtering actions
• 3 controls that allow specifying the filtering conditions for the data

. In the form, you can see how UtcDateTime based controls are displayed both in a regular group and in a grid.



Below is an explanation of the implemented functionality, in form of a Question/Answer section:

1. Q: Can I filter on the new UtcDateTime type, specifying the Date part only?
   A: Yes. You simply have to specify only the date part when applying the filter, like below. Note, that this also works fine when filtering directly from the UI (Ctrl+F).
   

   qbdsCustTable.addRange(fieldNum(CustTable, CreatedDateTime)).value(queryValue(DateFilter.dateValue()));

   What is interesting is how the kernel processes this range. In the below infolog, you can see that when viewing the query, it displays a "==" condition on a specific dateTime value.
   But in reality, as you can see from the SQL trace, a range ">= && <=" condition is applied to span exactly one day.
   Also note, that the values in the trace are displayed accounting for the TimeZone I am in, as well as for Daylight Saving Time
   
   
2. Q: Can I filter on the new UtcDateTime type, specifying the Time part only?
   A: No, this is not possible with a UtcDateTime type. The range applied when specifying a Time value is the minimum DateTime value, as seen below. Note, that in the SQL trace it is converted to "no range".
   
   
3. Q: Can I use similar query functions for UtcDateTime type?
   A: Yes. All the main existing functions for working with QueryBuildRange also support UtcDateTime. For example, in the infolog below you can see how a range on 2 UtcDateTime dates is applied. Global::queryRange method was used to achieve that. Note, again, that the SQL trace offsets the DateTime by the appropriate number of hours based on my location.
   
   
4. Q: How is the UtcDateTime stored in the database? Is it displayed the same way on forms?
   A: The UtcDateTime fields are in the database always stored in Coordinated Universal time (UTC). Whenever displayed on forms and bound to table fields, the data is converted to the user's preferred timezone. Note, that you need to take care of the conversion yourself, if the control is not bound to a field. For an example, see the init method of the tutorial form.
5. Q: What standard helper functions are present for working with UtcDateTime type in the application?
   A: The main entry point for working with UtcDateTime type is the DateTimeUtil class. It allows adding Days/Months/Years, as well as applying an offset, getting the user's preffered timezone, converting from/to other types, etc. An example from the form init method is posted below:
   

       // getSystemDateTime() returns the current DateTime set in the system, not the current machine dateTime.
       // Note that getSystemDateTime() returns a UTC date and time, not your local date time.
       // In order to receive your local DateTime value, you should use methods applyTimeZoneOffset and specify the preferred time zone.
       utcDateTimeFilter.dateTimeValue(
           DateTimeUtil::applyTimeZoneOffset(
               DateTimeUtil::getSystemDateTime(),
               DateTimeUtil::getUserPreferredTimeZone()));

6. Q: Does this mean that the support for Date and Time types has been removed?
   A: No, Date and Time are still supported. As you can see in the form init method, SystemDateGet(), timeNow(), today() are all still supported
7. Q: I don't see the actual filter values in the SQL log. Instead, all I see are "?"'s. Also, how can I limit the number of data/fields selected from the database?
   A: This is just some extra stuff, not related to UtcDateTime, but still useful to know and pay attention to.
   CustTable has a very large number of fields, and I am only displaying 4 of those in the form, so it would be unwise to always query and return all of the fields. Luckily, the datasource has a property OnlyFetchActive, which controls the query behavior by only selecting the fields actually displayed on the form. Note, that you should avoid using this with editable datasources. See comments to this post for details
   As for "?"'s in the SQL trace - that is happening due to the use of placeholders. This in general optimizes the performance of the queries, by creating a query execution plan and storing it for future use. But it is possible, and is required in some specific cases, to force the use of literals (meaning the actual values of the ranges in the query). This can be done using the literals method on the query. See method init on the form for an example.