5.2 Menus, Menu Items & Navigation

5.2 Menus, Menu Items & Navigation

Quick Answer: Dynamics 365 Finance and Operations abstracts user navigation, command execution, and security through Menu Items. There are three specialized types of menu items: Display (opens forms for interactive viewing and editing), Output (launches SSRS reports, Electronic Reporting formats, or report controllers), and Action (executes X++ classes, batch jobs, or transaction posting logic). Menu items define critical runtime properties including Object, ObjectType, Parameters, ConfigurationKey, CountryRegionCodes, and NeedsRecord. In the security architecture, menu items serve as the Entry Points within Security Privileges. Users cannot interact with a form, report, or class unless they are assigned a security role granting access to the corresponding menu item entry point.

---

1. The Dynamics 365 Navigation Framework

The web client navigation framework provides unified access to all functional modules, workspaces, and setup areas across the ERP application.

Primary Navigation Components

• Navigation Pane (Left Drawer): Hosts high-level navigation categories:
  • Workspaces: Curated, role-specific landing pages displaying tiles, lists, and links.
  • Modules: Complete alphabetical catalog of functional areas (e.g., Accounts payable, General ledger, Warehouse management).
  • Favorites: Personal pinned shortcuts configured by individual users.
  • Recent: Chronological history of recently visited forms and workspaces.
• Navigation Search (Alt+G): Global search bar located in the top navigation ribbon. Users search for forms or workspaces by typing terms (e.g., "All sales orders"). The search engine indexes labels and descriptions of all menu items flagged with WebSearchResult = Yes.
• Direct URL Navigation (Deep Linking): Forms can be launched directly using URL query parameters: https://<environment>.operations.dynamics.com/?cmp=USMF&mi=CustTable
  • cmp: The target Legal Entity context (Company ID, e.g., USMF).
  • mi: The target Menu Item name (e.g., CustTable), not the physical form name.

---

2. Menu Item Architecture & Types

A Menu Item is an AOT pointer that decouples the visual navigation trigger (buttons, links, menu nodes) from the target object being executed. This indirection ensures that security, parameter passing, and regional filtering are managed in one centralized metadata definition.

Navigation Trigger (Navigation Pane / ActionPane Button / Search Alt+G)
│
└── Menu Item Reference (Display, Output, or Action)
    │
    ├── Security Layer: Entry Point on Security Privilege (AccessLevel: Read..Delete)
    ├── Environment Filter: ConfigurationKey & CountryRegionCodes
    └── Execution Layer: Constructs Args object -> Launches Target Object

The Three Menu Item Types

---

3. Key Properties of Menu Items

Menu item properties control runtime behavior, environment filtering, and data passing:

1. Object and ObjectType

• Object: Specifies the exact AOT name of the target artifact (e.g., CustTable for a form, SalesInvoiceController for a class).
• ObjectType: Dictates the target artifact category (Form for Display; Report or Class for Output; Class for Action).

2. Parameters & Enum Parameters

• Parameters: A literal string passed to the target object via _args.parm(). Often used when a single generic form handles multiple operational modes (e.g., passing "Vendor" vs "Customer" to a shared address inquiry form).
• EnumTypeParameter & EnumParameter: Passes a strongly-typed enumeration value via _args.parmEnumType() and _args.parmEnum(). For example, opening a sales order list filtered specifically to open orders by setting EnumTypeParameter = SalesStatus and EnumParameter = Backorder.

3. NeedsRecord

• When set to Yes, the button or link referencing this menu item is automatically disabled in the UI unless an active record row is selected in the calling grid or form data source.
• Prevents runtime null-pointer exceptions when user actions depend on a specific record context (such as recalculating a discount for an active sales line).

4. MultiSelect

• Controls whether the menu item can be executed when multiple rows are highlighted in a grid.
• If set to No, selecting multiple rows in the client disables the button.
• If set to Yes, the calling form packages the selected records into the _args object using FormDataSource.getFirst(1) and FormDataSource.getNext().

5. ConfigurationKey

• Associates the menu item with a system license or feature configuration key (e.g., Asset, Retail, PublicSector).
• If the configuration key is disabled in License Configuration, the menu item is completely stripped from the UI and cannot be accessed by any user, including System Administrators.

6. CountryRegionCodes

• A comma-separated list of ISO 3166-1 alpha-2 country codes (e.g., US, CA, MX, or DE, AT).
• At runtime, the client compares these codes against the primary address country of the active Legal Entity (Company).
• If the active company's country does not match, the menu item is hidden from the navigation pane and ActionPanes.

7. WebSearchResult

• A boolean (Yes/No) indicating whether the menu item appears in the global Navigation Search (Alt+G) dropdown.
• Set to No for secondary child buttons, dialog helpers, or sub-processes to avoid cluttering search results.

---

4. Menu Extensions: Extending Navigation Without Overlayering

Standard menus in Dynamics 365 cannot be overlayered. Developers extend the navigation structure by creating Menu Extensions.

Extending MainMenu and Module Menus

• MainMenu Extension (MainMenu.Extension): Used to add entirely new top-level functional modules to the Navigation Pane drawer.
• Module Menu Extensions (e.g., AccountsReceivable.Extension, ProcurementAndSourcingMenu.Extension):
  • Standard module menus organize navigation into four standard submenus: Common, Inquiries, Reports, and Setup.
  • Developers add references to custom Display, Output, or Action menu items directly into these existing submenus.
  • Developers can also create new custom submenus within the module menu.

Positioning in Menu Extensions

When adding a menu item reference or submenu via extension, developers define its visual placement using the Position property:

• First / Last: Places the item at the start or end of the group.
• After: <TargetMenuItem>: Inserts the item immediately following a specified standard menu item.
• Before: <TargetMenuItem>: Inserts the item immediately preceding a specified standard menu item.

[!IMPORTANT] Menu Extension Limitation: You cannot remove or delete standard menu items from an existing menu via extensions. You can only add new menu items, create new submenus, and organize custom navigation nodes.

---

5. Security Linkage: Menu Items as Entry Points

Dynamics 365 Finance and Operations enforces a strict Role-Based Security Architecture (RBAC):

Security Role (Job function, e.g., Accounts Receivable Clerk)
│
└── Security Duty (Business process task, e.g., Maintain customer master data)
    │
    └── Security Privilege (Granular action, e.g., Edit customer records)
        │
        └── Entry Point (Direct pointer to a Menu Item)
            └── AccessLevel: Read | Update | Create | Correct | Delete

Entry Points in Security Privileges

• Under a Security Privilege, developers add an Entry Point node.
• The Entry Point has an ObjectType property (MenuItemDisplay, MenuItemOutput, or MenuItemAction) and an ObjectName property referencing the menu item.
• AccessLevel Property: Dictates the maximum permission granted to the underlying object:
  • NoAccess: Explicitly denies access.
  • Read: User can view data; forms render in read-only mode, fields cannot be modified, and New/Delete buttons are hidden.
  • Update: User can view and edit existing records, but cannot create new records or delete records.
  • Create: User can view, edit, and create new records, but cannot delete records.
  • Correct: Used primarily in temporal/dated tables to modify past historical records.
  • Delete: Complete operational permissions (view, edit, insert, and delete).

Permission Cascading

When a user accesses a form via a Display menu item entry point granted with Read access, the runtime security kernel automatically cascades Read access down to all form data sources and child controls. Unless explicit form control permissions override this behavior, developers do not need to secure individual form fields manually.

---

6. Scenario Walk-Through: Creating an Action Menu Item with Parameterized Security

Business Scenario

Contoso Manufacturing requires a command button on the All Sales Orders form that triggers an asynchronous credit re-evaluation process for the selected sales order. The button must only be active when a sales order row is highlighted. In addition, only users assigned to the Credit Specialist role should have permission to execute the action.

Implementation Steps

1. Develop Service Controller Class:
   • Create class ContosoSalesCreditEvalController extending SysOperationServiceController.
   • Implement static method main(Args _args) that inspects _args.record() for an active SalesTable buffer.
2. Create Action Menu Item:
   • In Visual Studio, add a new Action Menu Item named ContosoSalesCreditEvalAction.
   • Set properties:
     • Object = ContosoSalesCreditEvalController
     • ObjectType = Class
     • Label = @ContosoLabels:EvaluateCreditTitle
     • NeedsRecord = Yes (Crucial: ensures button is disabled if no order row is selected)
     • MultiSelect = No
3. Insert Button into Form ActionPane:
   • Create a form extension for SalesTable (SalesTable.ContosoExt).
   • Locate ActionPane > ActionPaneTabManage > ButtonGroupCredit.
   • Add a MenuFunctionButton referencing ContosoSalesCreditEvalAction.
4. Create Security Privilege & Entry Point:
   • Create Security Privilege ContosoSalesCreditEvalPrivilege.
   • Add an Entry Point named ContosoSalesCreditEvalAction with ObjectType = MenuItemAction.
   • Set AccessLevel = Update (permits executing business logic).
5. Link to Security Duty:
   • Extend standard duty CustCreditManagementMaintain and add ContosoSalesCreditEvalPrivilege.

---

7. Real-World Exam Traps: Menus, Menu Items & Navigation

[!WARNING] Exam Trap 1: Using the Wrong Menu Item Type for Classes or Reports A recurring MB-500 exam scenario presents a requirement to run an SSRS report from a button and asks which menu item to create. Selecting a Display menu item is incorrect. Running SSRS reports or report controller classes strictly requires an Output menu item. Running batch jobs or operational classes requires an Action menu item.

[!WARNING] Exam Trap 2: Forgetting NeedsRecord = Yes Leads to Null Buffer Errors When an ActionPane button executes logic dependent on the current row buffer (e.g., salesTable = _args.record()), failing to set NeedsRecord = Yes allows users to click the button when the grid is empty or during form load, triggering runtime null reference exceptions in X++.

[!WARNING] Exam Trap 3: Confusing Configuration Keys with User Security If a menu item is missing for a user who possesses the System Administrator role, candidates often mistakenly assume a security role or privilege issue. System Administrators bypass all security roles and duties. If a menu item is invisible even to a System Administrator, the cause is an inactive ConfigurationKey or a mismatch in CountryRegionCodes.

[!WARNING] Exam Trap 4: Direct Form Assignment in Security Privileges In modern Dynamics 365 Finance and Operations, forms and classes cannot be assigned directly as entry points on security privileges. Entry points must point to Menu Items. The menu item acts as the indispensable security gatekeeper.