Menu Items
A Menu Item is an AOT object that defines a single executable action in Dynamics 365 Finance & Operations. Every navigation link, button action, and report launcher in the application is backed by a menu item. Menu items are the glue between the navigation system (Menus) and the objects they execute — forms, classes, and reports.
There are three types of menu items, each corresponding to a different kind of target object:
| Type | AOT Node | Primary Target | Use Case |
|---|---|---|---|
| Display | Menu Items > Display | Forms | Opening a form to display or edit data |
| Action | Menu Items > Action | Classes (via SysOperationController or RunBase) | Running a business process, batch job, or action that may or may not show a UI |
| Output | Menu Items > Output | SSRS Reports | Launching a report for viewing, printing, or exporting |
All three types inherit from the abstract AxMenuItem base and share the same set of core properties. The only additional properties are on AxMenuItemAction, which adds state-machine integration fields.
Display Menu Items
A Display menu item opens a form. This is the most common menu item type — every list page, detail form, dialog, workspace, and lookup in the application is accessed through a Display menu item.
Set the ObjectType property to Form and the Object property to the name of the target form. When the menu item is executed, the framework creates an Args object, populates it with context from the calling form (if any), and calls FormRun to open the target form.
Typical scenarios:
- Navigation pane links to list pages and detail forms
- Button controls on forms that open related forms (e.g., "View details")
- Lookup forms opened from EDT relations
- Workspace tiles that open list pages with pre-filtered queries
Action Menu Items
An Action menu item runs a class. The target class must implement main(Args _args) as its entry point. Action menu items are used for processes that perform business logic — posting journals, running calculations, executing batch jobs, or any operation that transforms data.
Set the ObjectType property to Class and the Object property to the class name. The target class typically extends SysOperationController (or the older RunBase framework) and may optionally present a dialog to the user before executing.
Typical scenarios:
- Posting operations (e.g., posting a sales order invoice)
- Batch job execution
- Data import/export processes
- One-off actions triggered from form buttons (e.g., "Settle transactions")
- State machine transitions (using the
StateMachine,StateMachineDataSource, andStateMachineTransitionToproperties)
Output Menu Items
An Output menu item launches an SSRS report. Set the ObjectType property to SSRSReport and the Object property to the report name. The ReportDesign property optionally specifies which design within the report to use.
Typical scenarios:
- Printing invoices, packing slips, and purchase orders
- Generating financial statements and regulatory reports
- Exporting data to PDF, Excel, or other formats via the report framework
Context Passing with the Args Class
One of the most important concepts in D365 F&O menu item execution is context passing. When a menu item is executed — whether from the navigation pane, a button on a form, or programmatic code — the framework creates an Args object and populates it with contextual information. The target form or class receives this Args and uses it to determine what data to display, what record to operate on, and how to behave.
What Gets Passed Automatically
When a user clicks a button backed by a menu item on a form, the framework automatically populates the Args with:
| Args Method | What It Contains | Set By |
|---|---|---|
args.caller() | Reference to the calling FormRun object | Framework (automatic) |
args.record() | The currently selected record on the calling form's active data source | Framework (automatic) |
args.parmEnumType() | The enum type specified in the menu item's EnumTypeParameter property | Menu item metadata |
args.parmEnum() | The enum value specified in the menu item's EnumParameter property | Menu item metadata |
args.parm() | The string from the menu item's Parameters property | Menu item metadata |
args.menuItemName() | The name of the menu item being executed | Framework (automatic) |
args.menuItemType() | The type (Display, Action, Output) of the menu item | Framework (automatic) |
args.openMode() | The open mode (Auto, View, Edit, New) from the menu item's OpenMode property | Menu item metadata |
Accessing Context in a Form
When a Display menu item opens a form, the Args object is available in the form's init() method and throughout the form lifecycle.
Accessing Context in a Class
When an Action menu item runs a class, the Args object is passed to the main() method.
Automatic Record Context from Form Buttons
When a MenuFunctionButton control is placed on a form and bound to a menu item, the framework automatically passes the current record from the form's active data source as args.record(). This is the key mechanism that allows "drill-down" and "view details" navigation to work:
- User selects a record on Form A (e.g., a sales order line).
- User clicks a button bound to a Display menu item for Form B.
- The framework creates
Args, setsargs.record()to the selectedSalesLinerecord, and setsargs.caller()to Form A'sFormRun. - Form B opens, reads
args.record()in itsinit(), and filters or positions itself on the relevant data.
If the menu item's NeedsRecord property is set to Yes, the button will be disabled when no record is selected on the calling form. Use this to prevent users from opening context-dependent forms without a valid record.
Enum Type and Enum Value Parameters
The EnumTypeParameter and EnumParameter properties on a menu item allow you to pass a specific enum type and value through the Args to the target object. This is a powerful mechanism for reusing a single form or class for multiple purposes, with the enum value controlling behaviour.
How It Works
- On the menu item, set
EnumTypeParameterto the name of a base enum (e.g.,SalesUpdate). - Set
EnumParameterto the specific enum value name (e.g.,PackingSlip). - When the menu item executes, the framework sets
args.parmEnumType()to the enum type andargs.parmEnum()to the integer value of the specified enum member. - The target form or class reads these values and adjusts its behaviour accordingly.
Common Pattern: One Form, Multiple Menu Items
A frequent pattern in D365 F&O is to create multiple menu items that all point to the same form or class but pass different enum values. The target object inspects the enum parameter to determine which mode to operate in.
Accessing Enum Parameters at Runtime
The EnumTypeParameter and EnumParameter properties are especially useful for document posting workflows. The standard posting classes (SalesFormLetter, PurchFormLetter, InventTransferParmLine, etc.) all use this pattern to handle confirmation, packing slip, invoice, and other posting types through a single class with multiple menu items.
Open Mode
The OpenMode property controls how the target form behaves when it opens:
| Value | Behaviour |
|---|---|
| Auto (0) | The framework determines the mode based on context. Default behaviour. |
| View (1) | Opens the form in read-only view mode. |
| Edit (2) | Opens the form in edit mode for the current record. |
| New (3) | Opens the form and immediately creates a new record. |
This is commonly used when the same form is accessible from multiple navigation paths — for example, a "New customer" button uses OpenMode = New while the "All customers" list page uses OpenMode = Auto.
Copy Caller Query
When CopyCallerQuery is set to Yes, the target form inherits the query from the calling form's data source. This is the mechanism behind list page–to–detail form navigation: the list page applies filters (e.g., "open orders only"), the user clicks a record, and the detail form opens with the same filters applied so that the user can navigate forwards and backwards through the same filtered set.
Security and Permissions
Menu items are the primary unit of entry-point security in D365 F&O. The security framework uses menu items as entry points in security privileges, which are grouped into duties and ultimately into security roles. The permission properties on a menu item control the maximum access level granted when the menu item is used:
| Property | Description |
|---|---|
ReadPermissions | Grants read access to the form/report data sources |
CreatePermissions | Grants create (insert) access |
UpdatePermissions | Grants update access |
DeletePermissions | Grants delete access |
CorrectPermissions | Grants correcting-entry access (for journals) |
These properties accept Auto, Yes, or No. When set to Auto, the framework determines permissions based on the security privilege configuration. When explicitly set, they override the privilege-level settings for this specific menu item.
The LinkedPermissionType and LinkedPermissionObject properties allow a menu item to inherit permissions from another object (e.g., a form or code permission) so that security is centrally managed.
Menu Item Extensions
To modify properties on a standard menu item without overlayering, use a Menu Item Extension. The three extension types mirror the three menu item types:
| Extension Type | Applies To |
|---|---|
AxMenuItemActionExtension | Action menu items |
AxMenuItemDisplayExtension | Display menu items |
AxMenuItemOutputExtension | Output menu items |
Extensions can modify property values on the base menu item (e.g., changing the Object, Label, or permission properties) through PropertyModifications. They inherit from the abstract AxMenuItemExtension base.