Printable Formats and Per-Branch Defaults

You have been asked to make the invoices printed at GS-KV-01 look like the ones the branch used before BigLedger — its own header text, its own footer with the branch’s bank details — without changing what the other 21 branches print. By the end of this page you will know what a printable format actually is (a JasperReports template file you upload), how to set one as a branch’s default, where the header and footer text goes, and — the part nobody tells you — that the print button, the emailed PDF and the e-Invoice PDF each choose a layout by a different rule, so setting a branch default fixes one of the three. Uploading a format and setting a default takes about five minutes per branch once the template file exists. Designing the template is a job for whoever knows JasperReports; this page is about what BigLedger does with the file.

Meet GadgetSphere

GadgetSphere Sdn Bhd runs 22 branches. The Klang Valley branches print A4 tax invoices for corporate walk-ins; the Penang branches print a narrow receipt layout on the same document type; GadgetSphere Online (GSO) never prints at all — its invoices go out by e-mail with a PDF attached, and every one of them also becomes an e-Invoice whose PDF, with the LHDN QR code, is what the customer actually keeps. That is three layouts for one document type, chosen three different ways.

What a printable format is

A printable format is one uploaded .jrxml file — a JasperReports template — plus a code and a name, tied to one document type. BigLedger stores it as a header row in bl_prt_printable_format_hdr and exactly one extension row in bl_prt_printable_format_ext (param_code PRINTABLE_FORMAT_FILE) that points at the uploaded file in the platform’s file store. When you print, the backend fetches the file, compiles it on the spot, fills it with the document and returns a PDF.

Three facts about the record that explain most of what you will see:

No tenant ships with any formats. The platform seeds exactly one row, in bl_prt_printable_format_list_hdr: Jasper JRXML, the only template technology supported. Every format in your tenant was uploaded by someone in your organisation. 63 of the 90 tenants have done so; a median one has 27 formats.
The document type is in txn_type. A format for sales invoices carries txn_type = INTERNAL_SALES_INVOICE; the e-Invoice layout carries the literal E-INVOICE. Every dropdown that offers formats filters on that column and nothing else, so a format uploaded from the Sales Invoice applet never appears in the Cash Bill applet, and vice versa. The backend’s only rule on the column is that it is not blank. (The similarly named server_doc_type column on the same table is empty in every tenant; ignore it.)
A sub-report is a format with a parent. Complex layouts — a receipt voucher with its payment lines, a cash bill with its settlement block — are a main template plus one or more sub-templates linked by guid_parent and named by convention (INTERNAL_RECEIPT_VOUCHER_PAYMENT, …_CONTRA, …_JOURNAL). The dropdowns hide sub-reports; only the main format is selectable. 35 tenants use them.

Columns you will see in the API and can leave alone: category, default_print_format, sort_code and image_guid are stored and filterable, and nothing in the backend acts on them — in particular, ticking default print format does not make a format the default anywhere. Branch defaults, below, are the mechanism that works.

The records and how they connect

    flowchart LR
  BR["bl_fi_mst_branch<br/>the branch"]
  BD["bl_fi_mst_branch_default_printable_format_hdr<br/>branch default: document type, format, header, footer"]
  CO["bl_fi_mst_comp<br/>the company"]
  CE["bl_fi_mst_comp_einvoice_printable_format_hdr<br/>company e-Invoice format, with priority"]
  PF["bl_prt_printable_format_hdr<br/>the printable format (code, name, txn_type)"]
  PX["bl_prt_printable_format_ext<br/>PRINTABLE_FORMAT_FILE → the uploaded .jrxml"]
  PL["bl_prt_printable_format_list_hdr<br/>'Jasper JRXML' (one row per tenant)"]
  SUB["bl_prt_printable_format_hdr<br/>a sub-report"]
  IL["bl_prt_printable_format_image_link"]
  IH["bl_prt_printable_format_image_hdr<br/>an image file, per branch"]
  MT["bl_fi_gen_doc_message_template_branch_link /<br/>_comp_link — e-mail templates"]
  BD -->|branch_guid| BR
  BD -->|default_printable_format_guid| PF
  CE -->|company_guid| CO
  CE -->|printable_format_hdr_guid| PF
  PX -->|hdr_guid| PF
  PF -->|printable_format_list_guid| PL
  SUB -->|guid_parent| PF
  IL -->|printable_format_guid| PF
  IL -->|image_guid| IH
  IH -->|branch_guid| BR
  MT -->|printable_format_guid| PF

Every arrow is a foreign key in the schema. Read an arrow as “holds the key of”: a branch default holds the key of a branch and of a format; a company e-Invoice format holds the key of a company and of a format; the e-mail template links hold the key of a format of their own, which matters in the e-mail rule below. (The image tables are used by one or two tenants; they let a template pull a per-branch logo through a parameter named IMAGE_URL_<code>.)

Four rules for choosing a layout

This is the part to read twice. “The default format” means four different things depending on who is printing.

When	Which format is used	Where the branch default fits
You press Print on a document	The one selected in the print dialog’s dropdown. The backend takes whatever guid the screen sends; it has no fallback of its own	The dropdown is pre-selected with the branch default for that branch and document type; if there is none, with the applet’s PRINTABLE setting; otherwise nothing is selected and the print fails with CLIENT_PRINTABLE_FORMAT_GUID_IS_INVALID
A document e-mail goes out through a message template	The format named on the message template’s branch or company link; if the link names none, the branch default	Second choice. If neither exists the e-mail is sent without any attachment and no error is raised
The e-Invoice PDF (the one with the QR code) is produced	The company’s e-Invoice format for that document type — highest `priority` wins; if the company has none, a built-in template shipped with the platform (one for sales documents, one for the rest)	Never consulted. A branch default has no effect on the e-Invoice PDF
The old sales-invoice e-mail job (`SalesInvoiceEmailNotificationProcessor`) runs	The first format whose code is exactly `INTERNAL_SALES_INVOICE`, in no particular order	Never consulted

There is one more thing the branch default does: its Header and Footer text are handed to the template as parameters named HEADER and FOOTER. Whether they print depends on the template using them — the standard generic print path does not pass them; the specialised print services for the cash bill, receipt and payment voucher, purchase order and a few others do. If your header text does not appear, the template does not reference the parameter.

Before you start

A .jrxml file for the document type, built for BigLedger’s field names. Ask BigLedger support for the sample template for the document type rather than starting from a blank canvas; the field names are not documented anywhere a reader can see.
Access to the document applet’s Settings menu (Printable Format Settings, and Branch Settings for the default). The backend permissions behind the branch default are API_TNT_DM_ERP_BRANCH_DEFAULT_PRINTABLE_HDR_CREATE / _UPDATE / _READ.
For the e-Invoice layout: access to the Organisation applet’s company record.

Step 1: Upload the format from the document applet

Sales Invoice › Settings › Printable Format Settings › Add Printable Format

The outcome: GS-KV-01’s A4 layout exists as a format that the print dropdown can offer.

The form has three things: Format Code, Format Name, and a drop zone that accepts only .jrxml. Give it a code you will recognise in a dropdown of thirty — SI-A4-KV beats FORMAT3. The applet fills in the document type itself (txn_type = INTERNAL_SALES_INVOICE) and links the row to the Jasper JRXML list entry; you do not choose either.

Upload the Penang receipt layout the same way, as SI-RECEIPT-PEN. If the template has sub-reports, upload the main file first, then each sub-report with the main one selected as its parent.

The commonest failure: uploading the sales-invoice template from the Cash Bill applet. It saves without complaint, gets txn_type = INTERNAL_SALES_CASHBILL, and never appears in the Sales Invoice dropdown. Delete it and upload from the right applet.

Step 2: Set the branch’s default

Receipt Voucher (or any document applet that has it) › Settings › Branch Settings › the branch › Printable Format

The outcome: when anyone at GS-KV-01 presses Print on a sales invoice, SI-A4-KV is already selected, and the branch’s header and footer lines are available to the template.

The tab has a format dropdown — every format with this applet’s document type, sub-reports removed — and two text boxes, Header and Footer. Pick SI-A4-KV, type the header and footer the branch wants, and save. The screen first looks for an existing row for this branch and document type and updates it, so saving twice does not create two.

Two things to know about this screen:

The document type is fixed per applet and hidden. Each applet’s copy of the tab writes its own document type; there is no dropdown to change it. The Sales Invoice applet does not have this tab at all — set the sales-invoice default from an applet that does, or through the API.
There is no priority field. The column exists and is only honoured by the batch-print path; the print dialog and the e-mail job take the first row they find. One row per branch and document type is the only configuration that behaves predictably (see the aggregate note under Common mistakes).

Repeat for GS-PEN-01 with SI-RECEIPT-PEN. 21 of the 90 tenants have set branch defaults; a median one has four rows covering two document types.

Step 3: Set the company’s e-Invoice layout

Organisation › Company › the company › E-Invoice Details › Printable Format › Add

The outcome: the PDF with the QR code that GSO’s customers receive uses GadgetSphere’s own layout instead of the platform’s built-in one.

This form is richer than the branch one: Format Code, Format Name, a Document Type dropdown (ten document types offered), a Priority number, and the .jrxml upload. The applet saves the template as a format with txn_type = E-INVOICE and links it to the company for that document type; it refuses a second row for the same document type with A printable format already exists for this document type. The backend picks the highest priority when more than one row exists, so priority only matters if rows were created outside the screen.

This is per company, not per branch. All 22 GS branches share one e-Invoice layout; GSO and GSD each have their own. 29 of 90 tenants have set one; a median one has seven rows (one per document type).

Step 4: Print one of each and look

Print a sales invoice at GS-KV-01 from the screen: the dropdown should open with SI-A4-KV selected and the PDF should carry the branch header. Trigger the invoice e-mail: the attachment should be the same layout, unless the message template names a format of its own. Open the e-Invoice PDF for the same document: it should be the company layout from Step 3 — and it will be the same on every branch, because Step 2 does not reach it.

What success looks like

Open Printable Format Settings in the Sales Invoice applet and count: your uploaded formats are there, each with a code you recognise, none of them a sub-report showing as a main format. Open the branch’s Printable Format tab: one format selected, header and footer filled. Then print, e-mail and open the e-Invoice PDF for one invoice at that branch, and check that each of the three shows the layout you expect from the table above. If all three match, you are done; if the e-mail arrives with no PDF, see the second common mistake.

Common mistakes

The print dropdown is empty. No format in this tenant has this applet’s document type in txn_type — the template was uploaded from another applet, or (through the API) with a mistyped type. Re-upload from the right applet.
The e-mail arrives without the PDF. The message template’s link names no format and the branch has no default for that document type. The job logs it and sends the e-mail anyway. Set the branch default (Step 2) or name a format on the template.
The e-Invoice PDF ignores the branch layout. By design: it reads only the company e-Invoice format (Step 3) and otherwise uses the built-in template. Documents printed through the plain e-Invoice print endpoint, rather than the company-print one, always get the built-in template.
The header text does not print. The template does not use the HEADER / FOOTER parameters, or the document type is printed through the generic path that does not pass them. This is a template question, not a settings one.
Two people set a default for the same branch and document type from different applets or through the API. Nothing on the server prevents it — the aggregate run found 24 such duplicate pairs across 8 tenants — and the print dialog and the e-mail job then take whichever row happens to come first. List the rows through the API, delete the extra one. Four tenants also hold branch-default rows with no format selected; those pre-select nothing.