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 the format record and, for each upload, a pointer to 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.

It fills the template from what BigLedger hands over — a set of named parameters (company, branch, document header) and the document’s lines as a list of records — and never gives the template a database connection. That is the difference from the iReport habit of older systems, where a template carried its own SQL: here a query inside the template is never run, so the fields it expected from that query come out empty or stop the print with an error. Two things follow. Nobody needs a database account to design a template: you bind BigLedger’s parameter and field names and preview with sample values. And a broken file is not caught when you upload it — it is compiled for the first time when somebody prints, so print one test document straight after every upload.

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

• BigLedger ships no formats. The platform seeds exactly one template technology, Jasper JRXML — the only one supported. Every format in your tenant was uploaded by someone in your organisation — nothing is there until somebody puts it there.
• A format belongs to one document type. A format for sales invoices carries the document type INTERNAL_SALES_INVOICE; the e-Invoice layout carries the literal E-INVOICE. Every dropdown that offers formats filters on that type 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 it is that it is not blank.
• 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 to their parent and named by convention (INTERNAL_RECEIPT_VOUCHER_PAYMENT, …_CONTRA, …_JOURNAL). Not every dropdown hides them. The branch-default Format dropdown and the parent dropdown on the upload forms that have one leave sub-reports out; the Sales Invoice print dialog’s dropdown lists every format of the document type, sub-reports included, so give sub-reports codes nobody will pick by mistake.

A format’s category, sort code and image are stored and filterable, and nothing keys off them. The default tick does something, just not what its name suggests. No backend service acts on it, but the shared document-view dialog that applets inherit reads it when you print from that dialog: among the formats for the document type, the ticked one is chosen, and with none ticked the most recently updated one. Whether the branch comes first depends on the applet’s build. Each applet ships its own copy of that shared screen code: in older copies the dialog goes straight to the ticked format and ignores the branch; in the current shared code it looks for the branch’s default first (the most recently updated branch-default row for that branch and document type) and only then falls back to the ticked format. So if two applets pre-select different layouts in this dialog for the same branch, the difference is probably the build, not your settings. The Organisation applet’s e-invoice format listing pre-selects the ticked row the same way. The tick is a per-tenant marker for one document type; branch defaults, below, are what varies the layout branch by branch. (Do not confuse it with the Default checkbox on the Sales Invoice applet’s Printable Format Settings listing, which sets the applet’s own fallback setting — see Step 2.)

The records and how they connect

    flowchart LR
  BR["The branch"]
  BD["Branch default<br/>document type, format, header, footer"]
  CO["The company"]
  CE["Company e-Invoice format<br/>with priority"]
  PF["The printable format<br/>(code, name, document type)"]
  PX["The uploaded .jrxml"]
  PL["'Jasper JRXML'<br/>(the one template technology)"]
  SUB["A sub-report"]
  IL["Image link"]
  IH["An image file, per branch"]
  MT["E-mail templates<br/>(branch and company links)"]
  BD -->|for| BR
  BD -->|uses| PF
  CE -->|for| CO
  CE -->|uses| PF
  PX -->|file of| PF
  PF -.->|technology — not enforced| PL
  SUB -.->|parent — not enforced| PF
  IL -->|of| PF
  IL -->|image| IH
  IH -->|for| BR
  MT -->|uses| PF
  

Every solid arrow is a link the database enforces; the two dashed arrows are references nothing enforces, so a format can point at a parent or a technology that no longer exists. Omitted for legibility: branch → company, and the e-mail templates’ own branch and company links. 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 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.

The same four rules as a picture. Read each lane left to right: the first box is tried first, none moves to the next box, found ends the search. The table each box reads is in italics; the branch default appears in the first two lanes and nowhere else.

    flowchart TB
  subgraph R1["1 · You press Print"]
    direction LR
    P1["Branch default for this branch<br/>and document type"] -->|none| P2["The applet's PRINTABLE setting"]
    P1 -->|found| P3["Pre-selected in the print dropdown;<br/>the backend prints whatever the dropdown sends"]
    P2 -->|found| P3
    P2 -->|none| P4["Nothing selected — the screen fails<br/>before the backend is reached"]
  end
  subgraph R2["2 · A document e-mail through a message template"]
    direction LR
    E1["Format named on the template's<br/>branch or company link"] -->|none| E2["Branch default for this branch<br/>and document type"]
    E1 -->|found| E3["PDF attached"]
    E2 -->|found| E3
    E2 -->|none| E4["E-mail sent with no attachment,<br/>no error raised"]
  end
  subgraph R3["3 · The e-Invoice PDF, the one with the QR code"]
    direction LR
    I1["Company e-Invoice format for the<br/>document type: a row with no priority first,<br/>then the highest priority"] -->|none| I2["Built-in template shipped with the platform:<br/>one for sales documents, one for the rest"]
    I1 -->|found| I3["The company layout — the same at every branch;<br/>the branch default is never read"]
  end
  subgraph R4["4 · The old sales-invoice e-mail job"]
    direction LR
    L1["First format whose code is exactly<br/>INTERNAL_SALES_INVOICE, in no order"] -->|none| L2["No attachment"]
    L1 -->|found| L3["PDF attached"]
  end
  R1 ~~~ R2 ~~~ R3 ~~~ R4
  

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.

The e-mailed copy never carries them. The message-template e-mail (rule 2) renders its PDF on the generic print path, whatever the document type, so the branch’s Header and Footer are never passed to it — even though the same layout printed from the Sales Invoice screen does receive them, because that screen asks for a specialised print service. Same layout, different text: a template that prints GS-KV-01’s bank details from FOOTER prints them on paper and leaves them out of the e-mail. Anything the e-mailed copy must show belongs in the template itself, not in the branch’s Footer. The multi-format batch print below does not pass them either.

Two more paths in the Sales Invoice applet

The table covers the rules the platform applies wherever you are. The Sales Invoice applet adds two of its own, and both matter to a multi-branch group:

• Printing several invoices from the listing uses one format for all of them. The listing takes the branch default of the first selected row — for that row’s branch, the most recently updated default row — else the applet’s PRINTABLE setting, and prints every selected invoice with that one format. Select a Klang Valley invoice and a Penang invoice together and both print in the Klang Valley layout. Print one branch at a time. If the applet setting BATCH_PRINT_MULTIPLE_FORMAT is on, the server works differently: for each invoice it looks up that invoice’s own branch and prints it once for every default row that branch has for the document type, rows with no priority first, then highest priority first — two default rows, two copies of every invoice — and uses the format the listing resolved when a branch has none. This batch path passes no Header or Footer.
• The applet’s Send Email button does not use the branch default. It attaches the format named on the applet’s e-mail template, else the applet’s PRINTABLE setting, and renders it on the same specialised print service as the screen print, so this copy does carry the branch Header and Footer. Only the message-template e-mail (rule 2) reads the branch default.

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; for the e-Invoice PDF the parameter families a company format can use (COMPANY_*, BRANCH_*, E_INVOICE_*) are named on the admin applet’s §4b; for other document types 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 (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.

This form cannot link a sub-report to its parent. It has no parent field, so a sub-report uploaded here saves as one more main format, unlinked, and shows in the print dropdown beside the real one. Some applets’ upload forms do carry a parent dropdown — the Receipt Voucher applet’s is one: upload the main file first, then each sub-report with the main one chosen as its parent. For a sales-invoice layout that needs sub-reports, ask BigLedger support how to link them before you upload anything.

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

Replacing the file deletes the old one. Saving a new .jrxml on a format’s edit screen removes the previous file before the new one is stored, and every print and reprint from then on — March invoices included — uses the new file. The edit screen has a download button: download the current file first and keep it with the date it went live, or upload the new version as a new format with its own code and repoint one branch to test it.

Step 2: Set the branch’s default

Sales Invoice (or the document applet you print from) › 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.

Set it from the applet whose documents you print. Each applet’s copy of this tab writes that applet’s own document type, fixed and hidden, so the sales-invoice default is set in the Sales Invoice applet. (An earlier version of this page said the Sales Invoice applet had no such tab and told you to set its default from another applet; none of the other applets’ copies writes the sales-invoice document type, so that route never worked.) Two versions of the tab exist, and which one you see depends on the applet:

• The shared Branch Settings screen — the Sales Invoice applet uses this one. The tab lists the branch’s rows for this document type and adds a row with Format, Priority, Header, Footer and Device. Saving updates an existing row only when one with the same format and the same device already exists; otherwise it adds a new row. With no device chosen, every save adds a row.
• The older per-applet tab — the Receipt Voucher applet and many others. A format dropdown and the two text boxes, no priority. It looks for the existing row for this branch and document type and updates it, so saving twice does not create two.

Pick SI-A4-KV, type the header and footer the branch wants, and save.

Keep one row per branch and document type, and check the list after you save. The shared screen lets a branch hold several rows for one document type, and each path that reads branch defaults chooses among several in its own way:

None of the Sales Invoice paths above filters on the Device. BigLedger has not said which of these is the intended way to use several rows, so we describe what each path does and do not recommend it: with one row per branch and document type, every path prints the same layout, and that is the configuration to aim for. If you inherit a branch with several rows, delete the extras, or ask BigLedger support which row each path should use before relying on them.

The applet’s fallback. When a branch has no default, the print dialog and the listing fall back to the applet’s PRINTABLE setting. In the Sales Invoice applet you set it on Settings › Printable Format Settings: tick the Default checkbox on a format’s row. It is one setting for the whole tenant’s installation of the applet, not per branch or company — the safety net that stops a new branch’s print dialog from opening empty.

Repeat for GS-PEN-01 with SI-RECEIPT-PEN. Nothing sets a branch default for you, and nothing tells you a branch is missing one. With the applet’s fallback set, a branch with no default simply prints the fallback layout, so the print dialog never looks wrong; the dialog opens with nothing selected only when the fallback is missing too. The dependable check is a list: write down which format each branch should use for each document type, then open each branch’s Printable Format tab and compare. With 22 branches, do it when a branch opens and again whenever a layout changes.

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 has 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 of type E-INVOICE and links it to the company for that document type; before saving it checks for an existing row and refuses with A printable format already exists for this document type — but the check includes the priority whenever you type one. So the screen refuses a second row only at the same priority (or when you leave Priority blank and a row for that document type already exists); a second row for the same document type at a different priority saves. When a company has several rows for one document type, the e-Invoice PDF uses one: a row with no priority outranks every numbered one, and among numbered rows the highest wins. Keep one row per document type and replace it when the layout changes; if you do keep a second, make sure the one you want is the one with no priority or the highest number.

This is per company, not per branch. All 22 GS branches share one e-Invoice layout; GSO and GSD each have their own, and you need one row per document type you issue.

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 through its message template: the attachment should be the same layout, unless the message template names a format of its own — but without the branch header and footer text, which the e-mailed copy never receives (see the four rules above). If the e-mail must show that text, move it into the template. 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. Open the branch’s Printable Format tab: one row for the document type, 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

1. The print dropdown is empty. No format in this tenant carries this applet’s document type — the template was uploaded from another applet, or (through the API) with a mistyped type. Re-upload from the right applet.
2. 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.
3. 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.
4. The header text does not print, or prints on paper and not in the e-mail. The template does not use the HEADER / FOOTER parameters, or the copy was produced by a path that does not pass them — the generic print path, the message-template e-mail and the multi-format batch print never do. This is a template question, not a settings one: text every copy must carry belongs in the template.
5. Two copies print, or the layout differs depending on where you print from. The branch has more than one default row for the document type — the shared Branch Settings screen adds a row on each save unless the format and device match, and the API and older screens can add more; nothing on the server refuses a second. Each path then chooses among them differently (the table in Step 2). Open the branch’s Printable Format tab, keep one row per document type and delete the rest. A branch-default row saved with no format selected is possible too: the print dialog then falls back to the applet’s PRINTABLE setting, as if the branch had no default, and only with no fallback either is nothing selected. Delete such a row or give it a format.
6. The print comes out blank, or fails, with a template that worked in another system. The template runs its own database query instead of binding BigLedger’s parameters and line fields, and that query is never run here. Rebuild it on the sample template for the document type; do not ask for database credentials, because no print path would use them.
7. Printing fails with CLIENT_PRINTABLE_FORMAT_FILE_NOT_FOUND. The format record exists but no uploaded file is attached to it. Upload the .jrxml again (Step 1), print one document to confirm, and delete the empty record so nobody picks it.

Related documentation

• Document Numbering — the tenant, company and branch numbers a template can print
• Organisation Applet — branches and companies, and the company’s E-Invoice Details
• Sales Invoice (Internal) — Printable Format Settings and the PRINTABLE applet setting
• e-Invoice Submission Mechanics — where the e-Invoice PDF and e-mail sit in the LHDN flow
• MyInvois e-Invoice Admin — the two print endpoints for an e-Invoice