Dynamics 365 Business Central: What is Promoted action and How to Promote action?

Hi, Readers.

I often hear from developers about why their customized actions (buttons) can’t be placed where they want. So in this post, I would like to talk about what is promoted action and how to promote action in Business Central. The concept of Promote Actions is inherited from NAV.
Promoted actions are actions that are set up on the Actions, Navigate, or Report menus in the action bar, but are also configured to display on the Home tab. In short, this feature allows you to make a copy of an action and place it on the on the action bar where it is easier to find.

First let’s look at the properties related to Promoted Actions.

Page: PromotedActionCategories

Action: Promoted, PromotedCategory, PromotedOnly, PromotedIsBig

PromotedActionCategories: Sets a category for a promoted action.
Promoted actions can be grouped. You can add promoted actions by different grouped categories. You can choose between 10 categories: New, Process, Report, and Category4 through Category10. By default, the category names are used as the captions in the ribbon.

This is the first thing that needs to be defined and checked.
For example: page 31 “Item List”

PromotedActionCategories = 'New,Process,Report,Item,History,Prices & Discounts,Request Approval,Periodic Activities,Inventory,Attributes';

On the page: Promoted Action Categories (Groups) without any actions are not displayed on the screen, such as New and History.

The 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.

Promoted: To promote an action on the Home tab, you set the Promoted property of the action. This is the most basic property for promoting actions. If this property is not set to True, the following properties cannot be set.

PromotedCategory: Sets a category for a promoted action. The categories here correspond to the categories set in the PromotedActionCategories property of the page. But what is very disturbing is that except for the first three, New, Process, and Report, the others only display the number of Category. (Category4 ~ Category20)

So, if you want to add a new action to Item group on the Item List page, you should set PromotedCategory = Category4;

Let’s see one more example. If you want to add a new action to Attributes group on the Item List page, you should set PromotedCategory = Category10;

Note: For the Promoted Area (Home tab), the keywords addfirst, addlast, addbefore, and addafter are invalid.

Okay, the remaining two are relatively simple.
PromotedOnly: Specifies whether the selected action is promoted only, which means that it will appear only on the Home tab in the ribbon and not on the tab (ActionContainer control) where it is defined. The default is false.

If you set PromotedOnly to false, you can find the action in both Promoted Area (Home tab) and More Option Area (Actions tab). But if you set PromotedOnly to true, the action will appear only on Promoted Area (Home tab).

PromotedIsBig: Sets the action to appear before other promoted actions in the action bar, regardless of its position in the AL code of the page. The default is false.

PromotedIsBig = false;

PromotedIsBig = true;

Find out more about Promoted Actions from MS Docs.

Update 2022/09/05: Business Central 2022 wave 2 (BC21) new features: Promoted action groups, action references, and ShowAs Property (New Modern Action Bar)

END

Hope this will help.

Thanks for reading.

ZHU