AL Hierarchical Price List - User guide

1. Concepts in one minute

• A price list structure is one node of a hierarchy. It exists for a customer price group, and the prices of that group are the prices of the node.
• A hierarchy puts the structures under one another: a node inherits from its parent, the parent from its own parent, and so on up to the root. It is what makes a price list a refinement of another one instead of a copy of it.
• A hierarchy has to be certified before it is used. While it is open, it can be changed and it does not resolve prices; once it is certified, it resolves prices and it can no longer be changed until it is reopened.
• A customer assignment links a customer to one node, for a period. A customer can have one assignment per period, and the one in force on the date of the document is the one that counts.
• Resolving a price means: look for the price on the node of the customer, then on its ancestors up to the root, and stop at the first one that answers.
• The app works on both pricing engines of Business Central: the extended price calculation, where it adds the price sources of the hierarchy to the standard search, and the legacy one, where it walks the hierarchy itself.

2. Prerequisites

• Microsoft Dynamics 365 Business Central, version 28.0 or higher, online (SaaS) and on-premises. AppSource covers online environments; on-premises is distributed and installed directly by AppLibra, through the AppLibra License Manager.
• The dependencies installed: AL License and Trial Management, AL Foundation App, AL Role Center.
• Permissions: assign ALPHPL-USER for daily use, which is reading the hierarchies and assigning a price list to a customer, or ALPHPL-ADMIN, which includes it and adds the setup of the app, the removal of the customer assignments and the page where the hierarchies are built and certified. Building a hierarchy is an administrator action: an open hierarchy resolves no prices, and the documents of every customer hanging from it stop until it is certified again. The split of the two roles says who should build them, but it does not keep a user with the operative role from building them: the detail is in the troubleshooting chapter.
• Customer price groups: the hierarchies are built on them, so it helps to have them already in place, or to create them as you go.

3. Setup

3.1 Activate the license

Open Price List Setup (HPL) and choose Add License. The trial starts the first time the setup is saved; the same action reads the license again after it has been bought or renewed.

3.2 Price List Setup (HPL)

One switch, Create Price List Header on New Customer Price Group:

• on: every new customer price group gets its sales price list straight away, so the group can be used as a node of a hierarchy without opening the price lists first. It only has an effect when the extended price calculation of Business Central is on;
• off: nothing is created, and whoever wants the price list of a group makes it by hand.

3.3 The price list structures

A structure is created for every customer price group, so the list of structures follows the list of groups. Open Price List Structures (HPL) to see them, with the group each one reads its prices from.

3.4 Build and certify the hierarchy

Open Price List Hierarchy Setup (HPL) and choose the hierarchy, or create a new one. This page is in ALPHPL-ADMIN, which says who should use it and does not keep others from opening it, as the troubleshooting chapter explains. Then:

1. Add the root node with Get Price List Structures, choosing the structure of the most general price list.
2. Select the root and add its children with the same action, one for every price list that refines the general one. The indentation shows what inherits from what.
3. Repeat on the children as deep as the pricing policy needs: there is no limit to the levels.
4. Choose Certificate. From here on the hierarchy resolves prices, and it cannot be changed until it is reopened.

Each node can be checked while you build it: Price List opens the sales prices of its structure, Show Source opens the customer price group behind it, Customers shows who ends up on that node.

4. Assign a price list to a customer

Two ways, the same result:

• from the customer: open the customer card, group Hierarchical Price List (HPL), action Customer Price List Setups (HPL);
• from the list: Customer Price List Setups (HPL) from Tell Me or from the role center.

On the line, fill in the starting date, the ending date if the assignment expires, and choose the node with the drill down on Price List. Rules to know:

• an assignment always has a starting date;
• the ending date can be empty, and then the assignment does not expire;
• the ending date has to fall in the same year as the starting date;
• a customer that has a price list assignment does not keep a customer price group on its card: the app refuses one when the other is there, because the hierarchy is what decides the group. The refusal happens on the card: a group written from code, by an import or by another app, is not stopped, because the check hangs on the field being edited and outside a page there is none. When the combination exists anyway, the app does not stop the document, because the price is not ambiguous for it, it comes from the hierarchy: it says so with a warning while the price is being resolved, naming the customer and the group, with an action that opens the customer. The warning appears once per customer, not once per line. Leave one of the two on the customer.

5. How the price is resolved

On a sales document, for the customer of the document and the date of the document (the posting date on an invoice and on a credit memo, the order date everywhere else):

1. The app looks for the assignment in force on that date. If there is none, it does nothing and the standard engine works as usual.
2. It walks the hierarchy from the node of the assignment up to the root.
3. With the extended price calculation, it adds the customer price group of every node to the sources of the standard search, giving the most specific node the highest priority; the standard engine then picks the price.
4. With the legacy engine, it walks the same path itself and stops at the first price it finds.

The prices themselves live where they always did, in the sales price lists of the groups: the app does not copy them and does not calculate them.

One precedence to know, if AL Advanced Discounts and Pricing is installed too: a unit price forced by hand on the sales line wins over the hierarchy. With its setup switch on and a forced price on the line, the standard price search is skipped, so this app is not asked at all. It is deliberate, and it is the right way round: a price agreed by hand is not a price list.

6. Daily use

6.1 Move a customer to another price list

Add a new assignment with the new node and the date it starts from, and close the previous one with its ending date. The history stays readable: who had which price list, and when.

6.2 Read the hierarchy behind a price

Open Price List Hierarchy (HPL) and choose the hierarchy. On the node of the customer, Show Ancestors leaves only the path up to the root, which is the order the price is looked for in; Show All puts the whole tree back. Price List opens the prices of the node.

6.3 Change a certified hierarchy

Choose Reopen, change it, certify it again. While the hierarchy is open it does not resolve prices, and the sales documents of the customers assigned to it stop with an error, so it is work to do in a quiet moment and to close.

6.4 Rename or delete a node

If a node of a certified hierarchy is renamed, the assignments that pointed at it keep working with nothing to do: for the engine it stays the same node. If the node is deleted, the assignments are not lost: they stay parked without a node, and the name of the node they had is shown in the Previous Price List column. They go back to normal by themselves as soon as a node with that name comes back in the same hierarchy, and in the meantime they can be pointed at another node by hand: either way the parking empties. A node with that name in another hierarchy does not take them, because it is a different node with different prices.

Assignments parked by versions earlier than 28.0 remember no name and stay parked: those have to be pointed at a node by hand.

7. Where to find it

• Tell Me: search for the name of the page, or for HPL, which is on every page of the app.
• AppLibra hub: Shift+F12, Explore other roles, AppLibra, group Hierarchical Price List (HPL).
• Sales Manager role center: the same group in the sections.
• Customer card: group Hierarchical Price List (HPL) and the action in Prices and Discounts.
• Manual setup: search for Price List Setup among the setups of Business Central.

The pages of the app:

8. Tips and troubleshooting

• A sales document stops with an error on the hierarchy: the hierarchy of that customer is not certified. Certify it, or move the customer to a certified one.
• The price does not change: check that the assignment in force on the date of the document is the one you think, and that the price is in the price list of the node or of one of its ancestors. On the hierarchy, Show Ancestors shows the exact path that is searched.
• The customer price group of a customer cannot be changed: the customer has a price list assignment, and the group comes from the hierarchy. Remove the assignment, or change the node.
• A user with the operative role opens the setup pages all the same: the actions are shown to everybody, because that is how the role centers of Business Central work, and Price List Setup (HPL) and Price List Hierarchy Setup (HPL) are both in ALPHPL-ADMIN, but belonging to that set says who should use them and does not keep anyone from opening them: to open a page, Business Central does not ask for permission on the page, it asks for permission on the data the page reads. So Price List Setup (HPL) opens with the operative role too, and the permission error comes when a value is changed and not when the page is opened, because the setup of the app can be read by everybody and written only by ALPHPL-ADMIN; Price List Hierarchy Setup (HPL) opens and can also be used, because the permissions that count are the ones on the hierarchy tables, which belong to AL Foundation App and which the operative role has to have in order to read the hierarchies. If building hierarchies has to stay with the administrators in your organization, for now that is a rule of yours and not a control of the app. To see a node without the ADMIN role, open the hierarchy from the customer card: the drill down shows it on Price List Hierarchy (HPL), which is in ALPHPL-USER.
• The price lists of the groups are missing: turn on the switch in the setup, so that every new customer price group gets its price list, or create them by hand from the standard price lists.

9. Support and resources

• Product page: https://applibra.com/apps/al-hierarchical-price-list
• Guide: https://applibra.com/apps/al-hierarchical-price-list/help
• Support: the contacts on the product page.
• Terms: https://applibra.com/eula - Privacy: https://applibra.com/privacy-policy