Changing the Jazz User ID Using the RTC Plain Java Client Libraries

Recently there were several forum posts about changing the user ID used by JTS and the Jazz products RTC, RQM, RRC to authenticate them against the authentication realm like LDAP, or Tomcat based authentication. In some scenarios this is simply required to change a mistyped user ID while keeping the users association to the Jazz artifacts. Some scenarios are more complex. For example switch to a new LDAP system and changing the user ID.

The general approach is described in this tech note. Following the tech note you can use the administration UI to change the ID. If you need to completely switch the LDAP system and the new system has new user ID’s you have to take some more things into consideration.

1. Switch off the LDAP sync task, while you do the changes. Otherwise it might sync the new users with the different ID’s in.
2. You will need an administrative user after switching to the new system. Make sure you create one in the old system that conforms to the ID’s in the new system, or have one or more additional administrative accounts and change them to a valid new ID in the new LDAP system.
3. You can change all the other user ID’s in the current system or the new system. Consider to keep the admin ID for the old system as long as you are testing.

In Doors Next Generation this is not supported. See https://www.ibm.com/support/pages/workarounds-modifying-user-id-clm for work arounds.

Doing all the user ID changes manually might be tedious and error prone. It will also take time. While you do it, the system might not be available for the users.

Changing the user ID this way only changes the ID in the Jazz databases. You need to make sure to provide a matching user ID in the user registry you are using. If you just want to change the user ID’s and not change the registry, make sure to modify the user ID’s in the registry to match the user Jazz user ID.

If you run Tomcat and its built in registry, managing the ID’s in the file Tomcat/conf/tomcat-users.xml, you need to change the value of the property username to match the ID in the Jazz database. Shut down the server, change the property for the users to match their Jazz user ID, save the file and restart the server.

Yesterday, in a discussion with a team of RTC users that is currently looking into changing the LDAP system and all their user ID’S, the question about automation came up. I could not resist and looked into an opportunity to have more automation for this task. It turned out to be almost trivial to code up some tool that can help with the effort and allows to

• Simulate the user ID change, testing the input file and the user ID’s in the first column, but don’t change an ID.
• Run the user ID change, change the user with the ID provided in the first column to the ID provided in the second column.

Lets look at how that would work.

License and how to get started with the RTC API’S

As always, our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license, which basically means you can use it for internal usage, but not sell. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!

If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.

You should be able to use the following code in this environment and get your own automation or extension working.

To keep it simple this example is, as many others in this blog, based on the Jazz Team Wiki entry on Programmatic Work Item Creation and the Plain Java Client Library Snippets. The example in this blog shows RTC Client and Common API.

Download

The complete Eclipse project with the code is available as download here.

Solution Overview

The code contains two classes.

1. ChangeUserID is the main class that needs to be called
2. CSVFileReader is a utility class that helps with reading the input file

Warning!

Please consider to test this in a test environment and create a backup before you try this on a production repository. In contrast to using the UI there is no protection against changing the ID. You don’t have to enable it and you don’t have to switch the property User Registry Type from LDAP to UNSUPPORTED. If you run the command with an administrative user with parameter true your ID’s will be changed. You can seriously damage your environment if you do something wrong.

How to use the tool

You need to import the sources into Eclipse and provide the plain java client libraries as described in this article, in order to be able to run it. In this case a sample launch comes with the code. Alternatively you can compile the example code and provide the plain Java Client Libraries in the classpath.

Call ChangeUserID.main with parameters repositoryURI AdminUserId AdminPassword InputFileName performModification where performModification is true or false. The input file referenced by InputFileName needs to be a CSV file with at least two columns and ‘,’ as separator. The first column is the current user ID, the second the desired new user ID.

For example call it with these parameters for simulation

"https://clm.example.com:9443/jts" user password "C:\temp\modifyIDs.csv" false

Call it with these parameters to perform the changes

"https://clm.example.com:9443/jts" user password "C:\temp\modifyIDs.csv" true

Please be aware that the context root jts is not a typo. You want to change the users in JTS, which promotes the changes to all the other applications. Please check that the uid’s have been changed in the registered applications after running the tool.

The input file needs to have a compatible format as described above: It needs to be a CSV file with at least two columns and ‘,’ as separator. The first column is the current user ID, the second the desired new user ID. This would be a valid example:

bob,bobNew
tanuj,tanujNew

You can have additional columns and the tool will ignore them. The tool also makes sure that the original user ID exists and the new user ID is not empty. White space characters around the user ID’s  will be removed.

If your file is using a different separation character, you can modify the constant below at the beginning of the class ChangeUserID to fit your needs.

private static final String SEPERATOR = ",";

Is there automation to retrieve the user list?

As a starting point, you can run a repotools-jts command against your repository. The following command will provide you with a CSV file containing all the users in the repository:

repotools-jts -exportUsers toFile=userlist.csv repositoryURL=https://:/jts/ adminUserId= adminPassword=

The resulting text file has the right format. All you need to do is to add a new column that contains the new ID’s. I tried this with our Open Office based Symphony spreadsheet editor. The following steps worked for me:

1. Start Symphony
2. Select File>Open
3. Browse for the file and open it
4. Review the settings and make sure the separator is correct, the default worked for me
5. Finish the import

Once the file is in the spreadsheet editor, just click on the second column and add a column. You can add the new ID’s and keep the other columns in the file for easier user recognition and editing. You could potentially do the same with a test repository that has imported all the users of the new LDAP system. Maybe using some spreadsheet magic such as sorting helps you to use cut and past to get the new ID’s into the new column.

If you use Symphony you want to make sure to open Tools>Instant Corrections, switch to the Options tab and disable at least the option capitalize fist letter on every sentence if your ID’s start with a lower case letter. The image below shows an example screen shot.

file Edit user table

While editing the file, keep in mind, if you leave out the new user ID, the ID will not be changed. The tool does also not change the ID of the admin that runs the command.

After you are satisfied you can simply save the CSV file with Symphony.

I tried the same procedure with MS Excel and there are some issues.

• Excel by default wants a TSV file. It wants to use a tab as separator. You can change this if you use the Data>Import option instead of opening the file directly
• Excel writes the file as Colon Separated Values file using ‘;’ and not tab or a comma. Either fix this behavior or change the SEPARATOR constant in ChangeUserID

The API Code Explained

I am not going to try to explain all the code that is needed to get the data to be able to do the ID change in detail. It is simply trying to open a file, read it line by line, analyze the data and call the interesting API code with it.

The change of the user ID is done in the operation ChangeUserID.changeUserID() shown below. The code is really simple.

/**
 * Find the user ID and change to the new user ID. doUpdate = false does
 * simulation only. In simulation mode: Try to locate the contributor by
 * user Id but do no change.
 *
 * @param teamRepository
 * @param originalID
 * @param newID
 * @param doUpdate
 * @throws TeamRepositoryException
 */
public static void changeUserID(ITeamRepository teamRepository,
		String originalID, String newID, Boolean doUpdate)
		throws TeamRepositoryException {
	System.out.print("Set user: " + originalID + " to " + newID
		+ (doUpdate ? "" : " - Simulation"));
	IContributor user = teamRepository.contributorManager()
		.fetchContributorByUserId(originalID, null);
	IContributor contributorWorkingCopy = (IContributor) user.getWorkingCopy();
	if (doUpdate) {
		contributorWorkingCopy.setUserId(newID);
		teamRepository.contributorManager().saveContributor(
			contributorWorkingCopy, null);
	}
	System.out.println(" - OK");
}

The code simply uses the current user ID provided to fetch the contributor. If the contributor can be found it gets a working copy. If not in simulation mode, it sets the new ID and saves the working copy. The operation throws an exception in case the user with the original ID can not be found. This is caught in the calling method and displayed e.g. to be able to fix the input file.

The downloaded code has basic error handling and also works for malformed input files. However, you might want to extend it a bit for general usage. You should definitely consider using a test system to make sure your data is correct and you can use the system after you did the changes.

Well, writing the tool was less than an hour. Commenting and blogging took 4 times as much, so I hope this is useful for the readers and saves some poor guy with a huge user base some time.