api
Wiki: FrequentlyAskedQuestions

CollabNet Enterprise Edition Web Services FAQ

This is the complete FAQ for CollabNet's Enterprise Edition Web Services. We have used our Wiki for this FAQ so that it is easy for you to help us maintain the contents of this FAQ. You only have to be a logged in project member to use the Wiki. There should be an Edit this page link displayed above.

General Questions

I'm getting SOAP exception, "WSSecurityEngine: Callback supplied no password for:". What's wrong with my request?

Your security header doesn't have the correct login credentails. Assuming the username and password are in fact valid, this can be solved by following this format for the security section:

  username|domain name|projectname.

  For example:

<wsse:UsernameToken>
  <wsse:Username>user123|test.server.net|testing_project</wsse:Username>
  <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile1.0#PasswordText">mypassword</wsse:Password>
 </wsse:UsernameToken>

How do I find proper tag names and namespaces to use in my Dispatcher service requests?

CollabNet's Web Services for Project Tracker require "XML Names" for things like artifacts, artifact types, saved queries, etc. These names are not reflected in the web interface. In order to get the values for the items you will be querying for, run the Dispatcher's getArtifactTypes(), which does not require any data values. The SOAP request message looks something like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:services.ws.core.collabnet.com">
 <soapenv:Header>
  <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>{yourusername}</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{{your password}</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
 </soapenv:Header>
 <soapenv:Body>
   <urn:getArtifactTypes/>
   <urn1:getArtifactTypes xmlns:urn1="urn:ws.tracker.collabnet.com"/>
 </soapenv:Body>
</soapenv:Envelope>

References:
http://api.open.collab.net/ds/viewMessage.do?dsForumId=47&dsMessageId=56226

How do I set up CollabNet's sample client to connect to a site that is SSL enabled?

You need to create and use a certificate keystore. Java includes a command named "keytool" for this purpose. Here is what you need to do:

1. First, you need a copy of the server certificate. You can get this from your web browser. Just access your site using a web browser. In most browsers, you can double-click on the padlock icon to examine the server certificate. There is then usually an option somewhere in the resulting dialogs that lets you export the certificate to a file. Let's say you named the file cee_server.cert.

2. Next, you'll need to run the following commands in a command line/terminal session. Assuming you have Java's runtime environment available in your path, run the following command (write down the password you provide for your trusted certificate keystore):

   $ keytool -import -alias "replace this with some unique name" -file cee_server.cert -keystore my_cert_truststore.jks
   

3. Copy my_cert_truststore.jks to the sample client's 'cert' directory, $COLLAB_WS_CLIENT/certs/

4. Edit $COLLAB_WS_CLIENT/certs/server-cert.properties with these settings:

   org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
   org.apache.ws.security.crypto.merlin.keystore.type=jks
   org.apache.ws.security.crypto.merlin.keystore.password=YOUR_KEYSTORE_PASSWD
   org.apache.ws.security.crypto.merlin.file=my_cert_truststore.jks
   

Follow the rest of the general instructions for running the sample client. The sample client will use these properties to setup Axis to connect to your CEE site using the certificate authentication.

How do I set up CollabNet's sample client to connect to a site that requires personal digital certification?

If the CEE site you're attempting to connect to via SOAP Web Services requires that you securely identify yourself via a digital certificate (PKCS#12), you need to create a certificate keystore that will house both the site's certificate and your personal digital identification. You need to create and use a certificate keystore. Java includes a command named "keytool" for this purpose. Here is what you need to do. Execute the following commands on a command line where your environment has access to Java's runtime as well as OpenSSL, the open source toolkit for SSL.

1. If necessary, get a copy of your certificate by backuping it up from your browser.
   
   Let's say you name it my_cert.p12

2. Move/copy the certificate to the certs directory of the ?CollabNet web services sample software.

   cp my_cert.p12 $COLLAB_WS_CLIENT/certs/. 
   

3. Get a copy of the server's certificate.
   
   You can get this from your web browser. Just access your site using a web browser. In most browsers, you can double-click on the padlock icon to examine the server certificate. Navigate the resulting dialogs so that you can export the certificate to a file.
   
   Let's say you saved the file inside of $COLLAB_WS_CLIENT/certs/ as cee_server.cert.

4. Create a java keystore, named my_cert_truststore.jks for example, to manage your client and server keys. Run the following command.

   keytool -import -alias my_cee_server -file cee_server.cert -keystore my_cert_truststore.jks 
   

   Let's say you provided password YOUR_KEYSTORE_PASSWD.

5. Create a .pem file from your client side PKCS12 file. Be sure to use the following command line argument as we were only able to get it to work by adding those last few options to the command.

   openssl pkcs12 -in my_cert.p12 -out my_cert.pem -clcerts -nokeys 
   

6. Open the .pem file in an editor and remove everything before the line "-----BEGIN CERTIFICATE-----" (It seems that java's keytool may not be comfortable with additional verbiage in the certificate file. We've seen this reported, "keytool error: java.lang.Exception: Input not an X.509 certificate")

7. Add the client cert to your keystore

   keytool -import -keystore my_cert_truststore.jks -alias my_cert_client -file my_cert.pem 
   

8. Edit $COLLAB_WS_CLIENT/certs/server-cert.properties by having these settings:

   org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin 
   org.apache.ws.security.crypto.merlin.keystore.type=jks
   org.apache.ws.security.crypto.merlin.keystore.password=YOUR_KEYSTORE_PASSWD
   org.apache.ws.security.crypto.merlin.file=my_cert_truststore.jks