Getting started

A document model can be seen as a tree. The view in Blueriq on the left side is called the Tree View, see an example on the right. Whether a document was created using the RTF import wizard or a document is modeled from scratch it is advised to think about the intended structure and styles before you start modelling.

Define the smallest unit

Before you start modelling define the smallest unit. A unit most likely will be either a word, sentence or paragraph. Hence, it is possible to form a sentence over multiple nodes adding conditions on parts of the sentence, example:

This structure could be the corresponding tree with a sentence "The <2a>applicant</2a><2b>applicants</2b> are required to provide all necessary papers", with a precondition on node 2a and 2b to determine the number of applicants.

This could also be achieved by creating a node with one sentence and apply conditions within the sentence by selecting a part and click the 'Add condition' button. However, in complex documents with many conditions on phrases, breaking up the document in smaller units could be helpful. 

Tree model

A document model can be seen as a tree with different branches and finally leafs. A document model consists of nodes that contain nodes that can contain nodes and so on. When a content style is applied to a node it might depict which child elements are allowed. For instance, when the content style Table is applied to a node, its child elements may only have specific content styles (for example TableRow). These settings can be changed in the Global Element of the content style.

Most documents will contain the following content styles determining the structure:

Paper type (Normal/Letter/Column)
	Header(s) (-First/-Last)
		<content>
	Body
		<content>
	Footer(s) (-First/-Last)
		<content>

Within one document the structure above can occur one or more times, for example in case of appendices or a cover letter. 

In the example above the root node has a content style of either Normal, Letter or Column. These three styles are out-of-the-box styles and can be used directly. Please have look at the print space examples in the previous part for examples of a Normal and Letter style. The style Column divides the document into 2 columns by default, this setting and others can be changed in the style sheets (xsl files) for the style Column as for Normal and Letter. Also it is possible to create a (custom) style or variation to correspond with the corporate branding. 

The global elements in Blueriq Encore of these content style depict what styles are allowed as child elements.  

To create a maintainable and readable document model nesting and branching is strongly recommended. Most content styles require nesting (e.g. Table, TableRow or Letter), but it is recommended to apply nesting also if only for structuring purposes. 

Please refer to Document import and section 2. Preparing a Documents solution of this design guide to learn how to apply nesting during a RTF import. 

Reusable elements

Content items can be used as reusable components in Document . Other reusable components are Images and Text item. 

Possible uses can be:

• A content item could be a way to import new text or tables with the Document import. For example, an existing document requires change. The change includes adding many tables and text. It will not be possible to use the RTF import wizard to update an existing document, but it is possible to import the new tables and texts and save them as content items. These content items can be added as node in your document as reusable item or it is possible to temporarily add the item and extract the contents by copy-pasting it elsewhere in the document, after which the reusable item can be deleted.
• Large documents can get harder to maintain. Saving elements of the document as content item can make version control and searching easier. That is, changes made in a document (without content items) are not committed at a node level. In a large document it thus might be hard finding the change and avoids merge conflicts. Breaking up the document in reusable text items and content items will get around this, because changes will be registered at content item level narrowing the down parts of the document affected by a change. The same benefit holds for searching for content in a document. When the document's content is cut up in content items, the content item will occur in the search results instead of or next to the whole document. 
• Content such as an addressblock, footer, header, signature (Image), contact info or even whole paragraphs or letters often occur in multiple letters and documents. Create content items to reuse elements that occur often.

To maximize reuse in a maintainable way split content and layout as much as possible. This requires a style guide to avoid needing to specify layout like fontfamily or colors in the document model. Another way at a smaller level to split content and layout is to apply conditions and styles at the node instead of within the textbox. In this way the contents of the node can be reused even if the layout or condition deviates.

Logic and nodes

Repeat conditions

Using repeat conditions is an effective way of keeping the document model small and structured. If possible, group nodes that require the same context, e.g. Application.Applicants. This will only require one repeat condition and will keep the model structured. The same applies to the use of preconditions. 

Reusable expressions

Often a document serves as a final report or copy of a process. For archiving purposes or as a copy for a client or user. Data in the document thus must be consistent with data send to any back office or database or data shown to users during the process. This should encourage the use of reusable expressions or auxiliary attributes instead of defining new expressions in the document model. Additional benefit: maintainability increases as new rules will only need to be changed once to be applied in pages and documents for instance, creating a more robust application.

Node conventions

The document tree displays an overview of nodes, collapsed or expanded. These nodes can be assigned a name. A name is not required and does not have a functional purpose. However, assigning descriptive names will contribute to a readable document model and set up naming (and modelling) conventions is recommended. 

Recommendations nodes:

 Apply nesting in the document model to create structure. If necessary, add empty nodes just for the purpose of grouping nodes together. 

 Set up node naming conventions, examples: (1) codes/tags from the specification document or (2) the first three words of a sentence (3) or name the node after its content style (e.g. AddressBlock) since the content style cannot be traced back by looking at the tree view or (4) a combination of these.

Handle exceptions

Within Blueriq Encore validation messages will be shown when child nodes contain styles which are not allowed by the style on the parent node. Example: the content style Normal is not allowed on a child node within Table. Your project will become invalid if this would be the case and Encore will notify you.

There is another category exceptions which cannot be captured by validating your project within Blueriq Encore, though while testing a newly modeled document you may have seen it one or two times: a obvious red error message in the generated document. These exceptions have to me modeled explicitly in the xsl stylesheets (hence not in Encore) when adding new styles or functionality (custom). Out of the box many exceptions are already present, for example an error when using the style TableRow without modeling a childnode with TableCell. This type of error cannot be captured within Encore. This exception thus, is captured in the xsl files and will result in an obvious red error message in the generated  document:

Handling exceptions appropriately is important. When exceptions occur but no error message is shown in the output document, it might appear as no exceptions exist. Some part of the document might be missing because of an exception without you noticing it. Hence, when adding new functionality or styles make sure error messages are implemented as well.