NAV Design Pattern of the Week – the Hooks Pattern

A new series of NAV Design Patterns is just starting. To make a good beginning, the first one is not chosen randomly. It is indeed a very powerful pattern – the “Hooks”, by Eric Wauters. It is also different from most patterns you’ve seen so far, in that it does not exist in the core product. “How can it be? A powerful NAV pattern which is not in NAV?”, you wonder.

This is exactly the point of the Hooks. It is a partner pattern – something you, as a partner, can use, when you implement your customization. And if done correctly, it has the potential to make the next upgrade superfast.   

Are you having a hard time installing update after update, rollup after rollup? Does it consume more resources than you had wished? Is the customization code entangled with the core product code, in such a way that each update requires complicated merges, with the developer trying to figure out which code goes where?

To keep it short, here it is – the Hooks pattern. Most powerful when starting a new customization, as it can be implemented fully. It will keep things simple. As for the legacy customizations… it is still possible to use it, by refactoring key areas such as areas with the most update merge issues.

Hooks Pattern

by Eric Wauters (waldo), Partner-Ready-Software

Meet the Pattern

By minimizing the code in already existing application objects, you will make the upgrade process much easier, and all customization business logic will be grouped in new objects.  When using atomic coding, it will be very readable what is being customized on a certain place in an existing part of the application.

To minimize the impact of customizations, the idea of hooks is:

  • First of all, name the places in the already existing code where customization is needed;
  • Second, place your business logic completely outside the already existing application code.

Know the Pattern

When doing development over years, by different developers with different mindsets, the standard codebase gets changed a lot, adding multiple lines of code, adding local and global variants, adding or changing keys, changing existing  business logic, … .  In other terms, the standard text objects are being changed all over the place.. .

After years, it’s not clear why a change was done, and what was the place where the change was intended to be done.  And the latter is quite important in an upgrade process, when code in the base product is being refactored: if the exact place of the posting of the Customer Entry is being redesigned to a separate number, the first thing I need to know, is that I did a certain change at the place: “where the posting of the Customer Entry starts”.  The definition of that place, we call a “Hook“.

I recommend to use this concept on the following:

  • All objects of the default applications that need to be changed
  • On objects that should not hold any business logic (like tables, pages, XMLPorts)

Use the Pattern

Step 1 – if it doesn’t exist yet – you create your Hook codeunit.  As the name assumes .. this is always a codeunit.  We apply the following rules to it:

  • One Hook always hooks into one object.  Which basically means that I will only declare this new codeunit in one other object (which is its parent object)
  • The naming convention is: The_Original_Object_Name Hook.  Naming conventions are important, just to find your mapped object, and also to be able to group the Hooks.

Step 2, you  create the hook, which is basically a method (function) in your codeunit.  The naming is important:

  • The naming of the hook should NOT describe what it is going to do (So, examples like CheckMandatoryFields, FillCustomFields should not be used as a hook)
  • The naming of the hook should describe WHERE the hook is placed, not what the hook will be doing (as nobody is able to look into the future .. :-))
  • To help with the naming, it is a good convention to use the “On”-prefix for these triggers.  This way, it’s very clear what are hooks, and what aren’t..

Step 3, it’s time to hook it to its corresponding object and right place in the business logic of that object.  You do this by declaring your codeunit as a global in your object, and using the created hook function on its place in the business logic.  This way, these one-liners apply:

  • A Hook codeunit is only used once in one object only (its corresponding object)
  • A Hook (function) is used only once in that object.  As a consequence, changing the parameters has no consequence: you only need to change one function-call
  • The codeunit is declared as a global.  That exact global is the only custom declaration in the existing object .. Everything else is pushed to the hook-codeunit.

Step 4, implement your business logic in the hook.  Do this in the most atomic way, as there is a good chance that this same hook is going to be used for other business logic as well.  Best is to use a one-line-function-call to business logic, so that the Hook Function itself stays readable.


Suppose, we want to add business logic just before posting a sales document.  In that case, we have to look for the most relevant place, which is somewhere in the “Sales-Post” codeunit.  So:

Step 1: create codeunit Sales-Post Hook:

Step 2: create the hook function OnBeforePostDocument:

Step 3: declare a global in the Sales-Post codeunit, called SalesPostHook.  Then,…

Continue reading on the NAV Patterns Wiki…


Best regards,

The NAV Patterns team