Template administration overview
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.
Template is the Cogneris document-generation product. You upload a Word document (.docx) that contains placeholders, say where the value of each placeholder comes from, publish a version, and Cogneris renders it to PDF — for a Workflow process or for your own application through the API.
| How to get here | The Template product in the platform menu, or the Template application on its own (its window title is Cogneris Templates). It opens on Dashboard. |
| Who can use it | Templates and Playground, and every action in them: the tenant-management profiles — customer administrator (customer-admin), customer technical administrator (customer-tech), and the Cogneris operators (cogneris-admin, cogneris-tech). Deleting a template additionally needs the tenant administrator role (tenant.admin). Dashboard: any signed-in member of the tenant. Checked by the service; hiding a menu entry is not the control. |
| Content status | From source; not observed (template-fe ed4ab73, template-be cc0f2b0, 2026-10-22) |
Menu and routes
The menu has three entries. The breadcrumb starts at Template (which links to Dashboard); a template page reads Template › Templates › the template's name.
| Menu entry | Address | Screen | Chapter |
|---|---|---|---|
| Dashboard | /dashboard (also /) | Counters and quick actions | Dashboard below |
| Templates | /templates | The list of templates; create and delete | Templates |
| — (open a template card) | /templates/ + template id | Versions, upload, publish, detected keys, Redaction policy | Templates |
| — (no menu entry or link) | /templates/ + template id + /bindings | Field sources: where each placeholder's value comes from | Field sources |
| Playground | /playground | Render a published template to PDF in the browser | Render playground |
An address that matches no screen shows Page not found with a Go home button.
When Template is shown inside the platform, it hides its own side menu, top bar and breadcrumb, and the platform shows the same entries and trail instead.
From a .docx to a rendered document
- Prepare the .docx. Write the document in Word and put a placeholder wherever a value goes — two opening braces, a key, two closing braces (see Placeholder syntax). The Word add-in inserts placeholders from the list of fields your processes can supply.
- Create the template and upload the .docx — Templates. Each upload is a new version; Cogneris lists the keys it found.
- Say where each value comes from — Field sources. Each placeholder is bound to a document field, a form answer, a process value or the cross-check result, with a rule for when the value is missing.
- Publish a version — Templates. Only the published version is rendered; drafts are never served.
- Render — try it in the Render playground, then render from a Workflow phase or from the API (below).
Dashboard
The landing screen. It loads once when you open it.
Counters
| Counter | What it counts |
|---|---|
| Active templates | Templates of your tenant that are not deleted, published or not. |
| Published | Templates that have a published version. |
| Archived | Templates that were deleted — the service keeps them archived (see Delete templates). |
| Renders (7d) | PDFs rendered for your tenant in the last 7 days, from every caller (Playground, Workflow, API). Shown as +N, or 0. |
A counter shows — while it has no value.
Quick actions
| Tile | Where it goes |
|---|---|
| New template — Upload a .docx with … placeholders. We detect the keys and let you render PDFs. | Templates. Use + New template there. |
| All templates — Browse, search, archive, or open any template to manage versions and keys. | Templates. |
| Render playground — Try a render in the browser with an API key: fill the keys and generate a PDF. | Playground — see Render playground. |
| Publish a version — Only published versions are reachable from the M2M render endpoint. Promote a draft from any template. | Templates, showing only the templates with no published version (Show all returns to the full list). |
Common problems
| Message | Cause | What to do |
|---|---|---|
| We couldn't load your dashboard stats. with Try again | The service did not answer the counters request. | Select Try again. |
How a published template is used
Only the published version of a template is ever rendered. A template is addressed by its code — the slug Cogneris made from the name when the template was created (shown under the name on every card), which never changes. Each render counts toward the tenant's monthly render quota (5,000 renders a month unless your contract sets another value); a render served from the cache does not.
Workflow — the Generate document phase
The Generate document phase names the template by its Template code. At run time it sends the whole case — documents and their extracted fields, form answers, process data, the cross-check result — and the template's own field sources decide which value each placeholder takes:
- When every placeholder that matters can be filled, the service renders the PDF and returns it to the run.
- When a placeholder whose rule is Send for review cannot be filled, the service renders nothing and answers needs review, with the list of missing keys and why each is missing. The phase's Print even with gaps option makes the service render anyway, printing the fallbacks.
The details of what makes a value missing are in Field sources — at render time.
Your application — the render API
POST /templates/ + code + /render returns the PDF of the published version, filled with the values you send. You send the values yourself; the template's field sources are not used on this route.
| Part | What it is |
|---|---|
X-Xtrakt-Api-Key header | A tenant API key for the production environment. Sandbox keys are refused. |
| Proof of an approved caller | The request must also carry a body signature (X-Xtrakt-Timestamp, Unix seconds within 5 minutes of the server clock, and X-Xtrakt-Signature, an HMAC-SHA256 described below), or come from a Cogneris service. Browser calls are refused unless the environment allow-lists that browser origin. |
| Body | A JSON object with values (a list of key/value pairs) and the optional cache, strict and missingPlaceholder (example below). |
| Answer | application/pdf, named code + -v + version number + timestamp + .pdf, with the headers X-Xtrakt-Template-Version, X-Xtrakt-Render-Elapsed-Ms, X-Xtrakt-Render-Id and X-Xtrakt-Cache-Hit (1 or 0). |
| Rate limit | 10 requests a minute per API key. |
{
"values": [
{ "key": "nome", "value": "Maria Silva" },
{ "key": "valor", "value": "1.250,00" }
],
"cache": false,
"strict": true,
"missingPlaceholder": ""
}
- A placeholder you do not send is printed as
missingPlaceholder(empty by default), so no braces are left in the PDF. strict(default on) refuses a render that leaves out a required key. Uploads create every key as not required, so this check does not refuse anything today.cache(default off) reuses the PDF rendered earlier for the same version and exactly the same values, for 30 days.
The signature is the lowercase hexadecimal HMAC-SHA256 of the text below, with a signing secret configured on the service. How that secret is issued is not shown in the source; ask Cogneris.
timestamp.METHOD.path.code.apiKey.bodySha256
METHOD is in capitals, path is the request path, and bodySha256 is the lowercase hexadecimal SHA-256 of the raw request body.
| Answer | Cause |
|---|---|
| 401 render endpoint requires an approved origin or internal service token | No valid signature, and not an allow-listed origin. |
| 401 X-Xtrakt-Api-Key header is required / invalid tenant api key | No key, or a key that is revoked, unknown or not for production. |
| 400 template '…' not found | Unknown code, or a deleted template. |
| 400 template has no published version | Publish a version first. |
| 400 monthly quota exceeded (…/…) | The month's render quota is used up. |
| 400 template source (…) exceeds the synchronous render limit (…)… | The published .docx is larger than 25 MB (the default limit). |
| 429 | More than 10 requests in a minute. |
Related
- Templates — create, upload, versions, publish, delete.
- Field sources — where each placeholder's value comes from.
- Render playground — try a render.
- Word add-in — prepare the .docx in Word.
- Generate document — the Workflow phase that renders a template.
- Vision administration overview — the document templates (classifiers) whose extracted fields feed document sources.
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation