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

1. Download the newest version of codeBeamer DOORS Bridge from the PTC Software Download page.
2. Unpack the downloaded ZIP archive to your preferred location.
   E.g.
   

    C:\DOORS Bridge 

   When installing/unpacking to
   

   C:\Program Files

   , make sure to grant write permissions for the DOORS Bridge folder recursively.
3. Edit the file
   

   ~\DOORS Bridge\webapps\db\WEB-INF\classes\DOORS.properties

   and set:
   • BRIDGE.home to the absolute path of the DOORS Bridge installation.
     E.g.
     

      BRIDGE.home: C:\\DOORS Bridge 

     Important: Backslashes (\) must be written as double backslash (\\) in the properties file.
   • BRIDGE.tempDir (1.6.65 and newer) to the directory, where DOORS Bridge should store it's temporary data, e.g. unwrapped content and preview images for OLE Objects.
     If this is not set (the default), then DOORS Bridge will store temporary data in the directory denoted by the system environment variable java.io.tmpdir.
     But you can specify here the absolute path to an alternative temporary directory, that must exist and be writable.
     E.g.
     

      BRIDGE.tempDir: C:\\DOORS Bridge\\temp 

     Important: Backslashes (\) must be written as double backslash (\\) in the properties file.
   • BRIDGE.tempDirTimeout (1.6.67 and newer) is the timeout for an unaccessed temporary directory, before it gets deleted.
     You should not set this to less than 5min or more than 24h. The default is 30min.
     The higher this timeout, the more temporary disk space DOORS bridge may require.
     E.g.
     

      BRIDGE.tempDirTimeout : 30min 

   • DOORS.exe to the absolute path to the DOORS client executable.
     E.g.
     

      DOORS.exe: C:\\Program Files\\ibm\\Rational\\DOORS\\9.7\\bin\\doors.exe 

   • DOORS.poolSize (1.6.69 and newer) is the maximum number of DOORS clients, that can be started in parallel.
     This number should not be less than 4 and not more than half the number of available system processor cores.
     Please be aware, that you also need sufficient DOORS licenses, RAM and disk space for this number of DOORS clients !.
     E.g.
     

      DOORS.poolSize: 4

   • DOORS.port is by default the standard DOORS DXL server port (5093).
     You only need to change this, if the ports [5093 .. 5096] are already in use on your system.
     E.g.
     

      DOORS.port: 5095 

   • DOORS.database should only be set to the Port@Hostname/IP-Address of the DOORS database, if the DOORS Bridge should use a DOORS database connection other than the default DOORS client connection.
     E.g.
     

      DOORS.database: 36677@127.0.0.1 

   • DOORS.username and DOORS.password should only be used in the rare case, where your regular DOORS users do not have Edit DXL (in batch mode) permission.
     Only in that case, the DOORS Administrator must create a special DOORS user with Edit DXL (in batch mode) permission, for exclusive use by Intland DOORS Bridge, whose username and password must be specified here.
   • DOORS.localdata (1.5.41 and newer) is by default ${BRIGE.home}/temp.
     You should only specify the absolute path to a different directory here, if the DOORS client reports problems with LOCALDATA.
   • DOORS.timeout (1.6.54 and newer) is the max. timeout for DXL requests to DOORS.exe.
     You should not set this to less than the default of 2h. But if you encounter timeouts upon loading huge DOORS modules/baselines, then increasing this timeout may be necessary.
     Check also, if upgrading DOORS to 9.7.2.1 and higher is an option, see here.
     But the higher the timeout, the longer it takes, to detect a hung up DOORS.exe.
     E.g.
     

      DOORS.timeout: 4h 

   • DOORS.timelimit (1.6.59 and newer) is the max. time limit for DXL commands to DOORS.exe.
     You should not set this to less than the default of 2min. But if you encounter timeouts upon executing DXL commands, then increasing this time limit may be necessary.
     But the higher the time limit, the longer it takes, to detect a hung up DOORS.exe.
     E.g.
     

      DOORS.timelimit: 5min 

   • DOORS.preformattedAttributes (1.7.74 and newer) is a comma-separated list with the names of DOORS object Rich TEXT attributes,
     that should not be converted into codebeamer Wiki markup, but instead should be treaded as pre-formatted plain text.
     This is intended for custom DOORS Object attributes, although you can also specify the defaultObject Text (1.7.75 and newer) (not recommended!).
     Leading and trailing whitespace is regarded as part of the attribute name, so do not add extra whitespace around commas!
     Commas within an attribute name must be substituted with the special placeholder |
     E.g.
     

     DOORS.preformattedAttributes : Input Parameters,Reviewed_Input Parameters,Test Condition,Reviewed_Test Condition

4. If the default Apache Tomcat port (8080) is already in use on your system, or you want to use a different port anyway.
   Edit
   

   ~/DOORS Bridge/conf/server.xml

   and replace 8080 with a different port number.
5. As Administrator: Configure the Windows Firewall, to allow access to the DOORS Bridge program:
   

   ~\DOORS Bridge\bin\doorsBridge.exe

6. As Administrator: Install DOORS Bridge as a Windows Service, by running
   

   ~\DOORS Bridge\bin\service.bat install

   in a cmd window.
   E.g.
   

    cd "C:\DOORS Bridge\bin"
        set "JRE_HOME=C:\Program Files\Java\jre1.8.0_341"
        set "CATALINA_HOME=C:\DOORS Bridge"
        service.bat install 

   By default, the service name is Doors Bridge (diplayed as "codeBeamer DOORS Bridge"), but you can specify a different service name as (optional) second parameter:
   E.g.
   

    cd "C:\DOORS Bridge\bin"
        set "JRE_HOME=C:\Program Files\Java\jre1.8.0_341"
        set "CATALINA_HOME=C:\DOORS Bridge"
        service.bat install "Special DOORS Bridge" 

7. As Administrator: Check the installed service configuration, e.g. to start automatically or only manually, and start the service is not already running.
8. Check Web Access to DOORS Bridge from a different machine, by accessing this URL via a Web Browser:
   

    http://<host>:<port>/db

   • Where <host> should be the hostname/ip-address of the server, where DOORS Bridge was installed,
   • And <port> should be the port number assigned to the DOORS Bridge Tomcat server (default is 8080, see above).

Change service settings

To change settings of the codeBeamer DOORS Bridge service, e.g. Java memory, etc:

• As Administrator: Start
  

  ~\DOORS Bridge\bin\doorsBridgew.exe

  If you had installed DOORS Bridge with a special service name, you must also provide this special service name to the
  

  doorsBridgew.exe

  command via the
  

  //ES//

  parameter:
  E.g.
  

   cd "C:\DOORS Bridge\bin"
       doorsBridgew "//ES//Special DOORS Bridge"

• On the General tab, you can configure the Startup type and also manually Start and Stop the DOORS Bridge service.
  
• On the Log On tab, you can configure a special user for running the DOORS Bridge service (other than the default system user).
  
  
  This may be necessary, if running
  

  Doors.exe

  as system user is not allowed on your system.
• On the Java tab, you can increase the Maximum memory pool (default 1024 MB), if necessary.

Starting/Stopping Tomcat manually

If, for some reasson, you need to run the DOORS Bridge Tomcat instance manually (as a foreground process)

• Make sure the background service is stopped, e.g. via
  

  doorsBridgew

  (see above)
• Start DOORS Bridge via
  

  ~\DOORS Bridge\bin\startup

  in a cmd window from the installation directory.
  E.g.
  

   cd "C:\DOORS Bridge"
       set "JRE_HOME=C:\Program Files\Java\jre1.8.0_341"
       set "CATALINA_HOME=C:\DOORS Bridge"
       bin\startup 

• Stop DOORS Bridge via
  

  ~\DOORS Bridge\bin\shutdown

  in a cmd window from the installation directory.
  E.g.
  

   cd "C:\DOORS Bridge"
       set "CATALINA_HOME=C:\DOORS Bridge"
       bin\shutdown 

Troubleshooting

If OLE objects, that are embedded in rich text attributes of objects to export via codeBeamer DOORS Bridge

• are not exported at all,
• are only exported as preview pictures,
• are exported as blank pictures

then make sure,

• that the appropriate application, e.g. Microsoft Office for MS Word and Excel, is installed on the machine, where DOORS Bridge is running
• that the OLE objects are embedded and not linked.

If requested object attributes are not returned by the DOORS Bridge

• make sure, that the DOORS attribute names do not contain leading or trailing whitespace or commas,
• or upgrade DOORS Bridge to 1.6.66 or newer, where the problem with leading/trailing whitespace and commas in attribute names is fixed.

If importing large DOORS Modules is very slow or fails, then please check, if upgrading to the newest IBM® Rational® DOORS® 9.7 version is an option, because IBM® claims in the DOORS® 9.7.2.1 release notes, that

• The following performance issues about opening modules are fixed:
  • Long time was required to open modules.
  • At times, larger modules failed to open and the process used to get aborted.

If DOORS Bridge temporary files are not removed upon a DOORS Bridge or server shutdown/restart, then check, that you are using DOORS Bridge 1.6.65 or newer, because in DOORS Bridge 1.6.64 and older:

• The temporary folders and files are created and written by the DOORS client, via the DXL command tempFileName(), triggered by the specific DOORS Bridge DXL scripts
  • DXL reference manual about tempFileName():
    • Returns a string, which is a legal file name on the current platform, and is not the name of an existing file. This file can be used for temporary storage by DXL programs.
      • On UNIX platforms, returns a file name like /tmp/DOORSaaouef;
      • On Windows platforms, returns a file name like C:\TEMP\DP2.
  • See https://www.ibm.com/support/pages/where-find-rational-doors-temporary-directory-microsoft-windows
• The problemwith deleting these temporary folders and files is:
  • They will be deleted by DOORS Bridge after processing
  • But DOORS Bridge will only learn about new temporary folders and files to process (and delete) in the response from the DOORS client
    • If the DOORS client does not respond (in time) or aborts without sending a response,
      • then nobody knows about any created temporary folders and folders, so they will not get deleted
• Since DOORS Bridge 1.6.65 the temporary folders are created by DOORS Bridge itself, so they can be properly removed even if the DOORS client hangs up or aborts.

If DOORS® RichText is not properly converted into codeBeamer Wiki markup, then our support will typically ask for a Text example in form of a RTF file.

Here is how to export an object text as an RTF file from DOORS® via DXL:

• Manually open the module to export in the DOORS client on the DOORS Bridge machine.
• Select the object with the text to export
• Open Tools -> Edit DXL ..., then Load... the attached exportObjectTextAsRTF.dxl script and Run it
  • The script will export the text of the selected object to a file O-<Object Number>.rtf in C:\Windows\Temp
• Send us that exported file.

If DOORS® Links (= Link Modules) are not listed for a (formal) module:

• Open the module in DOORS
• Go to File -> Module Properties ...
• Go to the Linksets tab:
  
  
  
  • Make sure, that all required Link Modules are listed
  • Add missing Link Modules as needed
  • You can use this little DXL script, to check, which link modules DOORS Bridge will see via Tools -> Edit DXL ...in the module's menu bar:
    

    Module module = current Module
    Folder folder  = getParentFolder(module)
    string sourceId = uniqueID(module)
    string linkMod = null
    
    LinkModuleDescriptor lmd
    for lmd in folder do {
      print getName(lmd)
    }
    

• codeBeamer DOORS Bridge writes several log files to the directory ~/DOORS Bridge/logs, that may be helpful in analyzing problems:
  • commons-daemon[.<date>].log
    This are the log files of the codeBeamer DOORS Bridge Windows Service. One file per calendar day.
  • doorsbridge-stderr.<date>.log
    This log files collect all output to the error console. One file per calendar day.
  • catalina[.<date>].log
    This are the Tomcat server log files. One file per calendar day
  • doorsBridge.log[.<date>]
    This are the codeBeamer DOORS Bridge application log files. The log file for the current day does not have a date suffix.
  • doors_<port>.log
    This are logfiles of the running DOORS Client processes. Do not remove or modify any of them !
• You can safely remove log files, that include a <date> in their name, if that <date> is older than the current day, because these are not longer active.But you must not remove any other log files, while codeBeamer DOORS Bridge is running!In most cases doorsBridge.log is the place to look first.

De-Installation

To de-install codeBeamer DOORS Bridge:

• Stop the DOORS Bridge Windows service, e.g. via
  

  doorsBridgew.exe

• As Administrator: Remove the DOORS Bridge Windows service, by running
  

  ~/DOORS Bridge/bin/service.bat remove

  in a cmd window.
  E.g.
  

   cd "C:\DOORS Bridge\bin"
       set "CATALINA_HOME=C:\DOORS Bridge"
       service remove 

  If you had installed DOORS Bridge with a special service name, you must also provide this special service name to the remove command:
  E.g.
  

   cd "C:\DOORS Bridge\bin"
       set "CATALINA_HOME=C:\DOORS Bridge"
       service remove "Special DOORS Bridge" 

• Delete the installation directory:
  E.g.
  

   C:\DOORS Bridge 

Web Services

Please refer to Codebeamer DOORS Bridge REST API.