Appendix: Troubleshooting

Inspecting the Error Log

Tasktop Sync will log errors and warning to the Error Log. The Error Log can be selected by clicking on the “Tasktop Sync” drop-down menu in the Tasktop Sync toolbar and selecting “Open Error Log”. Once opened the Error Log will appear in the lower pane of Tasktop Sync.

The Error Log shows real-time messages at a higher level than the console view. Messages shown in this view will be of higher importance than those in the console view and will typically indicate that there have been errors during synchronization. Each error will provide information such as a description of the error, when the error took place, and a stacktrace indicating what code was executing when the error was encountered.

Generating an Error Report

In the event of an error while using Tasktop Sync, Tasktop Sync can generate an error report in .zip format for sending to Tasktop support. To generate the report, follow these steps:

Tasktop Sync Studio

In the top left corner of the Tasktop Sync Studio UI, click on the arrow next to the Tasktop Sync logo to open a drop-down menu.
Arrow next to Tasktop Sync Dashboard button

Select the “Create Error Report...” option from the menu that appears.
"Create Error Report" menu option

In the dialog that appears, select which components of the error report should be included. Each component can be selected, and a summary of the information included in that component will be shown. Once the desired components to include have been selected, click “Next”.
Error report dialog box with options

Choose a location to save the report. Click “Finish” to generate the error report.
Error report dialog box with options

The error report can now be sent to Tasktop support as a .zip file, found in the aforementioned location.
Error report file in file explorer

Tasktop Sync Web UI

On the Logs page of the Tasktop Sync Web UI, click the button labelled “error report...”.
Error report download button in Web UI

Wait for Tasktop Sync to generate the error report, this make take a few minutes. The error report will automatically download via the browser.

The error report can now be sent to Tasktop support as a .zip file, found in the downloaded location.

Error reports generated in the Tasktop Sync Web UI are not configurable, they exclude the Tasktop Sync database as well as all but the last seven days of synchronization logs.

Disclaimer

Error reports may contain confidential information. Before handling or transmitting the error report, please ensure that these procedures are in compliance with your organization’s policy regarding sensitive and confidential information.

Accessing and Understanding the Tasktop Sync Logs

Tasktop Sync maintains detailed logs of all operations it performs while processing synchronizations. These logs are helpful in determining the cause of synchronization errors. However, because they are so detailed, they can sometimes be hard to understand. This section explains how to access these logs, and how to pick out relevant information.

There are three primary places to look at logging information:

  1. The first source of logging information is the Console view. This log will show output in real time as Tasktop Sync is running; however, the default verbosity of the console view typically shows only high-level logging messages, and the console view is cleared each time Tasktop Sync is restarted. For this reason, the console view is useful for quickly determining if a problem has just occurred by looking through the backscroll of the view. Note that the verbosity of the Console view is limited by the verbosity of the global logging threshold.
  2. The primary source of detailed logging information by task is stored in the Sync Log editor. See the Sync Log for details on opening this log viewer.
  3. Finally, the on-disk log files contain the most detailed logging information. See the Log File for details on locating these log files. Note that these log files can be particularly difficult to read because they can contain interleaved messages as synchronizations are processed in parallel.

Reading Tasktop Sync Logs

Each line of the synchronization log follows the same format:

[LogLevel] [Date Time] Message

For example, each synchronization log starts off by printing the version of Tasktop Sync used to complete the synchronization:

[DEBUG] [2012-09-13 14:59:34.901] Tasktop Sync Version: 4.0.0.qualifier 

This is a DEBUG level log message that occurred on 2012-09-13 at time 14:59:34.901.

Each Tasktop Sync log also follows a consistent format for reporting details of the synchronization. This format is:


Tasktop Sync Version Information
RefreshSource
RefreshProxy
UpdateProxyState
UpdateSourceState
Done

These regions of the log files are delineated by log messages such as:

[DEBUG] [2012-09-13 14:59:35.787] Transitioning task using UpdateProxyState: https://rtc3.example.com:9443/ccm/resource/itemOid/com.ibm.team.workitem.WorkItem/_pnvAMP3tEeG0daazVVx5RA (5774)

This message shows which section of the log file is being entered, as well as the URL and task ID of the source task being processed.

The most interesting sections of the log are UpdateProxyState and UpdateSourceState. These sections detail determining which mappings should apply, as well as applying the relevant mappings. These sections also include the new values that were stored in the proxy task as a result of the synchronization process. Further, these sections print out each task attribute and its corresponding value before applying mappings and after applying mappings, which makes it easy to determine the initial and final state of the tasks retrieved from the repositories and submitted to the repositories.

Since UpdateProxyState and UpdateSourceState follow the same conventions, this section describes the logging output of only the UpdateProxyState.

The first two logging messages printed after entering the UpdateProxyState section are all the task attributes and their initial values for both tasks associated with the synchronization. These appear as:


[DEBUG] [2012-09-13 14:59:35.787] --begin source--
[DEBUG] [2012-09-13 14:59:35.787] SyncItem: https://rtc3.example.com:9443/ccm/resource/itemOid/com.ibm.team.workitem.WorkItem/_pnvAMP3tEeG0daazVVx5RA
isIncoming : true
itemType : task
BgClosingDate:
archived:
category: _jnk04_nAEeCOcd6Rixv_mw
contextId: _jF9WI_nAEeCOcd6Rixv_mw
correctedEstimate:
creationDate: 1347573294249
creator:
...
[DEBUG] [2012-09-13 14:59:35.787] --end source--

and


[DEBUG] [2012-09-13 14:59:35.787] --begin proxy--
[DEBUG] [2012-09-13 14:59:35.787] SyncItem: http://hpalm.example.com:8080/qcbin;SYNCHRONIZER;RyansArea-DEF2076
isIncoming : false
itemType : BUG
BG_ACTUAL_FIX_TIME:
BG_ATTACHMENT:
...
[DEBUG] [2012-09-13 14:59:35.787] --end proxy--

This is followed by two more sections: “computing synchronization plan”, and “applying synchronization plan”. These sections are delineated by the messages:

[DEBUG] [2012-09-13 14:59:35.787] ** Computing synchronization plan (source -> proxy)

and

[DEBUG] [2012-09-13 14:59:35.804] ** Applying synchronization plan (source -> proxy)

Computing the synchronization plan is where Tasktop Sync determines which mappings to apply or skip; log messages in this section include detailed information about why a particular mapping is or is not applied. This is the section to consult if you are unsure why a particular mapping is not being applied.

Applying the synchronization plan is where Tasktop Sync applies the mappings from a task to its proxy task. This section contains detailed logging information about which attributes are being changed as part of the synchronization process and the new values that will be submitted to the repository.

Log messages outputted when computing the synchronization plan look like:

[DEBUG] [<Date> <Time>] [<Action>,<Reason>]: <MappingType> [sourceId=<sourceId>, sourceKey=<sourceKey>, targetId=<targetId>, targetKey=<targetKey>, caster=<caster>, targetAttributeStratgey=<strategy>]

This message describes which mapping is being tested. It is common for one of sourceId or sourceKey and targetId or targetKey to be null as mappings specify only one source or target per mapping. The caster attribute specifies which caster is being tested; by default, this is CopyCaster, which copies the value from source to target without modification. targetAttributeStrategy specifies which synchronization strategies were defined for this mapping.

The most interesting sections of this message are the <Action> and <Reason> sections. <Action> is either Adding Mapping or Skipping Mapping, depending on whether Tasktop Sync will apply or skip this particular mapping. The <Reason> section describes the reasons why this action will be taken. For example, here are some sample synchronization plan computation messages:


(1) [DEBUG] [2012-09-13 14:59:35.803] [Adding Mapping,No Conflict,Modified Attributes]: DefaultTaskAttributeMapping [sourceId=task.common.summary, sourceKey=null, targetId=task.common.summary, targetKey=null, caster=com.tasktop.internal.sync.core.caster.CopyCaster@119cb48, targetAttributeStrategy=CREATE]
(2) [DEBUG] [2012-09-13 14:59:35.804] [Skipping Mapping,Source Attribute Not Changed]: DefaultTaskAttributeMapping [sourceId=null, sourceKey=description, targetId=null, targetKey=BG_DESCRIPTION, caster=com.tasktop.sync.core.caster.HtmlCopyCaster@4470e488, targetAttributeStrategy=CREATE]
(3) [DEBUG] [2012-09-13 14:59:35.804] [Skipping Mapping,No Matched Attributes]: DefaultTaskAttributeMapping [sourceId=null, sourceKey=BG_RESPONSIBLE, targetId=null, targetKey=BG_RESPONSIBLE, caster=com.tasktop.sync.core.caster.PersonCaster@4fabbfd2, targetAttributeStrategy=CREATE]
(4) [DEBUG] [2012-09-13 14:59:35.804] [Skipping Mapping,No Matched Attributes]: DefaultTaskAttributeMapping [sourceId=null, sourceKey=task.common.key, targetId=null, targetKey=BG_USER_01, caster=com.tasktop.internal.sync.core.caster.CopyCaster@14be9cdb, targetAttributeStrategy=CREATE]

Line 1 shows a mapping that Tasktop Sync will apply. The reason that this mapping applies is because Tasktop Sync has detected that applying it results in no conflicts, and that applying this mapping results in modified attributes ( No Conflict,Modified Attributes). Note that both the source and target attributes of this mapping are task.common.summary.

Line 2 shows a mapping that will be skipped ( Skipping Mapping) because the source attribute of the mapping ( description) has not changed ( Source Attribute Not Changed).

In this particular example, only one mapping will be applied, so the applying synchronization plan section is relatively straightforward. These messages look like:

[DEBUG] [<Date> <Time>] <TargetTask>#<AttributeName> <- <ValueList>

This message describes the target task and attribute which is being changed, and the values that are being stored in this attribute as a result of applying the mapping. Following our above example, the logging message for this synchronization would be:

[DEBUG] [2012-09-13 14:59:35.804] http://hpalm.exmaple.com:8080/qcbin;SYNCHRONIZER;ProjectArea#BUG::2076(DEF2076)##BG_SUMMARY <- [[New Summary]]

This message shows that the BG_SUMMARY attribute on DEF2076 is getting a new value: “New Summary”.

Finally, the last messages of the UpdateSourceState section will print out the values of the task attributes that are sent to the repositories as a result of the synchronization, and will print them out in the same format that the initial state of the tasks were logged.