How to Generate Appian Documents

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:

• HTML Doc from Template
• Open Office Doc from Template
• PDF Doc from Template
• Text Doc from Template
• Word Doc from Template

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