Preparation

System Requirements

The minimum server configuration needed to run Tasktop Sync is:

4 GB system memory
1 GHz processor, 2 cores
30 GB free disk space
A supported operating system
- 32-bit or 64-bit Windows; Windows Server 2007, 2008, 2012, 2016 or 2019 are recommended.
- Red Hat Enterprise Linux 5, 6, 7 & 8; GTK3 and X Windows are required.
  - To force GTK3, add the following to the TasktopSync.ini file before -vmargs:
    --launcher.GTK_version
    3
- SUSE Linux Enterprise Server 11, 12, 15; GTK3 and X Windows are required.
  - To force GTK3, add the following to the TasktopSync.ini file before -vmargs:
    --launcher.GTK_version
    3

Accounts

Before installing Tasktop Sync, ensure that login credentials for the following user accounts are available:

On the Tasktop Sync installation server:
- An account with administrative privileges that will be used to configure Tasktop Sync
On each repository to be accessed by Tasktop Sync:
- An account that Tasktop Sync will use to create and update tasks
- An account that Tasktop Sync will use to append logging comments when required

Required Files

Before installing Tasktop Sync you will need the following files:

The Tasktop Sync installation executable
A Tasktop Sync license file (tasktop.license)
Any vendor-specific downloads specified in the Certified Connectors document

Backup Installation Customizations

Installing Tasktop Sync will overwrite the following customizations you may have made to a previous install:

TasktopSync.ini: Ensure any changes made to this file are backed up so they can be applied again after installing a new version of Tasktop Sync.
Windows service log on credentials: If there is an existing installation of Tasktop Sync as a Windows service, and the service is set up to run under a specific account, ensure the account name and password are available to be entered again after upgrading to a new version.

Note that the working directory containing Tasktop Sync's configuration files (task mappings, repository settings, cache data, etc.) will not be overwritten by an install. Of course, it's a good idea to back these up on a regular basis anyway.

Vendor-specific Requirements

Consult the Installation requirements section for all vendors you wish to use with Tasktop Sync in Connector Documentation. These sections will identify additional information you will need during installation of Tasktop Sync.

Test Environment

We strongly recommend setting up a test environment, using snapshots of both repositories. Getting the mapping between the task attributes on both systems is tricky, and you are highly likely to change your mind about the configuration before you have finished. It is better to change your mind on a test environment than a production environment.

In your test environment, you probably want to turn off email notifications on your task repositories, so that you do not bury people with notifications as you test the synchronizer.

Installation on Windows

You will be provided with an installation package for Tasktop Sync as a standard Windows installer. The installer will provide instructions for how to install Tasktop Sync as server deployment and service deployment. There are several pages in the installation dialog which you do need to pay attention to. The first is the workspace selection page:

This option will allow you to select the location of the Tasktop Sync workspace. By default, the workspace is placed within the installing user's AppData directory.

This page allows you to enable and specify a shared master key for Tasktop Sync. Enabling this feature will allow multiple Windows user accounts to administer Tasktop Sync.

For more information on this feature, please refer to the Shared Master Key section.

If you want to run as a Windows service, you need to check the top box. If you are evaluating Tasktop Sync or only wish to use the Quick Start wizard we recommend not running as a Windows service as there are a few less steps involved to access the user interface. Further details on installing Tasktop Sync as a service are available in the Installing Sync as a Windows Service guide.

If you are using IBM Rational Team Concert or Microsoft Team Foundation Server, you also need to check the appropriate boxes here. If you do not check the boxes now and later decide to use one of these repositories, you will have to reinstall Tasktop Sync to install the appropriate connectors.

If you check any of the boxes, the next page will contain links to download the plugin for the repository you select (or the first repository you selected):

Click on the link for your repository to download it (if you have not done so previously), and then specify the directory where to find it. Alternatively, you may run the installer from the Windows command prompt and pass in the repository location through a parameter. The accepted command line parameters are:

-RTC for the IBM Rational Team Concert connector
-TFS for the Microsoft Team Foundation Server connector

For example, running TasktopSetup-sync.exe -RTC="C:\Downloads\RTC-Client-p2Repo-4.0\repo" will tell the installer to automatically install the IBM Rational Team Concert connector with Tasktop Sync, using the given repository directory.

NOTE: Getting the repository version exactly correct is important. For example, selecting 4.0.3 if you have a 4.0.1 repository will not be productive, and you will not be able to change it without reinstalling Tasktop Sync.

Shared Master Key

The Shared Master Key may be enabled during installation and is used to encrypt passwords in Tasktop Sync. Instead of user specific encryption, the Shared Master Key will be used as a master password for all Tasktop Sync administrators.

The Shared Master Key is stored in plain text format within the workspace. Upon installation, only Windows Administrators are granted access to the key file. It is important to ensure that appropriate Windows access permissions are placed on the Tasktop Sync workspace.

Installation on Linux

NOTE: In the following instructions the installer file is referred to as TasktopSetup-linux.bin for convenience. The actual file distributed by Tasktop will be called something like TasktopSetup-sync-lin64-3.5.0.20140320-0607-RELEASE.bin .

Open a terminal and change to a directory that the currently logged in user has write access to by typing "cd <path to directory>" in the terminal.
Ensure that the installer .bin file is executable by typing "chmod u+x <path to installer>" in the terminal.
Run the installer:
1. (Optional) Installation with IBM Rational Team Concert:
  1. Ensure that there is an IBM Rational Team Concert client p2 repository zip file available on the computer. If not, you can download the Rational Team Concert 4.0 repository from https://jazz.net/downloads/rational-team-concert/releases/4.0/RTC-Client-p2Repo-4.0.zip. Note that this zip file must be unzipped to a directory on the local machine.
  2. Use the optional command line argument "-DRTC", passing in the IBM Rational Team Concert p2 repository directory, when running the installer as described in step 3.3 (e.g. TasktopSetup-linux.bin -DRTC="/media/sf_shared/RTC-Client-p2Repo-4.0").
2. (Optional) Installation with Microsoft Team Foundation Server:
  1. Ensure that there is a Microsoft Team Foundation Server client repository available on the computer. If not, you can download one from http://download.microsoft.com/download/F/0/4/F04E054B-9DB5-4C24-AF84-DF1A290F5C73/TFSEclipsePlugin-UpdateSiteArchive-12.0.1.zip. Note that this file must be unzipped to a directory on the local machine.
  2. Use the optional command line argument "-DTFS", passing in the Microsoft Team Foundation Server p2 repository directory, when running the installer as described in step 3.3 (e.g. ./TasktopSetup-linux.bin -DTFS="/media/sf_shared/TFS-Client-p2Repo-10.0").
3. Type the path to the installer (e.g. ./TasktopSetup-linux.bin <optional args>) in the terminal and press enter to launch the Tasktop Sync installer.

4. Click Next.
5. Review the license agreement.
6. Specify the target directory.

7. Confirm packages to install.

8. Specify shortcuts to be created.

9. Wait for installation to finish.

10. Confirm that the installation was completed successfully.

Post-Installation Steps

Ensure that the following installation customizations you may have made to a previous install of Tasktop Sync are applied:

TasktopSync.ini -; Edit this file to apply any custom settings.
Windows service log on credentials -; If you are running Tasktop Sync as a Windows service, make sure that the login details used from a previous installation are entered again.

Starting Tasktop Sync

The method for starting Tasktop Sync is slightly different depending on whether Tasktop Sync was installed as a Windows Service or not.

Standard Installs

In a desktop installation, you can bring up the Tasktop Sync Dashboard by right-clicking on the Tasktop Sync icon in your system tray and selecting "Open Tasktop Sync." If this icon isn't visible, it means that Tasktop Sync isn't running, and you can instead start it from the start menu.

Windows Service Installs

See the Windows Service How-to document.

Starting and Stopping the Service

Starting and stopping the Tasktop Sync service can be done using the Tasktop Sync Service Manager installed as part of the installation process. Because interacting with Windows services requires administrative permissions, you will be asked for an administrator password when running this application.

After running this program you will be presented with a dialog:

This dialog contains buttons allowing you to start and stop the service.

Initial Setup and License Activation

The first time you run Tasktop Sync, you will need to do two things. The first is to initialize the secure storage that Tasktop Sync uses to store configured repository passwords. You will be prompted to create a master password and recovery questions for accessing secure storage the first time Tasktop Sync is run.

The second is to import the license file you have been provided (e.g. TasktopSync.license). To import your license file, look for the Tasktop logo in the top left of your Tasktop Sync window. Select the down-arrow drop-down menu beside this icon and select "Preferences..." This will pop-up a dialog window which allows you to import your license file. Click the "Import from File..." button and select the license file you extracted from your installation package. This should populate the License dialog box with the details of your particular license. Finish the import by clicking the "OK" button.