Chapter 6. The AX 2012 client

In this chapter

Introduction

Working with forms

Adding controls

Using parts

Adding navigation items

Customizing forms with code

Integrating with the Microsoft Office client

AX 2012 includes several updates and additions for the client. Some of the more substantial changes include new patterns for master records (details forms) and secondary data (list pages and transaction details forms), a new vertically expanding FastTabs control, the use of Action panes and Action pane strips to display actions more prominently, and the introduction of FactBoxes to showcase related information. For more information, see Chapter 5, “Designing the user experience.”

The majority of this chapter covers key aspects of the AX 2012 client. However, some of the information in this chapter is at the overview level. For more detailed information, see the “Client” section of the AX 2012 SDK at http://msdn.microsoft.com/en-us/library/gg880996.

To create a form, you use the Application Object Tree (AOT) to define the metadata for the form. If necessary, you can add code to handle any events that cannot be handled declaratively in metadata.

The following high-level steps describe the basic process for creating a form:

1. Create the form resource. You can create a form from scratch, but often, you can use an existing form or a template as a starting point. When you create the form, be sure to set the Caption property on the form’s Design node. This is an important but often overlooked step.

2. Add data sources and set up join information. You can define custom queries and filters, if necessary.

3. Add controls to the form. You can add controls that are bound to fields to display data and action controls, such as buttons and Action panes, that let the user perform actions on the current record.

4. Add parts to the form that display data related to the main record. Parts can reduce the navigation that users must perform to find information.

5. Add navigation items so that users can access your form. Create a MenuItem control that points to the form. Add a reference to that MenuItem to Menu controls, or to other forms through MenuItemButton controls, to let the user navigate to the form.

6. Override form and control methods if you cannot achieve the behavior that you want declaratively through metadata.

7. Add business logic to classes as necessary to implement the functionality that the new form provides.

The following sections in this chapter contain more information about the components in each step. For the latest information and most up-to-date examples about how to build and customize forms, see the “Client” section in the AX 2012 SDK at http://msdn.microsoft.com/en-us/library/gg880996.

When you create a form, select a form pattern that reflects the type of data that appears in the form and the interaction pattern that is provided to the user. The “Form User Experience Guidelines” topic on MSDN (http://msdn.microsoft.com/EN-US/library/gg886605) discusses each of the form patterns. These guidelines are useful to ensure a seamless experience between the new form and the existing forms in AX 2012.

After you select a form pattern, you can create a form by using a template: In the AOT, right-click the Forms node, click New Form From Template, and then select the template you want.

The form that AX 2012 generates contains property values and controls that implement the structure specified by the form pattern. Table 6-1 describes the form templates that are available and the purpose of each type of form.

Form.DataSources The data structures that are used for the form. For more information, see the “Form data sources” section later in this chapter.

Form.Designs.Design The controls that display the data for the record. This metadata node name is often shortened to Form.Design or Form Design. For more information, see the “Adding controls” section later in this chapter.

Form.Parts The additional parts that display related data. For more information, see the “Using parts” section later this chapter.

Figure 6-1 illustrates these nodes in the AOT for the CustGroup form.

Ideally, you should use metadata to customize forms. Metadata customization is preferred over code customization because metadata changes (also called deltas) are easier to merge than code changes. To ensure the greatest level of reuse, any changes you make to the metadata should be made at the lowest level possible—for example, at the table level instead of the form level.

When customizing forms, you should be aware of the metadata associations and the metadata inheritance that are used to fully define the form and its contents.

Inheritance also occurs within forms. Controls that are contained within other controls receive certain metadata property behaviors from their parents unless different property values are specified, including Labels, HelpText, Configuration Key, Enabled, and the various Font properties.

Table 6-2 shows examples of pieces of metadata that are inherited from associated metadata.

The form data source points to a specific table, map, or view. The field list on the form data source is automatically populated with the fields that are defined on the resource it refers to. From that list, you can bind controls to those fields or any of the data methods that exist on the table or form data source.

Form data sources can be divided into the following categories:

Root data sources Root data sources do not contain a value for the JoinSource property and therefore are not joined with or linked to any other data source. Most forms have only one root data source. The root data source references the table data that is the primary subject of the form. Root data sources are sometimes called top-level data sources.

Master data sources Master data sources are root data sources or dynalinked data sources. A single query is used to retrieve the data for a master data source and the data sources that are joined to it. You can think of a master data source as being at the root of a query hierarchy.

Joined data sources Joined data sources are those that are joined to another data source. These data sources have a LinkType value of InnerJoin, OuterJoin, ExistJoin, or NotExistJoin. Typically, you use a join to combine data sources so that the data is retrieved by a single query. For example, in the CustTable form, DirPartyTable is joined to CustTable.

Linked data sources Linked data sources are data sources that are linked to another data source in the form. These data sources have a LinkType value of Active, Delayed, or Passive. Use a link for data sources that have a parent/child relationship so that the data is retrieved in separate queries. For example, in the SalesTable form, SalesLine is linked to SalesTable.

The following types of dynalinks are available:

Intra-form Intra-form dynalinks occur between data sources that have a LinkType value of Active, Passive, or Delayed. The child data source has a query that is separate from the parent data source, and the query runs at a time that is determined by the LinkType property.

Inter-form Inter-form dynalinks occur between related data sources on forms where one form (the parent) opens another form (the child). The DataSource property of a MenuItemButton on the parent form is used to specify which data source is used as the parent form side of the link. The child form side of the link is the first root data source.

If you model a form data source on a table that is a base type, the derived types are automatically expanded into a subnode called Derived Data Sources. This node is not editable and is generated by the forms engine. The derived data sources have no properties or methods of their own because all of those characteristics are inherited from the base form data source. However, you can still override and add methods to the fields for derived data sources. For example, the DirPartyTable data source, shown in Figure 6-2, is part of a table inheritance hierarchy.

Figure 6-2 shows all of the automatically generated data sources, one for each derived type. The Fields node for each derived type lists the fields for that type. When there is only a single chain of base types, all of the base fields are collapsed into a single Fields node underneath the form data source. For example, if you model a form data source based on the DirPerson type, the Fields node would contain all of the fields in the chain.

Instance methods on the form data source also follow the table inheritance hierarchy. For example, if the user triggers the validateWrite event when the current active record is of type DirPerson, the FormDataSource.validateWrite method is called, which will call DirPerson.validateWrite, which will call DirPartyTable.validateWrite, which will call the kernel-level Common.validateWrite. However, non–instance-specific methods such as executeQuery work on the general form data source, so there are no calls to any base methods.

Because polymorphic queries are allowed, polymorphic creation of records is also supported. When a user clicks New on a form with a form data source that has no derived types, the concrete type to create is known. However, when the form data source has derived types, the user must be prompted to select a type to create.

Traditionally, to create a record in X++ code, you had to call only the FormDataSource.create method. However, that method does not let you specify the type. To support the polymorphic creation scenario, use the following method:

Click here to view code image

FormRun.createRecord(str _formDataSourceName [, boolean _append = false])

All create actions performed by the kernel are routed through this method. You should also use this method instead of the create method. The first parameter specifies the name of the form data source in which to create the record, and the second parameter contains the same append value that is passed to the create method. You can override this behavior by adding conditional code that depends on the type being created. The call to the super of the method executes the correct logic depending on the type.

If the type (or any of the types in the join hierarchy) is a polymorphic type, the user is prompted to select the type of record to create, as shown in Figure 6-3.

The createRecord method lets you override the behavior of the super to either specify the types of records that the user can create, or display your own dialog box to the user. To inform the kernel of which types you want the user to choose from, you use the following method:

Click here to view code image

FormDataSource.createTypes(Map _concreteTypesToCreate [, boolean _append = false])

The first parameter contains a map of string key/value pairs, where the key is the name of the form data source and the value is the name of the table type to create. For example, if your objective is to always create a type of CompanyInfo, you could use the next code snippet. Note that the name of the form data source is the name of the data source that is modeled on the form, not the derived data source, as shown in the following code:

Click here to view code image

public void createRecord(str _formDataSourceName, boolean _append = false)
{
    Map typestoCreate = new Map(Types::String, Types::String);

    if(_formDataSourceName == "DirPartyTable")
    {
        typestoCreate.insert("DirPartyTable", "CompanyInfo");
        DirPartyTable_ds.createTypes(typestoCreate, _append);
    }
    else
    {
        super(_formDataSourceName, _append);
    }
}

With this new approach, the write and delete methods no longer apply, because the actions occurred in the call to the super for those methods. With the change group mode behavior, the writing, written, deleting, and deleted methods are used. For each type of operation, when the validate method for each data source is called on the client, the methods ending in ing, such as writing, are called. The transaction then occurs on the server, where the table insert, update, or delete methods are called. Finally, the methods ending in ed or en, such as deleted or written, are called.

Unit of Work has an additional feature called OptionalRecord that saves database space by inserting outer-joined records only if the values have been changed from the default. For OptionalRecord, the two possible options are ImplicitCreate and ExplicitCreate. In the ImplicitCreate scenario, the forms engine automatically creates the outer-joined record if the record does not exist in the database. The record is saved only if values are changed from the default value. In the ExplicitCreate scenario, you can model a check box on the form that explicitly controls the behavior of record creation and deletion for the outer-joined record.

1. Form data source objects are created that reference the data that is retrieved from the database.

2. The form’s queries are run to retrieve data.

3. Controls that are bound to fields show data that was retrieved.

By default, when the FormDataSource.AutoQuery property is set to Yes, a query is created for the form based on its data sources. The query is created in the call to the super of the form’s init method. The query contains a QueryBuildDataSource object for each form data source in the direct join hierarchy. Additional queries are created for dynalinked form data sources. These queries are linked to the current data in their joined parent so that the queries are correct. This has the benefit of splitting tables across multiple database queries, which can improve performance and remove the cross-product results that occur in 1:n joins. Figure 6-4 shows the data sources for an example AutoQuery.

In this example, properties are set on the data sources as follows:

The CustTable data source is the root form data source; therefore, its JoinSource property is not set.

The CustGroup data source has its JoinSource property set to CustTable with a LinkType value of OuterJoin.

The SalesTable data source has a JoinSource of CustTable and a LinkType value of Delayed.

With AutoQuery behavior, a query will be created with a root QueryBuildDataSource object of CustTable that has a child data source of CustGroup. Because the SalesTable data source is linked with a dynalink, it has its own query with a single root QueryBuildDataSource object. The SalesTable QueryBuildDataSource object has a dynalink added to it through the addDynalink method to the CustTable data source. When the form loads, the initial query runs to retrieve the data from CustTable and CustGroup. After the results are returned, a query runs to retrieve the SalesTable data based on the record in CustTable that is currently selected.

The second way of modeling the data access for a form is to use a query as the basis for the data source structure. You can do this by performing a drag-and-drop operation to add the query to the Data Sources node, or by setting the Query property. In this scenario, the query causes the respective form data sources to be generated for the form. No additional data sources can be added. This method of modeling data access is generally used only for list pages, because it requires two metadata items to be created to model the form. The extra work is beneficial in the case of list pages, because composite queries are created that contain filters for the secondary list pages that reuse the same list page form. For example, Customers On Hold, which is a secondary list page, reuses the Customers list page.

The root data sources of the query must match the form data source.

The joined data sources for the query should also be compatible.

In AX 2012, the kernel automatically adds any missing QueryBuildDataSource objects for required form data sources. This makes the queries as compatible as possible.

For more information about query filters, see Chapter 17.

The implied context of a data source is particularly important when actions are executed and records are saved:

When an action executes, it executes in the context of a particular data source. For example, when it initiates an action to create a new record, the record that is created depends on the current data context.

If changes to a record have not been saved when the cursor focus moves from a control in one data source context to a control in a different data source context, the record is saved automatically.

When changing the form at run time, you should lock it by using the element.lock method and the element.unlock method to ensure the changes occur at the same time instead of flickering into effect gradually. Locking the form can also improve performance because the form is redrawn only once.

MenuItemButton Activates a MenuItem to open a form, run a class, or display a report. This is the most common type of button because the behavior is modeled rather than defined explicitly through X++ code. For more information, see the “Adding navigation items” section later in this chapter.

CommandButton Executes a system-defined command, such as OK, Export to Excel, and Close. Use this type of button whenever a system-defined command exists for the action that you want to add.

Button Provides a clicked method that you can override to add X++ code. This type of button is used infrequently. Avoid using it, if possible, because it means that code will be added directly to the form.

DropDialogButton Opens a drop dialog form. Drop dialogs let the user quickly provide information or make choices that are necessary to execute some action. For example, with a drop dialog, a user can select a specific hold state when putting a customer on hold.

MenuButton Displays a menu. This type of button can contain any button type except another MenuButton.

You should populate the Text property for a Button or a MenuButton. However, the text for a CommandButton or a MenuItemButton should come implicitly from the referenced command or MenuItem, respectively.

You can place buttons directly on a form or within a ButtonGroup that is on a form. More commonly, buttons are placed inside an Action pane or an Action pane strip.

Use an Action pane at the top of large forms when you need multiple tabs to display the actions that are available for the entire form.

Use an Action pane strip at the top of smaller forms when there are a small number of actions for the form. You can define an Action pane strip by setting the ActionPane.Style property to Strip.

You can also use an Action pane strip to display actions that have a specific context. Common locations for an Action pane strip are at the top of a TabPage, FastTab, or Group control. The context might be fields of a particular category within a record or a collection of associated child records. The most common usage of a contextual Action pane strip is when displaying the Add and Remove actions above a grid that contains associated child records, as shown in Figure 6-6. When you are using an Action pane strip in a particular data context, you should set the DataSource property of the Action pane control.

For more information about how to design Action panes, see Chapter 5.

Group A Group control provides a way to group and categorize individual controls within the form. The Design node of a form, in addition to containing all of the controls, has many of the properties and behaviors of Group controls.

TabPage A TabPage control organizes the controls and fields on the form so that only a subset is displayed at one time.

Grid A Grid control displays input controls in a simple row and column format that allows the compact display of multiple fields for multiple records of the same type.

Try to use table field groups whenever possible. Table field groups allow for easier maintenance of the application because a change to a table field group affects every form or report that uses that field group.

If you are manually adding controls and a caption to a Group control, be sure to provide a descriptive and understandable caption that accurately describes the group.

The following styles are available for TabPage controls:

Standard Shows TabPage controls stacked on top of each other so that only one TabPage is visible at a time. This style, shown in Figure 6-7, is used throughout the product and should be familiar to most users.

VerticalTabs Shows TabPage controls listed as a vertically organized set of links to the left of the TabPage that is visible so that only one TabPage is visible at a time. This style, shown in Figure 6-8, is commonly used on parameters forms. Forms using this style are often said to have a table of contents style.

IndexTabs Shows TabPage controls listed as a horizontally organized set of tabs underneath the TabPage that’s visible, so that only one TabPage is visible at a time. This style, shown in Figure 6-9, is commonly used to display the line details on transaction detail forms.

FastTabs Shows TabPage controls listed vertically and lets users show multiple TabPage controls at a time. The user can choose which pages to see, and expand and collapse TabPage controls as necessary. With the FastTabs style, shown in Figure 6-10, you can also display summary information for key fields, even when the control is collapsed.

To ensure that FastTabs are helpful to users, keep them short so that users can see only the information that’s necessary, provide descriptive labels, and display only the most important summary fields when the tab is collapsed. For more tips on creating effective FastTabs, see Chapter 5.

If you do not want the Grid control to take up the entire form, you can control the size by using the VisibleRows property. For example, when you are displaying the addresses of a customer, many customers will only have one or two addresses. Setting VisibleRows to 3 is one way to display the relevant information and take up minimal space.

1. Right-click the Form.Data Sources node, and then click Open In New Window.

2. Place the new window containing the form data sources next to the original AOT window.

3. Drag the fields you want from the data sources to the appropriate location in a Group, TabPage, or Grid control on the form. This action creates the appropriate type of input control (StringEdit for strings, IntEdit for integers, and so on) and binds it to the data source field.

When binding a control to a display method, use the Datasource and Datamethod properties to point at the appropriate display method.

Display methods use the display keyword in the method declaration. The best examples of display methods are those that already exist in AX 2012. Use the search capability in the AOT to find example display methods on tables by looking for the display keyword followed by a space (display).

The standard display method format is as follows:

Click here to view code image

display SomeEDT myDisplayMethod()
{
    //Code here...
    return "returnValue";
}

To use a .NET control within an AX 2012 form, the AOT must contain a reference to the .NET assembly that contains the control. To add new .NET controls, add the assembly or assemblies that contain the controls to the Reference node of the AOT by right-clicking that node and then clicking Add Reference.

To reference that .NET control within an AX 2012 form, add a ManagedHost control and then use the Managed Control Selector dialog box to select the control you want. Right-click the new control to subscribe to events.

Try this simple example to add a .NET button to a form:

1. In the AOT, right-click the Forms node, and then click New.

2. Right-click the Design node, and then point to New Control > ManagedHost.

3. In the Managed Control Selector dialog box, in the top grid, select the System.Windows.Forms assembly; in the Controls grid, select Button; and then click OK.

4. Set the name of the control to ManagedButton.

5. Right-click the ManagedButton control to open the Events dialog box, and then add the Click event.

6. Expand the Methods node for the form, open the init method, and replace the existing code with the following to set the text for the button:

Click here to view code image

public void init()
{
    super();
    _ManagedButton_Control = ManagedButton.control();
    _ManagedButton_Control.add_Click(new ManagedEventHandler(this, 'ManagedButton_
    Click'));
    _ManagedButton_Control.set_Text("Managed button");
}

7. Open the code for the Click method, and then replace the existing code with the following to display text in the InfoLog:

Click here to view code image

void ManagedButton_Click(System.Object sender, System.EventArgs e)
{
    info("Managed button clicked");
}

Run the form, and then click the button. The result is shown in Figure 6-11.

Info parts are displayed like forms at run time. At design time, info parts use a simplified set of metadata that allows them to be displayed in both the AX 2012 client and the Enterprise Portal web client. Info parts have simple styling and are essentially a collection of data fields from the specified query. Info parts can define a set of actions to display below the data fields. Preview panes for list pages should be modeled as info parts so that they are also visible in Enterprise Portal.

Cue groups are a collection of cues. Cues are a mechanism for showing the count of the records from a query. Often, the query used for the cue is restricted based on the record currently shown on the host form. A cue contains three things: a query that provides the count, a MenuItemName property that specifies the action to take when a user clicks a cue, and a label that informs the user what the count is for (if none is provided, the MenuItem label is used). For more information about how to use cues, see Chapter 5.

Form parts are pointers to existing forms that can be displayed as FactBoxes. The Form property specifies the form to display, and the Caption property provides the title caption for the FactBox. When you are building a form to display as a form part, set the Style property to FormPart, the ViewEditMode property to View, and the Width property to ColumnWidth to ensure correct styling.

To create a standard part reference, follow these steps:

1. Set the MenuItemName property to the MenuItem that specifies the part. A MenuItem is used to reference each part to ensure that standard MenuItem-based security can be applied.

2. Set the DataSourceName and DataSourceRelationName properties to specify the correct data relation (dynalink) to use between the host form and the part.

3. Set the PartLocation property to indicate whether the part should be displayed as a FactBox (the default) or as a preview pane.

4. (Optional. For list pages only.) Set the DisplayTarget property to indicate whether the part will be displayed in the AX 2012 client, Enterprise Portal, or both.

5. (Optional) Set the Visible property to hide the FactBox by default. The FactBox is still available for users if they choose to show it.

When adding a Menu item to a menu, ensure that the IsDisplayedInContentArea property is set appropriately. For list pages and content pages that are displayed in the client, set this property to Yes so that the address bar is populated correctly.

When defining a module menu or adding items to an existing module menu, try to follow the standard groupings that are used in other menus:

Common Contains the most commonly accessed forms in the module. The Common group usually contains links to list pages.

Periodic Contains links to secondary data forms.

Inquiries Contains links to forms that provide read-only views of data that are related to the current module.

Reports Contains links to reports.

Setup Contains links to setup forms, including the parameters forms. Sometimes this group also contains secondary data forms.

The primary list pages listed in the Common group should be accompanied by secondary list pages. A secondary list page is a list page that adds ranges (filters) to a primary list page. You can implement a secondary list page as a menu item that points at the primary list page form but also specifies a query that adds a filter.

When you customize AX 2012, the following ideas might provide good starting points for investigation:

Use examples in the base AX 2012 application by using the Find command on the Forms node in the AOT (Ctrl+F).

Refer to the system documentation entries (AOTSystem Documentation) for information about system classes, tables, functions, enumerations, and other system elements that are implemented in the AX kernel.

Add a debug breakpoint in the init method for the form when you are looking for a suitable location for your customization code. Step through the execution of the method overrides. Note that control events (such as Clicked) do not trigger debugging breakpoints. You must explicitly add the breakpoint keyword to the X++ code for the debugger to stop in these methods.

For simpler code maintenance, follow these guidelines:

Use the field and table functions of fieldNum, such as fieldNum(SalesTable, SalesId), and tableNum, such as tableNum(SalesTable), when working with form data sources.

Avoid hard-coding strings. Instead, use labels, such as throw error(“@SYS88659”), and functions such as fieldStr and tableStr, which return the names of specified fields or a specified table, respectively.

Use as few method overrides as possible. Each additional method override has a chance of causing merge issues during future upgrades, patch applications, or code integrations.

By overriding methods on form data sources and form data source fields, you can influence how the form reads and writes data and responds to user-initiated data-related events. Table 6-6 describes the most important form data source methods to override. The most commonly overridden form data source methods are init, active, executeQuery, write, and linkActive.

Table 6-7 describes the methods to override for fields in form data sources. The most commonly overridden method for form data source fields is the modified method.

To reference business logic in classes:

1. Put a static main method on the class.

2. Add the code to the main method that starts the business logic.

3. Create an Action MenuItem that references the class.

4. Add a MenuItemButton on the form that points at the Action MenuItem.

For an example, you can follow these steps, using the following code inside the main method:

static void main(Args args)
{
    print "Hello World";
    pause;
}

After control is passed to the class, the args method can provide contextual information that might be useful when the class is called from multiple forms.

Automatic lookups generated by the framework perform in the ideal way for usability. If you choose to create your own custom lookup form for a given table, you should use the same pattern so that the behavior is consistent.

Creating a simple custom lookup is simple, especially if you want it to be used for all lookups for the target table type. Model a simple form with a Grid control to display the records, and then use the form name as the value for the FormHelp property on the EDT for the foreign key field. This works for both regular foreign keys and surrogate foreign keys. When the FormHelp property is set, the custom lookup form will be used instead of an automatically generated lookup.

In some scenarios, such as query modification or custom record selection, you might want to provide logic that runs before or after the lookup form is loaded. In these cases, you can use the FormAutoLookupFactory class. This class is implemented in the kernel and exposes much of the same functionality, such as initial positioning and filtering, to allow custom lookups to behave consistently. For an example in the application, examine the HCMWorkerLookup form and class. Looking at the class, you will notice that there are many different scenarios in which this form can be loaded. The different methods on the FormAutoLookupFactory class are called in each case. There is also corresponding code on the form that handles these cases, such as the code to set the SelectMode for the different types of source control.

This section describes how to make data sources available to the Office Add-ins and then provides an overview of how to create Excel and Word templates and make them available to users.

1. In the AOT, under the Services node, right-click the service that you want to make available, and then click Add-ins > Register Service.

2. In the client, click System Administration > Setup > Services and Application Integration Framework > Inbound Ports, and then do the following:

a. Create a new inbound port.

b. Select the service operations to add to the port.

c. Activate the port.

3. In the client, click Organization Administration > Setup > Document Management > Document Data Sources.

4. In the Document Data Sources form, do the following:

a. Create a new document data source.

b. Select the module that is associated with the data source.

c. Set the Type field to Service.

d. Select the inbound port that you just added as the data source.

e. Activate the new document data source.

1. Define a new query in the AOT, if necessary.

2. In the client, click Organization Administration > Setup > Document Management > Document Data Sources.

3. In the Document Data Sources form, do the following:

a. Create a new document data source.

b. Select the module that the data source (the query) is associated with.

c. Set the Type field to Query.

d. Select the query that you want to use as the data source.

e. Activate the new document data source.

A template can be as simple as a listing of the latest sales orders or as complex as an executive digital dashboard. Figure 6-12 shows an example of an Excel template.

From within an Excel workbook, do the following to access data from AX 2012:

1. Open the Options dialog box from the Microsoft Dynamics AX tab on the ribbon to ensure that the appropriate server and port connection information is present.

2. Click Add Data, and then select the appropriate query and service data sources.

3. Double-click or drag fields from the field chooser to add them to the worksheet.

4. Refresh the worksheet to verify the data that is being retrieved from AX 2012 and added to the workbook. If the dataset is too large, use the Filter option on the ribbon to add a filter.

Before providing the workbook to other users, do the following:

1. If necessary, add filters to restrict the dataset that is returned.

2. Open the Connection Options dialog box and remove the existing connection information so that the user’s connection information is supplied automatically by the Client SDK (using the information contained in the Microsoft Dynamics AX Client Configuration Utility).

3. Save the workbook without connection information.

From within a Word document, do the following to access data from AX 2012:

1. Open the Options dialog box from the Microsoft Dynamics AX tab on the ribbon to ensure that the appropriate server and port connection information is present.

2. Click Add Data, and then select the appropriate query and service data sources.

3. Double-click or drag fields from the field chooser to add them to the document. If you want to show calculated fields (display methods) on a data source, right-click that data source in the field chooser and then click Show Calculated Fields.

4. (Optional) Add individual field bindings throughout the document. These fields can be interspersed with static text, formatting, images, and other content.

5. (Optional) Display repeated values, such as the lines of a Sales Order. To do so, insert a table, and then add field bindings into the first row of that table.

6. Add a filter to select a particular record. When you are using a template that is available through the generate-from-template functionality, this record-specific filter is not present.

7. Save the document.

8. Click the Merge button to generate a document from the template.

Before sharing a document template with other users:

1. Add filters to restrict the dataset returned as needed.

2. Open the connection options dialog box and remove the existing connection information so that the user’s connection information is supplied automatically by the Client SDK (using the information contained in the Client Configuration Utility).

3. Save the document without connection information.

4. Provide your users with a copy of the document.

To add a group of templates as an option in a Generate From Template list:

1. Create Word document or Excel workbook templates that have a filter that does not restrict the results to a single record.

2. In the client, click Organization Administration > Setup > Document Management > Document Types.

3. Create a new document type, setting the Class field to Template Library.

4. Set the Document Library field to point to the Microsoft SharePoint folder where the templates are located. Ensure that the URL points to the folder and not a page (for example, http://myserver/DocumentTemplates/).

5. Click Synchronize to import the template list and activate the templates.

6. Verify that the templates appear in the Generate From Template list on the form. If the templates are not shown, ensure that the primary data source for the templates matches the primary data source for the form.

If the Generate From Template button is not available on a form, users can still generate a document from a template by opening the Document Handling form (File > Command > Document Handling) and then creating a new attachment from the Template Library type.

To add the Generate From Template button to additional forms or list pages:

1. Find the Generate From Template button on the Customers list page and copy it to the form you want to add it to. The path to the button is as follows:

AOTFormsCustTableListPage.DesignsDesignActionPane:ActionPaneActionPaneTab:HomeTabButtonGroup:AttachmentsGroupMenuButton:mbTemplatesButton

2. Edit the MouseDown method on the button to pass the correct TableId to the createTemplateOnMenuButton method by changing the CustTable.TableId parameter to point to the correct table (for example, MyTable.TableId).