Troubleshooting .docx Templates

Qoblex leaves a field empty when it has no value for it, and it shows no error. There are three common reasons.

• The name is not one Qoblex recognises for this document, for example a typo or a name from another category. Compare it with the field list for your document type, including the dots (for example «Customer.Name»). Capital letters do not matter, so «Subtotal» and «SubTotal» both work.
• The record has nothing to show. An empty notes box or an empty second line of an address (the «LineTwo» fields) prints blank on purpose. A contact detail that is empty, such as a customer with no email address, prints blank in the same way. Open the order, invoice or purchase order, check the value is filled in, then print again.
• The field is in the wrong place. Fields for product lines only fill inside a repeating section, and order-level fields print blank inside one. See the two rows below.

For the Sales, Purchase and Packing Slip categories, copy names from the starter template rather than typing them again. There is no refund starter, so copy refund names from the refund field list.

Qoblex does not leave a placeholder for a name it cannot fill, so text in « » that appears in the PDF was never a merge field. It is plain text that you typed between « and ». Delete it and insert the field again with Insert > Quick Parts > Field > MergeField.

Each category has its own fields. A packing slip has «ShipmentNumber» and the line range «RangeStart:Items», while sales and purchase order templates use «RangeStart:OrderItems». A refund keeps its note in «Comments» and has «RangeStart:RefundItems». Moving a field like these between categories leaves it blank.

Some fields do work across categories. «Customer.Name» and «Supplier.Name» both fill on Sales and Purchases templates, because each shows the order’s contact.

Open the field list for the category you picked in Category and replace the names that do not appear there. The categories are Sales, Refunds, Purchases and Packing Slip.

Sales templates cover both sales orders and invoices, so one Sales template serves both.

Fields for product lines, such as «ProductName» or «Quantity», only fill between a «RangeStart:» and «RangeEnd:» pair. Outside that pair there is no single line to read from.

1. Put the row’s fields between «RangeStart:OrderItems» and «RangeEnd:OrderItems» (or the range name your document type uses).
2. Keep order-level fields, such as «Number», outside the range. Inside a range only the line’s own fields fill, so an order-level field there prints blank.
3. Print a test and check that every line appears.

The name after «RangeStart:» and «RangeEnd:» must be identical. Check these causes in order.

• Different names. «RangeStart:OrderItems» needs a matching «RangeEnd:OrderItems». If the names differ, the document does not print at all (see “The PDF will not generate”). Use the range names from the field list for your document type.
• Both fields in one row. To repeat a table row, put «RangeStart:» in the row’s first cell and «RangeEnd:» in its last cell. The row repeats once per line and the header row stays as it is.
• Both fields in one paragraph. The lines run on together inside that one paragraph. To get one line per item, use a table row, or put the start and end in separate paragraphs.
• Start and end in different paragraphs. Everything between them repeats for each line, including whole paragraphs.
• Nested ranges. A range can sit inside another, such as batch numbers inside packing slip items. The inner section repeats once for each batch inside each product line. Keep both inner fields in one cell inside the outer row, as the packing slip starter does: its batch cell holds «RangeStart:Batches» «Number» «RangeEnd:Batches».

Qoblex removes a repeating section when it has nothing to show. A row between «RangeStart:CustomItems» and «RangeEnd:CustomItems» disappears when the order has no additional charges. A batch line does not appear for a product without batches.

In a table, the header row above the repeating row stays, so you see a header with nothing under it. This is expected. Add a test order that has the item type you are checking, then print it again.

Rows and paragraphs outside a repeating section are not removed. A blank address line leaves a blank line in the PDF.

Order notes are typed in a rich-text editor, so Qoblex saves them with formatting codes. Plain «Notes» prints those codes as text in the PDF. Use «Html:Notes» instead: it turns the codes into real paragraphs and formatting such as bold.

This applies to the order-level notes on sales orders and purchase orders. Other documents differ.

• Refunds: «Comments» holds the refund’s own comment, or the order’s notes if the refund has none. Use «Html:Comments» when the order’s notes print. If your refund comment runs over several lines, print a test to check the line breaks.
• Purchase order lines: the «Notes» field on a product line in the starter is a different field, so leave it as it is.
• Packing slips: «CustomerNotes» holds the shipment’s comment. When you tick Include orders that are neither picked nor packed. in the packing slip job, an order with no shipment prints its own notes there, so use «Html:CustomerNotes» for those. For a multi-line shipment comment, print a test first.

1. Type the prefix exactly as «Html:», as in the starter templates.
2. Put the field in a paragraph of its own. If you place it inside a sentence, the formatted paragraphs break out onto their own lines and split the text around it.
3. If other text shares the paragraph, move the field to its own line and print again.

When the field has its own paragraph and there are no notes, the paragraph disappears and no blank line is left.

Product images use «Picture:Image». Check these points.

• Type the prefix exactly as «Picture:». Copy the image cell from the Sales or Purchase starter template if you are unsure.
• Keep the small placeholder picture that sits inside the field, as in the starter template.
• Print a test with a sample order that includes a product without an image, and one with an image, before you send documents to customers.

A number or date prints as Qoblex holds it unless the field carries a Word field switch. Without one, a price such as 12.5 prints without its trailing zero (not 12.50) and with no thousands separator, and a date prints with its time. On packing slips and refunds, a price can also show every decimal. The Sales and Purchase starter templates add switches such as \#0.00 on prices (the field code reads MERGEFIELD Price \#0.00) and \@ "dddd, dd MMMM yyyy" on dates. If you retype a field, the switch is lost.

• Copy the field from the Sales or Purchase starter template, or edit the field code in Word and add the switch back. Use \# "#,##0.00" for thousands separators.
• Yes/no fields such as «HasDiscount» print True or False. To show your own wording, use a Word IF field, as the sales starter does for its discount line.
• Print a test with a sample order to confirm the separators and date style are what you want.

The message is “The selected file is not a valid Microsoft Word DOCX document”. Qoblex only accepts files whose name ends in .docx.

• Open the file in Word and choose File > Save As > Word Document (*.docx).
• Do not rename a .doc, .dotx or .docm file. Renaming the extension does not convert the file.

The message is “This file is too big. The maximum file size allowed is 5MB”. Make the file smaller and upload it again.

• Compress large pictures in Word (select a picture, then Picture Format > Compress Pictures).
• Remove images the template does not need. Product photos are added from your products, so they do not belong in the file.

The message is “Unable to upload the .docx template. Please try again”. Try the upload once more.

If it fails again, check your connection and that the file is not open in another program. Save a fresh copy under a new name and upload that copy.

If you select Close without a file, Qoblex shows “Please correct the following:” followed by “Please upload a custom template file to continue or delete this element”. The template is not complete without its file.

• Upload a .docx file using Click to upload a template…, then select Close.
• Or select Delete this template if you no longer want the template.

Once a file is uploaded, the editor offers Click to download this template… and no way to replace the file.

1. Download the file and edit it in Word.
2. Select Delete this template, then select Save on the Branding and Customization page.
3. Select Add .docx Template, enter the name, choose the Category and upload the edited file.

When a sales order, invoice, purchase order or refund cannot be printed from a .docx template, the new browser tab that opens shows only plain text. The text reads “There was an error while generating the pdf document.” and there is no normal Qoblex screen around it.

Packing slips show “Could not download packing slips. Please try again” instead.

Qoblex does not accept or reject the contents of the file at upload. A damaged file uploads without a message and only fails when you print. A repeating section whose «RangeStart:» and «RangeEnd:» names do not match also fails at print time.

1. For sales orders, invoices and purchase orders, print the same document with the matching starter template (Sales or Purchase). Packing slips have their own starter. If it works, the problem is in your file.
2. There is no refund starter. For a refund, save a near-empty Word file with only a title and one field such as «Number», upload it as a Refunds template and print with it.
3. Add your own changes back a section at a time, printing after each, until the error returns.
4. Check that every «RangeStart:» has a «RangeEnd:» with the same name.
5. Check that the template’s Category matches the document you are printing.

If the starter or near-empty template also fails, contact support with the document number.

The Print Document list shows templates for the document you are printing. A refund shows Refunds templates and a sales order shows Sales templates. A purchase order shows Purchases templates and also any Product Labels templates. If a template is missing, check its Category.

Once you add a .docx or designer template for a document type, Qoblex preselects the first one and no longer offers Default Template. It comes back when no template is left for that document type.

The exception is a purchase order whose only template is a Product Labels one. Default Template is still offered, but the Product Labels template is preselected, so choose Default Template before you print.

Delete templates, then select Save on the Branding and Customization page.

The packing slip job never offers Default Template. It hides the template list when you have no packing slip templates and prints the built-in layout.

Print Word packing slips from these two places.

• The order page: open the order, stay on its Order tab, select the print (printer icon) menu, then Print Packing Slip.
• The Sales list: select orders, then Packing Slips.

In the packing slip job, choose your template and select Generate. Select Preview when it is ready. When you print several orders at once, each packing slip starts on a new page, and the page setup, headers and footers from your template are kept.

For a refund, open it from the order’s Refund tab and use the print button on the refund page.