Word add-in

Not yet checked on the product

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.

The Cogneris Word add-in is a task pane inside Microsoft Word. It lets a template author insert the fields a process can actually supply as structured placeholders, convert the placeholders of older templates, and send the open document to Template as a new version — and publish it — without saving a file and uploading it in the web interface.

How to get here	In Word: Home tab › Cogneris group › Templates (Modelos in Portuguese). The add-in must first be installed for you (see Install the add-in).
Who can use it	Anyone can open the pane and sign in. Every request it makes to Template (field list, template list, upload, publish) requires one of the roles customer-admin, customer-tech, cogneris-admin (or its older spelling cogneris-platform-admin) or cogneris-tech, in the tenant of the signed-in account. Without one, each tab shows an error that starts with 403.
Content status	From source; not observed (template-addin eee52f7, template-be cc0f2b0, 2026-10-22)

The add-in follows Word's language. When Word is displayed in Portuguese (any variant), the pane, the sign-in window and the ribbon button are in Brazilian Portuguese; in any other language they are in English. This chapter quotes the English text.

How it fits with the rest of Template

1. Create the template in Template first — the add-in cannot create one. See Templates.
2. Write the document in Word and insert fields from the Fields tab.
3. Send it from the Publish tab as a new version of that template, and publish it when it is ready.
4. Decide where each placeholder gets its value in the template's bindings. Inserting a field in Word does not create a binding. See Bindings.
5. A workflow renders the published version with the Generate document phase.

Install the add-in

The add-in has two separate parts, and both are needed:

Part	Where it lives	What it means for you
The pane (the application itself)	A Cogneris web service at a fixed HTTPS address, for example word-addin-dev.cogneris.ai for the development environment.	Word loads the pane from that address every time it is opened. Word keeps no copy: if the service cannot be reached, the pane does not open.
The manifest (manifest.xml)	Your own Microsoft 365 tenant.	It tells Word that the add-in exists and where to load it from. The service publishes it at https:// + its host + /manifest.xml.

Each environment (development, staging, production) has its own address and its own manifest, with its own add-in id, so two environments can be installed side by side. A non-production manifest can carry a label in the add-in name, for example Cogneris — Templates (dev) (Cogneris — Modelos (dev) in Portuguese). Ask Cogneris for the address of the environment you use.

For the whole organization (Microsoft 365 admin center)

This is the normal way for a company tenant. It does not go through Microsoft AppSource.

1. In the Microsoft 365 admin center, open Settings › Integrated apps › Upload custom apps.
2. Upload the manifest.xml file, or give its URL (https:// + add-in host + /manifest.xml).
3. Assign the add-in to the users or groups who author templates.

For a pilot (sideload)

Platform	How
Word for Windows	Put the manifest in a shared network folder. In Word, add that folder under File › Options › Trust Center › Trust Center Settings › Trusted Add-in Catalogs. Restart Word, then choose the add-in under Insert › My Add-ins › Shared Folder.
Word for Mac	Copy the manifest to ~/Library/Containers/com.microsoft.Word/Data/Documents/wef/.
Word on the web	Insert › Add-ins › Upload My Add-in › Browse, and choose the manifest file.

The Microsoft menu names above are Microsoft's and may vary with your Office version and language.

What the manifest declares

Item	Value	What it means
Name	Cogneris — Templates, Cogneris — Modelos in Portuguese (plus the environment label, if any)	The name in Word's add-in list.
Description	Insert process fields into Word templates and publish them to Cogneris.	Shown in the add-in list.
Office application	Word only.	The add-in does not load in Excel, PowerPoint or Outlook.
Minimum API versions	WordApi 1.3 and DialogApi 1.1.	Word refuses to install the add-in where these are missing. 1.3 is required because the conversion of old placeholders needs to know whether text is already inside a placeholder; on older Word it would wrap every placeholder twice.
Permission	ReadWriteDocument	The add-in reads and changes the content of the open document. It has no access to other documents or files.
Allowed domain	The Cogneris sign-in service of that environment.	Lets the sign-in window open the Cogneris sign-in page.
Ribbon button	Home tab, group Cogneris, button Templates (Modelos in Portuguese). Tooltip: Open the pane to insert process fields and publish this template.	Opens the task pane.
First-run hint	Cogneris — Templates: Open the Home tab and click Templates to begin.	Word shows it after installation.

Supported Word versions: Word desktop for Windows or Mac, and Word on the web — any Word that provides the API versions above.

Sign in

The pane does not use your Cogneris browser session: Word runs the pane in its own embedded browser (desktop) or in an isolated frame (web), where the Cogneris session cookie is not available. The add-in therefore signs you in through a separate Office window.

Fields and buttons

Element	What it does
Sign in to your Cogneris account to see the available fields and publish templates.	Shown until you are signed in.
Sign in	Opens a Word dialog window titled Cogneris — Sign in on the Cogneris sign-in page. While it is open the button reads Signing in… and cannot be clicked again.
Sign-in window	Shows Signing in…, moves to the Cogneris sign-in page where you sign in as usual, then shows Finishing… and closes itself. The pane then shows its three tabs.
Sign out	At the bottom of the signed-in pane. Forgets the add-in's access token and returns the pane to the sign-in screen.

What is kept. The add-in signs in with the same Cogneris client as the other Cogneris applications. It receives only an access token, which it keeps in memory: never in the browser's storage and never in the document, so the token does not travel with the .docx you send to someone. As a result, closing the pane signs you out, and you sign in again the next time you open it.

When the session ends. The add-in treats the token as expired one minute before its real expiry. The next action that calls Template opens the sign-in window again instead of failing.

Fields tab

The catalog of what a process can put into the document. Click a field to insert it as a placeholder where your text is selected.

Fields

Field	What it does	Required	Format / values	Default	Validation messages
Search fields…	Filters the list as you type. A field matches when its label or its key contains the text, ignoring case. A group that is not configured stays visible with its instructions.	No	Free text	Empty	No field matches the search.
Lock inserted fields against editing	When ticked, each field you insert from now on cannot be edited in Word: nobody can type inside it. It can still be deleted. Fields inserted before you ticked it are not changed.	No	Checkbox	Off	—
Field list	Grouped by origin, each group headed by its name. Each field shows its label, its key, and — when the value may be absent — Not always filled in — set a default value.	—	—	—	—

While the list loads, the pane shows Loading the data contract….

Groups and keys

The list comes from Template (GET /data-contract/fields). Template builds it for your tenant and keeps it for 5 minutes, so a classifier or form you just changed can take up to 5 minutes to appear. The group and field names and the instructions below are written by Template in Portuguese and are shown as sent, whatever Word's language.

Group	Comes from	Key format	Always filled?
One group per classifier, named after it	The fields that field discovery found for that classifier in Vision.	The classifier name in camel case, without accents and without short connecting words (de, da, do, e, para…), then a dot and the field path. Example: a classifier "Documento de Identidade — Beneficiário" with a field cpf gives documentoIdentidadeBeneficiario.cpf. The label is the last part of the path with a capital first letter.	Never — a document is only in a case if it was uploaded, and a field only if extraction read it.
One group per Portal form, named after it	The questions of the form's design. Fixed texts (titles, paragraphs) are left out.	The form name in camel case, a dot, and the question's name in the form designer — with accents removed and any character other than letters, digits, ., - and _ turned into _ (a question named Nome completo gives proposta.Nome_completo). The value still comes from the question itself. The label is the question's label.	Only for questions marked required.
Processo (Process)	Fixed.	process.identifier (Identificador do processo), process.requester.name (Nome do requerente), process.today (Data de hoje).	Only process.today.
Batimento (Cross-check)	Fixed.	crosscheck.decision (Decisão do batimento), crosscheck.summary.mismatch (Nº de divergências), crosscheck.summary.total (Nº de verificações). A placeholder bound earlier to crosscheck.findingsCount is read as crosscheck.summary.mismatch.	No.

A group with nothing to offer is still shown, with an instruction instead of fields:

Instruction shown (from Template)	Meaning
Ainda não há classificadores neste tenant. Crie um em Classificadores, carregue um exemplar do documento e execute a definição de campos — os campos aparecem aqui logo a seguir.	Your tenant has no classifiers yet. Create one in Vision, upload a sample and run field discovery.
O classificador "…" ainda não tem campos definidos. Abra-o em Classificadores, carregue um exemplar e execute a definição de campos.	That classifier has no discovered fields.
Não foi possível contactar o serviço de classificadores. Tente novamente; se persistir, os campos de documento não podem ser listados agora.	Template could not reach Vision. Document fields cannot be listed now.
Este tenant ainda não tem formulários. Crie um no Portal e desenhe os campos — aparecem aqui logo a seguir.	Your tenant has no Portal forms.
O formulário "…" ainda não tem campos de resposta — só textos fixos. Abra-o no Portal e acrescente perguntas.	That form has only fixed texts.
Não foi possível contactar o serviço de formulários. Tente novamente; se persistir, os campos do formulário não podem ser listados agora.	Template could not reach Portal.

Template reads classifiers and forms with your own sign-in, so you only see what you could see in Vision and Portal yourself. If one form's design cannot be read, that form is left out of the list without a message.

What inserting a field does to the document

A placeholder is two things at once:

a Word content control tagged   cogneris:<key>
whose visible text is           {{<key>}}

When you click a field:

1. Your selection is replaced by the key between double braces, for example {{process.today}}.
2. That text is wrapped in a Word content control (shown with a bounding box) whose tag is cogneris: followed by the key and whose title is the field's label.
3. The control can be deleted. It can be edited only if Lock inserted fields against editing was off.

Why both: the visible text is what Template detects and replaces when it renders, so the document works exactly like a template written by hand. The content control keeps the placeholder in one piece — Word cannot split it while someone edits the paragraph, and it cannot be half-deleted, which is what happens to typed text.

The add-in only accepts keys made of letters, digits, ., - and _ — the same rule Template uses to detect placeholders. A key outside that rule would look correct in Word and then be missing from the keys Template detects.

Inserting a field does not decide where its value comes from. After you send the version, set its bindings in Template: see Bindings. For a field marked Nem sempre preenchido, set what happens when the value is missing there.

Buttons and actions

Button	What happens	Who	Reversible?
A field in the list	Replaces the selected text with the placeholder, as described above.	Signed-in user	Yes — Word's undo, or Remove in the Document tab.

Document tab

What is in the open document right now, and the conversion of placeholders typed as plain text. The tab reads the document when you open it.

Fields

Element	What it shows
Markers to convert (…)	Only when the document has placeholders typed as plain text — in the body, in the headers and footers of any section (first page, even pages and the others), and in footnotes and endnotes where Word supports WordApi 1.5. Placeholders with spaces inside the braces ({{ nome }}) are included. The number is how many different keys. Below it: These {{campo}} are loose text. Once converted they stop breaking when someone edits the document — the visible text does not change, so the generated PDF stays exactly the same. Then one line per key: the key between double braces, ×, and how many times it appears.
Fields in the document (…)	The number of Cogneris placeholders (content controls whose tag starts with cogneris:). Content controls of other origins are ignored. With none: No fields yet. Use the Fields tab to insert the first one.
One row per placeholder	Its key, followed by · locked when it cannot be edited. When its visible text is no longer exactly the key between double braces (someone typed inside it), the row warns: Text changed (…) — it will not be replaced.

Buttons and actions

Button	What happens	Who	Reversible?
Refresh	Reads the document again. While reading it shows Reading the document… and the other buttons wait.	Signed-in user	—
Lock converted fields against editing	The same option as Lock inserted fields against editing in Fields — ticking one ticks the other. When ticked, Convert all locks every placeholder it creates.	—	—
Convert all	Wraps every plain-text placeholder found (body, headers, footers and, where supported, notes) in a Cogneris content control (tag cogneris: + key, title = key, bounding box, can be deleted, locked only when the lock option is ticked), then reads the document again. A placeholder already written as the key between double braces keeps its visible text. One with spaces inside the braces is rewritten without them ({{ nome }} → {{nome}}), because Template's renderer fills only the exact form. Running it twice does nothing the second time: text already inside a Cogneris placeholder is skipped.	Signed-in user	Yes — Word's undo, or Remove on each placeholder.
Locate	Scrolls the document to that placeholder and selects it.	Signed-in user	—
Remove	Asks for confirmation on the row itself: the button becomes Confirm removal, next to Cancel. Confirming removes the content control but keeps its text, so the key between double braces stays in the document as plain text (and appears again under Markers to convert). Delete the text yourself if you no longer want the placeholder. On a locked placeholder the button is disabled: unlock it first in the content control's properties in Word.	Signed-in user	Yes — Word's undo, or Convert all.

Converting an older template

Every template written before the add-in has its placeholders as plain text. To convert one:

1. Open the template's .docx in Word. Template's web interface and service do not offer a download of an uploaded version (template-be cc0f2b0), so use your own copy of the file that was uploaded.
2. Open Document and click Convert all.
3. Send it as a new version from the Publish tab.

A placeholder already written as the key between double braces keeps its visible text, so the rendered PDF stays the same; only the structure of the document improves. A placeholder with spaces inside the braces is rewritten without them, so that Template's renderer fills it.

What conversion does not find: on a Word without WordApi 1.5, placeholders in footnotes and endnotes are not scanned, although Template detects them.

Publish tab

Sends the open document to Template as a new draft version of an existing template, then — as a second, separate click — publishes it.

Fields

Field	What it does	Required	Format / values	Default	Validation messages
Target template	The template that receives the new version. Lists the templates of your tenant by name, most recently changed first, without archived ones. The list is limited to the 20 most recently changed templates and has no search: to send to an older template, change it in Template first so it moves up, or upload in the web interface.	Yes	List; first entry Choose…, not selectable	Choose…	The send button stays disabled until a template is chosen.
Notes for this version	Free text stored with the version. Hint: What changed.	No	Free text	Empty	—

Buttons and actions

Button	What happens	Who	Reversible?
Upload as a new version	Reads the open document from Word as a .docx (in slices of up to 4 MB) and sends it to Template (POST /templates/…/versions). The file name is the document's own name, or documento.docx when Word gives none. While sending it reads Uploading…. Template checks the file, stores it, creates a draft version with the next number and detects its placeholder keys in the body, headers, footers, footnotes and endnotes. If the content is identical to an earlier version of the same template, the stored file is reused but a new version is still created. The upload is recorded in the audit log. Then the pane shows Version … created with the version number, one line per detected key, and the Publish this version button. A key that matches no field of the data contract is marked No source in the data contract. When the document is identical to a version already sent: This document is identical to a version already uploaded. With no keys: No fields found in the document.	Roles listed in the table at the top	A draft is not used by renders. Template has no way to delete a version from this pane.
Publish this version	Appears only after a successful send, for the version just sent. Publishes it (POST /templates/…/versions/…/publish): the version is marked published, with the date and your e-mail, and becomes the template's published version — from now on every render of this template in the whole tenant, including the Generate document phase of every workflow, uses it. The publication is recorded in the audit log. Then the pane shows Published. This is the version the render now serves.	Roles listed in the table at the top	Yes — publish another version (see Templates).

Publishing is deliberately a separate click: it changes a production document for the whole tenant, and must never be the side effect of an upload. To publish later, send now and publish from Template's web interface.

What Template checks on upload

Check	Message (from Template)
A file is present and not empty.	file is required, file is empty
Size at most 50 MB.	file exceeds the maximum allowed size of 50 MB
.docx only, and a real Word document.	only .docx files are allowed
The archive is not abnormally large or compressed (protection against "zip bombs").	Decided by the service.
The template exists in your tenant.	template not found
For publish: the version belongs to the template.	version not found for this template

Several messages from Template are shown together, separated by ;.

Common problems

Message	Cause	What to do
Word shows its own "add-in could not start" error, or the pane stays blank.	Word could not load the pane from the Cogneris add-in service (service unreachable, or blocked by your network). Word keeps no copy of it.	Check that Word can reach the add-in host. If it persists, contact Cogneris support.
This pane only works inside Microsoft Word.	The pane was opened outside Word (for example in a browser or another Office application).	Open it from Word: Home › Cogneris › Templates.
The sign-in window opens, goes white and closes, with no message.	The environment's manifest does not allow the Cogneris sign-in domain.	Contact Cogneris support; this is fixed in the manifest, not in Word.
Could not open the sign-in window., or a message from Office.	Word refused to open the sign-in dialog.	Try again; check that Word does not block pop-up dialogs for add-ins.
The sign-in window was closed before finishing.	The sign-in window was closed before signing in finished.	Click Sign in again and complete the sign-in.
Sign-in cancelled. or a message from the sign-in service	Sign-in was refused or cancelled; the sign-in service's own description is shown when it gives one.	Sign in again with a valid Cogneris account.
The sign-in session expired. Try again.	The sign-in window lost its state during the round trip.	Click Sign in again.
Invalid sign-in response (state).	The answer from the sign-in service did not match the request.	Click Sign in again. If it repeats, contact Cogneris support.
Unexpected response from the sign-in window.	The sign-in window returned something the pane cannot read.	Try again; contact Cogneris support if it repeats.
A message starting with The sign-in service answered	The sign-in service refused to issue the token.	Try again; contact Cogneris support with the message.
Could not load /config.json (…). Check CONFIG_JSON on Cloud Run. or config.json does not define ssoAuthority — sign-in cannot start.	The add-in service of that environment is misconfigured.	Contact Cogneris support.
A message starting with 403 on any tab	Your account has none of the roles Template requires (see the table at the top), or the add-in is installed for an environment where your account is not a member.	Ask your tenant administrator for the customer-admin or customer-tech role.
No response from the server. Check your connection.	Template did not answer, or the request took more than 60 seconds.	Check the connection and try again. A large document on a slow connection may take long to send.
Empty response from the server. or The server returned an error.	Template answered without content, or with an error it did not describe.	Try again; contact Cogneris support if it repeats.
A group of Fields shows an instruction instead of fields.	That source is not configured, or could not be reached.	Follow the instruction (see Groups and keys).
"…" is not a valid field key. Use unaccented letters, digits, dot, hyphen or underscore.	The key has characters Template cannot detect. Keys offered in Fields are already valid: Template turns spaces and accents in form question names into _ and plain letters.	Use letters, digits, ., - or _.
The field "…" is locked. Unlock it in the Word content control properties before removing it.	You tried to remove a locked placeholder.	Unlock it in the content control's properties in Word, then Remove.
Text changed (…) — it will not be replaced	Someone typed inside the placeholder, so its visible text is no longer the key between double braces. Template will neither detect nor fill it.	Click Remove, delete the text, and insert the field again from Fields. Tick Lock inserted fields against editing to prevent it.
Word did not hand over the document. or a message starting with Could not read block	Word could not give the add-in a copy of the open document.	Save the document, close and reopen the pane, and send again.
file exceeds the maximum allowed size of 50 MB	The document is larger than Template accepts.	Reduce the document (for example compress images) and send again.
The template is missing from Target template.	It is archived, or it is not among the 100 most recently changed templates.	Upload in the web interface. See Templates.
A rendered document has a blank where a field should be.	The field has no binding, or its value was missing in the case.	Set the binding and what happens when the value is missing: see Bindings.

Known limitations in this version

• No source in the data contract compares each key with the data contract only. A key you bound by hand on Bindings is still marked if no contract field has that key.
• Only English and Brazilian Portuguese: Word in any other language shows the English text.

Related

• Templates — create templates, see their versions and publish from the web interface.
• Bindings — where each placeholder gets its value, and what happens when it is missing.
• Generate document — the Workflow phase that renders the published version.

---

Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation