{"title":"Promoted actions","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-promoted-actions/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-promoted-actions, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-promoted-actions","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Promoted actions are configured to display on the Home tab for accessing quick daily actions in Dynamics 365 Business Central.","date":"2024-07-09","meta":{"topic":"article"},"outline":[{"level":2,"title":"Promoting actions using the actionref syntax","slug":"promoting-actions-using-the-actionref-syntax","at":404,"chars":5405},{"level":3,"title":"Split buttons for actions","slug":"split-buttons-for-actions","at":2442,"chars":527},{"level":3,"title":"actionref syntax example","slug":"actionref-syntax-example","at":2969,"chars":1751},{"level":3,"title":"Extensibility and compatibility","slug":"extensibility-and-compatibility","at":4720,"chars":1089},{"level":2,"title":"Promoting actions by category (legacy syntax)","slug":"promoting-actions-by-category-legacy-syntax","at":5809,"chars":2791},{"level":2,"title":"Assigning an icon to the promoted actions","slug":"assigning-an-icon-to-the-promoted-actions","at":8600,"chars":3992},{"level":3,"title":"Example","slug":"example","at":9082,"chars":3510},{"level":2,"title":"Related information","slug":"related-information","at":12592,"chars":349}],"text":"You can promote actions that are used more often than others and thereby ensure quick access to them. This type of actions is called promoted actions. Promoted actions are either placed in the Home menu or in suitable menus and groups named so users know what to expect in each.\nPromoted actions can be used on Card, Document, List, ListPlus, and Worksheet pages to provide quick access to common tasks.\n## Promoting actions using the actionref syntax\n> APPLIES TO: Business Central 2022 release wave 2 and later\nWith Business Central 2022 release wave 2, the way that you promote actions on pages or page extensions has changed. Promoting actions is defined in a specific section of the code for a page and it contains a reference to the action. The new syntax provides more visibility in code, because the promoted actions are grouped in a separate section. And to the end user, the personalization experience is improved, adding options for promoting actions.\nIn Business Central the new action bar is enabled when the feature flag Modern Action Bar on the Feature Management page is set to Enabled. The flag can be switched off to simulate legacy behavior, but the promoted action code in the base application uses the actionref syntax.\n> IMPORTANT\n> The #promoting-actions-by-category-legacy-syntax for defining promoted actions is still supported in releases going forward, but it's recommended to implement the new syntax.\n> NOTE\n> Removing the Promoted property on a published action is considered a breaking change. See AppSourceCop Error AS0031<analyzers/appsourcecop-as0031> and UICop Warning AW0013<analyzers/uicop-aw0013>.\nTo define promoted actions, you specify an `area(Promoted)` in the actions section of a page or a page extension. Inside the `area(Promoted)` section, you can specify one or more actionref sections. An actionref is an object type that references an action on the page, and by adding it in the promoted area section it's promoted in the UI. An actionref can only be defined in the `area(Promoted)` section. You can either create groups in the `area(Promoted)` for the actionref references, or you can add actionref sections directly. An actionref inherits the properties of the referenced action. For page extensions, you can add to existing groups and you can add new groups.\nFor more information about behavioral changes introduced with the new action bar, see devenv-promoted-actions-behavioral-changes.\n### Split buttons for actions\nAs part of the new programming model for promoted actions, you can combine multiple actions into a split button to help organize the actions that you're promoting, thereby reducing clutter and improving coherence and closeness of related actions. A split button can be defined for a page action group, which renders as a combination of a button and a menu. Use the ShowAs property to specify that a certain page action group should render as a split button. See properties/devenv-showas-property.\n### actionref syntax example\nThis example illustrates a page with the promoted area syntax. In the example the `area(Processing)` section defines the MyBaseAction action for the page, which triggers a `Hello world` message. The MyBaseAction will be available from under the Processing group in the action bar and it will be promoted because it's added to the `area(Promoted)` section, which defines the actions to promote. The example illustrates that you can group your actionref sections, or specify them ungrouped. The `actionref(MyPromotedActionRef; MyBaseAction)` promotes the defined MyBaseAction so that it, in addition to being placed in the Processing group, also is promoted for easy access on the page.. Also, the example illustrates using a split button for Group2 where two actionrefs are included in the button.\n```al\npage 50105 ActionRefPage\n{\n    actions\n    {\n        area(Promoted)\n        {\n            actionref(MyPromotedActionRef; MyBaseAction)\n            {\n            }\n            group(Group1)\n            {\n                actionref(MySecondPromotedActionRef; MyBaseAction)\n                {\n                }\n            }\n\n            group(Group2)\n            {\n                ShowAs = SplitButton;\n\n                actionref(MySplitButtonPromotedActionRef; MyBaseAction)\n                {\n                }\n\n                actionref(MyOtherSplitButtonPromotedActionRef; MyBaseAction)\n                {\n                }\n            }\n        }\n        area(Processing)\n        {\n            action(MyBaseAction)\n            {\n                Visible = true;\n                trigger OnAction()\n                begin\n                    Message('Hello world!');\n                end;\n            }\n        }\n    }\n}\n```\n### Extensibility and compatibility\nSwitching over to use the new promoted actions syntax can be done gradually as legacy and new syntax will co-exist for a while. We do, however, encourage you to switch over as soon as you can. As you refactor the code, there are a couple of things to be aware of in that process:\n It's not allowed to use both legacy and new syntax for promoted actions on the same page or page extension. This means that if you add actionref syntax to your code, the Promoted properties (Promoted, PromotedOnly, PromotedActionCategories, and PromotedCategory) won't be allowed.\n Across a project you can mix legacy and new syntax and:\n   You can implement the new actionref syntax on a page without breaking any existing page extensions.\n   You can write a page extension with the new actionref syntax based on a page that uses the legacy syntax.\nA code action for converting pages using legacy syntax is available with Business Central 2022 release wave 2. The code action can be applied to a narrow or broader scope of code. See AL Code Actions<devenv-code-actions>.\n## Promoting actions by category (legacy syntax)\n> NOTE\n> The following section describes the former way of defining promoted actions for Business Central. It's recommended to switch to the actionref syntax for defining promoted actions.\nYou can promote any command from the existing actions menus to the ribbon. If there are no promoted actions, the ribbon remains hidden. To promote an action on the Home tab, you set the Promoted property of the action. If you want to display the action only on the Home tab, then you add an extra step to set the PromotedOnly property. See properties/devenv-promoted-property and properties/devenv-promotedonly-property.\nPromoted actions can be grouped. You can add promoted actions by different grouped categories. Typically, promoted actions are displayed in the ribbon of a page. You can organize promoted actions into different categories, where each category is indicated by a caption in the ribbon. You define up to 10 categories for a page. The following figure illustrates a page that has promoted actions under the following categories.\n New Document\n Request Approval\n Customer\n![image text.]\nYou assign a promoted action to a category by setting the PromotedCategory property of the action. By default, these category names correspond to the captions that are displayed for the category on the page in Dynamics 365 Business Central. You'll typically want to change the captions, especially the Category4 through Category10 captions. See the table below for the default PromotedCategory values. To change the default captions, set the PromotedActionCategories property.\nYou type the values of the PromotedActionCategories where each caption is separated with a comma as shown below:\n```al\nPromotedActionCategories = 'New_caption,Process_caption,report_caption,category4_caption,category5_caption,category6_caption,category7_caption,category8_caption,category9_caption,category10_caption';\n```\nThe position of the caption in the list determines its corresponding category setting in the PromotedCategory property for the actions as described in the table below.\nPromotedActionCategories caption position|Default PromotedCategory values|Example\nFirst|New|New_caption\nSecond|Process|Process_caption\nThird|Report|Report_caption\nFourth|Category4|Category4_caption\nFifth|Category5|Category5_caption\nSixth|Category6|Category6_caption\nSeventh|Category7|Category7_caption\nEighth|Category8|Category8_caption\nNinth|Category9|Category9_caption\nTenth|Category10|Category10_caption\nYou can change category captions on a page-by-page basis and for each Dynamics 365 Business Central Windows client language.\nFor more information about these properties, see properties/devenv-promotedcategory-property and properties/devenv-promotedactioncategories-property.\n## Assigning an icon to the promoted actions\nEach promoted action has an icon associated with it. You can accept a default icon, or choose your own from the Dynamics 365 Business Central image library by using the Image property, where each promoted action has an icon associated with it. Also, you can use a larger icon that makes it more prominent to the user by using the PromotedIsBig property. See properties/devenv-image-property and properties/devenv-promotedisbig-property.\n### Example\nThe example shows how to promote actions on a Customers page using different properties:\n1. The actions in the example are promoted to display in the New Document, Request Approval and Customer groups on the Home tab.\n1. The Sales Quote and Sales Invoice actions are promoted to the ribbon and grouped in a category called New Document.\n2. The PromotedCategory value; Category5 corresponds the caption position in the PromotedActionCateogories value with the New Document caption.\n3. Each promoted action in the example is assigned to a unique icon. Additionally, to display bigger icons, the Sales Quote and Contact actions are set with the PromotedIsBig property.\n4. The Sales Quote and Send Approval Request actions are set to appear only on the Home tab.\n```al\npage 50103 Customers\n{\n    PageType = Card;\n    SourceTable = Customer;\n    PromotedActionCategories = 'New,Process,Report,Manage,New Document,Request Approval,Customer,Page';\n\n    actions\n    {\n        area(Creation)\n        {\n            action(\"Sales Quote\")\n            {\n                Promoted = true;\n                PromotedCategory = Category5;  // PromotedActionCategories = New Document\n                PromotedOnly = true;\n                PromotedIsBig = true;\n                Image = NewSalesQuote;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                    Message('Create sales quote');\n                end;\n            }\n            action(\"Sales Invoice\")\n            {\n                Promoted = true;\n                PromotedCategory = Category5;  // PromotedActionCategories = New Document\n                Image = SalesInvoice;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                end;\n            }\n        }\n        area(Processing)\n        {\n            action(\"Send Approval Request\")\n            {\n                Promoted = true;\n                PromotedOnly = true;\n                PromotedCategory = Category6;  // PromotedActionCategories = Request Approval\n                Image = SendApprovalRequest;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                end;\n            }\n            action(\"Cancel Approval Request\")\n            {\n                Promoted = true;\n                PromotedCategory = Category6;  // PromotedActionCategories = Request Approval\n                Image = CancelApprovalRequest;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                end;\n            }\n        }\n        area(Navigation)\n        {\n            action(Contact)\n            {\n                Promoted = true;\n                PromotedCategory = Category7;  // PromotedActionCategories = Customer\n                PromotedIsBig = true;\n                Image = CustomerContact;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                end;\n            }\n            action(\"Account Details\")\n            {\n                Promoted = true;\n                PromotedCategory = Category7;  // PromotedActionCategories = Customer\n                Image = Account;\n                ApplicationArea = All;\n                trigger OnAction()\n                begin\n                end;\n            }\n        }\n    }\n}\n```\nFor more examples of how to use actions, see devenv-page-object and Page Extension Object<devenv-page-ext-object>.\n## Related information\ndevenv-actions-overview\ndevenv-adding-actions-to-a-page\ndevenv-promoted-actions-behavioral-changes\nActions in AL<devenv-actions-overview>\ndevenv-adding-actions-to-a-page\ndevenv-actions-user-interface\ndevenv-promoted-actions\ndevenv-organizing-promoted-actions\ndevenv-common-promoted-action-groups\ndevenv-action-bar-improvements"}