Walkthrough: Getting Started with Customizations

  • Article
  • 10 minutes to read

Customizing forms and customizing reports in MorphX are among the most common development tasks you perform in Microsoft Dynamics AX. This topic walks you through a scenario in which you customize the SalesTable table by adding a new field to one of the SalesTables field groups. Adding this field to the group makes the field visible on the SalesTable form. Next, you create and add a similar field to the CustInvoiceJour table and to the SalesInvoice report. This allows you to create a new sales order and fill in the new field. When you post the sales order, you see the text from the new field on the invoice.

Note

To go through this scenario you need to have your own label file.


The following steps walk you through the scenario.

Changing the Current Development Layer

MorphX supports layered development. Layered development enables you to easily identify your changes because they are located in a layer above the existing functionality. This feature eases the process of upgrading from one version to another. For more information, see Application Object Layers.

There are two layers that are used for making customizations in Microsoft Dynamics AX: the bus layer and the cus layer. The bus layer is used for implementing customizations that apply to all of your customers. This scenario walks you through a customization for a single customer, so you work in the cus layer.

Change the Current Development Layer

  1. Click Start > Control Panel > Administrative Tools > Microsoft Dynamics AX Configuration Utility.

  2. On the Development tab, select cus from the drop-down list in the Application object layer to open field, and then click OK.

    Note

    The configuration utility runs outside Microsoft Dynamics AX. You must stop and restart the client for the changes to have effect.


Opening the Development Environment

MorphX is the name of the development environment in Microsoft Dynamics AX. The main view of the programming environment is the Application Object Tree (AOT). The AOT contains all of the application elements in the application, and it contains tools to develop your own application or to modify the existing modules.

Open the AOT

  • Press CTRL+D.

Creating an Extended Data Type

Before you create a new field on the SalesTable table, you need to create an extended data type to base the new field on.

Extended Data Types are user-defined types, based on the primitive data types Integer, Real, String, Guid, int64, Time, Enum, and Date, and the composite data type Container. You can also base extended data types on other extended data types.

A major advantage of using extended data types is that they model higher level abstractions than primitive data types do. An extended data type named "StreetName," for example, has much more semantic meaning than the primitive type string. Use extended data types instead of primitive data types whenever possible. Using extended data types includes using them when you are writing X++ code and when you are creating your data model. A best practice in Microsoft Dynamics AX specifies that all table fields must be based on an extended data type.

Another major advantage of using extended data types is that an extended data type has a set of properties, such as the user interface text (labels) and Help text. Any table field that is based on a particular extended data type inherits these properties, so the developer has to update only one location to update type properties for all fields of that type. To view these properties, right-click the element in the AOT, and then click Properties. For more information, see Extended data type properties.

Create an Extended Data Type Based on a String

  1. Expand the Data Dictionary node, right-.click the Extended Data Types node, and then select New > String in the shortcut menu.

  2. Right-click the new extended data type, click Properties, and then type DeliveryText in the Name field.

It is a best practice in Microsoft Dynamics AX to base all UI text on labels. You must use a label because this extended data type will be used to create a field in a table that will be shown on a form and a report. Also, placing the label on the extended data type ensures that the label is inherited by any element that is based on this extended data type.

To add new labels, create your own label file. Having your own labels stored in a separate file facilitates the translation and upgrade process.

  1. Create a label and add it to the properties form of the extended data type.

    1. Type DeliveryText in the Label field of the property sheet.

    2. Click the browse button in the Label field. This opens the Label editor.

    3. In the Label editor, click the Setup tab, and then select your label file from the Label file ID field. Select your own label file.

    4. Click the Label tab, and then click Find now.

      Note

      The system searches all available label files to check whether the text already exists as a label. This is to ensure that identical labels are not accidentally created. The results of the search are displayed in a grid at the bottom of the form.


    5. Press CTRL+N to create a new label, and then enter a description in the Description field. Press CTRL+S to save the label.

      Note

      Entering a description in the Description field specifies the semantic use of the label. The semantic use of the label distinguishes it from other labels with the same text string and provides contextual information to translators.


    6. Click Paste label.

  2. To save the changes to the property sheet, select the extended data type, and then press CTRL+S.

Adding a New Field to an Existing Table

In MorphX, you can add fields to existing tables. You now need to add a new field based on the DeliveryText extended data type to the SalesTable table.

Add a New Field to the SalesTable Table

  1. Expand the Data Dictionary node in the AOT, and then locate and expand the Tables node.

  2. Navigate to and expand the SalesTable table node.

  3. Right-click the Fields node of the SalesTable table.

  4. Click New, and then select String as the primitive data type to base the field on. To base a field on an extended data type, you must first choose the primitive data type that the extended data type is based on.

  5. To base the field on the DeliveryText extended data type, right-click the field and select Properties.

  6. Click the ExtendedDataType arrow in the property sheet, and then select the DeliveryText.

  7. To rename the new field, select the Name field, and then type DeliveryText.

  8. Select the new field in the AOT, and then press CTRL+S to save DeliveryText field.

Adding a Field to a Field Group

It is a best practice in Microsoft Dynamics AX that fields shown on the user interface are members of one or more field groups. Field groups are a way to group logically related fields. Forms and reports are based on field groups rather than on individual fields.

Note

Any field that you add to a field group is applied to any form or report that is based on that field group. For more information, see Defining Field Groups.


Add the New Text Field to the Delivery Field Group

  1. Expand the Field Groups node under the SalesTable table.

  2. Drag the DeliveryText field from the Fields node to the Delivery field group. The DeliveryText field will be displayed everywhere that the Delivery field group is referenced.

    Note

    You can open more than one AOT instance at a time. This can ease dragging and dropping elements from one node to another node. To open another AOT instance, press CTRL+D.


  3. Press CTRL+S to save the changes.

Verifying the New Field on the Sales Order Form

Forms in Microsoft Dynamics AX have can have one or more data sources (Tables, Maps, Views) associated with them. The SalesTable table is one of the data sources that is associated with the SalesTable form. You can open the form to confirm that the field is visible on the SalesTable form.

View the New Field on the Form

  1. In the AOT, expand the Forms node, and then navigate to the SalesTable form.

  2. Right-click the SalesTable form, and then click Open.

  3. Click the Delivery tab on the form header, and then identify the new Delivery text field.

Adding a New Field to a Second Existing Table

You now need to add a similar field to the CustInvoiceJour table. The field should be based on the DeliveryText extended data type.

Add a New Field to the CustInvoiceJour Table

  1. Expand the Data Dictionary node in the AOT, and then locate and expand the Tables node.

  2. Navigate to and expand the CustInvoiceJour table node.

  3. Right-click the Fields node of the CustInvoiceJour table.

  4. Click New, and then select String as the primitive data type to base the field on.

  5. To base the field on the Delivery Text extended data type, right-click the field, and then select Properties.

  6. Click the ExtendedDataType arrow in the property sheet, and then select the Delivery text.

  7. To rename the new field, select the name field, and then type DeliveryText.

  8. Select the new field in the AOT, and then press CTRL+S to save the DeliveryText field.

Editing a Table Method

You now need to add a line of code to the initFromSalesTable method on the CustInvoiceJour table that populates the table with data from DeliveryText field in the SalesTable table.

  • In Microsoft Dynamics AX, tables are themselves application objects and have methods that allow a developer to write code that performs operations on records in the table. You can add new methods or override existing methods, such as insert, write, and delete. They are automatically invoked by the runtime in Microsoft Dynamics AX. For more information about table methods, see How to: Define and Modify Table Methods.

Modify the CustInvoiceJour.initFromSalesTable Method

  1. Navigate to and expand the CustInvoiceJour table node.

  2. Expand the Methods node, navigate to the initFromSalesTable method, and then add the following line of X++ as the last line (just before the closing brace):

    this.DeliveryText = salesTable.DeliveryText;

    Note

    Adding this line populates the Delivery text field in CustInvoiceJour table with corresponding data from the SalesTable table.


  3. Press CTRL+S to save the table modifications.

Adding a New Field to a Report Design

To display the data from the CustInvoiceJour.DeliveryText field on the invoice, add the field to the generated design of the SalesInvoice report.

Reports can have two types of designs: generated and autogenerated. Autogenerated designs automatically position the data that is made available to the report in a predefined configuration. The SalesInvoice report does not use an auto-generated design because it is very common to customize invoices.

Whether the report uses fields or field groups to display its data depends on the type of design. Autogenerated reports use field groups, and generated reports use fields. For more information about report design, see Best Practices for Report Design.

Add a Field to the SalesInvoice Report

  1. In the AOT, navigate to and expand the Reports node.

  2. Navigate to and expand the SalesInvoice report.

  3. Check out the report.

  4. Click DataSources > Query > DataSources > CustInvoiceJour > Fields, and then navigate to the DeliveryText field.

  5. Open another AOT instance by pressing CTRL+D.

  6. Navigate to and expand the SalesInvoice report.

  7. Click Designs > Standard > GeneratedDesign > PageHeader:Invoice.

  8. In the first AOT window, drag the DeliveryText field to the PageHeader:Invoice group.

  9. To position the DeliveryText text on the report header, select the Left field and type 9, and then select the Top field and type 10.

  10. Note   For more information about report properties, see Report properties.

  11. Press CTRL+S to save the changes to the report.

Verifying the Customization

Finally, you create a sales order, post it, and print out a sales invoice.

View the Text from the New Field on a Report

  1. Create a sales order.

  2. On the Sales order form, click the Delivery tab.

  3. Select the Delivery text field and type Large Box.

  4. Post the sales order.

    1. Click Posting > Invoice.

    2. Select the Print invoice field, and click OK.

  5. Confirm that the text that you entered in the Delivery text field appears on the report.

Next Steps

This walkthrough has shown you how to customize forms and reports in Microsoft Dynamics AX by using MorphX drag-and-drop development. For more information about MorphX, see Microsoft Dynamics AX IDE.