Maintainable and agile architecture

Before modeling any document, it is recommended to think about the functional architecture and the role of Blueriq Documents in it. Blueriq Documents, henceforth Documents, is best used when the document to be generated is process-specific or when a document contains many conditional parts, knowledge about the process, and dynamic content.

A document is created based on knowledge and content from an active profile and all available business rules and logic modeled in the application. A document model can contain static and dynamic parts.

To prepare your Documents solution you can read the design guide A maintainable and agile architecture. This design guide helps thinking about creating maintainable applications and decoupling parts of your application.

Decoupling

In the specific case of a Documents solution decoupling could be realized by creating a repository and project solely for generating and processing documents exposed as a web service (Decoupling patterns). Such an architecture would be advised when the generation is only a background process or acts as a service and no document has to be presented to the user as a download. This solution would be recommended when multiple systems and applications should be able to call this document service. Example: For some mortgage supplier applying for a mortgage can be done in multiple ways and in more than one application. However, all applications are sent to one Documents solution to generate an offer sent to the customer. 

Often a document serves as a copy for the user, for instance a copy of the results of a calculation tool or a mortgage application. In these situations the AQ_DocumentLink container can be used to display a download link and generate a document to be presented on screen. Modelling a document within the same project as the interaction (pages, flows etc. the Application Layer) is modeled would be most logical. 

Libraries

To prevent redundant code a (external) library can be created. This library can contain custom presentation (and content) styles and can also be used to model templates or examples illustrating the styleguide for both the business engineer and product owner. An external library would be overdoing it 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

There are situations in which creating a document based on a page could be the best solution. Modelling a document with a page is mainly different in terms of the editor used in Encore, but not the underlying principles. As long as the same structure is applied and content and presentation styles are correctly applied, identical documents can be generated. However, adjusting the default layout of the resulting document based on a page will take custom coding as the presentation and content styles available are primarily implemented for Documents and not for Pages out-of-the-box.

By default, a document based on a page will show exactly the same content as the same page shown on screen, i.e. fields (including their question text and value and all possible values in case of a boolean or value list), container display names, text and content items and also preconditions apply in the same way. Especially with regard to the question text, modelling a document based on a page has clear benefits, since a change will just have to be implemented once, i.e. in the attribute definition. Also the fact that the document is a page and thus can be reused as a whole or just the containers to be used 'on screen' could be a benefit. It should be noted though that reusing the whole page or parts can be a struggle since some styles will only apply to the document and not to the page and vice versa. Buttons do not appear in the document.

Presentation styles for pages do not automatically apply to documents. It is possible to apply content styles on the containers on the page in the same way as in a document, for example to 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?

Especially in the following situations Documents is preferred over Pages:

• Output contains much static text; the RTF import function saves time
• Output contains many sentences that contain variables/fields
• Output is generated in a batch process and no user interaction occurs

When to use Pages?

Using pages to model a document is less common, but in some situations it might be the best choice, for example:

• Output only contains a list of fields and their values without long texts
• Output is only generated for archiving purposes