You are not logged in. Click here to log in.

codeBeamer ALM

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 Baselining: Document- and Wiki 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 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 pop-up Wiki editor window has 3 tabs. The first 2 tabs, WYSIWYG and Wiki Markup, allow edits. The third tab Preview does not allow edits, and is only for viewing.

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.

WYSIWYG View

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

The Toggle Basic/Advanced mode button allows you to set the editor to allow a larger or smaller number of word-processing-like features.

Figure: WYSIWYG View in Wiki Edit Window

Diagram Editor

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

It is integrated into wysywig. There is a button on the toolbar where the edior can be started.

ALT_WIKI:%5B!mceclip215aa38ec11b.png!%5D

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.
    ALT_WIKI:%5B!diagram_editor_open.png!%5D
  • Insert from Documents
    If this option is selected then a dialog box is displayed where we can select diagrams from Documents.
    ALT_WIKI:%5B!diagram_editor_insert.png!%5D

Wiki Markup View

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

Figure: Wiki Markup View in Wiki Edit Window


Wiki Preview

This tab 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 Using 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 PropertiesChildren 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


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

or to view:

  • page history
  • document approval

or change:

  • permissions

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 & Attachmentstab:

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.

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

Wiki Approval Workflows, Publishing Workflows

Approval workflows can be applied to Wiki pages, see more information You must login to see this link. Register now, if you have no user account yet..

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 ppreserved. If paragraph B has smaller heading then 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 threated as normal text body.
  4. For tables, the converter doesn't 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:

Key Class Description
request HttpServletRequest
user UserDto
currentDate Date
project ProjectDto
requirementTracker TrackerDto
requirements SortedMap<ReleaseId, TrackerItemDto> ReleaseId class provides indexing and sorting for requirements.
Use ReleaseId.getRelease()
baseline Baseline Only available when exporting a baselined set of issues.
When exporting the HEAD (the latest revision), it's not available.
wikiMarkupProcessor WikiMarkupProcessor
incomingReferencesByIssue Map<Integer, Map<String, List<TrackerItemDto>>> Keyed first by the item ID, then by the field name and it maps to a list of tracker items.
outgoingReferencesByIssue Map<Integer, Map<String, List<TrackerItemDto>>> Same like the previous.


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:

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

Cause Description
FOP limitation Glyphs in Asian .ttf files are available only as "normal", no "bold" or "italic". FOP will not render these, but will ignore formatting.
FOP limitation No implicit auto line-breaks for Asian text if there is no explicit whitespace character inserted.
FOP limitation FOP can't fit table columns to the minimum necessary width, but all columns of a table will be 100%/noOfColumns wide.
FOP bug FOP throws exceptions when <table>'s have different cell count per row. This can be caused by both XLS plugin and regular wiki tables.
FOP limitation GIF export in RTF is not supported. It was added after FOP release 0.93!
FOP bug horizontal rulers are not exported to RTF!
FOP bug exporting structure of lists and ordered lists to RTF is buggy.
FOP limitation images are never resized, so it's very likely they can flow beyond the right margin.

Editing Wiki Pages Using Microsoft Word

Edit your wikis using Microsoft Word. See Editing Wiki Pages Using 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.

Figure Wiki UML and MindMap Plug-in examples.

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 DemoBudgetPlan.xls can be embedded into this page

[{ExcelPlugin id='22950'}]

with the Excel plugin using the syntax above.

The result is:

DemoBudgetPlan.xls

 Budget Plan
   2006 2007 2007
 Staff $750,000.00 $850,000.00 $950,000.00
 Infrastructure $100,000.00 $100,000.00 $75,000.00
 Tools $600,000.00 $120,000.00 $40,000.00
 External Help $350,000.00 $390,000.00 $100,000.00
 Ads $170,000.00 $222,222.00 $30,000.00
        
 Total $1,972,006.00 $1,684,229.00 $1,197,007.00

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:

Best Wiki pages
DocumentRating
General System Requirements
 
 
 
 
 
Average rating is 5 by 1 user(s).
Document Manager
 
 
 
 
 
Average rating is 5 by 1 user(s).
Using Subversion with CodeBeamer
 
 
 
 
 
Average rating is 5 by 1 user(s).
Software Subscription and Support
 
 
 
 
 
Average rating is 4.3 by 3 user(s).
Wiki Markup and Plugins
 
 
 
 
 
Average rating is 4 by 3 user(s).

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' entityType='FTC' title='Best Voted Forum
posts'}]|(vertical-align:top;)[{BestContentPlugin max='5' projectId='37' entityType='DOC'
title='Best Proposals in Documents'}]
}]

will result:

Best Voted Wiki pages
DocumentRating
General System Requirements
 
 
 
 
 
Average rating is 5 by 1 user(s).
Document Manager
 
 
 
 
 
Average rating is 5 by 1 user(s).
Using Subversion with CodeBeamer
 
 
 
 
 
Average rating is 5 by 1 user(s).
Software Subscription and Support
 
 
 
 
 
Average rating is 4.3 by 3 user(s).
Wiki Markup and Plugins
 
 
 
 
 
Average rating is 4 by 3 user(s).
BestContentPlugin plugin failed: Invalid entityType parameter, please use BestIssues plugin for entities, because this plugin is for Forums or Artifacts only!
(com.ecyrd.jspwiki.plugin.PluginException:Invalid entityType parameter, please use BestIssues plugin for entities, because this plugin is for Forums or Artifacts only!)
Best Proposals in Documents
DocumentRating
No pages rated.

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: Report (id: 22556) not found.
(com.ecyrd.jspwiki.plugin.PluginException:Report (id: 22556) not found.)

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.

Embedding Tracker Item State History Report Plugin

The TrackerItemStateHistory Wiki plugin shows the state change history of an issue (or bug, task, etc.), identified by its task-id. You must login to see this link. Register now, if you have no user account yet.

The Wiki plugin

[{TrackerItemStateHistory id='25479'}]

will display the issue's state change history.

TrackerItemStateHistory plugin failed: Can not find task with id=25479
(com.ecyrd.jspwiki.plugin.PluginException:Can not find task with id=25479)


Invalid source file: /help/WikiHelp.wki. Please add your source file to one of the following folders: /home/codebeamer/CB/repository/include, /home/codebeamer/CB/tomcat/webapps/cb/help