Text Doc From Template Smart Service

About Text Doc from Template

The Text Doc from Template smart service creates or updates a document using process data and a text-based template file.

The Text Doc from Template smart service supports the following file extensions:

• CSV
• JSON
• RTF
• TXT
• XLSX
• XML

Template files must be encoded in UTF-8 if Unicode characters appear in the document. The file extension of the template is not restricted by the system.

Requirements for Text Doc from Template

To use the Text Doc from Template smart service, the following requirements must be met:

• Template location: The template document must exist within Appian's document management.
• Permissions: The smart service initiator must have Author rights to the template document, the destination folder, and any document being replaced.

Text Doc from Template node

To configure the Text Doc from Template node, use the Setup tab and the Data tab. See Process Node and Smart Service Properties for common node configurations.

Node properties

The Text Doc from Template node has the following properties:

• Category: Document Generation
• Icon:

• Assignment Options: Unattended.

• Compatible with autoscale: Yes *

Configure the Setup tab

The Setup tab is the primary location for configuring the Text Doc from Template node. Use this tab to specify the template document, configure substitution key mappings, and set the output destination.

To configure the Text Doc from Template setup tab:

1. In the Template field, type the name of the template document, or click the Directory button to browse for the document.
2. (Optional) If you need to select a template dynamically, enter an expression in the Runtime Template field that specifies a document using a process variable or a constant. You can create constants that contain each desired template. The substitution keys in the runtime template do not have to match the base template exactly, but any keys used in the runtime template must be present in the base template.
3. Select a Destination option: create a new document or overwrite an existing document.
4. Configure the substitution key mappings in the substitution grid.

Once the template document is selected, the substitution grid is populated with the keys found within the template file.

Destination options for Text Doc from Template

If you selected Create a new document, complete the following fields:

If you selected Overwrite an existing document, specify the document to be replaced in the Document to replace field.

Substitution key mappings for Text Doc from Template

All substitution keys found in the template file appear in the Find in template document column in the substitution grid. Under the Replace with column, enter the text to substitute for each key. You can also use the Expression Editor to generate an expression. If the field is left blank, the smart service replaces the key with a blank value.

The substitution grid provides the following toolbar options:

• Sort alphabetically: Click A-Z to sort the list alphabetically.
• Sort reverse alphabetically: Click Z-A to sort the list in reverse alphabetical order.
• Original order: Click Original Order to revert to the order the keys appeared in the template.
• Rescan template: Click Re-scan Template to refresh the list of substitution keys after making changes to the template document. When the template path is changed, the smart service re-parses the specified document for substitution keys. Pre-existing keys are retained in the grid with their corresponding mappings.

Configure the Data tab

The Data tab for the Text Doc from Template node allows you to map the document output to a process variable for use elsewhere in the process model.

Configure node outputs

To configure the Outputs for the Text Doc from Template node:

1. In your process model, open the Text Doc from Template node.
2. Go to Data > Outputs.
3. Select New Document Created on the Results list. The result properties display.
4. Create a new process variable to store the result, or select an existing process variable with a Document data type from the available list.

Text Doc from Template node examples

The following examples illustrate how to create process models using the Text Doc from Template node. The data used in these instructions is for example purposes only. Replace any example data with the data available in your application.

Generate a plain-text order summary notification

Goal: Populate a plain-text template with order details for an email notification or printed receipt.

Sample template

Name: order_summary_template.txt

Content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Order Confirmation
==================

Order Number: ###OrderNumber###
Date: ###OrderDate###

Customer: ###CustomerName###
Email: ###CustomerEmail###

Items Ordered:
###ItemsList###

Subtotal: ###Subtotal###
Tax: ###Tax###
Total: ###Total###

###ShippingNote###

Thank you for your order.

Process variable mappings

The following table shows how to map each substitution key to a process variable or expression in the smart service configuration:

The joinarray() function concatenates the array of order line item strings with char(13) & char(10), which inserts a carriage return and line feed between each item. Each item in pv!orderLineItems must already be formatted as a readable string (for example, "2x Widget A - $19.98") before mapping.

Generate a CSV row for a customer data export

Goal: Populate a CSV template to append structured customer records to an export file, using char() to handle special characters that might appear in free-text fields.

CSV template

Name: customer_export_template.csv

Content:

1
###CustomerId###,###FullName###,###Email###,###Phone###,###AccountType###,###SignupDate###,###Notes###

Process variable mappings

The following table shows how to map each substitution key to a process variable or expression in the smart service configuration:

The char(34) function inserts a double-quote character to wrap fields that may contain commas or special characters. The Notes mapping uses substitute() to escape any double quotes within the notes text by doubling them ("")—the standard CSV escaping convention. This approach prevents free-text fields from breaking the CSV structure.

Using the Text Doc from Template smart service

The following considerations and behavior apply when you use the Text Doc from Template node in a process model.

Variable mapping behavior for Text Doc from Template

The Text Doc from Template smart service handles single-value and multiple-value process variables differently when mapping to template substitution keys:

• Single-value variables: Single-value variables provide better results when mapped to fields in the template.
• Multiple-value variables: When a multiple-value variable is mapped to a field in the template, the items are listed in a semicolon-separated list.
• Array line breaks: To list each item of an array on a separate line in a merge field, use a prior activity to combine the array into a single-value variable. The joinarray() function can save an array into a single-value variable where each item is separated by a carriage return and line feed character. For example: joinarray(pv!MyMultipleProcessVariable, char(13) & char(10))

Unicode support for Text Doc from Template

The Text Doc from Template smart service supports Unicode (UTF-8) templates and generates Unicode documents. Template files must be encoded in UTF-8 if Unicode characters appear in the document.

Permission errors for Text Doc from Template

If the smart service node is run as a user who does not have adequate rights to the template document, the document that is to be replaced, or the folder where the new document is generated, an error message is sent to the process administrator and the task is paused.

Usage considerations

Run at low throughput in autoscaled processes

This smart service is not intended for high-throughput usage and should only be used at low frequency in processes with autoscale enabled. The underlying services this node relies on may not scale to the same degree as autoscale-enabled processes, which may impact performance at high concurrency.

For autoscaled processes, consider one or more of these approaches:

• Position this node in less used paths within your process flow. This could be an exception path or an uncommon case for the process.
• Monitor node execution times during performance testing to see if the node performs differently at scale.

When used in an autoscaled process, the node should behave as it would in a standard process of comparable scale. For typical workloads, no special design considerations are needed.

Feedback