How to Generate Appian Documents

Appian Max Team — Tue, 23 Apr 2024 13:20:40 GMT

Current Revision posted to Guide by Appian Max Team on 4/23/2024 1:20:40 PM

Appian can generate documents to present data in a specific file format. Depending on your formatting needs and the number of documents that need to be generated there are several approaches to consider.

Alternatives to Generating Documents

First consider not generating documents, at least for your initial release. Instead send links to records and reports in Appian or have users print Appian screens using their browser if they need to use the data outside of Appian.

For best results use Chrome for printing from Appian.

Benefits of this simple, agile approach include:

Faster time to delivery as less time is spent implementing document generation functionality
Feedback from users can be gathered to prioritize where document generation is really required
All Appian interfaces have printer friendly stylesheet formats

Document Generation Use Cases

If you need to generate documents, consider whether you want to generate and store documents for later reference or simply need to generate them on-demand for immediate use.

Generate and Store

Capture the state of data at a certain milestone in a process for later reference
Generate a document on a schedule (e.g.: a monthly report)

Advantages

Stored documents can be downloaded instantly with one click from any SAIL interface
Users don't have to wait for the document to be generated
Especially important if the document takes a long time to generate

Disadvantages

Documents only reflect data at the time they are generated
Stored documents may require tighter security to control access

Don't try to keep stored documents up-to-date with frequent changes in the underlying data. Instead, use on-demand generation for these use cases.

On-Demand Generation

Download a document representing the current state of data
Send documents via email or to an external system

Advantages

Generated document is always up-to-date
Documents are only generated when they're needed, reducing unnecessary load on the system
- Especially important if the document format is complex or requires data from external systems

Disadvantages

Users must explicitly request the generation (versus a one-click download)
Users have to wait for the document to be generated

Scalability Considerations

High Fan-Out

Fan-out describes how one action (user initiated or process driven) can cause the generation of many documents. High fan-out can cause a sudden increase in system load, degrading overall performance. The impact is worse when generating complex documents or when documents require information from external systems.

Data from External Systems

If your documents require data from an external system and you need to generate a high volume of documents, be aware of how that system scales in response to that load.

General Guidance

Do

Protect against performance risks by limiting fan-out and/or by throttling the batch size and rate at which documents can be generated
- Understand the implications of peak volume, disk space usage, and integrations
Load test your solution using production-like scenarios
Review guidance related to transferring/processing of large data sets
Validate user entries if users have the ability to name documents or folders
- Avoid using characters that are disallowed in Appian Document Management filenames (/ \ : ; < > " \* ' ?)
Validate entries if the user text is entered directly into documents
- For example, Word Doc from Template does not allow HTML formatting tags or tags that match the document template delimiters

Don't

Use any function or plug-in (such as Base64 Conversion) that will result in storing a large amount of text or binary data in process variables or node inputs/outputs

Doc from Template Smart Services

Several smart services for generating documents are available out of the box:

Advantages

Quick and easy to implement
Supports the needs for most document generation through token replacement (i.e. mail merge)
Lower performance risk than more complex options

Disadvantages

Does not support dynamic content (showing/hiding sections or creating a table with an unknown number of rows)

Dynamic Tables and Content

The Advanced Document Templating plug-in supports generating Microsoft Word (.docx) files with dynamic content where the format or number of elements like tables, lists, and images is not known in advance. Use this plug-in when the out of the box smart services are unable to meet your dynamic formatting requirements.

Advantages

Supports dynamic length tables, showing/hiding content and embedding images

Disadvantages

Requires understanding Freemarker syntax
Uses a data model based on large XML strings which can increase system memory utilization

Dedicated System

Specialized systems should be used for very high volume or very specific document formatting requirements.

Advantages

Provide dynamic and flexible document generation
Resources are scaled and managed independently of Appian, minimizing the performance impact on users

Disadvantages

Requires additional software and hosting costs
Requires an expert to configure and manage the third-party system

Tags: design patterns, Architecture

How to Generate Appian Documents

Appian Max Team — Thu, 22 Feb 2024 21:17:12 GMT

Revision 5 posted to Guide by Appian Max Team on 2/22/2024 9:17:12 PM

Alternatives to Generating Documents

For best results use Chrome for printing from Appian.

Benefits of this simple, agile approach include:

Faster time to delivery as less time is spent implementing document generation functionality
Feedback from users can be gathered to prioritize where document generation is really required
All Appian interfaces have printer friendly stylesheet formats

Document Generation Use Cases

If you need to generate documents, consider whether you want to generate and store documents for later reference or simply need to generate them on-demand for immediate use.

Generate and Store

Capture the state of data at a certain milestone in a process for later reference
Generate a document on a schedule (e.g.: a monthly report)

Advantages

Stored documents can be downloaded instantly with one click from any SAIL interface
Users don't have to wait for the document to be generated
Especially important if the document takes a long time to generate

Disadvantages

Documents only reflect data at the time they are generated
Stored documents may require tighter security to control access

Don't try to keep stored documents up-to-date with frequent changes in the underlying data. Instead, use on-demand generation for these use cases.

On-Demand Generation

Download a document representing the current state of data
Send documents via email or to an external system

Advantages

Generated document is always up-to-date
Documents are only generated when they're needed, reducing unnecessary load on the system
- Especially important if the document format is complex or requires data from external systems

Disadvantages

Users must explicitly request the generation (versus a one-click download)
Users have to wait for the document to be generated

Scalability Considerations

High Fan-Out

Data from External Systems

If your documents require data from an external system and you need to generate a high volume of documents, be aware of how that system scales in response to that load.

General Guidance

Do

Protect against performance risks by limiting fan-out and/or by throttling the batch size and rate at which documents can be generated
- Understand the implications of peak volume, disk space usage, and integrations
Load test your solution using production-like scenarios
Review guidance related to transferring/processing of large data sets
Validate user entries if users have the ability to name documents or folders
- Avoid using characters that are disallowed in Appian Document Management filenames (/ \ : ; < > " \* ' ?)
Validate entries if the user text is entered directly into documents
- For example, Word Doc from Template does not allow HTML formatting tags or tags that match the document template delimiters

Don't

Use any function or plug-in (such as Base64 Conversion) that will result in storing a large amount of text or binary data in process variables or node inputs/outputs

Doc from Template Smart Services

Several smart services for generating documents are available out of the box:

Advantages

Quick and easy to implement
Supports the needs for most document generation through token replacement (i.e. mail merge)
Lower performance risk than more complex options

Disadvantages

Does not support dynamic content (showing/hiding sections or creating a table with an unknown number of rows)

Dynamic Tables and Content

Advantages

Supports dynamic length tables, showing/hiding content and embedding images

Disadvantages

Requires understanding Freemarker syntax
Uses a data model based on large XML strings which can increase system memory utilization

Dedicated System

Specialized systems should be used for very high volume or very specific document formatting requirements.

Advantages

Provide dynamic and flexible document generation
Resources are scaled and managed independently of Appian, minimizing the performance impact on users

Disadvantages

Requires additional software and hosting costs
Requires an expert to configure and manage the third-party system

Tags: design patterns, Architecture

How to Generate Appian Documents

joel.larin — Wed, 01 Nov 2023 15:17:34 GMT

Revision 4 posted to Guide by joel.larin on 11/1/2023 3:17:34 PM

Alternatives to Generating Documents

For best results use Chrome for printing from Appian.

Benefits of this simple, agile approach include:

Faster time to delivery as less time is spent implementing document generation functionality
Feedback from users can be gathered to prioritize where document generation is really required
All Appian interfaces have printer friendly stylesheet formats

Document Generation Use Cases

If you need to generate documents, consider whether you want to generate and store documents for later reference or simply need to generate them on-demand for immediate use.

Generate and Store

Capture the state of data at a certain milestone in a process for later reference
Generate a document on a schedule (e.g.: a monthly report)

Advantages

Stored documents can be downloaded instantly with one click from any SAIL interface
Users don't have to wait for the document to be generated
Especially important if the document takes a long time to generate

Disadvantages

Documents only reflect data at the time they are generated
Stored documents may require tighter security to control access

Don't try to keep stored documents up-to-date with frequent changes in the underlying data. Instead, use on-demand generation for these use cases.

On-Demand Generation

Download a document representing the current state of data
Send documents via email or to an external system

Advantages

Generated document is always up-to-date
Documents are only generated when they're needed, reducing unnecessary load on the system
- Especially important if the document format is complex or requires data from external systems

Disadvantages

Users must explicitly request the generation (versus a one-click download)
Users have to wait for the document to be generated

Scalability Considerations

High Fan-Out

Data from External Systems

If your documents require data from an external system and you need to generate a high volume of documents, be aware of how that system scales in response to that load.

General Guidance

Do

Protect against performance risks by limiting fan-out and/or by throttling the batch size and rate at which documents can be generated
- Understand the implications of peak volume, disk space usage, and integrations
Load test your solution using production-like scenarios
Review guidance related to transferring/processing of large data sets
Validate user entries if users have the ability to name documents or folders
- Avoid using characters that are disallowed in Appian Document Management filenames (/ \ : ; < > " \* ' ?)
Validate entries if the user text is entered directly into documents
- For example, Word Doc from Template does not allow HTML formatting tags or tags that match the document template delimiters

Don't

Use any function or plug-in (such as Base64 Conversion) that will result in storing a large amount of text or binary data in process variables or node inputs/outputs

Doc from Template Smart Services

Several smart services for generating documents are available out of the box:

Advantages

Quick and easy to implement
Supports the needs for most document generation through token replacement (i.e. mail merge)
Lower performance risk than more complex options

Disadvantages

Does not support dynamic content (showing/hiding sections or creating a table with an unknown number of rows)

Dynamic Tables and Content

Advantages

Supports dynamic length tables, showing/hiding content and embedding images

Disadvantages

Requires understanding Freemarker syntax
Uses a data model based on large XML strings which can increase system memory utilization

Dedicated System

Specialized systems should be used for very high volume or very specific document formatting requirements.

Advantages

Provide dynamic and flexible document generation
Resources are scaled and managed independently of Appian, minimizing the performance impact on users

Disadvantages

Requires additional software and hosting costs
Requires an expert to configure and manage the third-party system

Tags: design patterns, Architecture

How to Generate Appian Documents

joel.larin — Wed, 25 Oct 2023 13:26:15 GMT

Revision 3 posted to Guide by joel.larin on 10/25/2023 1:26:15 PM

Alternatives to Generating Documents

For best results use Chrome for printing from Appian.

Benefits of this simple, agile approach include:

Faster time to delivery as less time is spent implementing document generation functionality
Feedback from users can be gathered to prioritize where document generation is really required
All Appian interfaces have printer friendly stylesheet formats

Document Generation Use Cases

If you need to generate documents, consider whether you want to generate and store documents for later reference or simply need to generate them on-demand for immediate use.

Generate and Store

Capture the state of data at a certain milestone in a process for later reference
Generate a document on a schedule (e.g.: a monthly report)

Advantages

Stored documents can be downloaded instantly with one click from any SAIL interface
Users don't have to wait for the document to be generated
Especially important if the document takes a long time to generate

Disadvantages

Documents only reflect data at the time they are generated
Stored documents may require tighter security to control access

Don't try to keep stored documents up-to-date with frequent changes in the underlying data. Instead, use on-demand generation for these use cases.

On-Demand Generation

Download a document representing the current state of data
Send documents via email or to an external system

Advantages

Generated document is always up-to-date
Documents are only generated when they're needed, reducing unnecessary load on the system
- Especially important if the document format is complex or requires data from external systems

Disadvantages

Users must explicitly request the generation (versus a one-click download)
Users have to wait for the document to be generated

Scalability Considerations

High Fan-Out

Data from External Systems

If your documents require data from an external system and you need to generate a high volume of documents, be aware of how that system scales in response to that load.

General Guidance

Do

Protect against performance risks by limiting fan-out and/or by throttling the batch size and rate at which documents can be generated
- Understand the implications of peak volume, disk space usage, and integrations
Load test your solution using production-like scenarios
Review guidance related to transferring/processing of large data sets
Validate user entries if users have the ability to name documents or folders
- Avoid using characters that are disallowed in Appian Document Management filenames (/ \ : ; < > " \* ' ?)
Validate entries if the user text is entered directly into documents
- For example, Word Doc from Template does not allow HTML formatting tags or tags that match the document template delimiters

Don't

Use any function or plug-in (such as Base64 Conversion) that will result in storing a large amount of text or binary data in process variables or node inputs/outputs

Doc from Template Smart Services

Several smart services for generating documents are available out of the box:

Advantages

Quick and easy to implement
Supports the needs for most document generation through token replacement (i.e. mail merge)
Lower performance risk than more complex options

Disadvantages

Does not support dynamic content (showing/hiding sections or creating a table with an unknown number of rows)

Dynamic Tables and Content

Advantages

Supports dynamic length tables, showing/hiding content and embedding images

Disadvantages

Requires understanding Freemarker syntax
Uses a data model based on large XML strings which can increase system memory utilization

Dedicated System

Specialized systems should be used for very high volume or very specific document formatting requirements.

Advantages

Provide dynamic and flexible document generation
Resources are scaled and managed independently of Appian, minimizing the performance impact on users

Disadvantages

Requires additional software and hosting costs
Requires an expert to configure and manage the third-party system

How to Generate Appian Documents

joel.larin — Wed, 18 Oct 2023 20:28:01 GMT

Revision 2 posted to Guide by joel.larin on 10/18/2023 8:28:01 PM

Alternatives to Generating Documents

For best results use Chrome for printing from Appian.

Benefits of this simple, agile approach include:

Faster time to delivery as less time is spent implementing document generation functionality
Feedback from users can be gathered to prioritize where document generation is really required
All Appian interfaces have printer friendly stylesheet formats

Document Generation Use Cases

If you need to generate documents, consider whether you want to generate and store documents for later reference or simply need to generate them on-demand for immediate use.

Generate and Store

Capture the state of data at a certain milestone in a process for later reference
Generate a document on a schedule (e.g.: a monthly report)

Advantages

Stored documents can be downloaded instantly with one click from any SAIL interface
Users don't have to wait for the document to be generated
Especially important if the document takes a long time to generate

Disadvantages

Documents only reflect data at the time they are generated
Stored documents may require tighter security to control access

Don't try to keep stored documents up-to-date with frequent changes in the underlying data. Instead, use on-demand generation for these use cases.

On-Demand Generation

Download a document representing the current state of data
Send documents via email or to an external system

Advantages

Generated document is always up-to-date
Documents are only generated when they're needed, reducing unnecessary load on the system
- Especially important if the document format is complex or requires data from external systems

Disadvantages

Users must explicitly request the generation (versus a one-click download)
Users have to wait for the document to be generated

Scalability Considerations

High Fan-Out

Data from External Systems

If your documents require data from an external system and you need to generate a high volume of documents, be aware of how that system scales in response to that load.

General Guidance

Do

Protect against performance risks by limiting fan-out and/or by throttling the batch size and rate at which documents can be generated
- Understand the implications of peak volume, disk space usage, and integrations
Load test your solution using production-like scenarios
Review guidance related to transferring/processing of large data sets
Validate user entries if users have the ability to name documents or folders
- Avoid using characters that are disallowed in Appian Document Management filenames (/ \ : ; < > " \* ' ?)
Validate entries if the user text is entered directly into documents
- For example, Word Doc from Template does not allow HTML formatting tags or tags that match the document template delimiters

Don't

Use any function or plug-in (such as Base64 Conversion) that will result in storing a large amount of text or binary data in process variables or node inputs/outputs

Doc from Template Smart Services

Several smart services for generating documents are available out of the box:

Advantages

Quick and easy to implement
Supports the needs for most document generation through token replacement (i.e. mail merge)
Lower performance risk than more complex options

Disadvantages

Does not support dynamic content (showing/hiding sections or creating a table with an unknown number of rows)

Dynamic Tables and Content

Advantages

Supports dynamic length tables, showing/hiding content and embedding images

Disadvantages

Requires understanding Freemarker syntax
Uses a data model based on large XML strings which can increase system memory utilization

Dedicated System

Specialized systems should be used for very high volume or very specific document formatting requirements.

Advantages

Provide dynamic and flexible document generation
Resources are scaled and managed independently of Appian, minimizing the performance impact on users

Disadvantages

Requires additional software and hosting costs
Requires an expert to configure and manage the third-party system

Introduction

When generating documents in Appian, you’ll first want to decide which method to use, either Out-of-the-Box (OOB) functionality or the Advanced Document Templating (ADT) Smart Service. Factors you’ll want to consider when deciding which approach to take are the complexity of the document, how many inputs the document will have, and dynamism of inputs.

Out-of-the-Box Functionality - MS Word 2007 Doc From Template

Appian OOB functionality, using the MS Word 2007 Doc From Template node, is a good option for generating documents with:

10 or less inputs
Static sections/tables
Static content (unlikely to change format)

Good use cases for the OOB node include documents that have hard-coded, static values as inputs, as well as documents that do not need to handle for dynamism.

The benefit of using the OOB node is that it is less complex than the ADT node for documents that fit the criteria of the bullet points listed above. It also does not require any extra plugin to deploy to a new environment as it is apart of Appian’s base product.

Advanced Document Templating Smart Service

The ADT Smart Service, using the Advanced Document Templating Smart Service node, is a good option for generating documents with:

More than 10 inputs
Dynamic sections/tables
Dynamic content (the format of the document could undergo iterations of changes)

Good use cases for the ADT node include documents that need to dynamically display rows in a grid, sections of a word document, or images. Additionally, if you have more than 5 different documents that you’ll be generating in one process, you will want to use the ADT node because it allows for dynamic generation of multiple documents with one node.

Benefits of using the ADT node include:

A single XML rule handles all template changes, which allows for easy testing, troubleshooting, and updating of template
Capability to handle dynamic content
Can reuse the node for multiple documents, no need for multiple ADT nodes per process model

Comparison of OOB and ADT Methods

	OOB Word Template Generation	ADT Smart Service
Allows for Dynamism?	No	Yes
Management	Template & Node	Template & XML
Error Message Handling	Occurs when opening the document in Tempo	Output parameter of node in Process Model
Performance	Memory-efficient	Long strings of XML can take up memory
Inputs	###input###	Uses Freemarker language
Number of Nodes	One node per template	One node per multiple templates

OOB Solution Overview

The following steps outline the high-level solution overview for using the Out-of-the-Box document generation functionality.

Create a document template and wrap input values with ###

a. Example: ###firstName###
Upload the document template to Appian

b. Run spell check to avoid errors
Within the MS Word 2007 Doc From Template node

a. Select the template and map identified inputs to the correct process variables

b. If a new template version has been uploaded, select "Rescan Template" link to ensure the latest variables are available for mapping
Variables previously mapped in this node may need to be remapped if significant changes were made to the document.

ADT Solution Overview

The following steps outline the high-level solution overview for using the ADT document generation functionality.

Create a document template and using freemarker language
Upload the document template to Appian.

a. Run spell check to avoid errors
Create an XML expression rule containing all inputs to document template

a. Create nested rules if you have dynamic content

b. You cannot use the toxml() function when creating this XML because the plugin accepts a specific XML format not compatible with toxml()
Within the DOCX from Dynamic Template node

a. Map the required inputs
Required inputs are the Docx template, the XML data model and Create New Document (boolean).
b. Map any other relevant inputs

Other Technical Considerations

Illegal characters (<, >, and &) must be escaped before generating template
- Suggestion is to create a rule that you wrap around either each input in the OOB node or each input of XML for ADT node that replaces these characters with legal characters

How to Generate Appian Documents

joel.larin — Thu, 07 Sep 2023 15:55:34 GMT

Revision 1 posted to Guide by joel.larin on 9/7/2023 3:55:34 PM

dsfsd