When automating documents, it’s easy to introduce small mistakes that can lead to unexpected behaviour in the final output. This article highlights common templating errors and best-practice workarounds to help you create reliable, consistent, and easy-to-maintain templates in Avvoka.
Preparing the Document
Before adding any automation, it’s important to review and clean up the document itself. Many issues originate in the source document before it’s even uploaded to Avvoka:
Numbering
Avvoka detects all genuine numbering in uploaded documents, but some documents may contain “fake numbering.” These are numbers typed as normal text (e.g., “Section 1”) rather than true numbered items stored in the document’s metadata.
Correct numbering is important because it affects automation features such as Block Conditions, which automatically adjust numbering, and cross-referencing. Fake numbering will not update within Block Conditions and cannot be used as a cross-reference in either Microsoft Word or the Avvoka Editor.
How to identify fake numbering
In Microsoft Word, click on the number:
If Word highlights the entire numbering sequence, it’s genuine numbering
If it doesn’t, it’s likely fake numbering
In smaller documents, you can also use Avvoka’s cross-referencing feature to help identify numbering issues
Styling consistency
When focusing on automation, it’s easy to overlook inconsistent paragraph or heading styles.
Before uploading the document:
Review each paragraph’s style in Microsoft Word
Check font type, size, and spacing to ensure they match throughout the document
Use the Styles panel in the toolbar to confirm consistent formatting:
Automating the Document
After preparation of the document, the best way to automate the document, is to simply start automating! This doesn't go without error, and the following are some of the highest occurring errors during the automation process:
Attribute-Naming
Large templates often contain many placeholders, making it easy to lose track of attribute names. Using a clear and consistent naming convention helps, the format used can based on the preference of the user.
Naming Convention | Example |
Capitalized | Sample Placeholder |
Pascal Case | SamplePlaceholder |
Camel Case | samplePlacholder |
Snake Case | sample_placeholder |
Kebab Case | sample-placeholder |
When creating attribute names, take extra care to avoid adding leading or trailing spaces before or after the placeholder text, as these can cause automation to fail. You should also avoid using special characters (such as \,/) in attribute names, as they may result in unexpected behaviour.
Tip: Check for leftover square brackets It’s common to forget to remove square brackets from placeholders or conditions. To find any remaining brackets, click outside the document, press Ctrl + F, and search for [ and ].
Headers and footers
Headers and footers may sometimes contain fields that also require automation. To identify these, download the automated template and review the header and footer sections. If automation is needed, add square brackets around the attribute name, ensuring the capitalisation exactly matches the existing attribute in Avvoka.
Note: in the document body, automated text is shown with coloured brackets to indicate the type of automation applied. In headers and footers, however, these brackets will not appear in colour.
Roles and permissions
Access to templates in Avvoka is governed by user roles. Review the roles and permissions assigned under each template to ensure users have the appropriate rights to view or edit templates and documents as needed.
Questionnaire Setup
A well structured questionnaire improves templating and end-user experience.
Questions
Use clear, simple wording
Add hints or informational text for complex questions
Choose the correct question type (Text, Number, Email, Select, Date, etc.) to improve answer accuracy
Visibility conditions
Visibility conditions are also vital to an accurate and structured questionnaire. If a placeholder appears inside a block/inline condition, the linked question should usually have a corresponding visibility condition. Without a visibility condition, the question will always appear, which can confuse users when answers don’t visibly change the document.
Sections
Sections help organise questions and improve readability. Sections basically cut up the questions into separate pages based on how it's setup.
Best practices for sections:
Group related questions together
Name sections clearly based on their purpose
Example: In a loan agreement, questions may be grouped into sections such as: Borrower, Lender and Third party
If there are only limited questions in a template, sections may not be necessary.
Mantra to remember: Use, don’t abuse Sections!
Date formats
Use a consistent date format including locale across the template as per the requirements of that document. Read more about date formats here.
Test Regularly
Errors are easier to fix when caught early. Best practices to have an error-free experience:
Test each automation component as you build it
Use Live Demo to validate behaviour during drafting
Generate documents to test complete flow and output on download
Diagnostics
The Diagnostics tool is also helpful here and can be used to identify technical issues such as misnamed attributes, broken references, inconsistent conditions and other hidden automation errors. Run Diagnostics regularly, especially after a session of automation.
Save regularly! Unexpected issues such as network interruptions or system updates can result in lost work. Make a habit of saving your template frequently and avoid relying solely on autosave to preserve your changes.
Other Common Errors & Tips
Headers and footers may sometimes contain attributes that should be automated. To check, the user can download the template with automation and check the headers or footers for any attributes. The process of downloading the document to check automation is called round-tripping. The user can then add square brackets then the name of the attribute (with the exact capitalisation). Note: Avvoka automations have colored brackets indicating what type of automation is on the text, on headers and footers however, there is no color.
Users will typically have a role assigned to them determining how they can access the template. Regularly check the roles assigned to the user, so when they need to access the template, they have the proper permissions depending on what they need.
Date formats are generally based on where the user's organisation is from. A good practice would be to check the location of the organisation and all Date question types are adjusted for that location. There will be instances of a static date mentioned in the document, from here all date-type questions should be adjusted to that format.
Upon finishing the automation, generate a document and always compare it to the original document to check the output. Generally, it should be exactly the same in almost all aspects (Styles, Font, etc.).
By understanding the best practices, every user can create a template fit for the needs and wants of the organisation. Working around the common errors, ensure that the template has a smooth flow and give a marking experience for any user.
Final review
After completing automation:
Generate a document. Read more about generating documents here.
Compare it against the original version
Download the output and confirm styles, fonts, and layout match
The output should be identical to the original document, except for the intended automated variations.
By following these best practices and avoiding common errors, you can create robust templates that are easy to maintain and deliver a smooth experience for all users.