Building a Document Output extension app

The Continia Document Output Extension Builder lets you generate a ready-to-finish Document Output (DO) extension for your own documents and tables, without hand-writing the boilerplate that wires a page and its table into Document Output.

You tell the tool which email templates and which Microsoft Dynamics 365 Business Central pages you want to enable for Document Output, and it generates:

• FactBox pages that host the Document Output actions (Open/Send/Queue email, Print PDF, Save PDF).
• Page extensions that place those actions and a Document Output Log FactBox on your pages.
• Table extensions that expose the same actions as callable procedures.
• A subscriber codeunit that tells Document Output how to resolve your records (the OnGetVariantRecord event).
• Optionally, a stub codeunit for supplying your own merge-field values.

The feature is exposed to users through the page Document Output Extension Apps (found using the search () field). Internally, the objects are named Extension App (there's no object literally called "Extension Builder").

Prerequisites

Before you can download an app, the following must be filled in. These are enforced by the tool and will raise an error if missing.

On the app header (the card)

The following required fields must be filled in:

• App Name
• Publisher
• Version
• Object ID Range Min.
• Object ID Range Max.

You must own (be licensed for) the object ID range you enter – the generated objects are numbered inside it.

For each email template you add (Templates list)

• Template Code – an existing Document Output email template.
• FactBox Page No. and FactBox Name – auto-filled when you pick the template, but must not be blank at download time.
• The selected email template header must have a First Table in Report defined. This is the table the generated FactBox page and table extension are built on. A template without a first report table can't be used.

For each page you add (Pages to extend list)

• Page No. to extend – the Business Central page you want to enable.
• Page Extension Name – auto-filled from the page name, but must not be blank.
• Email Template Code – see the following note:

Limitation: two primary-key fields at most

The source table behind a page you extend may have no more than two primary-key fields. If it has three or more, the download fails with the following message:

Table <no> <name> has more then 2 primary keys. This is not allowed.

This limit exists because the generated Document Output Log FactBox links to your record using only Primary Key Field 1 Value and Primary Key Field 2 Value. Tables with a three-part (or larger) primary key can't be wired up automatically – you'd need to build the extension by hand for those.

To generate an extension app

The editor is a standard Card page – there's no assisted setup guide. Work top to bottom.

To generate an extension app, follow these steps:

1. Search () for and select Document Output Extension Apps. The list of previously created apps appears.

2. To create a new app, click New. A card opens with sensible defaults already filled in:

   • App ID – a new GUID.
   • Version – 1.0.0.0.
   • App Name – an incrementing default such as DO extension for project1.
   • Publisher – Default publisher.
   • Object ID Range Min./Max. – the next free 50-ID window (see Object ID range handling below).

3. Fill in the General group: Replace the defaults with your real App Name, Publisher, and Version, and set the Object ID Range Min./Max. to a range you own. Turn on Add MergeFieldValueFinder Codeunit if you want the merge-field stub included.

   Note

   The On Premise settings (Developer Services SSL Enabled/Port) only matter for on-premises debugging. Leave them blank for cloud.

4. Optional: Add dependency apps: In Dependency Apps, add a row for every extra app your generated code will reference (beyond Continia Document Output, which is always added). Fill in App ID, App Name, App Publisher, App Version, and leave Enabled on. Disabled rows and rows with an empty App ID are ignored.

5. Add email templates: In Templates used with this app, add a row and pick a Template Code. The tool auto-fills:

   • FactBox Page No. – the next free ID in your range.

   • FactBox Name – the template code in lower case followed by Actions (for example, salesinvoiceActions).

     Note

     It also shows the template's First Table in Report (number and name) so you can confirm which table the app will target.

6. Add pages to extend: In Pages to extend with Document Output FactBoxes, add a row and set Page No. to extend. The tool auto-fills:

   • Page Extension No. – the next free ID in your range.
   • Page Extension Name – the page name without spaces followed by FactBox.

7. Set the Email Template Code to match the template this page uses (required – see the note in Prerequisites above). Leave Document Output Action FactBox and Document Output Log FactBox on unless you want to omit one of them.

8. Click Download App to download. The tool validates everything and builds the ZIP, and your browser downloads <App Name>.zip.

Object ID range handling

The generated objects are numbered from Object ID Range Min. upward, so getting the range right matters.

• Defaults. A brand-new app starts at 52500–52549 (a 50-ID window).
• Automatic free range. When you create a new app, the tool scans existing apps and, if the default window overlaps one, moves your window past it – preserving the same width. So the second app you create lands on 52550–52599, and so on.
• Changing the minimum. If you edit Object ID Range Min. after adding templates or pages, the tool asks "Do you want to renumber existing pages?". Choosing Yes renumbers the FactBox pages and page extensions sequentially from the new minimum. Either way, Object ID Range Max. is recalculated to keep the original span.
• How generated objects are numbered:

Pages, table extensions, and codeunits can share the same number (for example page 52500, table extension 52500, codeunit 52500) because AL object IDs are unique per object type. Make sure your range is wide enough for the number of pages you add – the generated page IDs climb from Min and are not capped at Max.

What the download contains

Unzipping <App Name>.zip gives you a normal AL project:

Finishing the app in Visual Studio Code

This is the developer part. The ZIP is a starting point, not a finished, compilable app.

To finish the app in Visual Studio Code, follow these steps:

1. Unzip and open: Extract the ZIP and open the folder in VS Code with the AL Language extension installed.

2. Download symbols: The generated .vscode\launch.json is pre-filled from the Business Central session you downloaded from – environment type (on-premises/production/sandbox), server, server instance, and (on-premises) port. Use it to run AL: Download Symbols.

   Note

   The launch configuration's authentication is hard-coded to Windows. For a cloud/SaaS target, you'll need to change it (for example to MicrosoftEntraID) before symbols download or publishing will work.

3. Make dependency symbols available: Compilation needs the symbol packages for everything in app.json: Continia Document Output, the base Application/System apps, and any Dependency Apps you added. The Document Output dependency is pinned to a fixed version in app.json – adjust it to match the version installed in your target environment.

4. Implement the merge-field finder (if generated): MyMergeFieldValueFinder ships as a placeholder. It contains the comment "Replace the sample code to return your merge field value here" and a SalesHeaderGetFullDocType sample that only works when the template's table is Sales Header. Replace the sample 'YourParameter' case and the sample procedure with your own logic for your tables.

5. Review the rest: Update the placeholder brief/description in app.json, confirm the generated object names and IDs, and check that the FactBox/page extensions look right.

6. Compile, then build and publish: Compile the project, build the .app yourself (there's no server-side build – nothing produced a .app for you), and publish/install it into the target environment.

Button and field reference

Page: Document Output Extension Apps (list)

New rows can't be inserted directly on the list. Clicking New opens the card.

Page: Extension App Card

General group

On Premise settings group (on-premises only)

Action

Sub-page: Templates used with this app

Sub-page: Pages to extend with Document Output FactBoxes

Sub-page: Dependency Apps