Other
      Back to home
      1. Knowledge Base
      2. Troubleshooting
      3. Other

      Troubleshooting Smart Document Issues

      When creating Smart Documents, users may run into errors or issues.  This article is here to help explain how these issues can be addressed.  This article is also something that will be continually updated in the future as needed.

      Unsupported Characters

      Certain characters, like the < and > characters, can break the rendering of a smart document when those characters are passed into a smart document using a variable.  To address this, these characters can be removed from the variable.  Or, there's a method in the utils class that can remove the unsupported characters.

       

      For example, if a record has a vendorSKU of "BASIC-ITEM<1>", we can use utils.cleanText to strip away the unsupported characters.

       
      ${utils.cleanText($record.vendorSKU)}

      Using the && Operator in Smart Documents

      If you're having issues using the && operator in Smart Document templates, try putting them inside an HTML comment, like so:

       
      <!-- #if($var1 && $var2) --> <div>test<div/><!-- #end -->

      Custom Fields not showing up in Smart Documents

      To display custom fields in smart documents, the format is ${record.customFields.yourFieldName} where yourFieldName is the field name of the custom field.  For example, if we had 3 custom fields we wanted to show in a smart document, and we only want to display the third field if it isn't null, this code could be used:

       
      Project Number: ${record.customFields.projectNumber}
      Contract Date: ${record.customFields.contractDate}
      Contract Type: #if(${record.customFields.contractType}) ${record.customFields.contractType} #else -- #end

      Velocity Syntax Errors

      The code field of Smart Documents is rendered into HTML (and then PDF) using the Velocity Templating Language, which gives you access to basic programming structures, such as variables, logic, and loops.

      Velocity syntax errors, such as such as an un-matched #if #end or a variable without a closing curly bracket will result in errors that would prevent a smart document from rendering.  For example, when attempting to preview a smart doc that contains an #if but no matching #end, the following error is received.

       

      Removing the #if or adding a matching #end allows the document to render without errors.


      For syntax issues due to missing curly brackets:

      Bad syntax: ${record.customFields.projectNumber

      Good syntax: ${record.customFields.projectNumber}

       

      For more information see the velocity user guide.