The Tasktop Sync Interface

This section explains the layout of Tasktop Sync and how you can use the provided views to manipulate Tasktop Sync. To configure Tasktop Sync please see the configuration section.

The Tasktop Sync Toolbar

Tasktop Sync toolbar

Along the very top of the Dashboard window is the Tasktop Sync toolbar which provides ways to control and configure Tasktop Sync.

Tasktop Sync actions

The far left “Tasktop Sync” button provides access to general Tasktop Sync actions.

These action include:

Immediately to the right of the Tasktop Sync button are buttons to start, restart, stop and pause/resume Tasktop Sync. When the pause button is clicked, Tasktop Sync will finish any operations that have already been started, but will not begin any new processing.

On the far right is a drop-down menu with controls for Tasktop Sync’s web server. From here the web server may be started, stopped or restarted. Additionally the configuration for Tasktop Sync’s web server and OSLC adapter may be opened.

The Tasktop Sync Dashboard

In the main editor view is the Tasktop Sync Dashboard itself.

Tasktop Sync Dashboard

Dashboard Statistics

At the top of the Tasktop Sync Dashboard is the statistics section, which displays the following statistics:

The Active and Error Queues

Below the statistics section are the active and error queues. The active queue displays all of the active synchronizations. The error queue displays all synchronizations that didn’t complete successfully and require manual intervention. Right-clicking on any of the entries in the error queue and selecting “Open Source Data” or “Open Target Data” will display the attributes of the source or target task, respectively, as well as the values associated with those attributes. Double-clicking on an entry in the error queue will open the Synchronization Log Viewer of that task, which provides more detailed information about the synchronization history of the task. Both the list of task attributes and the Synchronization Log may be helpful in determining why a synchronization failed. Entries in the error queue can be manually retried by right-clicking on the entry and selecting “Queue for Synchronization”. Otherwise, the synchronizer will not automatically retry the synchronization until one of the participating tasks changes. Both the active queue and the error queue may be searched using the provided search boxes.

Tasktop Sync active queue

Tasktop Sync errors

Error Queue Filters

In addition to using the search box, the error queue can also be filtered by task mapping by using the drop-down menu located at the top right-hand corner of the queue:

Selecting a Mapping

When a mapping is selected, errors that did not originate from that mapping will not be shown. Errors that cannot be matched to a specific mapping will still be displayed, but will be shaded gray to indicate that they are unmatched. The selected filter can be toggled off and on by clicking on the filter icon next to the drop-down menu.

Filter On

Proxy Task Recreation

If one of the tasks in a synchronized pair has been deleted, the other task will end up in the error queue the next time it is synchronized. This occurs because Tasktop Sync is unable to locate the changed task’s proxy task. Tasktop Sync will not automatically recreate deleted proxy tasks, however this can be accomplished manually. Right click on the task in the error view whose proxy task has been deleted, and select “Recreate Proxy Task” under the “Advanced” sub-menu.

Recreate Proxy Task

Tasktop Sync will prompt you to confirm the proxy recreation. Once confirmed the selected task will have its proxy task recreated at the next opportunity.

Ignoring New Changes for Selected Errors

A synchronized pair of tasks in the error queue can be set so that their future changes are ignored. To do this, right click on the task pair in the error view, and select “Clear Selected Errors and Ignore Changes” under the “Advanced” sub-menu. The selected pair will also be cleared from the error queue.

The Diagnostic Views

Below the Tasktop Sync Dashboard is a panel with several views:

The Sync Tasks View

Sync Tasks

The Sync Tasks view lists all of the defined repository connections in Tasktop Sync, along with the queries associated with each. Each query can be expanded to list all of the tasks it returns. Note that the presence of a repository in this view does not necessarily mean it participates in synchronization; you must also configure mappings for these repositories if you want tasks to synchronize.

Along the top of the view are buttons to create a new repository connection, or a new query, as well as buttons to expand or collapse the contents of the view.

Many actions can be triggered from the Sync Tasks view by right clicking on repositories, queries, or tasks.

Repositories may have their schemas regenerated, or their configuration updated by right clicking on them in the Sync Tasks view. For more details on repository configuration and schemas see Repository Configuration Changes. Additionally a repository may have its URL changed by right clicking on them in the Sync Tasks view.

Tasks and their synchronization history may be inspected from this view. Right-clicking on any task in this list and selecting “Open Synchronization Log” will open the Synchronization Log Viewer, which displays the synchronization history of the selected task. Double-clicking any task in the list, or right-clicking on a task and selecting “Open Task Data”, will display the attributes of the selected task and the values associated with those attributes. Both the list of task attributes and the Synchronization Log may be helpful in determining why a particular task is or is not synchronizing.

The Services View

Finally, on the left of the screen, there is the Tasktop Sync Services View. This is where you will see a summary of the repositories and queries you have configured to actively participate in linking and synchronization. This list may be different than the lists in the Sync Tasks views if you have not configured Tasktop Sync to make use of all the repositories or queries you have defined.

Tasktop Sync Services View

The Services Toolbar

Along the top of the Service View is the toolbar. It contains the actions “Expand All” and “Collapse All”, which expand or collapse all of the nodes in the Services View, respectively. Individual nodes are expanded or collapsed by clicking the triangle to the left of each node, or right-clicking the node and clicking either “Expand” or “Collapse”. The toolbar also contains the actions “Open Working Directory”, which opens a file explorer pointing to the Tasktop Sync working directory, and “Open Synchronizer XML”, which opens a text editor containing the synchronizer.xml file.

The Services Filter

Directly below the toolbar is the “Filter Mappings...” text box. If you have a large number of task mappings or templates, you can filter out any that do not contain your search term. Entering text into this box will hide any mappings or templates whose name, repository connector kind, repository URL or repository label do not match your search. For detailed searches, this filter also supports regular expressions.

The Services Menu

Along the far right of the toolbar is the drop-down Services Menu, which contains a few more advanced actions. The “Run Sync Queries” action forces Tasktop Sync to run all repositories' changes queries. The “Clear Error Queue” action sets the state of all entries in the error queue to Aborted, and the “Clear Active Queue” action sets the state of all synchronizations that are currently active or pending to Aborted. Since these synchronizations are set to Aborted, they will not be retried until a change is made to the source or the proxy task. It is also possible to open the working directory and the configuration file from the Services Menu by clicking on the “Open Working Directory” and “Open Synchronizer XML” icons, respectively.

Tasktop Sync Services Menu

Integration Visualizer

The Integration Visualizer provides a compact view of how sync mappings unify and synchronize the activities between multiple repositories. The various nodes and links between them are automatically generated per sync configuration and will expand as your ALM architecture evolves.

Tasktop Sync Integration Visualizer

To access the Integration Visualizer, right-click “ALM Synchronization” in the Services view and select “Open Integration Visualizer”.

Open Integration Visualizer menu option

Repository Node

Integration Visualizer repository

Repositories are represented by their cylinders in the Integration Visualizer. Double-clicking the cylinder will open the Repository configuration wizard, which allows the editing of information regarding that repository.

Displayed on the node are statistics describing the synchronized tasks and users of a repository. The “Tasks” statistics displays the number of tasks that have had synchronizations completed, are being processed, have errored out, or have been aborted by all mappings connected to that repository. The “Users” statistics describes all users that have reported, been assigned to, or have posted comments or attachments to synced tasks from that repository.

Task Mappings Node

Integration Visualizer mappings

Between pairs of repositories with mappings, the task mapping node displays all the mappings in which the repositories are related. Double-clicking on any task mapping will open that mapping’s Task Mapping Editor.

The different colours on the bars for each task mapping represent the ratios of the states that synchronizations of that mapping ended in.

Colour of Task Mapping Bar: Interpretation:
Green Successful completed synchronizations.
Yellow Synchronizations that have been manually aborted.
Red Synchronizations that resulted in an error and are thus unsuccessful.

Starting the Synchronizer

From the Tasktop Sync toolbar or tray icon’s context menu, start the Synchronizer by pressing the Start Button in the toolbar. Tasktop Sync will begin synchronizing tasks between configured repositories.

The Synchronizer maintains a persistent store of all tasks that have incoming changes that have not yet been synchronized (including those with errors). When the server is restarted it will reload the queue and continue where it left off.

Marking for Synchronization

While setting up Tasktop Sync mappings and during troubleshooting, it can be useful to mark one or more selected task for synchronization. To do this, open the Sync Tasks view, select one or more tasks, right-click, and select “Mark for Synchronization”. This will cause the selected tasks to be added to the Tasktop Sync active queue for processing.

Mark for Synchronization action

Ignoring New Changes

Specific, unwanted tasks can be configured so that their changes will not be synchronized. To do this, open the Sync Tasks view, select one or more tasks, right-click, and check “Ignore Changes”. The selected tasks and their proxies will now have their changes ignored during synchronization. Unchecking the option will allow previously ignored tasks to be synchronized and will perform a Mark for Synchronization. Ignored tasks have a strikethrough and are greyed out.

Ignore Changes action

Synchronizing Attachments Again

If an attachment was marked as invalid while attempting synchronization, it will not be synchronized in the future. To manually re-synchronize a task’s attachments and clear their error state, open the Sync Tasks view, select one or more tasks, right-click, open the “Advanced” sub-menu, and select “Synchronize Attachments Again”. This will cause all of task’s attachments to be synchronized as well as a Marking for Synchronization to be performed.

General Settings

General settings for Tasktop Sync can be found under “General Settings” within the “Preferences” menu.

Preferences dialog location

General Settings Dialog

Instance Name

Tasktop Sync can be assigned an instance name. This will appear in the application’s title bar, in the web user interface, and in the subject of any emails Tasktop Sync may send. Information on emails can be found in the Notifications section. This setting may be useful when running multiple instances of Tasktop Sync.

The “Tasktop Sync Instance Name:” field sets the instance name, as shown below:

Instance name set

Legacy Schema Refresh Task Limit

Task limit

Some repositories require that all tasks be scanned when generating repository schema. This method is referred to as Legacy Schema Refresh. The Legacy Schema Refresh Task Limit setting limits the number of tasks which are refreshed and scanned during Legacy Schema Refresh. This can reduce the time required for repository schema generation, but has the consequence of possibly failing to retrieve the latest configuration if the limit is set too low. If this not set or set to 0, then there will be no limit. For task repositories not using Legacy Schema Refresh, this setting has no effect. For more information about repository schema generation, see Repository Configuration Changes.

Force Legacy Schema Refresh

Force Legacy

For task repositories that can provide repository schema details from a single task, you can still force Tasktop Sync use the slower Legacy Schema Refresh, forcing Tasktop Sync to review all tasks (or up to the limit defined in Legacy Schema Refresh Task Limit ) when refreshing the repository schema. To force Tasktop Sync to use Legacy Schema Refreshing on all repositories, click the checkbox beside “Force Legacy Schema Refresh”. For more information about repository schema generation, see Repository Configuration Changes.