{"title":"Organizing Promoted Actions","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-organizing-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-organizing-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-organizing-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":"Guidelines for which actions to promote in the action bar for Dynamics 365 Business Central","date":"2022-11-03","meta":{"topic":"concept-article"},"outline":[{"level":2,"title":"Which actions should be promoted in a page?","slug":"which-actions-should-be-promoted-in-a-page","at":144,"chars":973},{"level":2,"title":"Promote actions dependent on page type","slug":"promote-actions-dependent-on-page-type","at":1117,"chars":1080},{"level":2,"title":"How should promoted actions be organized?","slug":"how-should-promoted-actions-be-organized","at":2197,"chars":1215},{"level":2,"title":"Guideline for placing promoted actions","slug":"guideline-for-placing-promoted-actions","at":3412,"chars":1322},{"level":2,"title":"Related information","slug":"related-information","at":4734,"chars":295}],"text":"The following article gives guidance on which actions you should promote, how to organize the actions, and where to place the promoted actions.\n## Which actions should be promoted in a page?\nTo promote an action in a page, place an actionref for it in the promoted area in the page object. The recommendation is to only promote actions that are frequently used by the users of the page and actions that are an expected part of a common action group on the page.\nGive prominence via promotion only to actions that you expect many users need for their work and avoid promoting actions that have little or no tracked usage. When there's only a few users that need a certain action, it's better to let them personalize that action to a prominent place they prefer rather than promoting the action for everyone, which will distract the many users who don't need it.\nYou can configure and new define user roles (profiles) when you want to coordinate promoted actions across pages to suit a certain set of users needing a certain set of actions. See Customizing the User Interface for User Roles<devenv-role-customization>.\n## Promote actions dependent on page type\nFor a business entity, for example, a Customer, there's no virtue in promoting the exact same set of actions on the customer list and the customer card page, even when the same set of actions is available on both pages. On the contrary, doing so may not align with the patterns of use and it risks cluttering the action bar with actions that too few users need.\nInstead, on list pages, use action promotion to give priority to:\n Actions that allow users to process multiple selected rows at a time\n Actions that give access to more details about the chosen record\n Actions that users find relevant even as they might not see all fields about the record\nActions that users are most likely to use after creating or updating a record using the card page need only be promoted in the card page, and not in the list. For example, it's more useful to promote the action \"Request Approval\" in card and document pages than in list pages, since most users will check or update information in the card or document before requesting approval of it.\n## How should promoted actions be organized?\nOnce you've decided on the set of actions to promote in a page, it's time to organize the chosen set into a proper sequence and grouping. This must be done in a way where users easily discover the actions they need when they need them.\nBefore starting to create new groups for actions in a page, consider the total set of promoted actions in the page. If there are five or fewer promoted actions, it's often preferable to avoid creating new groups, and instead keep the actions together, and not in separate groups.\n> NOTE\n> If a page only has actions promoted to the Process/Home group, then the Business Central web client will show the actions as if they're not placed in a group. This is known as unpacking of the Home/Process group.\nWithin each group of actions, choose a sequence of actions that respect their relative importance. Start with actions that a user is likely to use first, or often, when opening a page. Common action groups are the exception to this recommendation, as they must instead have a consistent sequence of actions across the pages where they appear.\nUse subgroups within a group when the total number of actions in a group is more than 7.\n## Guideline for placing promoted actions\nThe promoted action...|Variations|Recommendations\nUpdates or creates data or info (possibly via an intermediate dialog page) and with clear feedback that the action took place.<br> Examples: Post, Suggest lines, Indent|A) The action is an expected part of a common action group on the page, for example Post.|Promote the action to its expected common action group. For example, promote the Post action to the common action group named \"Posting.\"\n-|B) The action is particular to the page, and not an expected part of a common action group.|Action should be promoted to Home/Process.\nOpens a relevant or related page (not a dialog) and that has no apparent side effects. <br> Examples: Statistics, Dimensions|A) The page that opens has information that is specific to the current record/row in the page.|Action should be placed in the common entity action group, which is the one bearing the name of the main entity of the page, for example, Customer.\n-|B) The page that opens has the same information regardless of current record/row in the page.|Action should be placed in the common Navigate action group.\nIs an action that runs a report, either directly or via an intermediate dialog page (request page).|(no variation)|Place report actions in the common action group Reports.\n## Related information\nActions in AL<devenv-actions-overview>\ndevenv-adding-actions-to-a-page\ndevenv-actions-user-interface\ndevenv-promoted-actions\ndevenv-common-promoted-action-groups\ndevenv-action-bar-improvements\ndevenv-promoted-actions-behavioral-changes\ndevenv-pages-action-bar-improvements"}