The first part of this guide concerns the necessary preparation of your document solution. What kind of solution do yo need? Do you need a quick report of a calculation tool? A nicely styled report for clients? Do you need a copy of a mortgage application just for archiving purposes? Are you developing a document street that should be available to different kind of applications across your organization? Does the user interacts with the application or does it run in background processes?

All these aspects may determine how your solution will look like.

Table of contents

Maintainable and agile architecture

Before modelling 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 generating a document is process specific or when a document contains a lot of conditional parts, knowledge about the process and dynamic content.

A document is created based on knowledge and content from an active profile, all available business rules and logic modeled in the application and a document model containing 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 (Decoupling patterns) could be realized by creating a repository and project solely for generating and processing documents exposed as a web service. 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 for instance. 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 is 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 or dynamic 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. A external library would of course be overdone if only one project contains documents.

Documents vs. Pages

This design guide focuses on modeling documents using Documents. This seems to be quite logical. However, there is another possibility, that is, modelling a document using Pages. The AQ_DocumentLink container for example can create a document based on either a document or a page, the same holds for 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 no common practice though and adjusting the layout of the resulting document will take custom coding as the presentation and content styles available are mainly implemented for Documents and not for Pages (snap de stylesheets niet..).

Default, a document based on a page will contain exactly the same 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 and text and content items and also preconditions apply in the same way. Buttons do not appear in the document.

Presentation styles do not automatically apply to documents based on a page. 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

Note: by editing the xsl stylesheets it is possible to change the document's layout and add custom presentation and content styles.

When to use Documents?

Documents is the preferred way to model Documents. Especially in these situations Documents is preferred over Pages:

Output contains a lot of static text; RTF import function will save a lot of time
Output contains a lot of sentences that contain variables/fields
Output is generated in a batch process and no user interaction occurs

When to use Pages?

Pages is not common practice, 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

Bare in mind that presentation styles do not automatically apply to documents based on a page. Editing/adding stylesheets will be necessary.

Previous: Documents guide

Next: 2. Preparing a Documents solution

1. Documents solution