Maintenance and Inspection

This section describes the tools provided by Tasktop Sync to ensure smooth operation and to allow inspection of synchronization and behaviour, as well as maintenance work that should be performed periodically.

Upgrading an Existing Tasktop Sync Installation

Upgrading an existing installation of Tasktop Sync is simple and requires very minimal manual intervention. The upgraded version of Tasktop Sync will have access to all your existing repositories, queries and configurations.

To upgrade an existing installation, follows these steps:

  1. Backup installation customizations — Installing Tasktop Sync will overwrite the following customizations you may have made to a previous install:
  2. Uninstall the existing Tasktop Sync version using the Uninstall option in the start menu. Ensure that Tasktop Sync is not running before you attempt an uninstall.
  3. Install the new version of Tasktop Sync as described in the Installation section.
  4. Reapply installation customizations:
  5. Complete the Tasktop Sync Post Installation Wizard (if required) as described in Post Installation.
  6. Allow Tasktop Sync to generate new Repository Schemas (if required) as described in Generate Repository Schema

Generate Repository Schema

New features in Tasktop Sync may require more detailed repository schemas. After upgrading, you may be prompted to regenerate these schemas. The prompt will list the schemas that must be generated, and ask you if you wish to generate them now.

Generate Repository Schema dialog

It is highly recommended that you generate the missing or out-of-date repository schemas before starting Tasktop Sync. Some features of Tasktop Sync will not function properly without valid schemas.

Post Installation

Sync may need to carry out the following required steps on installation upgrade:

If any of these steps need to be completed, Sync will launch the Post Installation Wizard on startup. The wizard must be completed before Sync can be run. Clicking Cancel at any point in the wizard will bring up a prompt asking if Sync should be shut down. If “Yes” is chosen, the wizard will reappear on the subsequent startup.

The first page of the wizard will list all required steps that will need to be performed.

If an installation step requires a workspace backup, such as with the database transform and repository upgrade, a page will appear asking you to manually back up your workspace before proceeding.

To proceed with the installation, Tasktop Sync requires a valid license. If there isn’t one present, a page will appear to help you import a valid license. Click the “Open License Preferences” button, and the Tasktop Sync license preferences dialog will appear. 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.

Upgrading a task repository will require that the repository is validated. If any repositories needing upgrade require validation, a page will appear allowing you to select the repositories you wish to validate. If skipped, repositories will be unable to synchronize and you will be prompted to validate them every time the application starts.

After the installation finishes, the final page will notify you of the status of all completed post installation steps.

Configuration Updates

A new version of Tasktop Sync will likely have more features and configuration options than your current version. Sometimes these features will require changes to your current configuration file. To make the configuration update process as smooth as possible, Tasktop Sync will attempt to migrate your configuration file for you automatically when you run the new version of Tasktop Sync.

Some changes may require that you manually edit your configuration after the update. This is the case if the new configuration contains a required attribute whose value must be specified by the user. The majority of configuration updates require no user intervention and will maintain the behavior of the previous Tasktop Sync configuration. Before updating the configuration, Tasktop Sync will back up your existing configuration for future reference.

Restoring a configuration without restarting Sync

If you revert your configuration to an older version, you will be prompted to update your configuration when starting the synchronizer, and the synchronizer will refuse to start unless you allow the configuration updater to run. The update prompt will outline the purpose of the configuration update and alert you to all the configuration changes that will be applied during the update. More details about configuration updates can be found here.

Update synchronizer.xml dialog

Synchronization Log Viewer

The Sync Log displays logged console messages per synchronization activity for every task. It provides information that is easily accessible for debugging and may provide information in determining why a synchronization was unsuccessful.

Synchronization Log Viewer

There are two ways of accessing the Sync Log: either by right-clicking a task under a query in the Sync Tasks view and selecting Open Sync Log, or by double-clicking a failed synchronization in the Error Queue of the Sync Dashboard.

Open Sync Log action in the Sync Tasks

Error Queue

The title is displayed in the top left of the Sync Log; this area displays the ID of each task being synchronized as well as its summary. Note that in this example, a red “x” icon is present in the upper left corner. The presence of this icon denotes that something went wrong during this synchronization, and manual intervention is required in order to successfully proceed. When viewing the log of a successful synchronization, this icon is absent.

Synchronization Log Viewer showing the error icon

On the top right corner is the toolbar, which provides buttons to quickly navigate logs for previous synchronizations that this task has undergone.

Synchronization Log Viewer toolbar

Repository Configuration Changes

If the configuration for your repositories has changed, the repository schema must be refreshed for Tasktop Sync to operate correctly. To refresh the repository schema, open the Sync Tasks view, right-click on the repository in question, and select “Refresh Schema”. When prompted, click “Yes” to get the latest repository data.

Refresh Schemas

Alternatively, use the Refresh Schema button in the Schema Viewer.

Refresh progress can be checked in the Progress view of Tasktop Sync. After refreshing the schema, the synchronization process must be restarted for changes to take effect. Some tasks may have been refreshed along with the repository schema, and if the synchronizer is running, any changes found may be synchronized.

Legacy Schema Refresh

Most repositories can provide schema details from a single task, but some require that Tasktop Sync scan many tasks. This is referred to as “Legacy Schema Refresh”. Refreshing the schema in this way may take some time. Additionally, refreshing the schema may run queries from the task repository.

Periodically Refreshing the Repository Configuration

There is also an option periodically refresh the repository configuration. This is done by defining a scheduled job, which will perform a prespecified action based on the provided schedule.
There are two scheduled jobs which are associated with the Repository Configuration changes:

  1. RepositoryConfigurationRefresh Job: This job will refresh the repository configuration of the specified repository
  2. RefreshSchema Job: This job will refresh every repository schema associated with the specified repository

Details on how to to configure scheduled jobs can be found in the section Configuring Scheduled Jobs.

Repository Users

If a user is added to a repository, then that user must be mapped in the person mapping to ensure that they can be synchronized correctly to the other repository. Simply update the person mapping with a mapping containing the user’s identity in each repository. Tasktop Sync must be restarted before the change to the person mappings will take effect. Read the person mapping section for more information on configuring person mappings.

Service Outages

If either the Tasktop Sync server or one of the synchronized repositories goes down for a period of time that is longer than the changes query polling schedule, it is strongly recommended that the configured initialization query is run to discover all the changes made during the server downtime. To run the initialization query, locate it under the “Sync Tasks” view, right-click and choose “Refresh”.

Backup and Restore

All of the state maintained by Tasktop Sync, aside from password information, is stored in the Tasktop Sync workspace. Therefore, to perform backups of your Tasktop Sync data, the only requirement is that you back up this workspace directory. This section discusses one possible way of backing up the Tasktop Sync workspace, as well as how to restore this workspace on another machine if the primary Tasktop Sync machine becomes unavailable. See the final section on Advanced Backup for other possibilities.

Archiving a Folder

The method for backing up and restoring described in this section requires that you archive a folder, and then restore that archive. This can be done by using a tool to create a zip archive file of the folder, and then using the same tool run unzip the archive file.

Note: Windows zip compression has been found to skip files, and fail on large filenames, and is therefore not recommended.

Creating the Backup

This section describes how to use a zip archive to create a backup of the Tasktop Sync workspace.

See the workspace directory section for instructions on locating your workspace directory.

To create a zip archive backup, follow these steps:

It is recommended that this process be automated and run on a schedule using your OS’s task-scheduling application. The more up-to-date a backup is with respect to the current state of synchronization, the easier it is to restore that backup.

Restoring a Backup

Restoring a backup of Tasktop Sync’s workspace is a fairly simple procedure. Please see the following two sections depending on whether you are restoring a backup on the same machine where the backup was created or onto a secondary machine.

Note that there are a few things to consider when restoring a Tasktop Sync workspace backup. In particular, the most recently available backup may be quite old compared to the overall synchronization state of your repositories. For example, if you only create a backup once a week, and the machine running Tasktop Sync becomes unavailable six days after the last backup, then many synchronizations will have completed since the last backup. If this backup is being restored, then it is possible that Tasktop Sync will report spurious conflicts during synchronization while it catches up on processing all of the tasks that changed during that six-day period. The best way of dealing with this situation is to increase the frequency of backups to ensure that the most recent backup matches the most recent state of synchronization as closely as possible.

Restoring a Backup on the Same Machine

To restore a backup saved in the file workspace.zip on the same machine where it was created, follow the steps below:

Restoring a Backup on a Secondary Machine

To restore a backup saved in the file workspace.zip on a different machine than the one where it was created, follow the steps below:

Note that if you are also running OSLC, and restoring the backup on a secondary machine, you will have to repeat the OSLC configuration steps in your repositories to ensure that the IP address of the secondary machine is listed as a friend in your repositories. Please see the relevant sections in this Tasktop Sync documentation for configuring the secondary machine as a friend.

Advanced Backup

The above sections described a simple way of backing up and restoring the Tasktop Sync workspace. However, Tasktop Sync is also compatible with other third-party backup solutions that your environment may have. Any third-party software that can archive the entire Tasktop Sync workspace will be effective at maintaining backups of Tasktop Sync’s synchronization state.

For example, one effective way to back up Tasktop Sync’s workspace so that a secondary instance of Tasktop Sync could be brought up quickly if the primary machine becomes unavailable is to use rsync. rsync can be used to maintain a mirror copy of the main Tasktop Sync workspace on a second machine. If the main machine goes down, then the second machine will have an up-to-date copy of the workspace which can be used to continue synchronization.

Logs and Logging Configuration

Tasktop Sync uses the Apache Log4j logging framework to maintain logs. By default, it keeps a single unfiltered log to make it easy for system administrators to diagnose problems with synchronization. The default location of the log file is $TASKTOPSYNC_HOME$\workspace\tasktop\log\tasktop-sync.log. Log files are rotated and compressed on a daily basis.

Log files are never deleted by Tasktop Sync. It is up to the administrator to determine a retention policy for old log files. However, all log files that have been rotated and compressed may be moved or deleted by an administrator without affecting the functionality of Tasktop Sync.

Logging can be customized by creating the file $TASKTOPSYNC_HOME$\workspace\tasktop\log4j.xml, which follows the standard Log4j XML conventions. You can read the Log4j documentation for more information on how to configure logging with an XML file here. If you wish to customize logging, a sample Log4j configuration file, log4j-sample.xml, is provided. To use this file, rename it to log4j.xml and make the required edits. Note that once a log4j.xml file is present, the logging of events to the tasktop-sync.log file described above is no longer enabled by default.

See advanced configuration for details regarding the value of $TASKTOPSYNC_HOME$.

While Tasktop Sync is running, you can temporarily change the amount of information being logged globally by changing the logging threshold. Log messages with a severity below the threshold will not be written to the log file or displayed in the console. To change the threshold, 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 under “Debugging Options” select the desired logging threshold. This will override the threshold of the root logger, and so it will affect the log message output to all configured logging appenders, including the Tasktop Sync console. The changes will not be saved when you exit Tasktop Sync.
Debugging Options Menu

Please note that repository passwords are stripped from logs prior to writing the log file. The password string is removed in every instance it is encountered.

Workspace, Configuration and Log File Paths

Tasktop Sync requires access to a directory to be able to store configuration information, save intermediate data for processing, and store cache data. This directory is determined automatically, but its location varies depending on what operating system you use and your initial installation procedure. Because of this variability, in the advanced sections of this manual we refer to this directory by the variable $TASKTOPSYNC_HOME$. The following is a list of common locations for this directory:

In each of these cases <User> refers to the user currently running Tasktop Sync.

The Tasktop Sync workspace directory is $TASKTOPSYNC_HOME$\workspace. This directory contains the Tasktop Sync working directory and other cache data used internally by Tasktop Sync.

The Tasktop Sync working directory is $TASKTOPSYNC_HOME%\workspace\tasktop. This directory contains all the Tasktop Sync configuration files, log files, and persisted data.

Sync History Trimming Policy (Advanced)

Tasktop Sync keeps a record of all synchronizations that happened while it was running. Details about each synchronization are stored in a local database, and individual synchronization log files are stored in Sync’s workspace. Over time, this history may grow to a significant size, negatively affecting Tasktop Sync’s startup time. To minimize that effect you can apply one of the following trimming policies:

(By default, no trimming is performed.)

Below is an extract from a synchronizer.xml file which keeps sync history for the last week only.

<sync-model ...>
   <sync-history-trimming-policy policy="delete-all-but-last-x-days" param="7"/>
</sync-model>

A selected policy will be applied when the synchronizer starts and then twice a day while the synchronizer is running.

Repositories in Error

If an error is encountered during synchronization while communicating with a repository, Tasktop Sync will mark the repository as being in error and will not attempt any further synchronization with the repository to avoid flooding the repository with invalid requests.

These errors should be resolved as soon as possible, as synchronizations will not proceed if one of the repositories on either side of the synchronization is in error.

Repository Authentication Errors

If an authentication error is detected with a repository, Sync will place the repository into “back-off” state, which is visible in the Sync Tasks view with a “[Login Error]” suffix:

Repository Login Error

When a repository is in back-off state, no communication will occur between Sync and the repository. This is to stop repositories from disabling the credentials used by Sync. The back-off will last for a period of time, and then communication will automatically resume. Back-off states are all cleared when the the Synchronizer is stopped.

The length of time a repository is in back-off state is dependent on how many authentication errors have occurred recently. On the initial 3 authentication errors, a repository will enter back-off state for 5 minutes after each error. On the fourth authentication error, the repository will enter long-term back-off state, which lasts for 24 hours by default. If the authentication credentials are corrected, and communication resumes for 24 hours without any more authentication errors, then back-off counting is reset to 0.

Repository back-offs can be configured though the “Preferences” menu.

Preferences dialog location

Repository back-off dialog

The following two configuration options are available:

  1. Repository Back-off Enabled: If this checkbox is enabled, repositories can enter back-off state. If not enabled, the back-off feature is completed disabled, and repositories will not enter back-off state.
  2. Back-off Time in Minutes: This sets the long-term back-off length, in minutes.

If you make any changes, and press the “Apply” or “OK” buttons, all repositories currently in back-off state are cleared, and communication will resume.

Changing a Repository’s URL (Advanced)

In the following section, we will refer to the actual server hosting the ALM service as the “server”, and the object within Tasktop Sync as the “repository”.

When the URL of a server is changed, Tasktop Sync needs to update its configuration and cache to use the new URL. Tasktop Sync provides a “Change Repository URL” wizard to assist you in this process. Please note that changing the URL of a repository used by the Tasktop Sync OSLC Linking service is not currently supported.

Prerequisites

Before proceeding with the wizard, you should ensure that the workspace is backed up as described in Backup and Restore.

The following criteria must be met before proceeding with changing the repository URL:

  1. The synchronizer must be stopped. If this has not been done, please click Stop
  2. The web service must be stopped. If this has not been done, please click Web service stop
  3. The configuration must be valid. If this is not so, please open the Mapping Editor (or alternatively open the XML) and make the necessary changes.
  4. The repository must not be being used by the Tasktop Sync OSLC Linking service.

Additionally, you should ensure that all task mapping and XML editors are closed.

Launching the Wizard

To launch the “Change Repository URL” wizard, open the Sync Tasks view and right-click the repository whose server’s URL has changed. Note that this option will only appear for repositories that support this feature.

Launch Wizard

A page will appear, checking for the aforementioned prerequisites. If any of these prerequisites are not met, you will not be able to proceed.

Prerequisites page

Next, a settings page for the repository will appear. Enter the new URL in the box labeled “Server:” and make any other necessary modifications to the repository settings. It is recommended to press “Validate Settings” if the server itself has already had its URL changed to check whether or not the settings are valid.

Repository settings page

After entering the new URL, you will be prompted to confirm the new URL.

Confirmation page

Clicking “Next” on this page will begin the migration process. This process may take several minutes.

Once migration is done, a results check list will appear indicating whether the migration succeeded. If a failure occurred, check the Error Log view and then restore the workspace from the backup created earlier. If the backup is not restored Sync will be in an invalid state after a failed repository URL change.

Migrating a Project to Another Server (Advanced)

In the following section, we will refer to the actual server hosting the ALM service as the “server”, and the object within Tasktop Sync as the “repository”.

When a project is migrated to another server, Tasktop Sync needs to update its configuration and cache to use the new URL. Tasktop Sync provides a “Migrate Repository to Another Server” wizard to assist you in this process. Please note that automatically updating the Tasktop Sync OSLC Linking service is not currently supported.

Prerequisites

This process is not supported by all ALM systems in Tasktop Sync. Currently the following systems are supported.

Before proceeding with the wizard, you should ensure that the workspace is backed up as described in Backup and Restore.

The following criteria must be met before proceeding with changing the repository URL:

  1. The synchronizer must be stopped. If this has not been done, please click Stop
  2. The web service must be stopped. If this has not been done, please click Web service stop
  3. The configuration must be valid. If this is not so, please open the Mapping Editor (or alternatively open the XML) and make the necessary changes.
  4. The repository must not be being used by the Tasktop Sync OSLC Linking service.
  5. The mapping involving the repository must be a full scope mapping.

Additionally, you should ensure that all task mapping and XML editors are closed.

Launching the Wizard

To launch the “Migrate Repository to Another Server” wizard, find the task mapping in the Services view which is synchronizing the migrated project and right click on the appropriate repository. Then select “Migrate Repository to Another Server...”.

Starting the wizard

A page will appear, checking for the aforementioned prerequisites. If any of these prerequisites are not met, you will not be able to proceed. If all prerequisites are met, click “Next”.

Wizard prerequisites

Next, the new server containing the project must be chosen. If a repository for this server has already been created it can be selected on the “Select Repository” page by selecting “Use existing repository connection”. If a repository has not yet been created for this server one may be created by selecting “Create new repository connection”.

Select or create a repository

After choosing the repository to use in the mapping, new initialization and changes queries must be configured. When queries are configured Tasktop Sync will perform a schema generation and ensure that the configured queries contain tasks which match the mapping’s scope. Note that the scope cannot be changed; to perform a migration the scope before and after the migration must be identical.

Select new queries

Once the schema has been generated and the configured queries have been validated, clicking “Next” will present a page detailing the migration process. Clicking “Next” on this page will begin the migration process. This process may take several minutes.

Confirm the migration

Once migration is complete, a results check list will appear indicating whether the migration succeeded. If a failure occurred, check the Error Log view and then restore the workspace from the backup created earlier. If the backup is not restored Sync will be in an invalid state after a failed migration.

Migration results

After Completing the Wizard

If a project which has been migrated is involved in more than one task mapping, for example if there are separate task mappings for synchronizing multiple item types within a project, then the wizard must be run separately for each of the relevant mappings.