Who is this article for?

Administrators looking to improve their report generation.

Middleware access is required.

PDF Character Substitution in Middleware ensures smoother report generation by automatically replacing invalid or unsupported characters in user-entered data. This prevents problems during PDF creation and improves the overall user experience.

This article outlines the potential problems with PDF report generation and how the functionality can help you resolve it.

1. Character limitations

When generating PDF reports, certain characters entered by users especially from non-standard keyboards, copy-pasted content, or special symbols can be incompatible with the PDF rendering engine:

• Entered text includes an unsupported character (Ѯ, β, ζ) in a text field. These could be non-English characters, special symbols, or Unicode characters not supported by the standard PDF font set.
• Entered text includes emojis such as 👍 or 😊.
• Entered text is a bullet point list in Microsoft Word, copy and pasted into Smartforms Client.

These characters, while valid in HTML or plain text, may cause rendering failures or exceptions when the Middleware attempts to populate the corresponding fields in a PDF report.

Before, Middleware handled a limited set of known problematic characters by silently substituting them with equivalent characters. For example, smart quotes generated by Microsoft Word were replaced with standard quotes.

However, many characters outside this predefined list would previously trigger a Middleware exception during session processing. This resulted in:

• Session submission failures
• Email notifications sent to administrators
• Sessions needing to be reassigned to the user, updated to use only supported characters, and resubmitted

To resolve this, we introduced the PDF Character Substitution functionality.

2. Character substitution

A new Middleware screen introduces a user-friendly interface to define substitution rules for invalid characters. 

This allows administrators to:

• Specify which replacement character should be used when an unsupported character is encountered.
• Apply these rules globally to all PDF-generating sessions.

To substitute characters:

1. Sign in to your Smartforms Middleware account.
2. Open the Admin menu.
3. Select PDF Report Generation.

4. Tick Replace invalid characters in PDF report.
5. Define Replacement character.
   This will allow you to define a single replacement character, by default set to a question mark (?).
   
   
6. Click Save.

The replacement character will be substituted for every invalid character when generating the PDF during form session processing. If not selected, no character substitution will be performed and any invalid characters in the form may cause exceptions to be thrown during session processing.
 

This feature modifies user‑entered data only in the PDF report. The original data remains unchanged in the session data file. Any additional data exports configured for the form including SQL database exports will also remain unchanged.

3. Impacted reports

This setting affects two distinct types of PDF reports: Designer-Defined Reports and Auto-Generated PDFs.

Designer-Defined Reports are:

• Created in Smartforms Designer under the Reports tab.
• Automatically saved to Smartforms Docs when the session is submitted.
• The report may also be attached to a mail notification by configuring in the Results tab.

Auto-Generated PDFs are:

• Enabled via the Results tab in the Designer by checking the Auto-generated PDF File checkbox.
• Automatically saved to Smartforms Docs when the session is submitted.
• The report may also be attached to a mail notification by configuring in the Results tab.

This setting will not affect the following:

• Client side - If a Designer-defined Report is generated in client script using _form.generateReportHTML(), the character substitution will not be applied. These reports use a different mechanism to generate the PDF and are not subject to the same character limitations.
• Server side - If a Designer-defined Report is generated in server script using myReportGenerator.GenerateReport(), the character substitution will not be applied by default.

Example

For Each rep as Report in _form.Reports
 If (rep.Name = "My Report") Then
   Dim rg as new MiCo.MiForms.DataPaths.Reports.ReportGenerator()
   myReportGenerator.GenerateReport(report)
 End If
Next

Character substitution is performed only when the corresponding parameters are explicitly provided.

For Each rep as Report in _form.Reports
  If (rep.Name = "My Report") Then
    Dim rg as new MiCo.MiForms.DataPaths.Reports.ReportGenerator()
    myReportGenerator.GenerateReport(report, "?", True)
  End If
Next