The SystemWeaver Document Management solution enables users to generate documents while keeping track of configurations and versions on each individual part of the document. In addition, the collaborative properties of SystemWeaver enable collaborative creation of documents and templates. This article focuses on the configuration of document templates, including configuring a menu option for document cloning, and is meant as a guide for SystemWeaver Architects as they are typically responsible for creating templates that end users can use when creating new documents. In this way, sections and report definitions can be reused each time a specific type of document is generated and architects can define/restrict the structuring of the documents. The following configuration topics are covered:
- Creating a New Template Document
- Adding Headers, Footers and Title Page
- Configuring Headers/Footers and Title Page
- Defining the Content Structure
- Report XML Configuration
- Configuring a Menu Option for Document Cloning
- Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
- An installation of the SystemWeaver Explorer client (swExplorer)
- Completed the SystemWeaver Report Generation - Introductory Training (XML configuration is the same for Reports and Documents)
- The system's meta model must support the Documents Model. (If it does not include the Documents model, a Documents meta model XML file (BasicDocumentModel.xml) is attached to this article which you can import.)
- The style and layout of the template are identified (usually, there is a document template outside of SystemWeaver, such as a Word template, that is being replicated)
- Assignment of the SW Architect role in the server
- An installation of the SystemWeaver Architect client (swArchitect)
Basic Documents Meta Model
Before getting started, you should be familiar with the SystemWeaver documents model and available features. Below is the basic meta model.
Required Item Types
The item that holds the entire document content, in terms of Sections, and Section Items
|SSSE||Section||A section contains document content.|
A template item is used for the purpose of defining standard parts of a document, like headers and footers.
By including specific "field codes" in a way similar to MS Word, content of the template can be filled-in automatically as part of the document generation. See the below table for a list of the template items.
|JREX||Report XML Definition||The item that controls the content and layout of document generation. Any content that is to be included in the output must be included in the definition. It has an attribute (ATRX) that holds the XML definition.|
Required Template Item Part Types
|IRHE||Header||A template item that defines the header of the inner document pages.|
|IRFO||Footer||A template item that defines the footer of the inner document pages.|
|IRTH||Title Header||A template item that defines the header of the title page.|
|IRTF||Title Footer||A template item that defines the footer of the title page.|
|IRTP||Title Page||A template item that defines the content of the title page.|
Note: It can be extended for the use of Section Item parts which is a convention for including items, e.g., Function, ECU, etc., other than sections into the content of a document. (An XML file (SectionItemModel.xml) is attached to this article which you can import.)
Because some document items and parts are hard-coded for the document model, the SIDs for the documents meta model should not be modified. Otherwise, certain functionality may break.
Creating a New Template Document
- If the document template will need default attributes that do not already exist for the document item type, define them in swArchitect.
Just like in MS Word, a template can be created in SystemWeaver for each type of document that is produced regularly within a project. Once the prerequisites above have been met, you are ready to create the template.
- On the Items ribbon, click New item. The New item page will display.
- Select the library/access that is valid for your new template under Chose Access.
- In Select Item Type, search for and select the Document item type to be used.
- Enter the name for the new template in the Enter Name field.
- Click Create Item.
The new document template, with its default document attributes, is created. Each time a document is created based off the template, the user can modify the attribute values. In the below example, a new document template has been created and it currently has three Default Attributes: Document Title, Approved By, and Classification. Users will be able to enter values for these each time they create one of these documents based off the template.
Adding Headers, Footers and Title Page
Repeat the following steps for each template item (header, footer, title header, title footer and title page).
- Right-click the document item and select New and select the template item.
- Select the library/access that is valid for your new item under Chose Access.
- In Select Item Type, select Template Item.
- Enter the name for the new template item in the Name field.
- Click OK.
When you have added all of them, your document template will include the following structure:
Configuring Headers/Footers and Title Page
The template items are configured using the Header/Footer view which is accessible via the Documents menu group on the Items ribbon. You can add text, logos and other images, field codes and more to the template items to make the template unique to it's purpose. The Header/Footer view is only available for template item types.
- In the structure tree, select the template item you want to modify.
- Select the Header/Footer menu option in the Documents menu group. The view will display a blank workspace with Document Attributes shown at the bottom.
- To insert one of available document attribute, right-click in the view, select Insert attribute and select the attribute type.
- To insert page numbering, right-click and select Insert page no.
- To insert a field code, right-click, select Insert field code and enter the exact field code. If you are unsure of which field code to use when inserting fields, refer to the Field Codes reference manual in the application's Help.
- Double-click in the Header/Footer view to open the advanced Description editor.
- Design the template item just as you would in a word processing program using the tools provided. For example,
- Add label text before each inserted tag for attributes, page numbering and field codes.
- Add logos, additional formatted text, horizontal lines, etc.
The Show field codes option will display a ::XX:: placeholder while the Show field values option will allow you to preview the values.
Example Title Page Configuration
The below example title page, being viewed in the Description editor, displays the text "Requirement specifications", an image of the Systemite logo, the label text "Creation Date:" and a tag for the field code CreationDate.
Example Header Configuration
The below example header, displayed in the Header/Footer view, contains a horizontal line at the top and bottom, a page numbering tag, a document attribute tag for Approver, and a field code tag for Status each with label text added before the tag.
Defining the Content Structure
Documents contain sections and subsections to structure content. They can also include other item types as section items.
- To add standard sections to the template, right-click the top-level Document item and select the section item(in the below example, "Report Section").
- Enter Description content for the item as needed. Here is an example where users are instructed to enter introduction text:
- To add a subsection to the section, right-click the section and select the subsection item (called "Sub Section" in the below example).
- Enter Description content for the subsection as needed.
- If you have a meta model that supports adding other item types as section items to sections, you can do this by selecting the section item where you want to add the section item and select Add and then Section Item.
- Search for the item you wish to add using any of the Search tools, select it and click Open item:
Tip: As with other tree structures in SystemWeaver, if you are adding a section item of a type that already exists in your document structure, you can select an existing section item and copy it (Ctrl+C) and paste it into your structure (Ctrl+V) to add a new one of the same type.
Example Content Structure
The below example content contains basic sections (e.g., Introduction, Terminology Section, Template Approval Sheet Section and Model Section) and subsections (Scope of Document, Mission/Theme, Terminology Subsection). It also contains section items (e.g., Function requirements) in Model Section. The meta model has been configured to allow users to add Function requirements to the Model Section, but not to the other sections.
Report XML Configuration
A report XML definition is a required part of a document. It basically controls the content and layout of the document that is to be generated. If the Document does not include an XML definition, the view assumes a default definition which means that all sections and subsections of the document are included in the output, but only the first level of any included items which are not true section or subsection item types, e.g., Function requirement containers. If the Document does include a definition, it will override the default setting. Normally, the definitions you create will include at least the content of the default definition.
The XML definition is managed as a separate item. Typically, you will create document templates that include XML definitions so that end users only need to select an existing template when creating new documents. Configuration of the XML definition is done using SystemWeaver Script Language.
Example Report XML Configuration
An example of a Report XML configuration for documents is attached to this article. The example includes the following parts:
- Optional: Text styles and Paragraph styles.
- Optional: Adds a table of contents.
- Required: Adds Report Sections.
- Required (needs to be modified based on the used meta model): Item Templates.
- Optional (needs to be modified based on the used meta model): Other Templates which can be used to print Glossaries, Acronyms and Document References.
- Optional (Recommended): PrintChangeLog.
- Optional (Recommended): Template for prints error in case of missing template.
Configuring a Menu Option for Document Cloning
Users can use the standard Create new document from this template option (as described in Working With Documents) but as an alternative to this, you can create a document cloning option for them. This is especially suitable if a template is used often by users where many items are consistently marked "ignore". You can configure a Clone view to provide users with a menu button where items are pre-set to be ignored. Basically, any items left out of the configuration will be ignored, i.e., you do not have to specifically configure the ignore actions. The configuration is done in Configure the explorer.
<Config id="Create document from template">
<Caption>New from template</Caption>
<Description>Create a new document from a template</Description>
<Part sid="IRHE" action="include"/>
<Part sid="IRFO" action="include"/>
<Part sid="IRTF" action="include"/>
<Part sid="IRTH" action="include"/>
<Part sid="IRTP" action="include"/>
<Part sid="IREX" action="include"/>
<Part sid="IRRS" action="clone"/>
<Part sid="ISSE" action="clone"/>
Resulting menu option
Refer to the Help for more information on the document concept in SystemWeaver.
Articles explaining the Documents model and end-user functionality are also available.