Na2009 enus rep_06

Chapter 6: Appendix

6-1

CHAPTER 6: APPENDIX Objectives

The objectives are:

• Understand the way the Form Transformation Tool works • Prepare the form transformation process • Transform forms to pages

Introduction In Microsoft Dynamics® NAV 2009, the RoleTailored client is the new, rich client and pages are the new way to view, insert, modify, and delete data in the RoleTailored client. The RoleTailored client provides an intuitive and customizable user interface (UI) that you can modify to support the job functions of different work roles in your organization.

Microsoft Official Training Materials for Microsoft Dynamics ® Your use of this content is subject to your current services agreement

Report Design in Microsoft Dynamics® NAV 2009

6-2

Understanding Form Transformation The RoleTailored client cannot run forms. You must transform your existing forms into pages. By transforming your forms into pages, you can reuse the business layout and logic of your forms. To transform your forms into pages you must use the transformation tool. The topics in this section describe form transformation, the principles behind form transformation, the different methods that you can use to accomplish the transformation from forms to pages, and an overview of the tool that you use to perform form transformation.

The following illustration shows the process of transforming forms to pages:

FIGURE 6.1 TRANSFORMING FORMS TO PAGES


Chapter 6: Appendix

6-3

Objectives

Form Transformation enables you to:

• Transform forms to pages (basic transformation) • Tailor resulting pages for the RoleTailored client (UX

transformation)

Form-to-page transformation is a basic transformation process that takes form objects from the Microsoft Dynamics NAV Classic application and creates page objects that you can use in the RoleTailored client.

User experience (UX) transformation supplements basic form-to-page transformation by adding additional user interface elements to pages that take advantage of the new user experience in the RoleTailored client.

Basic Transformation

Basic transformation is the conversion of a form, including its existing functionality and business logic, to a new page by mapping the form essentials—properties, controls and code—to the corresponding page components.

The mapping logic is based on rules that are generically applied to all forms. This mapping logic enables you to automate the transformation process. The transformation tool includes built-in mapping rules. In addition to the built-in mapping rules, the transformation input files to the tool include modifiable rules.

In addition to replacing existing elements on a form with the corresponding new elements on a page, mapping logic also extends to and includes rules that do the following:

• Ignore: The transformation tool ignores an existing element on a form without replacing it with a corresponding new element on a page. Typically, this occurs in one of the following cases: o The RoleTailored client supports the equivalent behavior in a

different way than the Classic client. o The logic does not require input from the original form. o There is not an equivalent element on a page in the RoleTailored

client.

• Add a property: The transformation tool adds properties to a page that were not on the original form. For example, PageType is a new page property that is a prerequisite to render a page. CardFormID is another new page property. You must assign a CardFormID to a list form that you will transform to a page. Other properties added to a page through transformation are a part of UX transformation.



6-4

The following tables list examples of generic rules that the transformation tool applies automatically during a basic transformation.

Form control

Mapping rule Page control

TableBox Replace Grid (Repeater)

TabControl Replace FastTab

Label In most cases, the CaptionML value of the label is transformed to the CaptionML of the parent or adjacent control.

Caption of field control is used as label.

MatrixBox Ignore MatrixBox control is not available.

Form Property

Mapping rule

Page Property

Width Ignore None. Pages and controls have built-in rendering and resizing logic.

Xpos Ignore None. Pages and controls have built-in rendering and resizing logic.

ParentControl

Ignore None. Pages and controls have built-in rendering and resizing logic.

ID Replace ID

Editable Replace Editable

RunObject Replace RunObject

Tooltip Ignore Not supported

NextControl

Ignore Not supported

Add new PageType

Add new CardFormID

For complete mapping information, see http://msdn.microsoft.com/en-us/library/dd301238.aspx.

UX Transformation

Through the UX transformation, the automatically generated pages can be tailored to make use of new user interface features in the RoleTailored client. You can either tailor pages through the transformation process or directly in the page object.


Chapter 6: Appendix

6-5

You can enhance a page as part of a UX transformation in the following ways:

• Adding FactBoxes and reports to pages. • Adding new actions that do not exist on the form. • Promoting frequently used actions and reports onto the Action Pane. • Assigning icons to actions. • Promoting fields to Fast Tab headers. • Adding home parts to a role center. • Modifying shortcut keys.



6-6

The following figure illustrates how a form looks before transformation and how the corresponding page looks after transformation.

FIGURE 6.2 SALES ORDER BEFORE AND AFTER TRANSFORMATION

The following changes were made to the sales order task page during UX transformation:

• Three FactBoxes were added to the right side of the page: Customer Sales History, Sales Line Details, and Notes.

• Frequently used actions, such as Post, Post and Print, and Release have been added to the Action Pane with the appropriate icons.

• The Lines FastTab has been placed directly under the General FastTab.

• Selected fields, such as Customer Bill-to No., Payment Terms Code, and Due Date have been marked with Essential importance so that they appear as a summary on the collapsed Invoicing FastTab.


Chapter 6: Appendix

6-7

Unlike basic transformation, UX transformation requires specific instructions for each form. You define these instructions in the transformation input files. For more information about transformation input files, see Understanding Form Transformation Input Files (http://msdn.microsoft.com/en-us/library/dd355283.aspx).

Principles

The form transformation tool was designed with the following principles:

• The tool converts all existing Microsoft Dynamics NAV forms into pages while retaining the same functionality as the original forms.

• Basic conversion rules (built into the tool) assume that the user interface and code on the form are compliant with the standard application development guidelines.

• The tool identifies deviations from the guidelines that may result in missing user interface (UI) elements or functionality of the original form. The tool logs these deviations for manual consideration.

• If the rules for modifying the page UI are generic to all pages, then the tool incorporates them into the tool mapping logic. The tool regards rules that represent "manual" decisions about certain user experience (UX) behavior, layout, and business logic as additional input. You define this additional input manually.

These principles turn the transformation into a highly automated process that makes the migration path to the new architecture as efficient as possible.

Fully automatic transformation is not possible for the standard global application or for add-ons and customized solutions. This may be caused by the following:

• Some control types in the Classic client are not available in the same form in the RoleTailored client. For example, the MatrixBox and Shape controls are not supported. To generate a page with the same functionality in the RoleTailored client, you have to either replace the original form with an alternate form containing controls that can be transformed, or modify the original form. One of the steps to prepare for form transformation is to redesign forms by either replacing or modifying forms.

• The RoleTailored client has enhanced behavior hard-coded into its controls. Therefore, some code that was necessary in previous versions of Microsoft Dynamics NAV is now obsolete when using the new controls. This means that pages contain fewer triggers than forms.

• Automation that has no UI and does some kind of processing which includes generating files as output (or consumes files as part of input) requires special consideration. To make this work, you must rewrite C/AL code to properly supply the input or output files needed for the automation.



6-8

• Automation that uses dialog boxes to display messages or errors requires special consideration. The automation may have its own window (like an OCX) or it may interact with hardware that is local on the client (like a bar code reader or card scanner). These are now unsupported scenarios. Any solution to this problem may require a redesign that functions the same way but takes advantage of Web services, C/FRONT.NET, or another integration technology.

The more your forms deviate from the design guidelines of the standard application, the more challenging it will be to transform them successfully to pages so that they support the same functionality and are compliant with UX guidelines.

If your goal is to retain one code base in the Classic client and the RoleTailored client, rather than moving all your application development onto the RoleTailored client, you will have to plan for some redesign efforts.

Methods

When you decide to migrate an application to the new three-tiered architecture, you must also decide which migration method is best suited to your business needs. Migrating to the new architecture can be an iterative process. You may need to run the form transformation tool multiple times and carefully alter any problematic forms to ensure that pages can be created that have the required layout.

It is important to remember that when you transform a form, the form does not change. For each form that you transform, a new page object is created with matching functionality that can be used by the RoleTailored client. You then have two objects—a form and a page. If you run the tool again and transform the same form, the new page that is created will overwrite the first page object.

If, at a later date, you decide that you want to change the functionality of your application, you can implement the changes in one of the following ways:

• Implement changes on the form and then transform the form to a page.

• Implement changes on the corresponding page. • Implement changes on both objects, depending on your business

needs.

You can choose between the following methods when you move your application from the Classic client to the RoleTailored client:

• Reactive Method • Proactive Method • Start from Scratch Method • Combined Method (all of the above)


Chapter 6: Appendix

6-9

The method that you choose can vary from one implementation to another. A good development practice is to use a copy of the database to see which method or combination of methods achieves the best results for each implementation.

Reactive Method

The following are the steps for the reactive method:

• Run the Transformation Tool. For more information, see How to: Run the Form Transformation Tool (http://msdn.microsoft.com/en-us/library/dd338649.aspx).

• Check the resulting pages and the log file. For more information, see Reviewing the Form Transformation Log Output File (http://msdn.microsoft.com/en-us/library/dd338760.aspx).

• Redesign or modify any forms that did not transform successfully. For more information, see Preparing for Form Transformation by Redesigning Forms (http://msdn.microsoft.com/en-us/library/dd338598.aspx).

• Run the tool again to transform the forms that you have altered.

Proactive Method

The following are the steps for the proactive method:

1. Redesign any forms that you know will not transform satisfactorily. 2. Run the Transformation Tool. 3. Check the resulting pages and the log file. 4. Modify forms that are still causing problems.

Start from Scratch Method

The following are the steps for the start from scratch method:

• Implement your entire application in the Page Designer and ignore the transformation tool.

Combined Method

The following are the steps for the combined method:

1. Transform some forms to pages. 2. If desired, modify the resulting pages in Page Designer to get greater

benefit from the new user experience (UX). 3. If desired, create some new pages without transforming the source

forms.



6-10

Overview

The 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 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.

FIGURE 6.3 THE FORM TRANSFORMATION FRAMEWORK

As this illustration shows, transforming forms is an iterative process. You may need to run the 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.


Chapter 6: Appendix

6-11

Rules

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

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 (http://msdn.microsoft.com/en-us/library/dd355283.aspx)

• Specifying Form Transformation Rules with the Transformation Input Files Editor (http://msdn.microsoft.com/en-us/library/dd338983.aspx)



6-12

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.

Input

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. The transformation input files are the following: o TransformPages.xml o MoveElements.xml o MovePages.xml o IgnorePages.xml o DeleteElements.xml

• 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


Chapter 6: Appendix

6-13

Output

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.

For more information about how to import and compile the pages in pages.xml, and how to view the new pages in the RoleTailored client, see How to: Import, Compile, and Run Transformed Pages (http://msdn.microsoft.com/en-us/library/dd301270.aspx).

For more information about the types of information in the log file and how to use the log file, see Reviewing the Form Transformation Log Output File (http://msdn.microsoft.com/en-us/library/dd338760.aspx).

Preparing Form Transformation The transformation process has two stages:

• Preparing for transformation • Transforming forms



6-14

The following diagram illustrates the process of transforming forms to pages.

FIGURE 6.4 PREPARING FORM TRANSFORMATION

The topics in this section provide an overview of the steps that you need to take to prepare for transformation.

If you take the time to prepare your forms for transformation, the transformation will be more efficient and complete.

To prepare for transformation, you need to perform the following steps:

1. Install the form transformation tool. For more information, see How to: Install the Form Transformation Tool (http://msdn.microsoft.com/en-us/library/dd339024.aspx).

2. Redesign existing forms in the Classic client. It is not possible to transform some forms, such as Matrix forms. Redesigning forms smoothes the transformation process and helps to minimize errors when you run the tool and layout issues in the transformed page.


Chapter 6: Appendix

6-15

3. Define the transformation input. Create mapping specifications by using the Transformation Input Files (TIF) Editor or by directly modifying the transformation input .xml files. You must assign each page a type. You can also specify additional layout and user experience (UX) changes.

Install the Form Transformation Tool

You must copy the form transformation tool files before you can transform forms. The files that you must copy are located in the TransformationTool folder and the TransformationTool\TIF Editor folder on the installation DVD.

The TransformationTool folder contains several files, including the .xml transformation input files. For more information about the transformation input files, see Understanding Form Transformation Input Files. The TIF Editor folder contains the TIF.fob and FormToPagetypeMapping.txt files.

Before you begin this procedure, confirm the following:

• You have Microsoft Dynamics NAV 2009 installed with a developer license.

• All Microsoft Dynamics NAV 2009 requirements are met.

To install the form transformation tool, copy the contents of the TransformationTool folder, which includes the TIF Editor folder, from the installation DVD. You can copy these to any location on the Microsoft Dynamics NAV 2009 server.

Redesigning Forms

You may need to redesign some of your forms to make them preserve the business logic and layout when you transform the form to a page. Redesigning means that you have to either create a new form to replace the one that cannot be transformed, or modify the original form. Usually you only need to redesign a few forms in your application.

Why Redesign Your Forms?

The following reasons may be why you may need to redesign some of your existing forms:

• Unsupported controls • Matrix-like layouts do not transform successfully • New user experience (UX) guidelines



6-16

Unsupported Controls

The RoleTailored client does not support certain control types that are used in the Classic client. The unsupported controls are the following:

• MatrixBox • Shape

You cannot map these controls in the Classic client to controls in the RoleTailored client. If a form contains one of these types of controls, then it will not transform. Matrix forms are examples of forms that use these types of controls. You must start at the beginning and design a new form.

Matrix-Like Layout

Certain controls, when used together, create a matrix-like layout. Although the individual controls are supported, the matrix-like layout will not transform successfully. You must redesign forms with a matrix-like layout.

New UX Guidelines

The RoleTailored client has new navigation principles and UX guidelines. This means that you must modify the behavior of some Classic client forms before they can be transformed, for example:

• In the RoleTailored client, the user must always be able to move from a list place to a card.

• In the RoleTailored client, Journal forms must connect to their respective batch lists

• In the RoleTailored client, separate list forms must be created for each document type.

Some forms in the standard application were redesigned to new forms for UX improvements. For more information, see http://msdn.microsoft.com/en-us/library/dd338598.aspx.

Preparing Transformation Tool Input

The transformation input files are XML files that define mapping rules. For most forms, before you transform forms to pages that you can use with the RoleTailored client, you must define the transformation input. Some simple forms do not require input, but for most forms, we recommend that you use the Transformation Input File (TIF) Editor to specify form transformation input files. You can also modify the transformation input .xml files directly instead of using the TIF Editor.

This topic describes the TIF Editor and the workflow that you use to create and modify transformation input files by using the TIF Editor.


Chapter 6: Appendix

6-17

Elements of the Transformation Input File Editor

The user interface for the TIF Editor is a form that you run from Object Designer in the Classic client. The form that you run is form 177000, Transformation Forms. In this way, the TIF Editor offers a familiar environment for creating and modifying the transformation input in a tabular format rather than in the XML file. If you use the Microsoft Dynamics NAV Developers Toolkit, the TIF Editor also has data about form objects, which significantly improves efficiency and accuracy of the input data entry.

The TIF Editor consists of the following objects:

• TIF.fob – A set of objects that make up the editor’s functionality. • FormToPageTypeMapping.txt - A list of form types, definitions, and

their matching page types. • Schemas - TransformationInput.xsd, DeletePageElement.xsd,

IgnorePage.xsd, IgnorePage.xsd, and MovePageElement.xsd

Transformation Input File Editor Workflow

In your application, you may have forms that are the standard application forms, with or without customizations, and you may have Microsoft Certified Partner solution forms. The following steps summarize the workflow for the TIF Editor. Some steps in the workflow are optional, based on whether you have standard application forms or partner solution forms.

1. Install the TIF Editor. 2. If you have standard application forms, import the standard

application transformation input files to view and modify transformation input specifications.

3. If you have partner solution forms, populate the TIF Editor with these forms.

4. Import the list of form types, definitions, and their matching page types, to be used for lookup.

5. Specify the page type for partner solution forms. The standard application forms already have the page type specified.

6. Specify the CardFormID for list forms that have associated cards and that are partner solution forms. The standard application forms already have the CardFormID specified.

7. Define additional input specifications for the form transformation. 8. Validate form transformation. 9. Export the input data out of the TIF Editor to create XML input files.

The files are validated against the XML schemas.



6-18

Evaluating Client Files and Automation

Before you move to the three-tiered architecture in Microsoft Dynamics NAV 2009, you must evaluate your files that reside on the client to determine whether you need to use different functions to upload or download those files. You must also evaluate your automation components to determine whether you need to use different functions, change code, or redesign them

Files

In the Classic client, if the application creates a file, then that file is created on the local client computer. In the RoleTailored client, if the application creates a file, the file is created on Microsoft Dynamics NAV Server. If you need to store a file on the client computer, then you must write code to download the file from Microsoft Dynamics NAV Server to the client. Similarly, if the application must access a file that is stored on the client, then you must write code to upload the file from the client to Microsoft Dynamics NAV Server.

The following examples demonstrate scenarios that access files:

• Reports or batch jobs in which the output is saved to a file • COM components that generate or consume files

The following table describes guidelines to determine what you must modify to work with files in the RoleTailored client.

Description of file Change required

File is used for processing only

No change is required.

File is generated on the server and is provided to the user

Use the DOWNLOAD Function (FILE) or DOWNLOADFROMSTREAM Function (FILE) in C/AL.

File is provided from the client and sent to the server

Use the UPLOAD Function (FILE) or UPLOADINTOSTREAM Function (FILE) in C/AL.


Chapter 6: Appendix

6-19

Automation Components

The following table describes guidelines to determine if you must modify your automation components for use in the RoleTailored client.

Description of automation component Change required

Component contains no UI and no client interaction and is for processing only

No change is required.

Component contains no UI and makes a file for a client

Use guidelines for files (see preceding table).

Component contains no UI and accesses local software or network resources, such as MSMQ

You may need to change code to make the computer resource path more explicit.

Component accesses client-local resources, for example, a Gantt server, or client-local hardware, for example, electronic scales

Component is not supported for use with the RoleTailored client. You must redesign using Web services.

Transforming Forms The transformation process has two stages:

• Preparing for transformation • Transforming forms



6-20

The following illustration shows the process of transforming forms to pages.

FIGURE 6.5 FORM TRANSFORMATION

The topics in this section provide an overview of the steps that you need to take to transform forms to pages. The steps to transform forms are the following:

1. Export your existing forms to an .xml source file. 2. Configure the log file settings and the input and output file locations. 3. Run the tool. 4. Review the log file. 5. If any forms did not transform successfully, you may need to make

changes to your existing forms or to the input files and then re-transform forms.

6. Import and compile the transformed pages into the Classic client so that you can view and use the pages in the RoleTailored client.

7. (optional) Transform the navigation pane in the Classic client to Departments in the RoleTailored client by transforming the MenuSuite object.


Chapter 6: Appendix

6-21

Create Forms.xml Source File

To transform forms to pages, you must create a source .xml file of the forms that you want to transform. The form transformation tool uses this source file as well as the transformation input .xml files and the schema files to transform forms to pages. This procedure describes how to create the source forms .xml file.

Before you begin this procedure, confirm that you have completed the necessary preparation for transforming forms

The following list of steps shows how to create the forms.xml input file. In the Classic client, click Tools, and then click Object Designer.

1. In Object Designer, click Form. 2. Select the forms that you want to transform. 3. Click the File menu, and then click Export. 4. In the Export Objects window, browse to the location where you

want to export the forms. We recommend that you export forms to the same folder where the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files reside.

5. In the File name text box, specify the name of the file. We recommend that you name the file Forms.xml.

6. In the Save As Type drop-down list, select XML Format (*.xml), and then click Save.

NOTE: After you have save the forms to the Forms.xml file, the next step in the transformation process is to configure the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file. When you configure this file, verify that it specifies the correct name and location for the exported forms XML file.

Configuring the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config File

Use the 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.



6-22

File Locations

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="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.

Message Type Description

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.

DeleteTriggers Specified trigger is not supported in the RoleTailored client and therefore, has been automatically deleted by the tool. Code from trigger will be moved to a new function and a call to this function will be typically be added to some other trigger.

Error Any error. Typically, the transformation tool cannot recover after such an error.

General Information

Any information. Typically, no action is required.


Chapter 6: Appendix

6-23

Message Type Description

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.

RemoveProperties Specified property on the form cannot be mapped to a matching property on a page.

TempCodeWash Message that is triggered by a code transformation.

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="DeleteTriggers" value="2" /> <add name="TempCodeWash" value="3" /> <add name="RemoveProperties" value="3" /> <add name="RemoveControls" value="3" /> <add name="ChangeCodeManualy" value="2" /> <add name="ValidateManualy" value="3" /> <add name="CheckInputFile" value="1" />



6-24

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, in the following code, the logging level is set to 1, log error messages and required information.

<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.

Run the Transformation Tool

The following procedure describes how to run the form transformation tool to transform forms for the Classic client to pages that you can use in the RoleTailored client.

Before you begin this procedure, you must do the following:

• Complete the necessary preparation for transforming forms. • Create the source forms.xml file. • Configure the input and output file locations and the level of logging.

The following list of steps shows how to run the form transformation tool.

1. Confirm that you have the following input files, and that the path to these input files is correct in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file: o Forms.xml o CodeRules.txt o TransformPages.xml o IgnorePages.xml o MovePages.xml o DeleteElements.xml o MoveElements.xml o DeletePageElement.xsd o IgnorePage.xsd o MovePage.xsd o MovePageElement.xsd o TransformationInput.xsd


Chapter 6: Appendix

6-25

o Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config o Microsoft.Dynamics.Nav.Tools.FormTransformation.exe

2. Navigate to the folder where

Microsoft.Dynamics.Nav.Tools.FormTransformation.exe is located. 3. Double-click

Microsoft.Dynamics.Nav.Tools.FormTransformation.exe. 4. Verify that the tool completes successfully and that you have the

following output files in the folder specified in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file: o Pages.xml o Transformation.log o TransformationLog.xml (contains the same information as

Transformation.log)

After you run the transformation tool, you must complete the following steps:

• Inspect the log file for errors. • If necessary, re-transform all or selected forms. • Import and compile pages.

Review the Form Transformation Log Output File

After you run the form transformation tool, the pages that the tool created might not contain functionality that is equivalent to the original forms and might not display correctly in the user interface. You can use the information captured in the log file to help you to diagnose problems. By inspecting the log file, you can identify issues before you deploy the new page objects in the RoleTailored client. To resolve these issues, you must modify the input to the form transformation tool and run the tool again.

This topic describes the information that is in the transformation log files. The same information is captured in the following log files:

• Transformation.log • TransformationLog.xml

For more information and examples of log messages, see Reviewing the Form Transformation Log Output File (http://msdn.microsoft.com/en-us/library/dd338760.aspx).

Re-Transform Pages

After you run the form transformation tool, you might discover errors or warnings in the transformation log file or issues with the page in the RoleTailored client. Form transformation is an iterative process. If the first transformation does not successfully convert all your forms into pages, then you may need to make changes and run the transformation tool again.



6-26

Before you begin this procedure, be sure that you have reviewed the Transformation.log file and that you understand any errors or warnings.

To re-transform pages, execute the following list of steps:

1. If needed, make changes to the source form objects. . 2. If needed, make changes to the transformation input files. 3. If you have modified any source form objects, re-create the

Formsl.xml source file. 4. Re-run the tool until you have transformed all your forms

successfully.

Import, Compile and Run Transformed Pages

After you have run the form transformation tool, you must import the Pages.xml file into Object Designer. Pages.xml contains all the metadata required to display your transformed forms as pages in the RoleTailored client. You must also compile all of the new page objects so they are compatible with the .NET Framework and the Microsoft Dynamics NAV architecture. After you import and compile the transformed pages, the Microsoft Dynamics NAV database contains both your original Classic client forms and your new page objects. You can run the RoleTailored client and view the transformed pages.

Before you begin this procedure, you must successfully run the form transformation tool.

1. In the Classic client, click Tools, and then click Object Designer. 2. Click the File menu, and then select Import. 3. In the Import Objects window, in the Files of type drop-down list,

select XML Format (*.xml), browse to the folder where the Pages.xml file is located, select Pages.xml, and then click Open. By default, the Pages.xml file, which was created when you ran the form transformation tool, is located in the same folder as the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe file and the transformation input files. If you changed the name or the location of the output .xml file in the Microsoft.Dynamics.Nav.Tools.FormTransformation.exe.config file, select the name of the file that you specified.

4. In Object Designer, click Page, and then select all the pages that you imported.

5. From the Tools menu, select Compile, and then click Yes. 6. Run the RoleTailored client to view your transformed pages.

NOTE: To view a specific page in the RoleTailored client, run the following command from a Command Prompt window. DynamicsNAV:////runpage?Page=<PageID>


Chapter 6: Appendix

6-27

Transforming MenuSuite Objects

In the Classic client, you access forms and reports from the navigation pane, which displays menus that are contained in a MenuSuite object. In the RoleTailored client, you navigate to pages and reports by using the following elements:

• Role Centers • Departments

You can transform a MenuSuite object that you use in the Classic client to a Departments page that you use in the RoleTailored client.

The Departments page contains the entire suite of functionality as licensed and available to the company. In this way, the Departments page in the RoleTailored client is similar to the navigation pane in the Classic client. The Departments page is also a MenuSuite object with a layered item structure but is designed specifically for the RoleTailored client.

In Microsoft Dynamics NAV 2009, when you create a new MenuSuite object, you must select either the Classic client or the RoleTailored client as the target.

If you support both the Classic client and the RoleTailored client, you must maintain two sets of MenuSuite objects.

The ID of a MenuSuite object for the RoleTailored client will be the Classic client ID plus 1000, as demonstrated in the following table.

MenuSuite object in the Classic client

MenuSuite object in the RoleTailored client

10 MBS 1010 Dept - MBS

51 Add-on 1 1051 Dept - Add-on 1

You transform a MenuSuite object by using the Transformation Input File (TIF) Editor. The MenuSuite transformation creates a suggestion for a Departments page that is based on the navigation pane, transformation rules, and input.

After you transform the MenuSuite object, you must verify whether you need to make additional updates to the transformed Departments page. The RoleTailored client has different functionality and different user experience (UX) requirements than the navigation pane in the Classic client. The additional updates that you make to the transformed Departments page can take advantage of the new functionality.



6-28

To reduce the number of these manual updates that you have to make after transformation, verify that you meet the following conditions before transforming a MenuSuite object.

Condition Reason

PageType is assigned to all form objects.

Form objects will be placed in a Department Category based on PageType.

CardFormID is assigned to all list form objects with a card.

Card Form IDs in MenuSuite will be replaced with the related list.

Microsoft Dynamics NAV Developer Toolkit is installed to provide data about which reports are ProcessingOnly reports.

ProcessingOnly reports are placed in the Tasks category on department pages. Other reports are placed in the Reports and Analysis category on department pages.

An example of a MenuSuite transformation can be found on How to: Transform a MenuSuite Object (http://msdn.microsoft.com/en-us/library/dd354979.aspx).

Summary More information is available on Transforming Forms to Pages (http://msdn.microsoft.com/en-us/library/dd338789.aspx).


Chapter 6: Appendix

6-29

Quick Interaction: Lessons Learned Take a moment and write down three Key Points you have learned from this chapter

1.

2.

3.



6-30


Date post:	07-Nov-2014
Category:	Technology
Upload:	peter-muscat
View:	678 times
Download:	0 times

Na2009 enus rep_06

Technology