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..). 

A page as base for a document has the following characteristics:

• Anything visible on screen will be visible in the document (i.e. any elements that are invisible due to preconditions will also not be visible in the output document), including the question text and all possible values and the selected value of attributes, container display names and text elements, buttons are not included