Escape Special Characters and Line Breaks for Template-driven Text Documents

DREL Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms., Handlebars, and FreeMarker documents reference data in submitted forms, including question answers and metadata. Special characters or line breaks in the data could cause the system to generate a document that’s not valid. To ensure the system generates valid documents in the specified format, you must escape the data. This is especially important when you use these documents to integrate with a third-party system.

This topic describes how to escape data for DREL, Handlebars, and FreeMarker Template-driven Text Documents in JSON, XML, HTML, and CSV formats.

Available on the Advanced and Enterprise tiers:

Contents

• Escape Special Characters and Line Breaks for Template-driven Text Documents
  • DREL
  • Handlebars
  • FreeMarker

DREL

Escape data for a single DREL expression

To escape the data referenced by a DREL expression, include a property with the following syntax:

[#escapeDocumentFormat]

where DocumentFormat is either Json, Xml, Html, Csv, or Url.

When the DREL expressions reference data with special characters or line breaks, the system escapes them in the specified format.

The following table includes examples of how to escape different types of DREL expressions in different document formats.

Format	DREL expression	Example
JSON	%a[CustomerFeedback][#escapeJson]	Input Excellent service. Thanks for the speed and attention to detail. Result Excellent service.\nThanks for the speed and attention to detail.
XML	%a[CustomerName][#escapeXml]	Input Gatwell & Bowman Result Gatwell & Bowman
HTML	%q[InspectLabel][#escapeHtml]	Input Locate the section "Equipment Information" on the label and take a picture. Result Locate the section "Equipment Information" on the label and take a picture.
CSV	%g[address][#escapeCsv]	Input 95 Walnut Street, Ottawa, ON K1A 2B3, Canada Result "95 Walnut Street, Ottawa, ON K1A 2B3, Canada"
URL	%u[name][#escapeUrl]	Input Harold Petrov Result Harold%20Petrov Tip:You can URL encode data from DREL expressions that you want to use as part of a URL. For example, the endpoint for a Salesforce Apex REST The Salesforce Apex REST is a type of Salesforce Data Destination that enables TrueContext to interact with Salesforce by means of an Apex REST API endpoint. If using an Apex REST API endpoint, developers can write APEX code to send custom messages that pull specific data from submitted forms. Data Destination A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats., or the URL Suffix in an HTTP Data Destination.

Escape data globally in a DREL document

To escape the data referenced by all DREL expressions in a document, include an expression with the following syntax:

#c[escapeDocumentFormat]

where DocumentFormat is either Json, Xml, Html, or Csv.

The system automatically escapes all DREL expressions included after this expression.

To override the global escape, include the following property as part of a DREL expression:

[#escapeNone]

In the following example:

• The expression #c[escapeJson] sets the output format to JSON. The system escapes the data referenced by all following DREL expressions to generate valid JSON output.

• Because the document is escaped globally, the system automatically escapes the data referenced by the DREL expression %a[Message].

• The system overrides the global escaping for the expression %a[recordID][#escapeNone].

#c[escapeJson]
{
    "body": {
        "messageSegments": [{
            "type": "Text",
            "text": "%a[Message] - Posted from TrueContext"
        }]
    },
    "feedElementType": "FeedItem",
    "subjectId": "%a[recordID][#escapeNone]"
}

Handlebars

To escape the data referenced by a Handlebars expression, include one of the following expressions:

• {{pf:outputFormat “DOCUMENTFORMAT”}}

• {{#pf:outputFormat “DOCUMENTFORMAT”}}...{{/pf:outputFormat}}

The following table includes examples of how to escape different types of Handlebars expressions in different document formats.

Format	Handlebars expression	Example
JSON	{{pf:outputFormat “JSON”}} {{answers.CustomerFeedback.[0]}}	Input Excellent service. Thanks for the speed and attention to detail. Result Excellent service.\nThanks for the speed and attention to detail.
CSV	{{#pf:outputFormat “DOCUMENTFORMAT”}} {{dataRecord.geoStamp.address}} {{/pf:outputFormat}}	Input 95 Walnut Street, Ottawa, ON K1A 2B3, Canada Result "95 Walnut Street, Ottawa, ON K1A 2B3, Canada"

Note:Handlebars automatically escapes values for HTML and XML. If you don’t want to escape output for HTML or XML, use the expression {{pf:outputFormat "NONE"}}.

FreeMarker

To escape data for a FreeMarker document, include the output format in the ftl header. The following example shows how to escape the output for a JSON document:

<#ftl output_format=”JSON”>

TrueContext supports escaping data with FreeMarker in the following formats:

• JSON

• XML

• HTML

• CSV