Dynamics NAV Form
Microsoft Dynamics NAV Form Transformation Tool converts form objects in the Classic client to page objects that you can use in the RoleTailored client. The tool uses a set of rules that map objects in the Classic client to objects in the RoleTailored client.
These rules are contained both in the transformation input files and in the Dynamics NAV Form transformation tool source files. In addition to the transformation input files, which specify the modifiable rules for transformation, the transformation tool uses schema files, a configuration file, and a coderules file to transform the source forms in the forms.xml file into pages.
The transformation tool creates a pages.xml file, which contains the pages that you can view in the RoleTailored client, and a log output file.
The following illustration shows the form transformation framework and how the transformation tool fits into that framework.
As this illustration shows, transforming forms is an iterative process. You may need to run the Dynamics NAV Form transformation tool more than once on a given form to create a page with the functionality that you want.
After you run the tool and view the transformed page, you may want to modify some of the rules that the tool uses and produce different page functionality or modify the user interface (UI) for the page. You change the rules by modifying the transformation input files. You can modify these files directly or you can use the Transformation Input Files (TIF) Editor to modify input files.
The set of rules that the transformation tool uses can be divided into three categories:
- Generic, built-in rules that are applicable to all forms.
- Generic, modifiable rules that are applicable to all forms.
- Non-generic, modifiable rules that are applicable to individual forms.
Built-in rules are part of the transformation tool itself. Modifiable rules are input to the tool in the transformation input files.
Generic, Built-In Rules
Most transformation tool rules are used for basic form to page transformations, and are related to controls and properties. These rules ensure that the generated pages contain the same functionality as the original forms. Additionally, there are some rules that specify user interface (UI) behavior that is universal across all pages. For example, a table is always placed second in the control hierarchy of a page, which means that the Lines FastTab appears after the General FastTab and before other FastTabs.
All rules in this category are built into the logic of the transformation tool. You cannot change these rules without modifying the source files.
Generic, Modifiable Rules
Some transformation rules are specified manually. These rules can be modified and are applied by the tool to all form objects. Examples of generic, manually-specified rules are the following:
- Mapping triggers and methods
- Mapping existing shortcuts
- Adding new shortcuts
- Promoting selected commands based on caption (rather than control ID)
- Assigning icons to commands
Non-generic, Modifiable Rules
Some rules are applicable to individual forms, not to the set of all forms. Two of these non-generic rules are required. All other rules in this category are optional and can be applied to pages that you want to modify. The required rules are the following:
- Assigning appropriate PageType properties to all pages.
- Assigning appropriate CardFormID properties to list pages.
Examples of optional, non-generic rules are the following:
- Ignoring specific pages
- Ignoring specific controls
- Replacing one form with another (applicable if a redesigned form is a new form).
All rules in this category are specified manually and therefore, can be modified. Similar to the generic, modifiable rules, these rules are contained in input files to the tool, and are applied when you run the tool. To modify these rules, you either use the TIF Editor or modify the transformation input .xml files directly. For more information about modifying the transformation input files, see the following topics:
- Understanding Form Transformation Input Files
- Specifying Form Transformation Rules with the Transformation Input Files Editor
The transformation tool uses the following input:
- Forms.xml – All forms that you want to transform, exported as XML files from the Classic client.
- CodeRules.txt – A set of rules that, through code pattern recognition, maps triggers and methods.
- Transformation input files.
- Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config – An editable configuration file that provides the location of input and output files and defines the scope of logging.
- XML schema files
The transformation tool produces the following output:
- Pages.xml – Pages that can be displayed in the RoleTailored client.
- Transformation.log – A file that logs progress information while the tool runs and provides information about issues detected by the tool. After you run the tool, inspect the log file to determine if you need to make changes to the input and run the transformation again. Use the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file to configure the output in the log file.
Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File
Use the Dynamics NAV Form transformation configuration file, Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config, for the following purposes:
- To define file names and path locations for input and output files. The form transformation tool references these files during execution.
- To define the scope of logging by specifying what types of exceptions you want to include in the output log file.
If you have saved your files to the default locations and if you want to use the default scope of logging, then you do not need to modify the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.
By default, the location of the input and output files is the same as the location of the tool. The configuration file contains the following lines, which specify the names and locations for input and output files.
<configuration> <appSettings> <add key="FormsFile" value=".\Forms.xml"/> <add key="PagesFile" value=".\Pages.xml" /> <add key="IgnorePages" value=".\IgnorePages.xml"/> <add key="MovePages" value=".\MovePages.xml"/> <add key="TransformPages" value=".\TransformPages.xml"/> <add key="DeletePageElements" value=".\DeleteElements.xml"/> <add key="MovePageElements" value=".\MoveElements.xml"/> <add key="CodeRules" value=".\coderules.txt"/> <add key="TranslationFile" value=".\PageTranslations.txt"/> <add key="SchemasPathLocation" value =".\"/>
You can change this information in the configuration file if you want to use input files from a different folder or if you change the names of the input or output files.
Scope of Logging
You can control the size and focus of your log file by including only the exceptions in which you are most interested. The following table describes the exception message types.
|ChangeCodeManually||Transformation of a specified control or property could not be completed. Additional, typically manual, change or input is required to address the exception that is associated with this message.|
|CheckInputFile||There is an inconsistency in an input file.|
|CodeCannotBeTransformed||Code cannot be transformed automatically. Manual change to the form itself is needed.|
|Error||Any error. Typically, the transformation tool cannot recover after such an error.|
|General Information||Any information. Typically, no action is required.|
|IgnoreForms||Specified form was excluded from the transformation and no matching page was created.|
|IgnoreWarning||Verify that there is not an issue, and then ignore this warning.|
|InputInformation||Information about input files.|
|RemoveControls||Specified control on the form was not mapped to a matching control on a page.|
|ValidateManually||Specified control or code has been changed during transformation. The change requires manual validation.|
|Warning||Any warning. Requires manual validation.|
To configure which type of messages to include in the log file and the degree of message details, you assign a value code to each message type in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file, and then set the TraceLevelSwitch value to specify the logging level.
The following example from the configuration file shows the default value code assignments for each message type.
<add name="Error" value="1" /> <add name="CodeCannotBeTransformed" value="1" /> <add name="Warning" value="2" /> <add name="GeneralInformation" value="4" /> <add name="IgnoreForms" value="3" /> <add name="IgnoreWarning" value="2" /> <add name="InputInformation" value="1" /> <add name="RemoveControls" value="3" /> <add name="ChangeCodeManualy" value="2" /> <add name="ValidateManualy" value="3" /> <add name="CheckInputFile" value="1" />
Based on the preceding value codes, the default logging levels can be described as follows:
- 1 Logs error messages and required information
- 2 Logs errors and warnings
- 3 Logs detailed error information
- 4 Logs verbose information
- 0 Logging is turned off
To specify the level of logging, you set the TraceLevelSwitch value. For example the logging level is set to 1, log error messages and required information in the following code.
<add name="TraceLevelSwitch" value="1" />
You can modify the level of logging or the value code for each message type in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file.