Creating and modifying external repository connections

An external repository connection is a IBM® Engineering Workflow Management (EWM) item whose properties contain information that the Jazz™ Team Server needs to create a connection to an external repository. You need to create an external repository connection for the ClearQuest® Gateway.

Before you begin

To create, modify, and delete external repository connections, you must be assigned either a Developer or ClearQuest Synchronizer Client Access License. In addition, the project area must be configured to grant permissions to your user role. To set permissions, open the project area; click the Process Configuration tab; click Project Configuration > Permissions; select a role; and select Item Connectors in the Permitted Actions list.

About this task

You can use the ClearQuest Synchronizer Setup Wizard to create an external repository connection. This topic shows how to create an external repository connection by using the EWM Eclipse client. It also shows how to disable or enable outgoing synchronization for the external repository connection. If you create an external repository connection by using the ClearQuest Synchronizer Setup Wizard, you must enable outgoing synchronization for it. The wizard creates the external repository connection with outgoing synchronization disabled.


To create an external repository connection:

  1. Login to the EWM client.
  2. In the Team Artifacts view, right-click the repository connection and select Administer > Synchronization Rules. In the Synchronization Rules view, right-click External Repository Connections and select New > External Repository Connection.
  3. If you are logged into more than one Jazz repository, select the one for which you want to create an external repository connection. Click Next. In the External Repository Connection window, enter a name for the connection in the Name field. Enter the URI of the ClearQuest Gateway in the Connection info field. For example: http://YOUR-CQ-GATEWAY-HOST:8081/cqconnector/gateway. If the Tomcat server that hosts the ClearQuest Gateway is configured to require user authentication for its service requests, enter values in the User ID and Password fields. Otherwise, leave those fields blank. The user ID and password that you enter must match those specified in the tomcat-users.xml file in the install-directory/gateway/tomcat/conf directory.

    You can restrict access to the external repository connection by setting permissions in a project area and then selecting that project area in the Project Area field. After you set a project area for an external repository connection, you cannot change it. If you need to set the field to a different project area or to no project area, you can delete the external repository connection and create a new one.

    If you need to temporarily stop synchronization from the Jazz server to this ClearQuest Gateway, select Disable outgoing synchronization. You might want to disable outgoing synchronization when you perform maintenance on the ClearQuest user database and it is temporarily unavailable. To enable outgoing synchronization, clear the Disable outgoing synchronization check box. Click Save to save the external repository connection.

    The default port numbers for external repository connections are 8444, for Secure Sockets Layer (SSL) connections, and 8081, for nonSSL connections. To change a default port number, edit the server.xml file in the /jazz/connectors/gateway/tomcat/conf directory. To disable nonSSL connections and configure the Tomcat server to require user authentication, perform the following steps:

    1. Start and stop the ClearQuest Gateway, which expands the cqconnector.war file.
    2. Edit the server.xml file in the install-directory/gateway/tomcat/conf directory to comment out this element:
      <Connector port="8081" maxHttpHeaderSize="8192"
          maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
          enableLookups="false" redirectPort="8444" acceptCount="100"
          connectionTimeout="20000" disableUploadTimeout="true" />
    3. Edit the web.xml file in the install-directory/gateway/tomcat/webapps/cqconnector/gateway/WEB-INF directory to uncomment the following element:
    4. Open the tomcat-users.xml file in the /jazz/connectors/gateway/tomcat/conf directory. The default user ID and password are cqconnector. Change the password. Optionally, change the user ID.
    5. By default, the password in the tomcat-users.xml file is stored in the clear, but you can encrypt the password and configure Tomcat to recognize it. To do so, use the repotools convertTomcatUsers command. Navigate to the JazzInstallDir/server/repotools directory. Enter the command and specify the path to the tomcat-users.xml file. For example:
      repotools convertTomcatUsers tomcatUsersPath=install-directory/gateway/tomcat/conf/tomcat-users.xml

      The converted tomcat-users.xml file is named tomcat-users.xml.converted. Rename it to tomcat-users.xml. If you ever need to change the password, you must change it in a copy of the original, unencoded file, and then the run the repotools convertTomcatUsers again. Preserve the original, unencoded, file in a secure place.

      After you run the command, edit the server.xml file in the /jazz/connectors/gateway/tomcat/conf directory as follows:

      Comment out the following element:

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"

      Uncomment the following element:

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"


The external repository connection that you create appears under the External Repository Connections node in the Synchronization Rules view.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki