Using the Office Add-ins API [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2

The Microsoft Office Add-ins for Microsoft Dynamics AX enables you to integrate data from the Microsoft Dynamics AX client together with Microsoft Excel or Microsoft Word. When you install Office Add-ins, a tab labeled Dynamics AX is added to the ribbon in Excel and Word. You use the controls on this tab to add, remove, or update Microsoft Dynamics AX data that appears in an Excel spreadsheet or Word document.

• How to: Add an Office Add-in Filter to a Spreadsheet
• How to: Use Office Add-ins to Lock an Excel Spreadsheet

The Microsoft Dynamics AX 2012 R2 Office Add-ins include an application programming interface (API) that you can use to change filter and other criteria in an Excel spreadsheet or Word document. You use the API when you want to programmatically customize a spreadsheet or document.

For example, you use the Export to Excel button on the Action Pane of a form to create a spreadsheet that is used by several people. You now want to create a version of that spreadsheet file for one person who works with a smaller set of records. To show a subset of records in the spreadsheet, you create an application that uses the API to filter records from the spreadsheet. You then save that file as a separate version of the original spreadsheet.

Working with Spreadsheet and Document Files

---

Excel 2007, Word 2007, and later versions use the Office Open XML format for spreadsheet and document files. To programmatically modify these files, you use the Open method of theSpreadsheetDocument class or the WordprocessingDocument class of the DocumentFormat.OpenXml.Packaging namespace. The namespace is found in the DocumentFormat.OpenXmlassembly.

XML Metadata for Office Add-ins

---

The Office Add-ins embeds a custom XML part in every spreadsheet or document. The XML part includes metadata that describes the connections, tables, fields, filters, and other information that helps show Microsoft Dynamics AX data in the spreadsheet or document.

The following illustration shows how the metadata in the custom XML part is organized for an Excel spreadsheet. In the diagram, the Office Add-ins XML is the embedded XML part. The diagram also shows that the part includes nodes for the workbook options and data sources.

To programmatically add, remove, or modify the XML that Office Add-ins embeds in a file, you use the Serializer class. The class is in theMicrosoft.Dynamics.AX.Framework.OfficeAddin.XmlParts namespace of the Microsoft.Dynamics.AX.Framework.OfficeAddin.XmlParts.dll .NET assembly. When you install the Office Add-ins, the assembly is put in the C:\Program Files (x86)\Microsoft Dynamics AX\60\OfficeAddins folder. The Serializer class includes the following methods:

Method	Description
GetWorkbookXmlPart	Get the custom XML part from a spreadsheet. The method returns a WorkbookXmlPart object.
SetWorkbookXmlPart	Saves changes to the custom XML part of a spreadsheet.
GetDocumentXmlPart	Get the custom XML part from a Word document. The method returns a DocumentXmlPart object.
SetDocumentXmlPart	Saves changes to the custom XML part of a document.

In addition, the DocumentFormat.OpenXml and Microsoft.Dynamics.AX.Framework.OfficeAddin.XmlParts assemblies are added to the list of References in the AOT. As a result, you can use the classes in these assemblies from your X++ code to programmatically add, remove, or modify the XML in a spreadsheet or document. For more information about how to use a .NET assembly from X++, see How to: Compile and Run X++ that Calls CLR Managed Assemblies.

Workbook Options

The workbook options node is a collection of properties you use to control the behavior of an Excel spreadsheet. You can use the Office Add-ins API to programmatically access the following properties of the workbook options node:

Property	Type	Description
IsDesignLocked	bool	Specifies whether the spreadsheet or document is locked. To enable the lock, set the property to true. For information about how to programmatically access the workbook options node, see How to: Use Office Add-ins to Lock an Excel Spreadsheet. If the file is locked, you cannot use the controls in the Dynamics AX tab to modify the data source or fields that appear in the spreadsheet.
RefreshAllDataOnOpen	bool	Specifies whether the data in the spreadsheet is refreshed when the file is opened. To refresh the data, set the property to true. You can also use the Options for working with Microsoft Dynamics AX window from the Dynamic AX tab to set this property value.

Data Sources

The data sources node is the XML metadata that describes one or more data connections that a spreadsheet or document uses to obtain data from Microsoft Dynamics AX. Typically, the data sources are added when you export data from a form or you use the Office Add-ins to retrieve data.

The following illustration shows the structure of the XML metadata for the data sources node. Notice how a data source can include filters and matrix fields.

Using the Office Add-ins API with XML Metadata Nodes

To programmatically add, remove, and modify Office Add-ins XML nodes, you use several classes in the Microsoft.Dynamics.AX.Framework.OfficeAddin.XmlParts namespace. The namespace is found in the Microsoft.Dynamics.AX.Framework.OfficeAddin.XmlParts.dll .NET assembly. The classes include properties and methods that you use to modify the metadata values in the Office Add-ins XML part. To see how you can use API classes to add a filter to a spreadsheet, see How to: Add an Office Add-in Filter to a Spreadsheet.

The following table shows the class you use with each XML node you find in the custom XML part that Office Add-ins embed in a spreadsheet or document file.

XML node	Class
Office Add-ins XML	You use the WorkbookXmlPart class to represent the Office Add-ins XML part from a spreadsheet. You use the DocumentXmlPart class to represent the Office Add-ins XML part from a document.
Workbook options	You use the WorkbookOptionsXmlPart class to access the workbook option properties for a spreadsheet. You use this class to change the IsDesignLocked andRefreshAllDataOnOpen properties for a spreadsheet.
Data sources	You use the DataSourcesXmlPartDictionary class to get the collection of data sources in the Office Add-ins XML.
Data source	You use the DataSourceXmlPart class to get a single data source node from the data source collection of a spreadsheet or document.
Filter collection	You use the FilterXmlPartCollection class to get the filters for a specified data source. You can use the Add method of this class to create a new filter node. You can also use the Remove method to delete an existing filter node.
Filter	You use the FilterXmlPart class to view and modify the properties of an individual filter node.
Matrix field collection	You use the MatrixFieldXmlPartCollection class to get the matrix fields for a specified data source.
Matrix field	You use the MatrixFieldXmlPart class to view the properties of an individual matrix field node and modify the expression property of that matrix field.

Filtering Records in a Data Source

---

The earlier diagram shows that a data source can include filters. The diagram also shows that the Filters node can include one or more individual filter nodes. A filter node includes the criteria that specify the data records that appear in a spreadsheet or document. To customize the spreadsheet or document, you can use the Office Add-ins API to add, remove, or modify filter nodes.

Filter Nodes

A filter is an XML metadata node that specifies a field, a table, and criteria. The data source uses the properties of the filter to determine what records appear in a spreadsheet or document. A filter node is like a Range in an AX query. For information about how to modify a filter, see How to: Add an Office Add-in Filter to a Spreadsheet. To learn about AX queries and ranges, see Query Elements in the AOT.

To populate the properties, you use the same values that you would use with Add Condition in the Filter results dialog window. The following table shows the properties for a filter node.

Property	Type	Description
Criteria	string	Specifies the filter operation and value. For example, you could use > 0 to specify the criteria for a credit limit field.
FieldFullyQualifiedName	string	Specifies the fully qualified name of the field for the filter. The format for the name is <data source>.<table name>.<field name>.
TableFullyQualifiedName	string	Specifies the fully qualified name of the table where the field appears. The format for the name is <data source>.<table name>.

Modifying a Matrix Field in a Data Source

---

The earlier diagram shows a data source can include a collection of matrix field nodes. A matrix field is an XML metadata node you use to show a total for a group of related records on a spreadsheet. To add a matrix field, you use the Create New Matrix Field dialog window in the Dynamics AX tab. A matrix field includes the following components:

• A field that contains the values that you use to put related records into groups. For example, you could group customer records by Credit rating.
• A measure field that contains the numeric values that you want to total for each group. For example, you could total the Credit limit field to show the total credit available to eachCredit rating group.
• An expression that specifies whether to include a record in one of the groups that appears in the spreadsheet. The total for the measure field will not include the value of any records that are excluded by the expression. For example, you could use the expression to show credit rating groups for customers from a specified country or region.

The following table shows the properties for a matrix field node. You use the read-only properties to identify the matrix field you want to work with. You can then use the Office Add-ins API to modify the expression property for that matrix field. If you change the value of a read-only property, the value that you set will be ignored when you save the XML to the spreadsheet.

Property	Type	Description
DataSourceName	string	The name of the data source. This property is read-only.
DataSourceQualifiedName	string	The full name for the data source. This property is read-only.
DisplayName	string	The name of the filter. This property is read-only.
ExpressionModel	string	The serialized form of the expression associated with the field. To modify a matrix field, you change the values in the expression To de-serialize and modify the expression, you can use the ExpressionInfo class and related classes in theMicrosoft.Dynamics.AX.Framework.OfficeAddin assembly.
FieldName	string	The name of the field. This property is read-only.
FullyQualifiedFieldName	string	Specifies the fully qualified name of the field for the filter. This property is read-only.
Id	Guid	Specifies the ID of the MatrixField object associated with this filter. This property is read-only.
MeasureFieldFullyQualifiedName	string	Specifies the full name of the field that defines the measure for the matrix field. This property is read-only.

Extending the Alerts Functionality [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

The guidelines in this section provide information about how the Alerts functionality can be customized within the Alerts framework. The Alerts functionality is a notification system that helps users track critical events in Microsoft Dynamics AX, and the Alerts framework is the framework that enables the Alerts functionality.

• Creating Rules for Alerts
• Event Detection and Processing for Alerts
• Viewing Alerts
• Event Enabling a Field for Alert Rules
• How to: Add Custom Actions for Alerts
• How to: Add Custom Actions UI for Alerts
• How to: Implement a New EventType Class
• Registering New Event Types

Understanding the framework will enable you to customize it for your customers’ needs. You will also receive step-by-step guidance on how to customize events, actions, and the user interface (UI) for rules, as indicated in the table below.

The Alerts functionality consists of four major parts; with the exception of event detection, you are likely to modify all of them:

• Rule creation
• Event detection
• Event processing
• Alert viewing

The following two tables describe various aspects of Alerts (on a module-by-module basis) that are essential to customizing the Alerts functionality.

Topic	Description
Creating Rules for Alerts	Provides information about where rule information is collected and where it can be maintained.
Event Detection and Processing for Alerts	Provides information about the processing and detection of change-based (Create/Update/Delete, or CUD) events and due date events.
Viewing Alerts	Provides information for customizing the EventAlertInbox form.
Event Enabling a Field for Alert Rules	Provides information for event enabling a field so that alert rules can be created in that field.
How to: Add Custom Actions for Alerts	Provides information for implementing custom EventAction classes.
How to: Add Custom Actions UI for Alerts	Provides information for adding UI for custom actions on the CreateAlertRule form and the ManageAlertRule form.
How to: Implement a New EventType Class	Provides information for implementing custom EventType classes.
Registering New Event Types	Provides information for registering new event types with the Alerts framework.

Terminology applied

---

Term	Description
Event	Any type of change (in data) or activity being monitored. The current implementation of the Alerts functionality can monitor change-based events and due date events. A change-based event is an event type that occurs when users create, delete, or change a record. Change-based events are categorized into create and delete events. These event types include creating and deleting records, and updating events that include changing records. Change-based events are also referred to as Create/Update/Delete (CUD) events. A due date event is an event type that occurs when a date occurs that is specified in the system.
Rule	To monitor events, you must subscribe to them. A rule is basically your subscription to a certain type of event; for example, when a record is inserted in a specific table.
Alert	A notification that you receive when an event occurs to which you have subscribed.
Action	The response of the system to a certain type of event. For example, an action could be inserting an alert in a user's inbox or sending an e-mail message. The current implementation of the Alerts functionality enables multiple actions per event to be carried out.

Wizards in Microsoft Dynamics AX [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

A wizard is a special form of user assistance that takes the user through a task by using a series of dialog boxes. Wizards are especially useful for complex or infrequent tasks that the user may have difficulty learning or doing, or for tedious, frequently performed tasks.

• Guidelines for Wizard Development
• Enabling Wizard Buttons Depending on User Input
• How to: Create Wizards
• Wizard Classes

Following are examples of standard Microsoft Dynamics AX wizards, available in Tools:

• The Report Wizard simplifies report generation process by leading the user through the steps necessary for creating a report. The wizard provides identical functionality to the commands in the Report node's shortcut menu.
• The Class Wizard guides you through all the required selections necessary to create a class, and allows you to inherit from an existing Microsoft Dynamics AX class.

To help you create your own wizards with the same look and feel as the standard wizards, Microsoft Dynamics AX includes a Wizard Wizard.

Tip
Use the Application Hierarchy Tree facility to get a list of all the wizards in Microsoft Dynamics AX. Open the Application Object Tree and select the SysWizard class. Right-click to open the shortcut menu and then click Add-Ins > Application Hierarchy Tree.

Menus and Menu Items [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

You can create menu items to provide access to forms, reports, classes, jobs, and queries in Microsoft Dynamics AX. You can also create menus.

You can add menu items to menus. You can also add menu items to forms and reports by using controls. For more information, see Form Control Properties.

You can customize the menus and menu items that ship with Microsoft Dynamics AX by using properties. For more information, see Menu Properties and Menu Item Properties.

• How to: Create Menus and Menu Items
• How to: Access a Class from a Menu
• How to: Add a Submenu

Parts [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

A Part is a specialized type of control you use to retrieve and show a collection of data. A part specifies how to retrieve the data that appears in the FactBox pane of a form, the preview pane of a list page, or the enhanced preview of a control. You use parts to provide information related to a record that appears in a form.

• How to: Create a Form Part
• Info Parts
• Cues and Cue Groups

Parts and Forms

---

When you add a part to a form, the collection of data that appears on the form is called a FactBox. A FactBox always represents a single part. To create or modify a FactBox, you create or modify the underlying part.

Unlike other form controls, a part is defined by using metadata. Each part you create extends a common metadata model for parts. The metadata model enables you to create parts that can appear in both the client and Enterprise Portal (EP). In addition, the metadata model enables you to create a part by populating a relatively small number of properties. For example, you do not have to specify values for properties like color, font size, borders, and margins.

To create or modify a part, you use the properties of that part to describe how to retrieve and show data. For example, you use a part property to specify the data source for the part. Typically, you use a query as the data source for a part. You also use properties to specify the data fields that show when the part appears as a FactBox on a form.

Note
To guarantee that a part can appear in both the client and EP, you cannot override methods for the part or the controls that appear in the part.

To add a part to the FactBox pane or preview pane of a form, you add a part reference to the Parts node of the form. For information about how to add a part reference to a form, seeHow to: Add a Part to the FactBox Pane.

Types of Parts

---

There are several types of FactBoxes that you can use in the FactBox pane of a form, the preview pane of a list page, or the enhanced preview for a control. For information about the types of FactBoxes, see FactBox Panes. To create each type of FactBox, you use one of the following part types.

Part type	Description
Info Part	A part that shows a collection of data fields from a specified query. An info part uses metadata to describe how the data appears. As a result, you can use an info part in both the client and EP.
Form Part	A part that represents a pointer to a form. You use a form part when you want a form to appear in the FactBox pane, enhanced preview, or preview pane. Caution Enterprise Portal does not support the use of a form as a FactBox. To use a form part with Enterprise Portal, you use the ManagedContentItem property to specify a User Control. The specified User Control appears in Enterprise Portal as the FactBox.
Cue Group	A part that includes reference to one or more cues. You use a cue group to list a collection of query results. Typically, the list shows summary data that is related to a record or a task.

To create, modify, or remove a part, you use the Parts node of the AOT. If you remove a part, you must be certain that the part is not used in the FactBox pane of a form, the preview pane of a list page, the enhanced preview of a control, or in a User Control for Enterprise Portal.

Controls in Microsoft Dynamics AX [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

This section of the documentation describes the types of controls you can add to a Microsoft Dynamics AX form. A control is an object that displays data, performs actions, or guides the user. The following sections provide information about each type of control.

In This Section

---

• Using Controls in a Form Design
• Form Controls
• .NET Controls
• ActiveX Controls
• Applying Country Specific Functionality
• How to: Set a Form Control to be Country Specific

Form Data Sources [AX 2012]

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

A form data source is the database query, table, or view that a form uses to retrieve the data that is displayed by the form. The data source also defines a connection to the Application Object Server (AOS) that the form can use to create, update, or delete database records. This section of the documentation describes how to use the Application Object Tree (AOT) to configure a form data source.

In This Section

---

• Data Sources for Forms
• Reference Data Sources for Forms
• Derived Data Sources for Forms
• Date Effective Data Sources for Forms
• Change Group and Optional Record Modes
• AutoJoin System
• How to: Join Data Sources for a Form
• How to: Join Parent/Child Data Sources for a Form
• How to: Add a Field Group to a Form
• Form Data Source Properties
• Form Data Source Field Properties
• Methods on a Form Data Source

Using COM to Open a Form from an Application [AX 2012]

When you install the Microsoft Dynamics AX client, AX32.exe registers as a COM server. Microsoft Component Object Model (COM) is a platform-independent, distributed, object-oriented system for creating binary software components that can interact. As a result, you can use the Dynamics AX COM server to open a specified form. For example, you can create a .NET application that uses the DynamicsAxApplication COM interface to open the customer list page form.

• How to: Use COM to Open a Form
• How to: Specify the Partition for the Form
• Dynamics AX Client Type Library Reference

Using the Dynamics AX COM Object

---

The Dynamics AX COM object represents a running instance of the Microsoft Dynamics AX client application. You will have a Dynamics AX COM object for each client workspace that is running on your computer. To use the Dynamics AX COM object, you use a COM interface that specifies the methods, properties, and enumerations for the COM object. In addition, the COM interface starts the client for you whenever a running COM object is not found.

In Microsoft Dynamics AX 2012 R2, you can use a moniker to specify a partition for the Dynamics AX COM object. A COM moniker is a name that uniquely identifies a COM object. Apartition is a division of processing into logical or functional parts for an application. In Microsoft Dynamics AX 2012 R2, partitions are used to enable data isolation. For example, you might use partitions to represent independent subsidiaries for an organization. For information about how to specify a partition, see How to: Specify the Partition for the Form.

Note
If you use the COM interface to start the COM object, the interface will use the default partition for the logged in user.

The COM interface always connects to the first running instance of the Microsoft Dynamics AX client. The interface does not check that the COM object is associated with a specified partition. If you can view data in more than one partition, you have to verify that you are working with data from the targeted partition.

Using the Dynamics AX Client Type Library

---

To provide access to the Dynamics AX COM object, AX32.exe includes a type library named Dynamics Ax Client 1.0 Type Library. A type library (.tlb) is a file that stores information about the properties and methods of a COM object.

You use the Dynamics AX Client Type Library when you want to use the Dynamics AX COM object from an application. For example, you want to open a form from an application built by using the Microsoft .NET Framework. The .NET application uses the type library to add an interop assembly to the project. The interop assembly enables you to use the interfaces associated with the COM object.

For each interface in the type library, the interop assembly defines .NET equivalents, or wrappers, for the COM properties and methods. When you call a method from an interop assembly, a .NET-to-COM translation is executed, and then control is passed to the COM component. When the COM object returns a result, a COM-to-.NET translation is executed. In addition, the COM result is checked, and an exception is thrown if there is an error. For information about how to add the type library to a .NET application, see How to: Use COM to Open a Form.

Using the DynamicsAxApplication Interface

DynamicsAxApplication is the interface you use to open a specified form. The following table shows the method that you use.

Method	Description
OpenMenuItem	Opens a form. You use a menu item to identify the form. The COM object executes “open form” logic with the specified menu item.

For more information about the interfaces in the type library, see Dynamics AX Client Type Library Reference.

Security

---

To use the Dynamics AX COM object, you must be logged in as an authenticated Microsoft Dynamics AX user. The implementation of the API assumes each menu item has an associated security key. If the menu item is found not to have a security key, the call to OpenMenuItem returns the HRESULT value E_ACCESSDENIED.

See also

---

Partitions, Companies, and Data Isolation in Microsoft Dynamics AX