The platform includes an ingenious system for helping you to draw all of the components together and ensure that they fit together properly.
When automating sophisticated documents or complex decision-making processes, there are a lot of moving parts. The platform will automatically flag any issues that arise as between the online components (see here for more details). The error checking process explained in this guide helps to bridge the gap between the online components and the template document, which is offline.
Components of the system
To understand the power of the error checking process, it's important to keep in mind all of the "moving parts" - ie, the different possible components of the system:
calculations within fields
Document template (built offline)
Online components relating to the template
- Named Ranges (ie, logical rules on the ranges of conditional content)
- Replacement Rules + logic on Replacement Rules
With all of these moving parts, especially for large projects, it would be impossible for an ordinary human being to manually check that they all fit together properly. That is why we invented an ingenious error-checking system to do this for you.
How to run the error checker
At present, in order to run the error checker, you need to have first uploaded a document template. If you are building a smart form for a purpose other than document automation, you can simply upload a blank MS Word file and the error checker will still work for you.
To run the error checker, navigate to the "Error checking" tab in the builder and hit the "Verify" button, as shown below:
What the error checker reports
Bridging the gap between the online components and the template
The primary purpose of the error checker is to detect mismatches between the online components and the template. These can arise if:
- A content control within the template is given a name for which you haven't yet created a Named Range in the builder.
- The reverse of the above - ie, you have created a Named Range in the builder but it hasn't yet been applied to any ranges of conditional content in the template.
- There is a naming mismatch in the Named Ranges, either because you:
- made a typo when entering a name
- changed the name in one place without updating it in the other
- deleted a name in one place without deleting it in the other
Same as the above but for merge fields - ie:
- A merge field in the template refers to a field that you haven't yet created.
- A field that is intended to be used as a merge field hasn't yet been inserted as a merge field in the template.
- There is a naming mismatch in the merge fields, either because you:
- made a typo when entering the field label
- changed the field label in one place without updating it in the other
- deleted the field but didn't delete its corresponding merge field markers in the template
- deleted the merge field markers in the template but didn't delete the corresponding field in the form
Inconsistencies in the online components
In addition to bridging the gap between the online components and the document template, the error checking process also helps to ensure that all of the online components fit together properly. It is possible for mismatches to arise as between online components where a field, or an option within a field, is deleted after a logical rule or calculation has been built referring to that field/option.
Contents of the report
The error checker tests for and reports the following:
- Unused Fields in the Form – In an automated system, it is rare for the form to contain a field that isn't used in any other components (fields can be used in logical rules, calculations, replacement rules and merge fields). Fields that aren't being used anywhere else are identified and report to you.
- Fields in the form that are only used in other fields – Although, in more complex products, it is quite common for fields to only be used within other fields (ie, in logic or calculations), such fields are identified and reported to you in case there is supposed to be a link between those fields and the document that you have accidentally overlooked. You can ignore these (see below) if they are not in fact errors.
- Fields in the form that are only used in replacement rules – In document automation, most fields are used either in the logic of Named Ranges or as merge fields. If a field is only used in a replacement rule (ie, either in the logic of the replacement rule or for field replacement), it will be identified and reported to you as well. Again, you can ignore these (see below) if they are intended.
- Content Controls in the template without corresponding Named Ranges – If you have applied a name to a range of conditional content in the template but haven't yet created a logical rule for that Named Range in the builder, the error checker will report that for you. Mismatches can also arise from typos and when names are deleted/changed in one location but not the other.
- Named Ranges without corresponding Content Controls in the template – The reverse of the point above - ie, Named Ranges that have been defined in the builder but haven't been applied to any ranges of conditional content in the template.
- Comments in the template with no corresponding field in the form – Merge field markers in the document template that refer to a field in the form that doesn't exist.
- Named Ranges & Replacement Rules referring to invalid fields/options - This can arise when a field or option is deleted after it has been used in a Named Range or Replacement Rule. In addition to being reported in the error checker, these are also flagged for you within the Named Ranges and Replacement Rules tabs (see below).
As explained above, some of what is reported are items of a type that have a high risk of being an error but, in the context of your particular product, may not in fact be errors. Where items are reported that aren't in fact errors, you can remove them from the error report by "ignoring" them. To ignore an item, simply click the red circle icon to the right of the item as shown below:
By default, ignored items are not displayed, but you can turn the "Hide ignore fields" toggle off if you wish to see them, as shown in the screen recording above. If you have ignored an item by mistake, simply click the undo arrow to the right of the ignored item to restore it to the error report.
Error checking in the Named Ranges and Replacement Rules tabs
If you create a Named Range or Replacement Rule that refers to a field or option that you subsequently delete, naturally, that will break the Named Range or Replacement Rule. Helpfully, these are not only reported in the "Error checking" tab as mentioned above, but broken Named Range and Replacement Rules are also flagged for you in their own tabs.
When navigating to the Named Ranges or Replacement Rules tabs, start by clicking the "VALIDATE" button at the top of the table to refresh the list. If there are any broken items, you will see a notice appear in the bottom-right corner of your screen as shown in the screen recording below, and broken items are flagged in red within the table.
Additional error checking within MS Word
In addition to the error checking discussed above, you can also use the Word plugin to detect errors within the MS Word template.