Why can't I edit a file that I previously locked from my Citrix machine?

In some environments the DITA CMS Eclipse Client must be configured with a logical_citrix_server_name to ensure the user's lock information is recognized.

Symptom

A user logs in to the DITA CMS Eclipse Client and locks a file. After working on it, the user closes the DITA CMS Eclipse Client and the remote session without releasing the file. When the user logs back in and tries to edit the locked file, it cannot be edited and is displayed in purple in the Search Results or Map view.

Problem

The DITA CMS Eclipse Client uses the hostname and the username to create unique lock information. This may cause issues when there are multiple servers in a Citrix or Remote Desktop farm and a load balancer is used to dispatch user sessions.

When multiple servers are in a farm, the hostname used for the lock information is the local server name. With a load balancer, once a session is running, the user will connect back to the same session on the same server. If the session is closed (the user logs off or closes the application), then there is no guarantee that the user will log back in to the same server. In this case, the lock information will be different, so the user will not be recognized as the person who did the initial lock. The files will be displayed in purple and the user will not be able to work on them.

Solution

To solve this issue, add the following line to the eclipse.ini file, after the -vmargs line:

-Dcom.ixiasoft.cms.override.hostname=<logical_citrix_server_name>

where <logical_citrix_server_name> is the name given to all the servers in the farm; for example, "Citrix-Farm-Prod". The same name must be configured in each eclipse.ini file for each server in the farm.