Maintainable and Agile Architecture

Before modeling any document, it’s important to consider the functional architecture and the role of Blueriq Documents within it. Blueriq Documents (henceforth referred to as Documents) are best utilized when the generated document is process-specific or contains many conditional elements, knowledge about the process, and dynamic content.

Documents are created using knowledge and content from an active profile, as well as all available business rules and logic modeled in the application. A document model may consist of both static and dynamic elements.

To prepare your Documents solution, refer to the Design Guide A maintainable and agile architecture. This guide provides insights into creating maintainable applications and decoupling different parts of your application.

Decoupling in Document solutions

In the context of a Documents solution, decoupling can be achieved by creating a dedicated repository and project focused solely on generating and processing documents exposed as a web service (using Decoupling patterns). This architecture is ideal when document generation occurs as a background process or service, without the need to present documents directly to the user for download.

This approach is especially recommended when multiple systems and applications need to call the document service. For example, consider a scenario where an organization has several applications used to apply for a mortgage. Regardless of the application, all requests are directed to the same document service, which generates the mortgage offer that is then sent to the customer.

In contrast, when a document is intended to serve as a copy for the user—such as a result from a calculation tool or a mortgage application—you can use the AQ_DocumentLink container to display a download link, generating a document that will be presented on screen. In this scenario, it makes more sense to model the document within the same project as the user interaction (pages, flows etc.), also referred to as the Application Layer. This helps maintain a clear structure and flow for the user-facing aspects of the application.

Document styles

To avoid redundant code, it's best to create a library for your document styles. This library can include custom presentation and content styles, and can also be used to model templates or examples that illustrate the style guide for both business engineers and product owners. However, using an external library may be unnecessary if only one project contains documents.

Documents vs. Pages

This design guide focuses on modeling documents using Document. This sounds quite logical. However, there is another possibility, that is, modelling a document using Page. The AQ_DocumentLink container for example can create a document based on either a document or a page, the same holds for Service call type: AQ_Document_Generate service type. 

Modeling documents with pages

In some cases, generating a document based on a page is the best solution. A common use case is when you want to create a document from a summary page, allowing users to download their summary as a well-structured document for their own records.

Modeling a document with a page differs mainly in the editor used in Encore, but the underlying principles remain the same. As long as the structure, content, and presentation styles are properly applied, the resulting documents can be identical. However, adjusting the default layout of the document based on a page will require custom coding, as the presentation and content styles available are primarily designed for documents, not pages, out of the box.

By default, a document based on a page will display exactly the same content as the page shown on screen. This includes fields (with their question text and values, as well as all possible options for boolean or value list fields), container display names, text, content items, and preconditions. When it comes to question texts, modelling a document based on a page offers clear benefits, as any changes need to be made only once, in the attribute definition. 

Additionally, since the document is based on a page, it can be reused in its entirety or with specific containers for on-screen display. However, reusing the whole page or parts of it can be challenging, as some styles apply only to the document and others only to the page. Buttons, since they are an interaction element, will not appear in a document.

Presentation styles for pages do not automatically carry over to documents. However, you can apply content styles to containers on the page in the same way as in a document. For example, you can model a table in your document.

Page
	Container A: content style Table
		Container B1: content style TableRow
			Container C1: content style TableCell
			Container C2: content style TableCell
		Container B2: content style TableRow
			Container C3: content style TableCell
			Container C4: content style TableCell

When to use Documents

Blueriq documents are best suited for cases where there is a lot of textual content, such as generating letters or detailed reports. These types of documents benefit from the rich formatting and structure that Blueriq offers.
Benefits of modeling a document:

• The RTF import function saves time
• Good support for incorporating variables/fields in the text
• The document editor will displays all of the document's content, while a page will only show the names of the text- and content items

When to use Pages

If the document primarily consists of a summary of data—such as a report that presents key figures or a brief overview—modeling the document with a page might be a better approach. Pages are particularly useful when you need to present data in a simplified format, without a heavy focus on textual content.

Benefits of using a page to model a document:

• The content of the document and the page are similar, providing a single source of maintenance
• It's easier to test the conditions on a page