A model driven document (MDD) is a Microsoft Word® document (.doc) generated from a MooD repository. Each MDD is a type of MooD synchronizer called Documents. This defines what is extracted from the repository and how it is structured and formatted. For example, you could create an MDD that generates a document detailing all projects with a particular status.

Once you have a Documents synchronizer, you use it like any other synchronization you have in Business Architect. Synchronizers are listed under Synchronize in the Explorer Bar’s Libraries section, and you can schedule or execute them as required.

 

The template, fragments and patterns

Figure 1.     Relationship between the template, fragments and patterns

Each MDD is based on a Microsoft Word template. A document based on this template is created and fragments are inserted into it. Patterns are used within fragments. Put simply, fragments are the elements you want to include in the document, and patterns are the content you want to include for each element. The sections that follow elaborate this basic description.

About the Microsoft Word template

All generated documents (.doc files) are based on a Microsoft Word template file (.dot or .dotx files). The template defines the basic properties of the document such as page size, margins, headers and footers etc. and any fixed text required, such as corporate logos, titles, or standard content. The template also defines the Microsoft Word styles that you will use in patterns.

The template can include bookmarks and you can insert content from the MooD repository directly into a bookmark location. Bookmarks can be included in the body of the template and in its headers and footers. One use of bookmarks is to have an entire document as the underlying template and only insert specific pieces of information from the MooD repository at bookmarked points. This is in contrast to generating all of a document’s content from the repository. You can, of course, have any combination of fixed and generated content.

When you generate a document, Business Architect creates a new document based on this template file. It will not alter the template file itself. This means you can use the same template file as the basis for many generated documents. You can create a Microsoft Word template file in a variety of ways, including saving an existing Word document as a template file. See your Microsoft Word documentation for more information on templates.

About fragments

Fragments define structure and are inserted into the document.

Fragments reference elements in the MooD repository. Elements can be explicitly inserted or inserted as the result of a query. Fragments and their elements are inserted into the generated document. Fragments provide the structure for the content that will be extracted from the MooD repository. You can have multiple fragments. Each fragment can reference as many individual or sets of elements as required.

The order of fragments is the order they will be inserted into the document unless you use bookmarks in your template file. Fragments can be inserted at a bookmark location. If you use bookmarked fragments, any fragments that are not bookmarked are inserted at the end of the document.

About patterns

Patterns define content and format. Patterns are used within fragments.

Each element is given a pattern. As elements are inserted into the generated document their patterns are applied. The pattern defines what content from the element will be added to the document, and how that content will be ordered and formatted (using styles from the underlying template). For example, a pattern can include the element’s name formatted as a heading, field values formatted as a list, and then an image of the element’s model. Business Architect gives you a variety of repository building blocks (rules) to construct your patterns, such as, Name, Field and Matrix. Patterns are reusable and ensure consistent content and presentation within the generated document.

Exposing variables and parameters as pins

If you include content from your repository that requires variables, you can either set these at the rule level, or you can pass them upwards to the document level. At the document level they become exposed for pinning.

Templates within patterns

In the preceding overview, a pattern gets its styles from the underlying Microsoft Word template. However, patterns can have their own Microsoft Word template.

Content from any elements that such a pattern is applied to is inserted into the generated Word document within a section based on the pattern’s template and using styles from that template. This means that within a document based on the underlying Microsoft Word template, you can have any number of repeating sections based on other Microsoft Word templates. Each template has its own bookmarks, formatting and structure.

This feature simplifies the development of documents with many repeating sections. Rather than maintain one mammoth template, you can design, use, maintain, and more importantly reuse, component templates. The Documents synchronizer’s underlying template can become simpler and act as a wrapper for your various repeating templates.

However, two key points to note are:

• Because each template can have its own bookmarks, patterns that use a template must define their rules within fragments. A pattern’s fragments are then inserted into the pattern’s template at their bookmarked location. Business Architect will not let you break this rule.
• Headers and footers in the generated document are taken from the underlying template. Any headers and footers in pattern templates are ignored.

 

Creating a Documents synchronizer

Each model driven document (MDD) is a MooD synchronization of type Documents.

Task 1    To create a Documents synchronizer:

1. In the Explorer Bar, under Libraries, click Synchronize

The Synchronize tab opens. This lists your synchronization groups.

2. Click the group that you want to add the Documents synchronizer to.

Adding groups

To add a group, on the ribbon, on the Home tab, in the Groups group, click New.   In this task, a Documents group already exists. The new Documents synchronizer is added to this group.

On the Home tab, in the Insert group, in the gallery of synchronizers, click Documents.

A synchronizer called New Synchronizer appears in the selected group (you can’t rename this until you have completed the next step).

4. Do one of the following:

• Drag an element into the Drag starting element here area.

This type of Documents synchronizer lets you generate the same basic document many times but base it on a different element each time. 

Note: Although it is possible to start from a matrix, and this can be of limited use with respect to the Name rule, this isn’t generally done. Matrices are catered for by the Matrix rule.

• Click Apply to Whole Repository if you do not want to use a starting element.

In either case, the synchronizer will then appear as follows with either the repository or starting element included in the detail.

5. Right click the synchronizer, click Rename, and then give the synchronizer a meaningful name.
6. 

You can now double-click the synchronizer and construct your document model. 

About the Documents synchronizer tab

You use a Documents synchronizer tab to construct your model driven document (MDD).

Note:     You must have a Documents synchronizer before you can access this tab.

The tab’s name will be the name of your synchronizer. However, this guide always refers to it as the Documents synchronizer tab.

Task 2    To open the Documents synchronizer tab for an MDD:

1. In the Explorer Bar, under Libraries, click Synchronize.

The Synchronize tab opens. This lists your synchronization groups and the synchronizers within.                 2. Right click the Documents synchronizer you want to configure, and then click Edit.

The Documents synchronizer tab for that MDD is displayed. It will look similar to this:

The Documents synchronizer tab has three areas:

• The Fragments pane.
• The Document Generator Properties pane. This includes two tabs: Patterns and Groups.
• The ribbon.

The purpose and features of these three areas are outlined in the following sections.

 The Fragments pane

This holds fragments. Fragments define structure.

Fragments contain elements from the repository. You can insert individual elements into a fragment, or you can insert a query that will find and insert elements. Documents can include one or more fragments. Combined together, these fragments, and the elements they hold, define the structure of your generated document. You can consider fragments as analogous to sections in a finished document.

Note:     While fragments will typically reference elements, they can also include rules more commonly used in patterns, for example, Custom Text and Matrix rules. If you create a Documents synchronizer that uses a starting element, you can construct fragments that do not include element references. Such fragments get their element reference from the starting element. 

The order of fragments in the pane is the order they will appear in the generated document, unless they have the same name as a bookmark in the Microsoft Word template file being used, in which case the fragment is inserted into the generated document at its bookmark. If you use bookmarked fragments, any fragments that are not bookmarked are inserted at the end of the document.

You can reorder fragments, and preview individual fragments. You can reorder the items within a fragment, move items between fragments, and duplicate items (Ctrl drag).

 

The Document Generator Properties pane

This area lists basic settings, such as the Microsoft Word template file to use, and where to save generated documents (you can include tokens in this filename). When you create a document model, you should set these before you build your document structure. It also holds the Patterns and Groups tabs described next

The Patterns tab

This holds patterns. Patterns define content and format.

Each element must have a pattern. Patterns are reusable. When a document is generated, each element has its pattern applied. The pattern uses rules to specify what content from the element will be included in the generated document, and how that content will be ordered and formatted. For example, you could have a pattern that includes the element’s name formatted as a heading, followed by an image of its model. The same pattern can be applied to any number of individual elements, or to all of the elements returned by a query.

Patterns can include any number and combination of the following rules:

• Name – the element’s name.
• Field – values taken from the element’s simple fields.
• Formatted Text – content taken from the element’s HTML and rich text memo fields.
• Pick List – content taken from Pick lists associated with the element.
• Model – the element’s model, a selected element’s model, or a Model Master applied to an element.
• Matrix – a matrix associated with the element, a matrix generated against an element, or a selected matrix (ignoring the current element).
• Custom Text – pieces of fixed text that you type yourself when you construct a pattern, that is, it is not drawn from the element.
• Break – assorted page and section breaks.
• Lists – there are two rules (Start List and End List) that you can use to insert formatted lists without using styles from the underlying Microsoft Word template.
• Element and Query – more complex patterns can include elements and queries to provide a degree of nesting.

o  Parameterized queries are useful within patterns as they get their parameter (an element) from the element to which the pattern is applied. 

The Fragments pane and Patterns tab synchronize with each other. If you click an item in either pane, the fragments or patterns that use the selected item are highlighted in the other pane.

When you select an item in either pane, a Delete button  appears.
Note: If you delete a pattern that is used elsewhere, a warning icon is inserted beside the affected rules. Your document will still generate, but the affected elements will be excluded.

Patterns can also include fragments when the pattern is using its own Microsoft Word template to insert specially formatted or repeating sections into the generated document. 

To duplicate a pattern, use Ctrl drag.

The Groups tab

This holds pattern groups. Pattern groups include multiple patterns and are used with queries. As a query can return multiple elements, you use a pattern group to apply different patterns to the different types of elements returned by the query.

 

If you'd like to learn more about this matter, please click on the attachment.