Microsoft have a very good walkthrough that a lot of this document will be referencing, and is certainly worth reading as a pre-requisite, it’s found here.
Extension Dependency for Zetadocs
A dependency on the Zetadocs Capture and Zetadocs Delivery Extension needs to be added to the App.json of the Per Tenant Extension, the following is a code snippet to do this, note the version should match the version of Zetadocs installed (this can be found by searching BC for Extensions):
"dependencies": [
{
"appId": "069f3d48-1c17-459e-bbc6-3f00693bb507",
"publisher": "Equisys",
"name": "Zetadocs Delivery and Zetadocs Capture",
"version": "1.0.20185.15"
}
]
Once the dependency has been added, make sure to Download Symbols (in VS Code this is Ctrl+Shift+P and type AL: Download Symbols)
Events
The idea is that you can run customized code at certain points in the software using events, they’re based off the .net framework so should be quite familiar, they comprise of three parts:
- Event – Declared by an AL method, this is an event publisher function and is just a signature, it does not execute any code.
- Publisher – this is the object that exposes the event to subscribers, this is where you want them to hook into. This on its own does nothing, you still need to raise the event for a subscriber to respond.
- Subscriber – listens for and handles a published event. In AL this is a method that subscribes to a specific publisher method and when raised runs its own code.
Subscribe to an event
- You must decide which codeunit to use for the event subscriber, either a new codeunit or an existing one.
- Add a new AL method
- Add code to the method to handle the event
- Decorate the method with the EventSubscriber attribute, see below.
[EventSubscriber(ObjectType::<Event Publisher Object Type>, <Event Publisher Object>, '<Published Event Name>', '<Published Event Element Name>', <SkipOnMissingLicense>, <SkipOnMissingPermission>)]
<Event Publisher Object Type> this is the type of object that’s publishing the event, so Codeunit, Page, Table. For example, Codeunit
<Event Publisher Object> the object that publishes the object, you can use the id or the name, so for example Codeunit::” MyPublishers”
<Published Event Name> the name of the publisher method, in our example this is, OnAddressLineChanged.
The rest of the values are less important and can usually be left to default values ‘’, false, false. Look up the MSDN documentation for more information if you need it here.
In the example Subscriber below note how the method parameter matches the parameter from the Publisher event.
codeunit 70000002 MySubscriber
{
EventSubscriberInstance = StaticAutomatic;
[EventSubscriber(ObjectType::Codeunit, Codeunit::"MyPublishers", 'OnAddressLineChanged', '', true, true)]
procedure CheckAddressLine(line : Text[100]);
begin
if (STRPOS(line, '+') > 0) then begin
MESSAGE('Cannot use a plus sign (+) in the address [' + line + ']');
end;
end;
}
Examples of our Events can be found in the Zetadocs Customize codeunit.
Creating a BC Extension
To create a more in depth BC extension, with new tables, pages, and codeunits, you should be able to follow the Microsoft example, I will just outline a way of producing a very simple Per Tenant Extension.
- Load up VS Code
- Hit Ctrl+Shift+P this will bring up the VS console, and type AL: Go! And select the option, it will bring up a location to save your project to, select a value and hit enter
- It will ask you a target platform to select, at the time of writing Business Central 16 has just come out so the latest available platform is 5.0, if you want to create a PTE on BC15 select 4.0, BC14 3.0 etc etc. For this example, select 5.0
- It will then ask you to select a server, choose the local option.
- We now have the skeleton of a PTE, we just need to start configuring it, starting with the launch.json, this file tells VS code which server to connect to when we run it, you can have multiple configuration, for different languages or server locations.
- You will need to modify the server value to point to your local instance of BC.
- On the left-hand side select the newly created HelloWorld.al file, you should be presented with the code file. Currently it’s set a trigger on the page opening (in this case the Customer List page which we’re extending) to display a message, we’re going to create a new page extension to add two new fields to the Purchase Invoice page, so right click under the HelloWorld.al and select Add new…
- Call the new file Table Extension Purchase Invoice.al (remember to add the .al so VS Code knows what languages it needs to use). Type out the following:
- We have told VS that we want to create a tableextension, with a unique id of 50101, called Purchase Inv Line Extension, that extends the existing table Purchase Header. We’ve defined some new fields under the fields keyword, each field has a unique id, 50101, and a name Description3, and a type Text[25]. These fields will now be available to the Page extension we will create.
- Call the new file Page Extension Purchase.al, at the top of the file start typing pageextension 50102 “Whatever you want it to be called” extends “Purchase Invoice”. So, we have told AL we are creating a pageextension, given it a unique id, a name and what page we want to extend.
- We want to add two new fields to the General section in the page, type out the following:
- What we’ve done here is to say, after the final field (addlast) in the “General” section add two new fields, the first parameter is field name in the table and the second is what is shown to the user.
page 50110 PageName
{
PageType = Card;
actions
{
// Adds the action called "My Actions" to the Action menu
area(Processing)
{
action("My Actions")
{
Promoted = true;
PromotedCategory = Process;
ApplicationArea = All;
trigger OnAction()
begin
Message('Hello World');
end;
}
}
area(Creation)
{
// Adds the action "My New document" to the New Document group in the Actions menu.
action("My New document")
{
ApplicationArea = All;
RunObject = page "Customer Card";
Image = "1099Form";
}
}
area(Navigation)
{
// Adds the action called "My Navigate" to the Navigate menu.
action("My Navigate")
{
ApplicationArea = All;
RunObject = page "Customer Card";
}
}
area(Reporting)
{
// Adds a submenu called "My Label" to the Report menu.
group(NewSubGroup)
{
Caption = 'My label';
group(MyGroup)
{
// Adds the action "My Report" to the My Label submenu.
action("My Report")
{
ApplicationArea = All;
RunObject = page "Customer Card";
}
}
}
}
}
}