Tuesday, 6 March 2012

Editing existing help in Ax 2012

This post describes how to modify an existing help file in an Ax 2012 environment. As an example, we'll add some text to the help that appears for the Customers form.

As a general rule, the steps you'll go through to modify help are as follows:
  • Find the form in the AOT. For this example, it's CustTable.
  • Determine the help topic ID for the form. This will typically be Forms.[FormName], so for us it's Forms.CustTable. The correct way to find the help topic ID is to right-click the element in the AOT, then select AddIns -> Help properties. This help topic ID is referenced and indexed in the help files.
  • Determine the file that corresponds to the help topic ID. This isn't all that straightforward as far as I can tell, so I've created a helper document and application to assist in resolving the links (See below).
  • Edit the file in-place.
  • The help server will pick the changes up immediately. All content is served centrally so there's no need for any additional deployment to clients.
The help topic / file mappings for a standard installation can be downloaded here: Ax2012 help file mappings.
I've included a small utility application that will scan the entire help directory and build an index of the help topics and their corresponding files. This can be downloaded here. The easiest way to run this is to unzip and copy it to the C:\ of your help server, then run it. The full path to the help server directory must be supplied as an argument. To find that, open IIS, find the Ax help virtual directory, and view the "Physical path", normally in "Basic settings". The source-code is also included - To compile it, copy it into a new C# command-line project.

So for our example, do the following:
  • Find CustTable in the AOT.
  • Right-click then select Add-ins -> Help properties. Make a note of the help topic it shows, although this will generally be Forms.[FormName].
  • Open the mapping file (link above) in your browser, and search (Ctrl+F in Internet Explorer) for the help topic (Forms.CustTable).
  • Open the file and edit as necessary in a text or html editor. Note that you'll need to either log directly onto the help server, or substitute the local path for a network path. Grab a developer if you're not sure how to do that.
The changes should take effect immediately.

Note, the key thing that Ax uses to link a help topic to a file is the "Microsoft.Help.F1" meta-tag. It uses the Windows search/indexing service to build an index of all files and the help topic they reference. If for any reason you need to change the value of that meta-tag (to link it to another form for example, or if you're authoring help for a new form/object), then the change may not be picked up immediately. In this case you can stop/start the Windows search service on the help server to recheck and rebuild the index.

Additional information can be found in MSDN here.


  1. Nice post! This is Margo Crandall from the Content Publishing team at Microsoft. The one thing that I'd like to point out is that if you modify the Microsoft version of a help file directly, you may lose your changes when a help update is installed, for example, with CU1. If instead, you copy the Microsoft file to another publisher folder, and add that folder as a publisher, then we won't overwrite your changes.

  2. Thanks for the info Margo. Another query I had come up recently was from a VAR that ships their own modules. In their scenario, they may need to add information to an existing help page (for example if they're adding a few fields to the customer table/form). In that scenario there didn't seem to be a straightforward way to ship their new content for merging into other, existing applications. We'd looked at separating their content out and referencing it via in IFRAME, but the internal help viewer doesn't seem to handle that too well (Specifically, that content after the IFRAME is not shown).