Templates
This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.
Create document templates, upload their .docx versions, see the placeholders Cogneris found, publish the version that is rendered, and delete templates you no longer use.
| How to get here | Templates in the Template menu. A template page: select a card in the list. |
| Who can use it | Tenant-management profiles (customer administrator, customer technical administrator, Cogneris operators). Deleting also needs the tenant administrator role (tenant.admin). Checked by the service. |
| Content status | From source; not observed (template-fe ed4ab73, template-be cc0f2b0, 2026-10-22) |
Template list
The header reads Templates with … total under it — the number of templates that match the search, archived (deleted) ones excluded.
Each template is a card with its name, a status chip, its code, its description (when it has one) and N Versions. Cards are ordered by last change, newest first.
- The list shows at most 20 templates — the 20 most recently changed that match the search — and has no next page. The total counts all of them. Use the search to reach the others.
- The status chip reads Published when the template has a published version, Draft when it has none, and Archived for an archived template. (The service's own template status is only Active or Archived; whether a version is published is recorded on the version.)
While the list loads, six grey placeholder cards are shown. With no templates (or no match), the list shows No data.
Only templates without a published version. Arriving from the Dashboard's Publish a version tile, the list shows only the templates that have no published version, under the note Showing templates without a published version. Show all returns to the full list. This view looks through the 100 most recently changed templates.
Fields
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Search by name or code | Filters the list as you type (after a short pause). Matches any part of the name or the code, ignoring case. | No | Text | Empty, or the value of ?search= in the address | — |
| Card check box (Select template …) | Selects the card for deleting. Selecting it does not open the template. | No | On / off | Off | — |
Buttons and actions
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Copy link | Copies the address of this page, search included, to the clipboard. The label changes to Copied! for about two seconds. | Anyone who can open the page | — |
| + New template | Opens the New template dialog. | Tenant-management profiles | — |
| A card | Opens the template page. | Tenant-management profiles | — |
Create a template
+ New template opens a dialog titled New template.
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Name | The template's display name. The service also makes the template's code from it. | Yes | Text; spaces at both ends are removed | Empty | Save stays disabled while it is empty. |
| Description | Free text shown on the card. | No | Plain text. HTML markup is refused — a less-than sign directly followed by a letter, /, ! or ?, also when the sign is written as an HTML entity. A less-than sign followed by a space or a digit, and an e-mail address in angle brackets, are accepted. | Empty | description must not contain HTML markup |
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Save | Creates the template, shows Template created and opens its page. The template has no versions yet. | Tenant-management profiles | Delete it (archives it). |
| Cancel, or a click outside the dialog | Closes the dialog. What you typed is kept until you leave the page. | — | — |
How the code is made. Accents are removed, the name is put in lowercase, and every run of characters other than a–z and 0–9 becomes one hyphen (Fatura Mensal V1 gives fatura-mensal-v1). If the code is taken — also by a deleted template — -2, -3… is added. An empty result becomes template. The code cannot be changed afterwards; the name and description can, with Edit details on the template page.
Template page
The header shows the template's name, and under it the code and N Versions. While the template loads, the page shows Loading….
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| ← Back | Returns to the list. | — | — |
| Edit details | Opens a dialog with Name and Description (same rules as in Create a template) and the note The code … never changes, so callers keep working. Save stores them and shows Template updated; a blank description removes it. | Tenant-management profiles | Yes: edit again. |
| Field sources | Opens the template's field sources. | Tenant-management profiles | — |
The left column lists the Versions, with the upload area under them. The main area shows the version you select; when the page opens it shows the published version, or the newest one when none is published. With no versions, it shows Pick a version.
Upload a version
The upload area reads Drop a .docx file or click to choose. Drop a file on it, or click it to choose one; the upload starts at once. Only the first file is used when you drop several.
Above it, Notes for the next version (optional) — up to 1,000 characters stored with the version you upload next and shown on its row in the timeline. The box is cleared after a successful upload.
| Rule | Limit | Message |
|---|---|---|
| A file must be sent | — | file is required |
| Not empty | — | file is empty |
| Size | 50 MB | file exceeds the maximum allowed size of 50 MB |
| Extension | .docx only — the file chooser offers only .docx, and the service checks the name | only .docx files are allowed |
| Real .docx content | Must be a ZIP (Word) archive | file is not a valid .docx (zip) archive. |
| Number of parts inside the archive | 512 | document archive has too many entries (limit 512). |
| Uncompressed size | 200 MB | document archive uncompressed size exceeds the limit (200 MB). |
| Compression ratio | 100 to 1 | document archive compression ratio exceeds the limit (100:1). |
| Text parts read for placeholders | 64 parts, 2 MB each, 8 MB in all | The upload fails (the service's message). |
On success:
- New content — Version … uploaded. The new version gets the next number and is selected; it is a draft (not rendered) until you publish it.
- Same content as an earlier version (byte-for-byte identical) — Content identical to an existing version — new version tracked as duplicate. A version is still added with the next number, the stored file is reused, and its keys are copied from the earlier version. In the timeline it carries the chip Duplicate of v… with the number of the version it repeats.
A file larger than 25 MB can be uploaded but cannot be rendered with the default settings (see overview — render API).
Placeholder syntax
The service reads the main text, the headers, the footers, the footnotes and the endnotes of the .docx, and recognises a placeholder written as two opening braces, a key and two closing braces:
{{nome}}
{{ titular.cpf }}
{{documentos.documentName}}
- The key may use letters (A–Z, a–z), digits,
_,-and.. Spaces inside the braces are ignored. Anything else — accented letters, spaces inside the key — is not a placeholder and is left in the text as typed. - Keys are case-sensitive when they are detected:
Nomeandnomeare two keys. - Word often splits text into pieces when you edit it; the service joins them before looking, so a placeholder typed in two goes is still found.
- A dot names a field inside a group. A key such as
documentos.documentNameis how a repeating block is written.
Versions and publishing
Each version row shows v + number, the file name, its size, and when it was uploaded (in the language of the interface), and its note when it was uploaded with one. The published version carries a Published chip. Select a row to show that version's keys.
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Publish this version (on every version except the published one) | Makes this version the one rendered for the template's code, at once and without a confirmation. Shows Version published. Every render after this — Playground, Workflow, API — uses it. The version published until then becomes Archived: a template has one published version at a time. Keys of the new version that have no Required / Default value of their own take them from the version it replaces. | Tenant-management profiles | Yes: publish another version. Any older version, archived ones included, can be published again. |
The template's field sources belong to the template, not to a version: a new version keeps every source whose placeholder it still contains.
Keys detected
The selected version's heading shows v + number, its file name, and a Published chip when it is the published one. Under it, Keys detected (count) lists the placeholders the service found, in alphabetical order:
| Column | What it shows |
|---|---|
| Key | The placeholder's key. |
| Occurrences | How many times it appears in the document. |
| Type | Always string: every key is stored as text. |
With no placeholders, the table reads No keys found.
Redaction policy
A card under the keys, Redaction policy — Publish the tenant's default Redaction policy for this template. The policy itself is kept and enforced by the Vision service; this card only shows its state and publishes the tenant default.
| State chip | Meaning |
|---|---|
| Not published | The template has no Redaction policy. |
| Draft | A policy version was started but not published. |
| Published · Version … | Published, with the number of the newest published policy version. Under it: … categories · …-hour retention. |
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Publish policy (when nothing is published) | Asks Publish Redaction policy? — This template will use every category allowed by the tenant policy. Confirming with Publish policy creates a draft from the tenant's live policy, validates it and publishes it; Redaction policy published confirms. Cancel, Esc or a click outside closes the question. | Decided by the Vision service | Decided by the Vision service. |
| Resume publishing (when a draft exists) | Same question; validates and publishes the existing draft. | Decided by the Vision service | Decided by the Vision service. |
If the state cannot be read, the card shows The Redaction policy could not be loaded. with Retry, and no publish button.
Delete templates
Select one or more cards. A bar appears with … template selected (or … templates selected) and three buttons:
| Button | What happens | Who | Reversible? |
|---|---|---|---|
| Select all visible | Selects every card on the screen. | — | — |
| Archive | Asks Archive templates? — This archives … templates: they leave this list and can no longer be rendered. Their versions are kept. Confirm with Archive; Cancel, Esc or a click outside closes the question. While it runs the button reads Archiving…. | Tenant administrator (tenant.admin) | Not from the screen (see below). |
| Clear selection | Unselects every card. | — | — |
What happens in the service: the template is archived, not erased. It leaves the list and the Playground, every render of its code answers template '…' not found, and it is counted under Archived on the Dashboard. Its versions and render history are kept, and its code is never given to another template. The screen offers no way to restore it. Deleting a template that is already archived succeeds and changes nothing.
Each template is deleted separately, so one result can mix outcomes:
| Message | Meaning |
|---|---|
| Archived … templates | That many were archived. |
| Templates not archived: …. Only a tenant admin can archive templates. | You lack the tenant administrator role. These are not offered for retry. |
| Failed to archive some templates — click to retry | Others failed for another reason. They stay selected; click the message to try them again. If that also fails: Failed to archive some templates (retry failed). |
Common problems
| Message | Cause | What to do |
|---|---|---|
| The list is empty after the Dashboard's Publish a version tile | Every template already has a published version. | Select Show all. |
| A template you know exists is not in the list | The list shows only the 20 most recently changed matches. | Search by its name or code. |
| An error message with — click to retry when the list loads | The list request failed; the message is the service's. | Click the message to load the list again with the same search. |
| description must not contain HTML markup | The description contains markup. | Remove the tag-like text. |
| template not found | The template was deleted, or belongs to another tenant. | Return to the list. |
| version not found for this template | The version is not part of this template. | Reload the page. |
| An upload message from the table in Upload a version | The file broke a limit. | Save the document again as a Word .docx and check its size. |
| A placeholder is missing from Keys detected | Its key uses a character outside letters, digits, _, -, ., or it is in a part the service does not read (for example a text box outside the main text, headers, footers, footnotes and endnotes). | Rename the key and upload a new version. |
| Duplicate of v… on a version | You uploaded a file identical to that earlier version. | Nothing to do; publish either. |
Related
- Template administration overview
- Field sources — bind each detected key.
- Render playground — check the published version.
- Word add-in — insert placeholders in Word.
- Generate document
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation