Wiki

What is a Wiki?

Wiki, an abbreviation for "What I Know Is", is a widely used concept in collaborative networks. A wiki is a collection of interconnected pages with a simple text based syntax for formatting. A wiki page supports hyper links to other pages. Wikis are also used as a knowledge sharing tool that allow users to add, remove, or otherwise edit and change all content very quickly and easily. To better understand the wiki concept http://en.wikipedia.org/wiki/Wiki is well worth a read.

Also see Wiki Markup and Plugins

Document Baselines is an important new feature in codebeamer 5.5 . It enables you to capture a snapshot of wikis & documentation at a particular time, with particular revision numbers. Please see Baselines for more details.

Credit: codebeamer's Wiki implementation includes many source code modules and ideas from the Open Source JSPWikisystem. It uses the same Wiki syntax. Many JSPWiki plugins were implemented and ported to codebeamer. Thanks to Janne Jalkanen and to the JSPWiki community for the contribution.

What is codebeamer's Wiki?

Unlike many wiki implementations, codebeamer's built-in wiki implementation is an enterprise grade tool. It helps you to capture and manage knowledge in an open, scalable, secured and controlled way. Interrelated artifacts, such as Trackers, Office/Wiki Documents, or Tasks, can be as structured as you wish while allowing a large degree of artifact inter-connectedness.

You can extend codebeamer's Wiki with your own plugins. Using codebeamer's open-source plugins and writing your own plugins as necessary, your work environment can be customized to fit your needs. For example, a plugin could be created to identify the dependency structure, or graph of artifact inter-relatedness.

codebeamer's Wiki can allow your information-flow to be as democratic as Wiki system used by communities, or it can instead allow structured document approval to, for example, implement publication processes.

Efficient communication is a key factor in any successful development project. You can use the wiki to collaborate and to prevent communication problems.

Each project has a separate wiki space that can be accessed by the Wiki tab.

A wiki space consists of individual wiki pages, that can be organized into a hierarchical structure, cross-referenced in various ways and browsed navigating along the links.

For each page, besides maintaining its content, you can:

• set up access rights,
• set approval workflow,
• set up notification settings,
• add comments,
• add attachments,
• check history and restore older versions
• list child pages,
• change permissions based on roles or groups.

Wiki Page Structure

A wiki page has a page tree, a content, a navigation and a property section. In the example below, the page tree is a box in the left and the navigation section is a box on the right, with various links. The property section can be reached by clicking on the Properties button near the top left. The content shown is the top of a wiki for mathematical abstractions, with the document title, and the Table of Contents.

Figure: Wiki page in codebeamer.

The wiki page tree contains the full wiki page structure from the root wiki page (personal or main project wiki page). The wiki content can be loaded by clicking on the wiki page's name in the tree.

In the top of the tree there is a toolbar with three components:

• in the left side there is a collapse/expand button which can be used to hide show the wiki tree.
• search text field: tree ages can be filtered by the specified text (it can search in the wiki name and the content as well which can be configured in the next button)
• settings button: wiki tree and content settings can be configured from the opening dialog

Figure: Wiki settings.

The search scope can be specified by using the first two checkbox: If the wiki page name is checked the wiki page filter show only that items in the tree as result which name contains the specified filter text. If the wiki content is checked then the application will check the wiki content as well.

There are two more settings which can be set:

• HighLight Recently Updated Wiki Pages: a day limit can be specified. If the wiki page in the tree has modification which not older than the specified day the wiki page rendered with green background in the tree. This feature can be disabled by give 0 to the day limit.

Figure: Highlight recently updated wiki pages.

• Show heading numbers: if this feature is enabled the wiki rendering engine injects an auto generated heading numbers inside the wiki. For example the feature is enabled in the left sine, and disabled in the right:

Figure: Heading numbers.

The exported document from wiki not contains the auto generated header numbers regardless the feature is enabled or not.

Writing Content

When you edit a Wiki Document, the Wiki editor overlay has 3 modes. The first 2 modes, Rich Text and Wiki Markup, allow edits. The third mode Preview does not allow edits, and is only for viewing. You can switch between modes in the Rich Text options menu.

Figure: Rich Text options

Wiki content is saved in a special notation, the so-called wiki markup syntax. This is a simple and flexible language to produce clean, structured on-line information. Besides the standard basic text elements like paragraphs and headings or more advanced ones like tables and inline images, codebeamer supports additional markup constructs targeting the developer audience.

Rich Text View

For instant editing, use the Rich Text editor. It has familiar word-processing features and buttons to include images and links. The Rich Text view removes the learning curve typically required to start with Wiki. It helps you to add tables, images, links and easily edit text.

Figure: Rich Text View in Wiki Edit Overlay

In CB-9.0.0 the Rich Text view is updated. The editor toolbar can be found at the bottom of the edited wiki content, and the editor buttons are grouped into several toolbars like the Formatting options, Advanced options, Link options and Rich Text options.

There is a new feature introduced in CB-9.0.0 which provides editing in an overlay window. The 'Toggle Overlay' button can be found on the main editor toolbar. The toolbar of the editor is moved to a new location when editing a Wiki section in CB-9.1.0, it is under the action bar.

Multiple file upload

From codebeamer 9.4.0 you can upload multiple files at the same time using Drag&Drop or editor's Upload File button.

Mentioning Members / Teams / Areas

From codebeamer 9.4.0 you can mention project Members / Teams / Areas within the rich text editor. Type @ key, and some beginning characters and you will get a small autocomplete overlay from where you can select the designated Member / Team / Area.

Kindly note: Opposite to "Comments & Attachments" section, Mentioning Members / Teams / Areas within the rich text editor area will not trigger email notifications.

Diagram Editor

Diagram Editor is a tool where we can create or edit diagrams.

It is integrated into wysiwiy. There is a button in the Advanced options menu on the toolbar where the editor can be started.

Options:

• Insert or Edit Diagram
  If this option is selected then the Diagram Editor is displayed. You can create new diagram which will be inserted after you press the Save button.
  
• Insert from Documents
  If this option is selected then a dialog box is displayed where we can select diagrams from Documents.
  

Wiki Markup View

Alternatively you can switch to Wiki Markup view of the editor. This shows the raw text, links, plugins, etc. as they are stored and interpreted/compiled by the Wiki engine.

Figure: Wiki Markup View in Wiki Edit Overlay

Wiki Preview

This mode allows a quick view of how the finished Wiki page will appear. This view is not editable. The Preview does not refresh the Table of Contents and other Wiki Plugin Contents.

Edit Wikis in MS Word

codebeamer wikis can be edited in MS Word. Please see Editing Wiki Pages with Microsoft Word for more information.

Copying and Pasting Wiki Documents

In CB-5.3 wiki pages and their children can be copied recursively. To copy a wiki page and its children to the clipboard, select Copy from the Actions menu of the source page.

To paste the wiki page and its children, select Paste from the Actions menu of the destination Wiki page, or select Paste from the More actions ... menu in the Children tab of the destination (or target) Wiki page.´ The copied Wiki page becomes a new child under the (destination) parent page. It is visible under Properties, in the Children tab. Its children are visible under its own Properties → Children tab, and so on.

Upon paste, you will be presented with a popup that shows the hierarchy of pages to be pasted and allows you to continue or cancel.

Figure: Pop-Up Showing Paste Hierarchy with Options to Paste or Cancel

You must login to see this link. Register now, if you have no user account yet.
The pasted pages will be added as children of the destination/target page. Because the destination page does not contain references to these new children, you will not be able to see/navigate to the new child pages, unless you edit the destination page and manually add references to them. The document numbers of the new child wiki pages will appear either in the URL field when you navigate to them by clicking the link in the Children tab in Properties, or the document number will appear in a tooltip, when you hold the cursor over the document name in the Children tab of Properties .

Wiki Page Properties

Wiki page properties are used

to add:

• child pages
• comments and attachments
• links
• associations

to view:

• page history
• document approval

to change:

• permissions
• Maximum number of versions stored and displayed in the History tab. This value can be set in tab Wiki ►Max. Versions drop-down list.
  

Figure: Wiki Properties Display

Commenting Pages and Attaching Files

You can leave your questions, answers or notes as comments attached to any page by opening the Comments & Attachments tab:

Figure: Comments and Attachments Tab in Wiki Properties

Discussions related to the topic of the page are an essential part of a content reviewing process.

You can also easily upload and associate files with any page by opening the Comments & Attachments tab and clicking Add Comment. The resulting Wiki-Editor-type pop-up window allows you to enter comments and to browse for documents to attach.

These attachments are used for:

• sharing content with other users;
• inclusion in the owner page, for example to display inline images.

Associations

Associations are used to list related documents and functions.

Figure: Associations Tab in Wiki Properties

Links

The Links tab shows incoming links (other documents that link to this document) and outgoing links to other documents.

Figure: Links Tab in Wiki Properties

Children Pages

Using the Children tab in Properties, you can organize your pages into a tree hierarchy, using any grouping based on your demands. At project creation time only the root of the page tree exists. You can start adding information immediately by editing it or by adding new pages.

When you are editing the wiki page and need a new child page, the simplest way to add a child page is to enter:

[my marketing page]

When you save the current page a new child page called my marketing page will be created. The Wiki link in the parent page will point to the non-existing my marketing page Wiki page. It will be decorated with a little new icon as shown below, and clicking the new link brings up the Wiki editor, to allow you to add content to the new child page.

You must login to see this link. Register now, if you have no user account yet.

The document number will be assigned after the new child page has content. Then the document will be viewable under the Children tab. One easy way to find the document number is to place the cursor over the link to the child page, and look at the last number displayed on the bottom area of your browser.

Alternatively, you can

1. Click the Properties link,
2. Select the Children tab,
3. Click New Child Page link,
4. Edit the contents of the new child page,
5. Click Save.

The child pages (Children) of a document are displayed under the Children tab under the Properties.

Figure: Children Tab in Wiki Properties

Notifications

You can subscribe to individual wiki pages to keep track of changes by opening Notifications tab in Propertiesview:

Figure: Notification Tab in Wiki Properties

After activating it, you will receive notification e-mails about every page access (read) and update (write).

Permissions

The Wiki page Permissions are based on user role and group level. Read and edit (write) access is controlled at each wiki page level, in a very similar way to how the Document Manager works.

To set page level read/edit security:

1. Select the Properties link,
2. Click on the Permissions tab,
3. Select the checkboxes from the Read and Edit columns for each of the user roles,
4. Click on Save to activate the settings.

Figure: Permissions in Wiki Properties

You can set the permissions recursively for all child pages

Approvals

In Properties, you can view the Document Approval Workflow approvals flow of this document using the Approvals tab.

For more information, please see You must login to see this link. Register now, if you have no user account yet.

Figure: Approvals Tab in Wiki Properties

Page History

Page content is fully audited and versioned. The History tab in Properties allows you to see the changes between the revisions. You can also restore a previous version of the page at any time.

Figure: History Tab in Wiki Properties

Importing Issues and Wiki Pages from RTF (Microsoft Word Documents)

Importing Requirements from RTF

You can create issues from your RTF document. This option is available under more menu in Requirements tracker.

Rules of import:

• Each heading creates a new issue.
• Heading texts will be used as issue summaries.
• Paragraphs between headings will be used as issue descriptions.
• Hierarchy of paragraphs in original document is preserved. If paragraph B has smaller heading than paragraph A, issue B will be child of issue A.

Importing Requirements from Non-RTF Documents

It is possible to import doc and docx formats. In this case, codebeamer performs Doc to RTF to Wiki conversion. This requires OpenOffice or LibreOffice installation on server. The feature is available for importing requirements only.

1. Expand more menu of Requirements tracker.
2. Click Import from Word or Excel.
3. Select option Word/Office Documents or Rich Text Format.

Importing Wiki Pages from RTF (MS Word Documents)

codebeamer can convert RTF (Rich Text Format) files to wiki markup. You can find this option as Import From Word in wiki page action bar.

Known Limitations of Importing RTF

1. RTF Specification, Version 1.9.1 is supported. This means documents that are created in Microsoft Office Word 2003 or newer.
2. Supported image formats: gif, png, jpeg. Other image format (including vector graphics) will not be converted.
3. Headings (paragraphs) are detected by their conventional style names: Heading 1, Heading 2, Heading 3, Heading 4, Heading 5. Other text independently of font size and style will be treated as normal text body.
4. For tables, the converter does not support special cell styles (custom background and border color, border width, margins, spacing).
5. Text placed inside vector objects (like rectangles) is ignored.
6. Equation formulas are not supported.
7. MS Office-specific list styles are not preserved. List a) b) c) will be converted to 1. 2. 3.

Generating Specification Documents: Exporting Issues (Requirements) to MS Word Documents

codebeamer can export issues from requirements trackers into DOC files. To find this option open Requirements tracker, move mouse over the more menu and click Export to Word.

Technically speaking, the generated document is in MHTML format, a multipart HTML document format that is natively supported by newer MS Word version. The .doc extension makes Word the default editor for created file.

The following properties of the issues are exported to the document:

• Summary
• Description
• Revision
• Business value (priority)
• Status
• Issue references (associated issues, child and parent issues, etc.)

Customizing the MS Word Output

It is possible to freely customize the document generated from requirements. You can tune both the content and its formatting.

As mentioned above, the output document is in MHTML format. The content is generated by rendering two Velocity templates. In order to customize the output, modify the following templates:

• <cb tomcat dir/webapps/cb/config/templates/html/requirement-document-export-body.vm
• <cb tomcat dir/webapps/cb/config/templates/html/requirement-document-export-headerfooter.vm

The following objects are available in the Velocity context and can be used in template:

Tip: check this paragraph for details on the codebeamer domain model classes.

Generating Documents: Exporting Wiki Pages to PDF, RTF and HTML

You can export the content of the current wiki page to a PDF-file (suited for printing to paper or for static export), an RTF file or an HTML document. There are a few options:

To export the current page only to PDF, click more -> Export to PDF when viewing a wiki page.

To export a set of pages to PDF, use the ExportWiki plugin (see Printing to PDF), or use the more -> Export Multiple Pages to PDF GUI.

To export anything to HTML, use the more -> Export Multiple Pages to PDF GUI, and there is a button to select HTML output.

To export to rtf, use the ExportWiki plugin which is documented in Printing to PDF. The ExportWiki plugin documentation describes how to select RTF output format.

For example, generate a PDF Document from the Wiki pages with IDs 1004 and 1005 using the ExportWiki plugin with the following statement put in a wiki:

[{ExportWiki id='1004,1005' format='pdf'}]

This results in a link in the existing wiki page called "Export as PDF" that creates a document when selected:

You must login to see this link. Register now, if you have no user account yet.

For more information about how to use the ExportWiki plugin, please see Printing to PDF

Customizing the PDF Output

The ExportWiki plugin offers both content- and formatting customizations, beyond the parameter selections defined in the ExportWiki documentation, however they require XSL-FO experience. codebeamer relies on the open source Apache FOP project as print formatter.

codebeamer will transform the HTML output of a wiki page to XSL-FO using the INSTALL_DIR/tomcat/webapps/cb/WEB-INF/classes/xhtml2fo.xsl stylesheet. You can freely edit this stylesheet to fine tune the output to fit your needs and company standards.

Changing the Font Set to Support Asian and Eastern European Languages

For Asian or Eastern European language characters, you have to switch the formatter to use character sets that support the special Chinese, Korean, Japanese, Czech, Hungarian, etc. glyphs. There are 4 separate font families to support them, in addition to the default "Helvetica". Make sure that exactly one of the font families is activated!

To make the switch, please uncomment the appropriate section in WEB-INF/classes/xhtml2fo.xsl (around line 65) and restart codebeamer:

<!-- Remove this if you want to use Eastern European, Chinese, Japanese or Korean character support -->
<xsl:attribute name="font-family">Helvetica</xsl:attribute>
<!-- Uncomment this for Eastern European support (arial*.ttf) -->
<!--
<xsl:attribute name="font-family">Arial</xsl:attribute>
-->
<!-- Uncomment this for simplified Chinese serif character support (simsun.ttc) -->
<!--
<xsl:attribute name="font-family">SimSun</xsl:attribute>
-->
<!-- Uncomment this for Japanese serif character support (msmincho.ttc) -->
<!--
<xsl:attribute name="font-family">MSMincho</xsl:attribute>
-->
<!-- Uncomment this for Korean serif character support (batang.ttc) -->
<!--
<xsl:attribute name="font-family">Batang</xsl:attribute>
-->
-->

Known limitations of the PDF/RTF export

Editing Wiki Pages Using Microsoft Word

Edit your wikis using Microsoft Word. See Editing Wiki Pages with Microsoft Word

Wiki as Framework - Combine Content using Plugins

Using these enhanced features you can:

• reference codebeamer documents, tracker items, reports or forums,
• add graphical charts, graphs or even UML class diagrams.

Figure Wiki Chart Plug-in examples.

You must login to see this link. Register now, if you have no user account yet.

Figure Wiki UML and MindMap Plug-in examples.

You must login to see this link. Register now, if you have no user account yet.

For detailed information about Plug-ins and the Wiki markup syntax, please see the Wiki Markup and Plugins page.

Wiki - Advanced

Most of the complex or dynamic content of a wiki page, like reports, charts, MS-Excel or graphs, is served by plug-ins.

You can combine (embed) codebeamer internal content such as reports, documents, tasks, requirements, bug and other artifacts into wiki pages.

The document You must login to see this link. Register now, if you have no user account yet. can be embedded into this page

[{ExcelPlugin id='22950'}]

with the Excel plugin using the syntax above.

The result is:

ExcelPlugin plugin failed: Failed to convert XLS to HTML: Document (id: 22950) not accessible by user (id: 2853)
(com.ecyrd.jspwiki.plugin.PluginException:Failed to convert XLS to HTML: Document (id: 22950) not accessible by user (id: 2853), com.ecyrd.jspwiki.plugin.PluginException:Document (id: 22950) not accessible by user (id: 2853))

You can make the spreadsheet editable, and you change the spreadsheet the Wiki content is changing.

Embedding the BestContentPlugin using the syntax:

[{BestContentPlugin max='5' projectId='37' entityType='WIKIPAGE' title='Best Wiki pages'}]

will result:

You can combine ratings into a Table, using the following syntax

[{Table

|(vertical-align:top;) [{BestContentPlugin max='5' projectId='37' entityType='WIKIPAGE'
title='Best Voted Wiki pages'}] |(vertical-align:top;)[{BestContentPlugin  max='5'
projectId='37' title='Best Voted Forum
posts'}]|(vertical-align:top;)[{BestContentPlugin max='5' projectId='37' entityType='DOC'
title='Best Proposals in Documents'}]
}]

will result:

See Wiki Markup and Plugins and at Developing Wiki Plugins. To integrate with external systems or customize your own wiki, the plug-in mechanism is the primary extension point.

Embedding Reports into Wiki pages

You can embed reports into Wiki pages using the Report Wiki plugin.

The Wiki plugin

[{Report id='22556'}]

will result:

Report plugin failed: Could not find plugin Report
(com.ecyrd.jspwiki.plugin.PluginException:Could not find plugin Report, java.lang.ClassNotFoundException:Class 'Report' not found in search path!)

There are two additional fields that can be used for display and sorting in merged reports: Project and Key. The Project field represents the codebeamer project the tracker belongs to. The Key field is the internal tracker key in the system.

Collaborative Section Review

Application offers a simple way to collaboratively review blocks of texts within the wiki content. This functionality builds on the commenting capabilities of the platform. Users can start a review from the WYSWYG editor by selecting some text and creating the first comment. After that other users can add further comments to the review comment thread.

Creating a Section Review

Any user with sufficient permissions can initiate section reviews. User must have:

• permission to add comments in the tracker,
• permission to edit items in the tracker,
• permission to edit the wiki field.

Specific steps for the process are as follows:

First initiate editing of a wiki field and select some text.

Click on the Add Comment icon in the toolbar.

Type the comment and click on Save button

After saving the section review colored triangles appear in the wiki content. These triangles mark the start and the end of the text block. Furthermore a new comment appears in the Comments & Attachments tab.

Adding Comments

Users can add further comments to a section review. These comments form a thread and will be displayed as replies to the initial comment. User must have the same permission as described in the previous section to add new comments. Otherwise:

• If any of the editing permissions is missing, then the user only sees a read-only list of the existing comments.
• If the user does not have permissions to see the comments, then a warning appears.
  

First, open a page where the tracker item and the wiki field are displayed. (Details page of the tracker item, any kind of view, like Table View or Document View etc.) Make sure that wiki field is in read-only mode. The following functionality does not work on the editing screen, or if the inline editing is active for the field!

Locate the start or end triangle in the wiki content, which belongs to the section review.

Click on the triangle. A dialog opens. It contains all the existing comments and a comment editor, if the user has proper permissions.

Type some text and click on the Save button. A new comment appears in the comment thread.

Ending a Section Review

Ending a review involves editing the tracker item. User with permissions to edit both the tracker item and the wiki field can remove the triangles from the wiki content, which effectively closes the review.

Initiate editing of a Wikitext field.

Delete one of the triangles. This action removes its pair automatically.

Save the changes.

Hiding Section Reviews

Users can decide to hide the triangle indicators in read-only mode of the tracker item by switching off the related option on the Preferences dialog. For more information about the user preferences see User Preferences page. Triangles always show up in editing view of the tracker and item and while inline editing the wiki field.