This article describes the basic Documents model and application features in SystemWeaver.
The SystemWeaver document management solution enables users to work with documents and keep track of the versions of each individual part of the document. In addition, the collaborative properties of SystemWeaver enable real-time collaborative creation of documents. Documents can be integrated with all models in SystemWeaver in that items of any type may be added to a document and then a configuration specifies how the items will be interpreted and output in the generated document.
Given its full integration with the SystemWeaver platform, the document management solution has built-in:
- Version management
- Configuration management
- Access management
- and more
A document is a type of report with the added benefit of being able to structure your content. It adheres to a standard document model, but can be expanded to include any type of section item. Essentially, a document consists of multiple items and they typically fall into three categories:
- Template Items (to define the layout)
- A Report XML definition
Template Items (to Define the Layout)
To structure the content of your document, the following document parts can be used and are supported by the Document View:
- A Title Page
- Title Page Header
- Title Page Footer
- Page Header
- Page Footer
Note: These items are configured by your system's SystemWeaver Architect. We suggest that you contact the Architect if any updates need to be made.
Section and subsections are item types specific to the document model in SystemWeaver. They contain the actual content of the document and are editable by end users. Users can modify, add and delete content. The content itself consists of the included sections and subsections and the section structure. Each section of the document can include multiple subsections. In addition, you can expand the document model to include any other item types in SystemWeaver as section items in a document. For example, you can include requirements or components as section items. The important point to remember when it comes to content versus the actual generated document output is that the output is entirely defined by the script in the report XML definition item explained in the next section. In other words, a document may encompass a number of content items, but if those items are not included in the report XML definition and scripted for output, they will not be included in the printed document.
Note: If you add item types other than true sections and subsections to a document, be sure to consult with your SystemWeaver Architect to confirm that they are included in the XML definition you are going to use.
A Report XML Definition
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. So, what you see in the Document View depends on the XML definition item being used by the document. 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. If the Document does include a definition, it will override the default setting. Normally, definitions created by an Architect will include at least the content of the default definition.
The XML definition is managed as a separate item. Typically, a SystemWeaver Architect will create document templates that include XML definitions so that end users only need to select an existing template when creating new documents. If you are unsure which XML definition or template to use for your document, it is best to consult with the requester or your SystemWeaver Architect. They configure the XML definitions using SystemWeaver Script Language which offers a flexible means to adapt the presentation as needed.
Tip: If your organization uses a number of document templates, consider creating an official list in SystemWeaver accessible to all users and Architects. In this way, document template usage will be clearly defined for all users. Example:
Basic Document Meta Model
Below is an example of the standard document meta model shown in the structure tree. Unless otherwise configured by the Architect, the template items are usually listed above the content.
Normally, as a user you are only interested in viewing the content of a document so the template items are typically hidden from the Default tree view setting.
For easy access to the document solution tools, a Documents menu group is available on the Items ribbon tab. There, users can quickly access the following features:
- Document View
- Create new document from this template
- Print Preview
- Header/Footer View
Tip: In addition to the tools described here, the Architect can configure a menu option that end users can use to quickly access a list of approved document templates.
This view enables you to interactively view the content of a document in outline mode. The view does not include any page information like headers and footers. Whenever you select a document or any item within the document in the structure tree, the view will redirect the focus to the corresponding position in the outline. Likewise, If you select anything in the Document View, the corresponding item is highlighted in the structure tree.
The context menu available when using the Document View, provides search options as well as the option to Save As... an RTF file which can then be opened in MS Word:
Create new document from this template
This option allows you to copy an existing document as a means of creating a new one and is the most common way users create new documents. You can chose to copy the entire document or select items in the document to ignore before you copy.
The available options are:
- Create Copy: Creates a copy of the item to create a new item. The new item receives its own unique id. If you create a copy, you will have the option to Include or Ignore the content of that section. If you want to keep an entire substructure identical to the original (template), copying should be avoided since copies create redundant maintenance effort and possible confusion. Often there are sections in documents that are common between many documents, like reading guidelines, terminology etc., and that kind of content should not be copied, but rather included for consistency purposes.
- Include: Includes the existing section in the new document. In other words, the existing section will be reused, i.e., used in multiple documents. If you chose this option, make sure that the original section is released or that any changes to the section are coordinated between you and the author of the section. When you include, you naturally get all the content of the included section. This also means that you cannot modify any of the content. (As you can see in the example above the content below an "Include" section is gray.)
- Ignore: The item will not be included in the new document. If you want to ignore a item that is a sub-item of a section, you must select Create Copy for the "parent" section prior to ignoring the sub-item. In the example below, in order to set "Ignore" for the Audio control design function item so that it will not be copied or included for the new document, the Model section item is set to "Create Copy".
To assist you with setting the copy option for each item, the dialog displays the item's Properties and Description to the right for quick reference.
Note: By default, all document items are set to be included in the new document with this option. If a template is used often by users to create a new document and many items are consistently marked to be ignored, a Clone view can be configured by your system's SystemWeaver Architect to provide users with a document cloning option in the form of a one-click menu button for creating a new document where specific items can be pre-set to be ignored.
This option lets you preview your document before you print it. You can confirm the number of pages and chose to print specific pages only. You must have a document item selected in the structure tree to use Print Preview.
Click in the preview region to toggle between a ~100% and a ~50% preview zoom.
Use the Print button to send the document to a printer.
The Printer field is read-only and displays the currently selected printer.
The Settings button opens the Print dialog where you can make changes to printer settings.
Use the Print range option to select which pages to print.
Use the navigation buttons or keyboard equivalents (PgUp, PgDn) to navigate through the pages.
Print the document using your Windows print dialog.
The Header/Footer option opens the Header/Footer view and is used to design the title page and all footers and headers. These items can contain content such as text, images (e.g., logos), page numbering and often are designed to include one or more document attribute value and/or document properties (field code), e.g., Version, Status, etc. If you are creating a new document from an existing one, you will likely want to modify some of the attribute values at a minimum. In the view, the document's attributes are displayed for you at the bottom of the screen. Just like when modifying an item's Description field, you can opt to work directly in the space provided or double-click to open the editor. As you view the content, you can select to Show field codes (i.e., ::XX:: will display as a placeholder for where the actual values will display when you print) or their respective values (Show field values). The below screenshot is displaying the actual values.
The context menu in the Header/Footer view provides a quick way to add some specific content:
Insert page no.: Inserts a page number field at the cursor position.
Insert attribute: Opens the Select attribute type dialog where you can select among the Document attributes listed at the bottom of your screen.
Insert field: Opens the Field code dialog where you can specify a property of the document to be inserted: (Refer to the Help's Field Codes section for more information including a list of field codes you can use.) The Field code entered must be accurate or the value will not print.
You can learn more about documents in the application's Help. Now that you are familiar with the documents management concept in SystemWeaver, you can begin Creating Documents. A separate article covers configuration for SystemWeaver Architects.