Word Round-trip

Watch a video on the Word Round-Trip here.

Overview

With Round-trip editing of Requirements (or other kinds of issues like Tasks / Bugs etc.) in codeBeamer users can:

• Export several issues to a Word document and view, read or print it in Word
• Edit the issues' descriptions or summary in Word. When editing, users can attach pictures or use rich formatting capabilities of Word
• View comments made by other users on the exported issues
• Add new comments to issues
• Finally easily import back all these changes made in the Word document to the original issues or Requirements
• During import users have the option to review all changes and selectively import only the desired ones

Round-trip workflow

Exporting issues

The next dialog appears, where the "Round-trip" option should be choosen:

When this menu is selected codeBeamer will build a Word document which contains the issues displayed by the current view and the download of that Word document will start in few seconds automatically. The generated file name will contain the current project's and tracker's name, so it is easier to identify later where that export file is originated from.

Please note that when exporting to Round-trip only those issues/requirements will be exported which match the active view in that tracker. So you can easily control which issues are exported by defining a new Tracker view or choosing an existing view that matches your needs.

Editing issues in Word

When opening the round-trip document in Microsoft Word you will see following contents:

• All exported requirements or issues are rendered nicely including all usual formatting (bold, italics etc...)
• The images appear embedded in the Word document as they appeared in codeBeamer
• All existing comments made on the issues are appearing on the side bar and are linked to the appropriate issue

You can immediately start editing the content - modify, add or delete text, insert images or add comments to each issue in the document. Following screenshot shows an example of such an editing session:

The interesting pieces on that screenshot are:

• Each exported issue will have a bounding box (with blueish borders and title "Chassis" in this screenshot). All modifications to this issue must be made inside of this box, as that's the way the importer will find the original issue. Anything that is written outside of such boxes will be ignored during import.
• The Round-trip Word document is using Word's Track changes feature to find the changes you made to the document. As a result Word will highlight all changes, too.
• All comments are appearing on the right side and linked to the issue they belong to. You can make new comments on any text inside the bounding box of an issue, and that comment will be also imported to the respective issue.

Incorporating changes back from Round-trip document to codeBeamer

After finished editing of the Round-trip Word document, it is time to import the changes back to codeBeamer. This can be done with the "Import from Word or Excel" menu in the "more" menu of any tracker.

The first page of the import wizard will appear. Here the round-trip docx document can be selected and uploaded. This is the same wizard that is used for normal - i.e. non Round-trip- import, but the importer will automatically recognize the Round-trip documents, and will display the specialized import page for them.

The importer will read the Round-trip document and scan it for changes. The import wizard will display the changed issues only, and will also show the differences to the original issue. For example this may look like:

The highlights of that page are:

• Import page will only show the issues that were actually changed. The original summary and description of these issues are rendered, plus a link is shown where you can open the affected issue in a new window so the original/current content can be reviewed again.
• The changes found in the imported document are highlighted using a diff algorithm, so that removed text is highlighted in red, added text is green.
• Images inserted to the Word document will be added as attachments to the target issue and correctly referenced from the generated Wiki markup.
• If any new comment has been added to an issue it will also appear on this page. The comments which were previously present when the document was exported will be ignored and not shown.
• Changes to summaries are also highlighted and displayed.
• During import the user can select which changes should be imported by clicking on the "Apply?" checkboxes next to each changed issue.

After reviewing the import data the user can save and apply the changes, whereafter a summary of changes is displayed:

Known limitations and issues

Only Microsoft Word on Windows is supported.

The most important limitation is that only Microsoft Word (version 2007 or above) is supported by Round-trip export. This feature will not work with LibreOffice or OpenOffice as Round-trip uses special features that are available in Microsoft Word only.

Word on Mac is NOT supported either!

All other known issues are listed in codeBeamer trackers, and will hopefully be resolved soon...

Error message when trying to import an unchanged Word export from codeBeamer

If you do this, this won't work:

• Export some items from codeBeamer to Word
• Do not change the export Word file (.docx file) but try to import it to codeBeamer (to a different tracker for example).

This will NOT work because of some technical limitation that requires that the exported Word document needs some conversion made by Word when you change something/anything in the Word document and save it.

codeBeamer detects this scenario (when unchanged Word document arrives) and rejects the import and shows this error message. The workaround is that to modify anything -even just a space- in the Word document and save it, and then try to import the changed Word document.

Why wiki-text are changed during Word-round roundtrip? Why other unwanted changes appear?

When editing some codeBeamer content in Word you may find during the import back that there are some unwanted changes appearing, and some new lines are added or removed or some wiki text -like wiki tables- has different structure than it was before.

Why this is happening?

This is simply because during the Word roundtrip or Office-edit there are several conversions happening, and each conversion can bring in some differences, some of the styling or layout may get lost or even errors may happen.

To explain such conversions happen during Word roundtrip or Office-edit:

• The original wiki text is converted to HTML
• The HTML is slightly modified with CSS so it will look better in Word
• Images are added to the HTML, and they are resized if necessary
• The result HTML is fed to Word, which converts that to its own Word-Markup-Language
• Then while edit this in Word, the change-tracking is turned on so we know which parts are changed during round-trip import
• The round-trip import processes the Word-Markup-Language and converts that back to wiki (also captures images and comments).
• Only those changes are imported back in round-trip which contain "Tracked changes" added by Word.

So during the Wiki->HTML->Word Markup -> Word edit -> Word Markup -> Wiki processing several conversions are taking place.

These conversions can not be perfect because of the largerly different feature set of Word and HTML and Wiki. Word is far more advanced than HTML, and HTML is far more capable than Wiki. Wiki is just largerly simplified subset of HTML. Therefore there will be always some differences or features that can not be converted or kept during these conversions.

Also because the conversion is machine generated the result wiki will never look as nice as human a human written Wiki markup, neither the original wiki markup can not be reproduced perfectly during these conversions. Some new-lines and white spaces will be added here-and-there, some tables will be structured differently and many more differences may appear.

Our primary goal during Word roundtrip and Office edit is to keep every information and structure of the information as much as possible. It is a bit less important to keep the perfect look of the information - like text colors or alignment or fonts-. And then the least important -if possible at all- is to keep the result wiki close to the original wiki text.

FAQ

1. Can I delete specific fields and add additional fields in the roundtrip word file?
   No, Word Roundtrip is limited.
2. What can I change specifically in the excel roundtrip file? Word roundtrip supports rich text files with e.g. images and comments. You can only change editable fields that appear in the roundtrip file, such as:
   

• name
• description
• comments
• severity
• priority and
• business value