Fifamè Sossou manages the Dépôt Houngbédji in Porto-Novo. The invoices she hands to bars and restaurants look plain, and Codjo, the owner, wants the depot’s logo and a line about delivery on them. A designer has also prepared a delivery receipt for the drivers. Fifamè needs to test each look before using it. The same steps apply to any company that wants its invoices, purchase order forms or delivery receipts to carry its own look.

​
Choose a template from the catalogue

Fifamè browses the catalogue with Browse template catalogue, filtered by type or name. She opens one with View a catalogue template and checks its history with List template versions. When she likes one, Add a catalogue template adds it to the depot. No payment is taken. The template arrives inactive, pinned to its current version, with empty settings.

​
Import your own template

The designer sends two files. Fifamè uploads them with Import my own template, choosing the type of document: invoice, purchase order form or delivery receipt. Exowpee checks the files before accepting them, including a test render on sample data. She can activate the template right away or later.

​
See and preview your templates

List my document templates shows the depot’s templates, and View a document template shows one with its current version. Before using a template, Fifamè looks at a sample document with Preview a document template.

​
Customize it

Codjo wants the delivery line to appear. Fifamè changes the display options with Customize a template’s settings, and renames the template with Rename a document template.

​
Activate a template

A company uses one template for each type of document. Fifamè makes the new invoice the one in use with Activate a document template. The invoice template that was active before is switched off.

​
Update an imported template and its versions

When the designer fixes the delivery receipt, Fifamè reads the current files with View imported template files and uploads the new ones with Update imported template files. Each update becomes a new version, and the history is listed with List imported template versions. To move a template to another version, or back to an older one, she first checks what would change with Preview a template upgrade, then applies it with Switch template version.

​
Delete and bring back

When the old invoice is no longer wanted, Delete a document template removes it from the lists. If it was the active one, Fifamè names the template that takes its place. A mistake can be undone with Restore a deleted template.

​
The rules

  • Templates belong to the company that uses them.
  • A company has at most one active template for each type of document. Activating one switches off the other active one of the same type; activating one that is already active changes nothing.
  • Adding a catalogue template needs company_templates.create. The template must be listed and have a published version, and company-owned templates cannot be obtained this way. A company holds one copy of each catalogue template: a deleted copy is restored and not duplicated, comes back inactive, pinned to the current version, and settings no longer in the configuration are removed.
  • Importing needs company_templates.import, and also company_templates.activate when the template is activated at once. The type is invoice, purchase-order-form or delivery-receipt. The template file is named template.hbs (at most 256 KB) and the configuration file config.json (at most 64 KB).
  • Files must pass a valid configuration schema, compilation and a test render. A file refused by one of these checks is recorded in the publication log; a configuration file that cannot be read as a JSON object is refused before that and is not recorded.
  • Imported files can be read and updated only for templates the company imported itself, with company_templates.view_imported_files and company_templates.update_imported_files. A catalogue template is refused. An update needs at least one of the two files; a file not sent is taken from the current version.
  • Each update publishes a new immutable version (v2.0, v3.0 and so on) and pins the template to it. Settings already saved are kept and are not checked against the new configuration.
  • Customizing settings needs company_templates.update. The settings must be an object of at most 64 KB. Each key must exist in the configuration of the pinned version, with a value of the declared type. The whole settings map is replaced: keys left out go back to their defaults.
  • Switching versions needs company_templates.upgrade. The version must belong to the same template, and an older one is accepted, which is how you roll back. Settings that the target version does not support are removed and reported.
  • Deleting needs company_templates.delete. For an active template, a replacement of the same company and the same type is required, and it becomes the active one. A deleted template can be restored. Restoring needs company_templates.restore and brings the template back inactive.
  • Preview needs company_templates.preview, activation company_templates.activate, and renaming company_templates.update.
  • Listing, viewing, previewing an upgrade and the catalogue reads need no permission.

​
All the actions of this topic

  • List my document templates: Lists the document templates your company owns (invoices, purchase order forms, delivery receipts), filterable by type and name.
  • Import my own template: Uploads your own template and configuration files to create a custom document template, optionally activating it right away.
  • View a document template: Shows one of your company’s document templates with its current version.
  • Rename a document template: Renames one of your company’s document templates.
  • Delete a document template: Deletes a company template (it can be restored later). If it is the active one, a replacement of the same type must be named and becomes active.
  • View imported template files: Shows the template and configuration files of a template you imported.
  • Update imported template files: Uploads new template and/or configuration files for a template you imported, creating a new version.
  • List imported template versions: Lists the version history of a template you imported.
  • Customize a template’s settings: Replaces the customization settings (such as display options) of a template, checked against what its version allows.
  • Activate a document template: Makes a template the one used for its document type, switching off the previously active one.
  • Preview a template upgrade: Shows what would change before moving a template to another version: added or removed settings keys and settings that would be dropped, with a sample render payload. Nothing is saved.
  • Switch template version: Moves a template to another version of the same template (the current one when none is named), or back to an older one. Settings not supported by the target version are dropped and reported.
  • Restore a deleted template: Brings back a document template that was deleted.
  • Preview a document template: Returns the template, its configuration and sample data filled with the company’s details and settings, so the app can render a sample document. Nothing is saved.
  • Browse template catalogue: Lists the document templates offered in the catalogue that your company can get, filterable by type and name.
  • View a catalogue template: Shows one catalogue template, or one of your company’s own templates, with its current version.
  • List template versions: Shows the version history of a catalogue template or of one of your own templates.
  • Add a catalogue template: Adds a catalogue template to your company, pinned to its current version and inactive until you activate it. A previously deleted copy is restored.
From other topics, also used here:
  • Generate an order invoice: Creates the invoice document of a completed order using the active invoice template, and keeps it as a fixed copy. If one already exists it is returned instead.
  • View an order invoice: Retrieves the saved invoice document of an order.
  • Generate a purchase order form: Creates the purchase order form document for a purchase using the active template, and keeps a fixed copy. If one already exists it is returned instead.
  • View a purchase order form: Retrieves the saved purchase order form document of a purchase.