Codebeamer DOORS Bridge

Codebeamer DOORS Bridge

Codebeamer DOORS Bridge is a Java application, running as a Web Service in an Apache Tomcat® container, that provides online web access to an IBM® Rational® DOORS® installation on the same server.

DOORS Bridge was developed and tested against IBM® Rational® DOORS® 9.6.

Prerequisites

The following steps are required prior to installing Codebeamer DOORS Bridge on a 64-bit Windows 8.1 or newer system, supported by IBM® Rational® DOORS®.

1. Download and Install a 64-bit Java SE Runtime Environment (JRE) or a full Java Development Kit (JDK), version [1.]8.
   • The location of the installed JRE (e.g. C:\Program Files\Java\jre1.8.0_341 ) must be made available in an environment variable called JRE_HOME.
   • If you installed a full JDK, then the location of the JDK must be made available in an environment variable called JAVA_HOME, e.g. C:\Program Files\Java\jdk1.8.0_341 .
     
     
2. Install an IBM® Rational® DOORS® client, version 9.6 or later. We recommend DOORS 9.7.2.1 or newer.
   • DOORS Bridge in combination with DOORS versions older than 9.6 does not work, due to missing DXL functions.
   • Only the IBM® Rational® DOORS® client must be installed on the same server, where Codebeamer DOORS Bridge is going to be installed.
   • The IBM® Rational® DOORS® Database Server and the IBM® Rational® License Key Server can be located anywhere on the network.
     
     
3. If OLE objects, are embedded in rich text attributes of objects to export via Codebeamer DOORS Bridge, then all applications associated with OLE objects to export must also be installed on the same machine where Codebeamer DOORS Bridge is going to be installed.
   • E.g. Adobe Acrobat for PDF, Microsoft Office for MS Word and Excel, etc.
   • If there is no associated application installed for a specific OLE object, the IBM® Rational® DOORS® client
     • will not be able to export the unregistered OLE object at all, or
     • will only export a preview picture (in some cases the OLE preview picture may be totally blank).
       
       
4. If you intend to export huge DOORS® modules with 10.000s of objects and hundreds/thousands of embedded OLE objects, then the server, where DOORS Bridge and the DOORS® client are installed, should have at least
   • 8 cores
   • 8 GB of available memory
   • 256 GB of free disk space in the volumes where BRIDGE.tempDir and DOORS.localdata resides (see below).

Download and Installation

Importing Requirements via the Codebeamer DOORS Bridge

Importing requirements from IBM® Rational® DOORS® via the Codebeamer DOORS Bridge is available in CB-8.2.0 and newer.

Each Codebeamer Tracker can be associated with at most one DOORS Formal Module at a time!
Such an association can be configured any time, even for trackers that are not empty.

If you want to import multiple DOORS Modules from the same DOORS Project/Folder, then please check Importing DOORS Projects, Folders and Baseline Sets via codeBeamer DOORS Bridge.





If the current tracker is not associated with a DOORS module yet, and you have Tracker Admin permissions, you can choose to configure it now:

DOORS Bridge Settings

First you have to enter the Web-Address (hostname, ip-address and port) of the Codebeamer DOORS Bridge Server and a DOORS Username and Password to login:





DOORS Bridge is a transparent proxy for the underlying DOORS instance, that forwards all requests to DOORS, including the user authentication.
So basically you can use any DOORS user, but in combination with DOORS Bridge only users with Edit DXL (in batch mode) permission will work:





Then you need to Select... the DOORS Formal Module to associate with the current tracker:





If you are not sure, whether the selected module is the correct one, then you can show a Preview... of the first 50 entries.
Please note, that generating a preview with lots of embedded images and objects may take a few seconds.


The import from the selected DOORS module is Enabled by default, but you can disable (and re-enable later) at any time, by (un-)checking the appropriate checkbox.




Since CB-9.2 and newer, you have also to decide, whether to Trust the DOORS history of the selected Module or not ?

Bad experience with real life customer DOORS installations showed, that the DOORS object history is not always reliable, e.g.

• Attribute values have changed between baselines, but the lastModifiedTime of the objects did not change, nor does the object history contain this change.

If the DOORS history can be trusted:

• Consecutive imports will be incremental imports, that will only import objects, that were modified since the previous import, based on the lastModifiedTime of the objects and the object history.
• Incremental imports are significantly faster than Initial/Full imports, but can cause data loss, should the DOORS object history be actually flawed !

If the DOORS history can not be trusted:

• Not only the first/initial import, but also consecutive imports, will always download the full module/baseline. Depending on the size of the module, this can take quite some time.
  • The object change history is re-build upon the import by comparing the newly loaded values against the values from the previous imports.
  • If the DOORS history is also imported (see below), the imported history entries (changes) and the computed differences will be merged into a consistent history.

If you are importing historic module baselines, and are not sure about the quality of the baseline history, then import the baselines without trusting the DOORS history!
Since this is a one time migration, the quality of the imported data should have precedence over the duration of the import.

But it should be save, to switch to incremental imports, after the initial migration is finished and before you start an automatically/periodically recurring synchronization.

Lock Module and Link Objects

These options are for migrating DOORS modules to Codebeamer:

• Lock module
  • will lock the module in DOORS as "migrated", after having imported all relevant baselines and the current version to Codebeamer.
  • The specified DOORS user must have permission to lock/control the DOORS module, and the module must not be locked otherwise.
  • Because Lock module will prevent further editing of the module in DOORS, it is not necessary to check for updates in DOORS periodically.
    • The option Run every interval (see below), will therefore be disabled!
  • The only way to remove that lock later, is to remove the association between the DOORS Module and the Codebeamer tracker (see below).
• Link objects
  • will add external links to all objects in the DOORS module, that refer to the migrated items in the target Codebeamer tracker.
  • Only available in combination with Lock module and only, if the specified DOORS user has permission to modify the DOORS module.

DOORS User Handling

Before you start with mapping DOORS Module Attributes to Codebeamer Tracker fields, you should decide, how to handle DOORS User references:



In order to map DOORS user attributes, e.g. Created By, Last Modified By, etc. to the appropriate Codebeamer item fields, e.g. Owner/Assigned to, etc., you have to enable Users import (requires Codebeamer User Admin permission!):

• All DOORS Users referenced by imported DOORS objects, where no appropriate Codebeamer user (with the same name) already exists, will be created as Codebeamer users
• Only these user attributes will be imported:
  • user name,
  • first/fore/given name,
  • last/sur/family name,
  • email address,
• All imported users will be initially disabled,
  • because their password cannot be imported and has to be reset manually, before such a user can log into Codebeamer.
  • to not exhaust the available number of Codebeamer user licenses.
• Because this synchronization is on tracker level, the imported users will not be member of the Codebeamer Project !

DOORS Attribute Mapping

Next you have to map DOORS Module Attributes to Codebeamer Tracker fields:





By default only the object Id, Summary and Description are mapped automatically, all other Attributes need manual mapping.

For choice attributes, choice values also have to be mapped to Codebeamer ALM's choice options (missing choice options can be created via -- New..., if necessary).
E.g. DOORS Attribute Priority mapped to Codebeamer Field Business Value:





If there are lots of DOORS choice values, that all need to be mapped to new target choice options, you can automatically map all of them at once:




If you want to import an attribute, but there is no appropriate target tracker field yet, you can add a new tracker field, based on the DOORS attribute definition, via -- New....
E.g. Map DOORS Attribute Status to a new custom field named "DOORS Status":









If there are lots of DOORS attributes, that need to be mapped to new target fields, you can also use the Attributes Import all function, to automatically maps all attributes,

• that have not been mapped yet, or
• whose name starts with a selected prefix,

to new target fields, whose name and type are derived from the attribute.

You can also Ignore all attributes, whose name starts with a selected prefix.

DOORS modules can also have special attributes, whose values are computed upon access via the DOORS eXtension Language (DXL).

Importing lots of objects with DXL attributes can be slow!

At the end of the Attributes mapping, you should also decide, whether to also import:

Unless you have specific reason, Attachments should always be imported, because this includes Pictures and OLE objects embedded in the DOORS requirements text.

If you want to make a clean cut and only import the current head revision of the DOORS module, then you should not import Users, Discussions and History!

If you want to migrate from DOORS to Codebeamer including the past, then you should at least import Users and History!

Please note, that you can only import DOORS Object Discussions and History, if you are also importing the DOORS Users !

DOORS Link Mapping

DOORS Object Links can be mapped to Codebeamer Associations, based on the Link Module:

Link attributes can be mapped to Association attributes in the same way than Object attributes:

DOORS Import Interval and History

The DOORS Import can be configured to run automatically in the background, e.g. every 4h:





The smallest allowed import Interval is 10 min.

If the import runs very frequently, you should limit the size of the import History/Log, e.g. to only keep the last 100 imports.

Please note: the first/initial import has always to be started manually!

Re-Using DOORS Bridge Settings

In order to re-use the DOORS Bridge Settings of one tracker (as a template) for other trackers as well, you can

• Save a configuration as a configuration file, and then later
• Load this configuration file when configuring another tracker import.

Please note, that loading a configuration from file will overwrite the current settings. So you should do this right at the beginning !

Removing DOORS Bridge Settings

In CB-9.0 and older, you cannot remove DOORS Bridge Settings from a tracker, once it was configured.

The only way to re-assign a DOORS Module, that was previously associated with a tracker X, to another tracker Y, was to irreversibly delete

• the tracker X
• or the whole project, where tracker X belonged to.

Since CB-9.1, you can now remove the association between a DOORS Module and a tracker, via Remove... in the DOORS Bridge Settings dialog.

This is also an irreversible process, that will delete

• the DOORS Bridge settings of the tracker,
• the DOORS import history of the tracker,
• the DOORS import job/schedule of the tracker, and
• the DOORS import status of all imported tracker items in this tracker, including the original DOORS object id.

But in contrast to deleting the tracker: the tracker itself, the tracker configuration and also the tracker items will remain.

But beware: Tracker items, that were previously imported from DOORS, are now not longer recognized as such!

• If you later import other DOORS objects (into a different tracker), that have links to objects, that were previously represented by items in this tracker,
  • then the newly imported items will not be associated with any items in this tracker.
• Should you later setup Import from DOORS for that same tracker again, perhaps even associated with the same DOORS Module than before:
  • Importing will not update any existing tracker items, but will instead create new items for all objects in the DOORS module.

If you only want to disable the import from the selected DOORS Module, without loosing any import settings, history and status, and with the possibility, to re-enable it at any time later, then simply uncheck the Enabled checkbox, but do not delete the DOORS Bridge settings!

In CB-10.0 and newer, you can implement and deploy a Tracker Synchronization Listener, in order to be notified, whenever a Tracker is attached/detached with DOORS or the DOORS Import Configuration changes.

Import from DOORS

After having completed the DOORS Bridge configuration, or any time via Tracker -> Import from DOORS, you can now start a new Import from the associated DOORS Formal Module:

Importing from DOORS is an iterative process:

• The first/initial import will always be a full import.
• All subsequent imports are incrementalimports, that will only include objects, discussions and comments,
  • that have been created/updated since the last import, or,
  • in case the last import was a baseline import: are newer than the imported baseline.

Please keep this in mind, when planning a migration from DOORS to Codebeamer. You can migrate DOORS Modules including

• Baselines,
• History,
• Discussions and Comments.

But you must import Baselines in proper chronological order, and you must decide how far back to start with the import.
Selectively importing baselines is also possible, but beware

• Skipped baselines cannot be imported any more later, and,
• because each DOORS Baseline exclusively holds the time segment of the module's history between the creation date of the previous baseline and the creation date of this baseline,
  • this period of time will also be missing in the imported history (if any)

Please also note:
If you have configured automatic import in regular time intervals, this scheduled import (of the current/head revision) will only start after the first/initial manual import of the current/head revision!


In CB-9.1 and newer:

• If there are importable Baselines:
  • All baselines are selected for import by default. You have to de-select any baselines you want to skip.
  • OK will start importing the selected baselines in proper chronological order, or close the import dialog, if no (more) baselines are selected or can be imported.
    • The import will stop automatically, as soon as an error occurs, or all selected baselines have been imported successfully.
    • The statistics about a successful import are not shown automatically. You have to click on the name link of an imported baseline, to show them.
    • Therefore, the import dialog will stay open after the import has finished or was cancelled.
    • To repeat a failed or cancelled import, simply click OK again.
  • Cancel will cancel the currently running import, or, if no import is active: close the import dialog.
• If there are no importable Baselines (only the current HEAD revision of the DOORS Module)
  • OK will start importing the current module version
    • The result of the import will be shown automatically: Either statistics upon success or an error message upon failure.
  • Cancel will close the import dialog, without doing an import.

In CB-9.0 and older:

• Only the current (head) revision of the DOORS Module will be imported by default.
• To see (and select) any importable baselines, you have to pull down the Baseline selector.
• If you have selected multiple baselines to be imported, e.g. "0.1" and "0.2"
  • OK will start to import the first selected baseline.
    • The result of the import will be shown automatically: Either statistics upon success or an error message upon failure.
    • If the import was successful and there were more baselines selected for import:
      • You have to decide whether to Continue with the next baseline (if any), or to Cancel the outstanding imports.
    • If a baseline import fails, or you Cancel the outstanding imports: the import dialog is closed.
  • Cancel will close the import dialog, without doing an import.
• If you have only selected one baseline, or there is only the current (head) revision to import
  • OK will start importing the selected baseline or the current (head) revision
    • The result of the import will be shown automatically: Either statistics upon success or an error message upon failure.
  • Cancel will close the import dialog, without doing an import.

Because the initial import potentially imports lots (hundreds or thousands) of tracker items, the import statistics will only show numbers, but not actual item information.

But for all subsequent/incremental imports, detailed information about imported, updated, deleted or failed data is available:

For example by clicking on the number of updated objects, you can see which items were updated and what were the changes:

The configured number of the last X imports can also be viewed at any time later, via the History... link in the Import from DOORS dialog:





Administrators can also look at the settings, that were in effect for each of the imports.





In CB-10.0 and newer, you can also implement and deploy a Tracker Synchronization Listener, in order to be notified, whenever a Tracker is synchronized with DOORS.

Known Limitations

There is a known problem in IBM Rational DOORS with Word/RTF tables.

• Exporting a Word Table from DOORS
• Woes with RTF tables
• Is there a way to display a table?
• problem with tables in doors
• ...

You cannot create/edit Rich Text Tables in DOORS directly, but if you happen to have pasted Rich Text Tables (e.g. from Microsoft Word) into DOORS Rich Text Attributes, such tables will be displayed, because DOORS delegates this task to the Microsoft Rich Text Control.

But DOORS itself does not provide tools, to operate on RTF tables!

Especially the DOORS eXtension Language, that DOORS Bridge is build upon, will simply ignore/skip unsupported RTF markup (e.g. RTF table tags), so upon export (even with the build-in DOORS tools), RTF tables will loose all decorations.

DOORS Bridge 1.3 and newer, therefore use a different approach.

Instead of parsing DOORS rich text with the build-in DOORS/DXL parser, the raw rich text is exported as RTF fragments and post-processed with an own RTF parser, that is able to handle also RTF elements, not supported by DOORS natively:

• RTF Pictures
• RTF Objects
• RTF Lists
• RTF Tables, including nested tables
• RTF Bullets and Numbering

Another known problem are Symbols using the special Symbol and/or WingDings fonts.

Codebeamer (Wiki) Text uses the UTF-8 character set and a standard Web font (e.g. Arial):

• Only a subset (~70%) of the Symbol and/or WingDings characters have an equivalent UTF-8 character.
• Even if there is an equivalent UTF-8 character, not all fonts support all UTF-8 characters.
• So some exotic symbols may not be imported properly and show as �

Yet another known problem is whitespace, especially tabs within text.

RTF renders each whitespace character "as is", but Codebeamer Wiki Markup is translated into HTML, and HTML typically renders consecutive chunks of whitespace into a single space.

Text that uses tabs and spaces

• to show multiple lines in a tabular form, or
• to simulate numbered and bulleted lists with different indentation,

can therefore appear to be misaligned in Codebeamer.

Transformation of DOORS Test Specifications to Codebeamer Test Cases

There is no standard schema for Test Specifications in DOORS, so customers have invented their own methods of defining Test Cases, including

• Prerequisites
• Test Steps
• Test Parameters
• etc

in Formal DOORS modules.

But this means, that there is also no standard way of mapping these custom schemas to the Codebeamer schema upon import.

But in CB-10.0 and newer, you can implement and deploy own Java code, that plugs into the import process, to perform special data transformations, not supported by default.

OLE Objects are Displayed as Attachments

If new Office is installed on DOORS bridge server it could happen that OLE objects within import files which were created by older Office versions are shown as .png attachments after import.

To resolve this error you should install also an older Office version on DOORS bridge server (e.g. Office 2003) so these OLE objects can be imported properly.