Task Synchronization Configuration

Creating a Task Mapping

Creating a task mapping in Tasktop Sync requires that three primary items be configured: a connection to each participating repository, a set of queries defining the scope of the synchronization, and a mapping that defines how synchronization between two repositories should be handled.

Tasktop Sync provides a repository creation wizard as well as a thorough task mapping editor to assist you in creating all three of these requirements. However, some synchronization setups require complicated definitions. To support the full range of synchronization complexity, Tasktop Sync also allows manual configuration of the synchronization mapping through its configuration file. For details on manual editing of the configuration file see the Manual Configuration section.

However, even if you require the ability to later edit the configuration files by hand, it is recommended that you initially create your task mappings using the Quick Start Wizard and task editor.

In order to use the Quick Start Wizard, you will need to create a test task in each of the repositories you want to sync (these tasks can be deleted after you are done with the Quick Start Wizard). You can use pre-existing tasks, but that is generally a bad idea if you are using a production system.

If you have not yet defined any mappings, you will see a “Launch Sync Quick Start” link in the upper left Services view:

Launch Quick Start menu option

If that link is available, click on it to start the Quick Start Wizard. Otherwise you can right-click the “ALM Synchronization” node in the Services view and select "New Task Mapping."

If you have not yet defined any mappings, you will be presented with a welcome page which reminds you that you need credentials for the two repositories to sync. This page will not appear if you already have mappings defined.

Quick Start welcome page

The next page will ask you for some details about the mapping to configure. In addition to the mapping name (used for display in the UI), you will be asked to choose your desired type of mapping.

A “Full Scope” mapping will apply your synchronization to all existing tasks returned by your queries, replicating each existing task from one repository in the other and creating any new tasks added to one in the other. See Create Queries for more information.

A “Limited Scope” mapping asks you to select only a single pair of existing tasks returned from your queries to test your configuration between the two before applying your synchronization to all in-scope tasks.

Note that if you start with a scope limited to a single pair of tasks, you can convert it later to use queries to cover many tasks.

Quick Start mapping details page

Next, you will see a page which allows you to specify which kind of repositories you would like to sync. The order in which you specify the two repositories doesn’t affect the synchronization at all.

Quick Start repository selection page

After you select which type of repository to use for Repository One and Repository Two, you will see two pages where you will enter your credentials for each repository. These will be different depending upon which repository type you select. Here is a screen shot of the credentials page for an HPE QC / ALM connector:

Quick Start repository settings page

Full Scope

If you chose “Full Scope”, the next page will ask you some details about the source and scope of the first repository. This includes the two queries that define the mapping source, the scope of the tasks, and the proxy storage configuration.

Quick Start scope page

For each repository, you need to configure queries. See Create Queries for more information about query scope. You may choose existing queries, or create new queries.

For each of the scope fields, select the value that matches your tasks within your queries.

You need to configure proxy storage. See Proxy Association Storage for more information.

This must be repeated on the next page for the second repository.

After you press Finish, Tasktop Sync will open the task mapping editor for your new mapping. The mapping will be configured to synchronize the summary attribute (and only the summary attribute) between the sets of tasks you defined.

Limited Scope

If you chose “Limited Scope”, the next two pages will ask you to choose queries from each repository. You only need to fill in the initialization query and the scope for each repository; the changes query and proxy storage configuration are optional.

Quick Start scope page

After completing the source and scope page for each repository, you must choose a task from each repository. The results of each initialization query are shown on the page; click on a single task in each list. To help you locate the desired task, you can enter some filter criteria to narrow down the list.

Quick Start scope page

After you press Finish, Tasktop Sync will open the task mapping editor for your new mapping. The mapping will be configured to synchronize the summary attribute (and only the summary attribute) between the two test tasks that you created.

In order to start synchronizing, Tasktop Sync must be started. See The Toolbar for how to start Sync.

Editing a Task Mapping: The Task Mapping Editor

The Task Mapping Editor displays the mapping configuration in a user-friendly format. It shows you information about the repositories, queries, and mappings. The editor also provides direct links for viewing repository schemas, editing repository scope, and editing query parameters.

Task Mapping Editor Overview page

To access the Task Mapping Editor, double-click on the mapping title in the Services view or right-click the mapping title and select Properties.

Services View repository list

Task Mapping Editor Layout

Repositories

General repository information is displayed in the upper sections of the Task Mapping editor. The repository information includes the repository URL, credentials, proxy creation trigger, and the proxy storage configuration. The name of the repository type will be in the header of this section, and the icon for the repository type will be next to the URL link.

Overview page repository information section

This section of the editor links to the repository “Properties” editor through the URL and Username/Password links. If a username or password has not been supplied, a yellow warning sign will be displayed next to the text box.

Repository Scope

The Repository Scope section defines the set of tasks which are candidates for synchronization between two repositories. If you created your mapping with the Quick Start Wizard’s Limited Scope, the scope will initially be a single task for each repository. The URL of this task will be displayed in the Task ID field shown in this section.

To expand the scope of your synchronization you will have to configure Tasktop Sync to use a set of queries as its definition of the source. You can convert to using queries as the defining source by clicking on the “Switch to Full Scope” hyperlink shown underneath the Task ID field.

Repository Scope section with Limited Scope

Once you have expanded the scope to use queries, this section will be replaced by two fields for selecting queries. If you chose your queries in Quick Start’s Limited Scope, then some or all of the queries will already be selected.

Repository Scope section with queries

The “Initialization” query is used to initialize or reinitialize the synchronization between tasks. This query should capture all of the tasks that you wish to synchronize from each of the repositories.

The “Changes” query is used to capture the subset of the initialization query tasks which Tasktop Sync should check for changes that require synchronization. This query is run by Tasktop Sync frequently and so should ideally capture a smaller set of tasks than the initialization query. Typically this query captures tasks that have been modified in the last few days.

Note that Tasktop Sync will attempt to synchronize a task even if the proxy task doesn’t fall into the queries on the other side of the mapping.

You can change these queries by clicking on the textbox and selecting a pre-existing query for that repository; clicking on the Changes or Initialization links will bring up the Edit Query dialog. Clicking on the New... button will allow the creation of a query that is immediately defined as your changes or initialization query.

Artifact Scope

The Artifact Scope section displays the fields used to match your tasks within the repository. When tasks are received from your source queries, their attributes must match the scope field values defined here; otherwise, they will be ignored. Each repository will have its defined list of scope fields, and their values. These can be defined by using Quick Start, or they can be edited by clicking the Edit button. Consult the Tasktop Sync Connectors guide for more information.

It is possible that the specification of a system’s scope may change when Tasktop Sync is updated. Tasktop Sync’s configuration must be updated to align with the new scope definition. Until the configuration is updated Tasktop Sync will not run. Details on how to handle this scenario are found on the Tasktop Sync FAQ.

Artifact Scope section

Mapping Preferences

The Mapping Preferences editor defines further mapping configuration options, including attachment, comment, and time worked synchronization, as well as person mappings.

Mapping Preferences

Repository Preferences

Repository Preferences

The “auto-comment user” is the user who will appear as the author of Tasktop Sync’s automatically generated comments.

The “author validation policy” is employed when synchronizing both comments and attachments. It is used to decide whether to validate the authors of comments and attachments, and what to do when author validation fails. When “Do not validate” is selected the mapped authors of comments and attachments will not be validated. When “Use auto-comment user on validation failure” is selected the mapped authors of comments will be validated to determine if they exist in the target repository, if they do not exist the auto-comment user will be used as the author on submission.

To synchronize worklogs, enable “Synchronize Incoming Time Worked”. If enabled, a user’s time worked entries will be synchronized to the associated repository.

Comment Synchronization

Comment Synchronization

To synchronize comments between tasks, click one or both checkboxes labeled “Synchronize Incoming Comments”. Each checkbox represents the target repository to copy comments into.

Aside from enabling or disabling comment synchronization, the “comment content-type” can also be defined for this repository. The “comment content-type” will be used during comment synchronization to convert rich text comments from the format used in the source repository to the format used in the target repository.

The “Add Author Header to Comments” can also be enabled or disabled. The “author header” is a short line of text appended to the beginning of a comment which states the author of the comment from the source repository. For example, if this setting is enabled and the user John Smith in the source repository created the comment This is a comment, then the comment will be appear as the following in the target repository:

(Comment by John Smith) 

This is a comment

Enabling this setting will cause the author header to be added to every new comment synchronized into this repository. Previously synchronized comments will not be modified.

The “Comment Visibility To Synchronize” setting allows the synchronization of specific comment visibilities (e.g. only synchronizing private comments). This setting can only be used by repositories which support the notion of public and private comments. When this setting is set to “All Comments”, no filtering is done and both public and private comments will be synchronized out of the repository. When this setting is set to “Only Private Comments”, only private comments will be synchronized out of this repository. When this setting is set to “Only Public Comments”, only public comments will be synchronized out of this repository.

The “New Comment Visibility” settings specifies the visibility of the comments that Sync will create in that system. This setting can only be used by repositories which support the notion of public and private comments. When this setting is set to “Retain Comment Visibility” newly created comments will have the same visibility as in the comment’s originating system. When this settings is set to “Submit Comments Privately” newly created comments will all have a visibility of private regardless of their visibility in the originating system. Sync can similarly assign public visibility to all new comments by selecting “Submit Comments Publicly”. It is recommended that a setting other than “Retain Comment Visibility” be selected when synchronizing comments from a system which does not support public and private comments to one that does.

Attachment Synchronization

Attachment Synchronization

To synchronize attachments between tasks, click one or both checkboxes labeled “Synchronize Incoming Attachments”. Each checkbox represents the target repository to copy attachments into.

Beyond enabling or disabling attachment synchronization, a “Large Attachment Handling” filter may be defined for this repository. Defining a “Large Attachment Handling” filter will place an upper limit on the size of attachments which will be synchronized into the repository. The attachment filter is configurable with a custom maximum file size and a handling strategy, either to fail a synchronization when an attachment is oversized or to skip the synchronization of the oversized attachments allowing the rest of the synchronization to proceed. The criteria for an attachment being oversized can be set by changing the “Maximum Attachment Size (Bytes)” value.

Additionally, you can configure an “Invalid Attachment Handling” filter to handle invalid attachments. The attachment filter is configurable to either fail on attachment error or to ignore attachment errors during synchronization. After problems are resolved, skipped attachments can be re-synchronized by synchronizing attachments again.

General Preferences

The General Preferences defines configuration options that apply to the entire task mapping. These options include an optional person mapping file (see person mappings ) and conflict resolution and notification policies.

Mapping Settings section

The filename found in the Person Mapping box will also display at the top of the Services view as a link to the person mapping file.

Conflict notification can either be set as Log or Comment. If Comment is selected, when Tasktop Sync detects a conflict it will be reported as a comment in the target task where the conflict was detected. If Log is selected, detected conflicts will be reported in the Tasktop Sync console and on-disk logs. It is recommended that you use Log for conflict notification.

The Conflict Resolution Policy box will display the default conflict resolution policy of this task mapping. When a conflict is detected, Tasktop Sync uses this policy to determine what value should be recorded for the attribute in question. If Do not synchronize is specified then no action is taken to resolve the conflict, and each repository will keep its own value. Otherwise, one of the repositories can be specified as the dominant repository. In this case, the value from the dominant repository will take precedence in resolving the conflict. The conflict resolution policy can be overridden on an attribute-by-attribute basis in the attribute mapping editor.

Attribute Mappings Editor

The attribute mappings editor is used to configure the specific attribute-level mappings that are used when synchronizing tasks between repositories. Before you can configure attribute mappings, you must have a refreshed schema for each repository (see the schema view ). Each part of the attribute mapping editor is described below.

Attribute Mappings editor

Mappings Table

Attribute Mappings

The Mappings table displays all the attributes currently being synchronized. The arrows between the attributes displayed visualize the direction in which the attributes are synced; synchronization can be unidirectional from one repository to another, bidirectional, or non-existent if the mapping should not be applied. The plus and minus buttons on the top right allow the addition and removal of attribute mappings.

Mapping

Attribute Mappings header

This area allows you to define the attributes being mapped. The direction of synchronization can be configured in the Direction box.

Caster

Similar attributes on different repositories often come in different formats, resulting in the need for values to be transformed to the proper format for a given repository. The caster section allows you to configure casters which can perform these transformations.

Casters can also be used for maintaining task relationships. When a task has a relationship to another task in the repository, such as a related defect or a parent requirement, this relationship is exposed as an attribute. For example, an HPE ALM defect has an attribute named “Linked Entities”, which contains a list of related defects, requirements, and test cases. When synchronizing this defect, you may want to synchronize this relationship as well. Tasktop Sync can mirror this relationship to a target repository, if all tasks involved are being synchronized, or it can synchronize the relationship as a web URL, linking back to the source repository.

Once you have selected the attributes being mapped, and the desired direction of the synchronization, the list of casters will be presented. This list is dependent on the mapping details, and will vary depending on the attribute types. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)

Tasktop Sync provides several different casters by default. This section will explain how to configure and use these casters.

No Caster

No caster selected

The simplest cases, such as syncing Summary, require no casters at all, and <None> is the default value.

Value Mapping

Value mapping caster

Some enumeration attributes, such as “Severity” and “Priority” attributes, often have different values between repositories. To map a finite set of values to another finite set of values, such as with enumeration attributes, use the value mapping caster.

Because each mapped attribute may have a different number of values, the value mapping caster allows you to provide a mapping for each direction of the value. Use the tables provided to configure the mappings between the repositories. Note that you should take care to not confuse which direction applies to which table. In the example above, the table on the left shows the mapping of HPE ALM values to Jira values, and the table on the right shows the mapping of Jira values to HPE ALM values.

So, for example. “Major” in HPE ALM becomes “Minor” in Jira. But “Major” in Jira becomes “Major” in HPE ALM.

Tasktop Sync will automatically map two options if they share the same id, when synchronizing by id, or the same label, when synchronizing by label. These mappings do not require manual configuration, and are displayed in the tables as italicized, grey text. The “Critical” value in the example above is an example of such a mapping. Note that these mappings can be overridden by manually configuring the value mapping for the automatically mapped value.

The tables will also display values which are unmapped and cannot be automatically synchronized. These mappings are highlighted in yellow. The values “Semi-Major” and “Urgent” in the above example are such mappings. Additionally, mappings which have been configured but have not been saved are highlighted in green. The “Major” value in the above example is such a mapping.

If there are similar values on both repositories, you can click the “Suggest mappings...” button to automatically fill in mappings. This will generate mappings between values which have similar labels, but will not overwrite any existing mappings.

The value mapping caster can also be configured to map using labels. This setting can be enabled by checking the “Map Using Labels” checkbox. When this setting is enabled the caster will consider only the user facing labels on the attribute and not the internal IDs. This can be useful for sharing value mappings between configuration templates for systems whose IDs are project or type specific.

For example. If a field in Jira has an option “Normal” with ID “1” and IBM RTC has an option “Medium” with ID “_FggUIOfEEeG6psipjwbkrQ” the value mapping caster can be configured to map “Normal” to “Medium” instead of mapping “1” to “_FggUIOfEEeG6psipjwbkrQ” when the map by labels attribute is enabled. The value mapping caster may then be stored in a configuration template which can be re-used to create multiple task mappings involving multiple Jira and RTC projects even if the option IDs change, as long as the labels are consistent across all projects.

This mode has the additional functionality of automatically mapping values which have the same label.

For example. If a field in Jira has an option “Normal” with ID “1” and IBM RTC has an option “Normal” with ID “_FggUIOfEEeG6psipjwbkrQ” the value mapping caster will map these automatically without an explicit mapping when set to map using labels. However if an explicit mapping exists for this option it will be applied instead of the implicit label mapping.

The value mapping caster can also be configured to ignore case when mapping. This setting is enabled by checking the “Ignore Case During Mapping” checkbox. Enabling this setting will cause the case of the incoming value to be ignored when mapping.

For example, consider the a mapping where the value with id “1” and label “Normal” is mapped to the value with id “a” and label “Medium”. If “Ignore Case When Mapping” is disabled, and “Map Using Label” is enabled, then an incoming value with label “Normal” will be mapped to “Medium”, whereas an incoming value with label “normal” will not. If “Ignore Case When Mapping” and “Map Using Label” are both enabled, then an incoming value with label “Normal”, an incoming value with label “normal”, and an incoming value with label “nORmaL” will all be mapped to “Medium”.

External Value Mapping

External value mapping caster

A value mapping can also be defined using a properties file. The properties file will contain the desired mappings, and can be loaded into Tasktop Sync through the user interface. The “Map Using Labels” checkbox indicates whether the mappings within the properties files are specified using the option label or the option id. The “Ignore Case During Mapping” checkbox indicates whether the caster should ignore case when mapping. This will function in the exact same way as the Value Mapping caster. For more information, see the Value Mapping section.

Note: In order for the properties files to be used, they much reside within the “tasktop” directory within the workspace.


A new mapping file can be generated by clicking the “New Mapping” button. This will generate a file which contains mappings for values which have the same label or id, depending on whether “Map Using Labels” is checked.

The properties files for the mappings specified in the Value Mapping section would be defined as follows:

The “HPE ALM-Jira-value-mapping.properties” file:

1-Low=Trivial
2-Medium=Minor
3-High=Major
4-Very\ High=Critical
5-Urgent=Blocker

The “Jira-HPE ALM-value-mapping.properties” file:

Blocker=5-Urgent
Critical=3-High
Major=2-Medium
Minor=1-Low
Trivial=1-Low

Note that two different mapping files are required (one for each direction) because the mappings are not one-to-one.

The contents of the properties files follow the Java properties file format. Some details of the format as are follows:

Further details on the Java properties file format may be found in the Oracle Java documentation

Date/Time Transformation

Date/time caster

For repositories with different date/time formats with attributes such as Date Modified or Date Created, a Date/Time Transformation may need to be used. Pressing Ctrl-space will enable content-assist when filling out the formats. See the Date-Time Caster section for more details.

Person Mapping

Person mapping caster

For fields such as Assignee, Reporter or any other field involving the user identity of a person, the Person Mapping caster can be used if user IDs are different in each repository. This caster must be used in conjunction with the person mapping filed defined in the General Preferences.

Clicking on Go to person mapping settings goes to the General Preferences section of the task mapping editor, to define which person mapping file is being used.

Clicking on Go to person mapping file will go to the Person mapping file currently being used. The person mapping caster uses mapping specified in this file. Read about person mapping files to learn how they are configured.

Text Markup Transformation

Text markup caster

For fields such as Description, different repositories may use different markup to store formatting. When this is the case, use the Text Markup Transformation caster. Select from the drop-down menu to specify the text content-type of each repository.

In the case that a repository does not support rich text, we suggest setting the format to Textile, as it is a rich text format which is easily readable as plain text.

If both repositories use HTML markup, we suggest using the Text Markup Transformation with HTML selected for the text content type for both repositories. This will enable a transformation that handles differences in HTML generated by repositories from different vendors.

Literal Value

Literal value caster

If you want attributes to be set to a specific fixed value, use the Literal Value caster. Read here for more information about the usage of this caster. If the attribute being written to with a literal caster comes from an enumeration, then contest-assist, available via Ctrl-space, is available to get a list of options to select from. This can be useful for setting defaults on enumerated types when syncing repositories with required fields which do not conveniently map to a field in the other repository.

Multi-value to CSV String

Multi-value to CSV caster

If you have a multi-select attribute in one repository and want to synchronize the labels of the selected options to a string field on the other, you can use the Multi-value to CSV String caster. This caster supports bidirectional synchronization between a multi-select field and plain-text string field. When synchronizing to the string filed, the value will be a comma delimited list of the labels from the multi-select field (e.g. one,two) and when synchronized to the multi-select, the correct options will be selected based on the labels provided in the string field. When using this caster, the none of the values of the multi-select field may contain a comma.

Value to String

Value to String caster

If you have a single-select attribute in one repository and want to synchronize the label of the selected option to a string field on the other, you can use the Value to String caster. This is also useful when you just want a 1-way mapping of the label from a single-select field to a string field for reference in the other system. This caster supports bidirectional synchronization between a single-select field and plain-text string field. When synchronizing to the string field, the label of the value in the single-select will be written. When synchronizing to the single-select field, the correct value will be selected that matches the label specified in the string field.

Custom Script

Custom script caster

If you have defined custom casters, then you can use these as casters for your attributes. Read here for more information about how to define custom casters. To assign your custom caster, first select the caster “Custom Script”. You can then assign a custom caster to each attribute. These casters will be used when writing to the associated attribute.

Task Link to Task Link caster

When synchronizing task relationships, use the Task Link to Task Link caster. This caster will copy the relationship from one repository to the other, mirroring the task hierarchy in each. For example, if you are synchronizing both test cases and defects between two repositories, you can maintain the link between them in both repositories.

This caster can only be selected for a mapping that meets the following condition:

  1. Both attributes in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)

If this condition is not met, the caster will not appear in the Caster selection list.

Validate links before synchronizing

There are conditions where relationships in the source task should not all be synchronized to the target task, and you only want to copy over a subset of relationships. There are two primary examples of these conditions: when the referenced task in the source will not synchronize to the target repository, or when the target task’s link field has restrictions on the types of relationships it accepts.

For example, if your relationship references both test cases and defects, but Tasktop Sync only synchronizes test cases, then any tasks that reference defects will result in an error (since the defects do not have proxy associations in the target system). To further the example, even if both test cases and defects are synchronized, but the target repository only allows links to defects, then any tasks that reference test cases will result in an error.

To stop this from happening, check the box beside Validate links before synchronizing. When this option is checked, Tasktop Sync will only synchronize relationships that meet the following conditions:

  1. The referenced task matches a task mapping synchronizing to the target repository (see “Task Matching Criteria” below).
  2. If there is a restriction on the target attribute, the referenced task, when synchronized, meets these restrictions.

All references to tasks that do not match the conditions will be ignored.

Task Matching Criteria: A task “matches” a task mapping if the following criteria are met:

  1. The repository URL of the task and the task mapping are the same.
  2. The task attributes match the values defined in the task mapping Artifact Scope.
  3. If specified, the task meets the task mapping conditions.
  4. The task is returned by the task mapping’s changes query
Task Link to Task Link Group

Task Link to Task Link Group caster

To synchronize multiple task relation attributes from one repository to a single task relation attribute in another repository, use the Task Link to Task Link Group caster. For example, if one repository defines many different forms of relationships in different attributes, such as “blocked by” and “duplicates”, and your target repository has only a single attribute for these relationships, “links”, you can use the Task Link to Task Link Group caster to combine all relationships in both “blocked by” and “duplicates” into the target of “links”.

This caster works as a compliment to the Task Link to Task Link caster, allowing you to combine two or more attribute into a single mapping to a target attribute. This caster can only be used to combine the mapping with an existing mapping with the Task Link to Task Link caster, so you must define this mapping first. To continue the previous example, you would first define a mapping between “blocked by” and “links” with a Task Link to Task Link caster. You then create a second mapping between “duplicates” and “links” using the Task Link to Task Link Group caster. In a final step, in the configuration of the Task Link to Task Link Group caster, you combine the two mappings by assigning “blocked by” as the default attribute.

An important feature of the Task Link to Task Link Group caster is that it only supports unidirectional mappings. The associated Task Link to Task Link caster can be bidirectional. This directs Sync on which attribute to add new task relations found in the target repository attribute. To once again continue on the example, if a new task relation was added to “links”, this task relation would be synced to “blocked by”, since it was mapped with the bidirectional Task Link to Task Link caster.

This caster can only be selected for a mapping that meets the following conditions:

  1. Both attributes in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. The mapping must be unidirectional from the repository with multiple attributes to the repository with the single attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Note: The relationship can only be synchronized if the tasks on both sides of the relationship are being synchronized between the two repositories. If only one of the tasks is being synchronized, the synchronization will result in an error.

Task Link to Web Link caster

To synchronize an internally referenced task as a web URL, use the Task Link to Web Link caster. With this caster, you can synchronize the association to referenced tasks, without synchronizing the referenced tasks themselves. What will be synchronized to the target task will be a web URL, which can be opened in a browser to view the referenced task.

This caster also supports formatting of the target link’s label. Pressing Ctrl-space will enable content-assist when filling out the format. See Task Link To Web Link Caster in the advanced Transforming Task Attribute Values with Casters section for more details.

This caster can only be selected for a mapping that meets the following conditions:

  1. One attribute in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. One attribute in the mapping must be of the type “externalLink”.
  3. The mapping must be unidirectional from the “taskDependency” attribute to the “externalLink” attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Task Link to Web Link Group

Task Link to Web Link Group caster

To synchronize multiple internal task relation attributes from one repository to a single web URL attribute in another repository, use the Task Link to Web Link Group caster. For example, if one repository defines many different forms of relationships in different attributes, such as “blocked by” and “duplicates”, and your target repository has only a single attribute for storing web URL link, “web links”, you can use the Task Link to Web Link Group caster to combine all internal relationships in both “blocked by” and “duplicates” as URLs into the target of “web links”. What will be synchronized to the target task will be web URLs, which can be opened in a browser to view the referenced task.

This caster works as a compliment to the Task Link to Web Link caster, allowing you to combine two or more attribute into a single mapping to a target attribute. This caster can only be used to combine the mapping with an existing mapping with the Task Link to Web Link caster, so you must define this mapping first. To continue the previous example, you would first define a mapping between “blocked by” and “web links” with a Task Link to Web Link caster. You then create a second mapping between “duplicates” and “web links” using the Task Link to Web Link Group caster. In a final step, in the configuration of the Task Link to Web Link Group caster, you combine the two mappings by assigning “blocked by” as the default attribute.

This caster also supports formatting of the target link’s label. The configuration for this caster is shared with the configuration for the referenced default attribute mapping.

This caster can only be selected for a mapping that meets the following conditions:

  1. The source attribute in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. The target attribute in the mapping must be of the type “externalLink”.
  3. The mapping must be unidirectional from the “taskDependency” attribute to the “externalLink” attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Task Link to String

Task Link to String caster

If you need to synchronize an internally referenced task as a web URL, but your target repository does not support attached web URLs, use the Task Link to String caster. With this caster, you can synchronize one or more associations to referenced tasks as web URLs, formatted into text attributes, in your target repository.

This caster also supports formatting of the target text attribute. Pressing Ctrl-space will enable content-assist when filling out the format. See Task Link To String Caster in the advanced Transforming Task Attribute Values with Casters section for more details.

This caster can only be selected for a mapping that meets the following conditions:

  1. One attribute in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. One attribute in the mapping must support text entry.
  3. The mapping must be unidirectional from the “taskDependency” attribute to the text attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Note: Since the resulting text will concatenate multiple web URLs, it can be quite large. It is recommended that the target text attribute support strings of at least 1024 characters.

Task Link to OSLC Link caster

When synchronizing task links to a system which uses OSLC linking, such as IBM Rational Team Concert, Tasktop Sync can be configured to synchronize Task Links to OSLC Links. This caster will convert the internal Task Link on the source task into a link referencing the linked task via Tasktop Sync’s built-in OSLC Adapter.

To use this caster, Tasktop Sync’s web server and OSLC adapter must be fully configured. For details on configuring Tasktop Sync’s OSLC Adapter, see the sections on Task Linking Configuration and Web Container Configuration. For Tasktop Sync to provide the linked task via OSLC, the linked task must appear in a query which is configured to be exposed by the Tasktop OSLC Adapter.

If any of the above requirements are not met the Caster may fail to cast the Task Link, or the OSLC Link may not be able to be resolved by Tasktop Sync’s OSLC Adapter.

This caster can only be selected for a mapping which meets the following conditions:

  1. One attribute in the mapping must be of the type “taskDependency”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. One attribute in the mapping must be of the type “externalLink”.
  3. The mapping must be unidirectional from the “taskDependency” attribute to the “externalLink” attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Value to Web Link caster

If you need to synchronize a task relationship to a data enumeration, such as a project from CA PPM, to a single select field in Jira, use the Value to Task Link caster. This caster enables you to map an attribute value in one repository to a task link in another.

The mappings for this caster are configured through a table, where the values from the data enumeration are located on the left column, and the tasks associated with the values can be configured by entering task IDs into the right column. To help you locate that desired tasks, you can assign a query under “Search for tasks in”. Select or create a query that will return all the possible tasks you wish to map to. Selecting this query will enable content assist, allowing you to select tasks from a list instead of manually typing in task IDs. In addition, having a query selected will cause the table to display the task key and summary in the right column instead of the task ID. It is recommended to select a query as configuring the caster with content assist is easier than typing in task IDs. Note that the mapping configured will always be one-to-one.

The table will highlight rows which have not been mapped in yellow, and rows with unsaved changes in green. In the above example, “Epics” and “Tasks” are examples of values which are not mapped, and “Defects” is an example of an unsaved mapping.

In addition, the caster can be configured to “Map Using Labels” or to “Ignore Case During Mapping”. When “Map Using Labels” is enabled, the underlying configuration in the XML wil contain the labels of the values instead of the IDs. When “Ignore Case During Mapping” is enabled, the casing of the values will be ignored. For example, when “Ignore Case During Mapping” is disabled, and “Task” is mapped to a task with ID “1”, then only “Task” will be mapped to task “1”, and “task” will not. However, when “Ignore Case During Mapping” is enabled, “task”, “TASK”, and “Task” will all map to task “1”.

This caster can only be selected for a mapping which meets the following conditions:

  1. One attribute in the mapping must be of the type “Single Select” or “Multi Select”.
  2. One attribute in the mapping must of of the type "Task Dependency"

If these conditions are not met, the caster will not appear in the Caster selection list.
Note: To determine the attribute type, click on the repository schema page, and click on the desired attribute.
Note: An attribute which supports multiple values may be synchronized with an attribute which only supports single values as long as the attribute supporting multiple values contains at most one value. An error will occur when attempting to synchronize multiple values into an attribute which only supports single values.

Web Link to Web Link caster

To synchronize referenced web URLs between repositories, use the Web Link to Web Link caster. With this caster, you can synchronize one or more attached web URLs between two tasks. This synchronization can be either bidirectional (web URLs attached to either task will be synchronized to the other) or unidirectional (only web URLs attached to to the task in one of the repositories will be added to the other).

This caster can only be selected for a mapping that meets the following condition:

  1. Both attributes in the mapping must be of the type “externalLink”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)

If this condition is not met, the caster will not appear in the Caster selection list.

Web Link to String

Web Link to String caster

If you need to synchronize web URLs from one repository to another, but your target repository does not support attached web URLs, use the Web Link to String caster. With this caster, you can synchronize one or more web URLs, formatted into text attributes, into your target repository.

This caster also supports formatting of the target text attribute. Pressing Ctrl-space will enable content-assist when filling out the format. See Web Link To String Caster in the advanced Transforming Task Attribute Values with Casters section for more details.

This caster can only be selected for a mapping that meets the following conditions:

  1. One attribute in the mapping must be of the type “externalLink”. (To determine the attribute type, click on the repository schema page, and click on the desired attribute.)
  2. One attribute in the mapping must support text entry.
  3. The mapping must be unidirectional from the “externalLink” attribute to the text attribute.

If these conditions are not met, the caster will not appear in the Caster selection list.

Note: Since the resulting text will concatenate multiple web URLs, it can be quite large. It is recommended that the target text attribute support strings of at least 1024 characters.

Location to Web Link caster

If you need to have the URL of the source task as a web link on the target task, use the Location to Web Link caster. This caster will create a web link, which points to the source task, on the target task.

This caster also supports formatting the label of the created web link. Pressing Ctrl-space will enable content-assist when filling out the format. See Location to Web Link Caster in the advanced Transforming Task Attribute Values with Casters section for more details.

This caster can only be selected for a mapping that meets the following conditions:

  1. One attribute in the mapping must be of type “externalLink”.
  2. One attribute in the mapping must be of type “url”.
  3. The mapping must be unidirectional from the “url” attribute to the “externalLink” attribute.

(To determine attribute type, click on the repository schema page, and click on the desired attribute.)

If these conditions are not met, the caster will not appear in the Caster selection list.

Note: If the link label is configured to contain the task summary, it is recommended to use a mapping strategy of “always” to ensure the label is always up to date. For more details on setting the strategy, see the Advanced section.

Status Transition

If you need to synchronize status into a repository with a workflow, use the Status Transition caster. With this caster you can synchronize status by executing transitions to move the target task between statuses following the workflow defined in the remote repository.

This caster can only be selected for a mapping that meets the following conditions:

  1. The target attribute is the Status attribute.
  2. The mapping must be unidirectional.

If these conditions are not met, the caster will not appear in the Caster selection list.

To configure this caster both a value mapping and a transition graph must be specified. The value mapping is used to translate the status of the source task into a desired status on the target task. The transition graph is used to determine the sequence of transitions which must be executed to attain the desired status.

Status Transition Caster

The mapping from source repository status to target repository status is configured using the “Status Mapping” table on the left. For each source status a corresponding target status should be configured.

The status transitions are configured using the “Status Workflow” table on the right. For every possible transition between statuses in the target system, a row must be configured in this table. Each transition must be configured with a status from which the transition may be applied, as well as the status which will result from applying the transition. Some transitions may have more than one valid status from which the transition can be applied. A row in the table must be configured for each of these possible statuses. Similarly there may be multiple transitions originating from a status, or resulting in a status. Because of this the same status or transition may appear multiple times in the table.

To add rows to the table click the “Add” button and a new unconfigured row will be added. To remove rows from the table they must be selected using the checkboxes in the table, then the “Remove Selected...” button can be used to remove them.

The configuration may be partially generated by clicking the “Suggest...” button. This button will add rows for all known status and transition combinations. Tasktop Sync is aware of which transitions may be executed from a given status, however it is not aware of what status the transition will result in. This information must be configured manually. Some statuses may not appear in the table after the “Suggest...” button is clicked. Details on which transitions are known to Tasktop Sync may be found in the Schema View.

In some repositories, an initial status must be defined when creating a new task. This status represents the initial state of the task. To configure, select the starting status beside “Status on Creation”.

For further details on the behaviour of the Status Transition caster see Status Transition Caster.

If you need to synchronize workflows in both directions, create two attribute mappings with this caster, one in each direction.

Advanced

Advanced attribute mapping settings

The Conflict Resolution Policy box specifies the policy for synchronization of this attribute in case of a conflict. If Default behavior is selected, the policy defined in the task mapping will take effect. Selecting any other option will override the mapping-wide default behavior. See the resolution policy in the mapping settings for details.

The Attribute mapping strategy box specifies when this attribute should be synchronized. The default behavior is Copy if target attribute exists, which only synchronizes the attribute if it exists in the other repository, so undefined attributes will not be created. Initialize will only create the attribute on the creation of a new proxy task, and will not synchronize in subsequent synchronizations. Always will always copy the attribute to the target regardless of whether a change has been detected on the source attribute.

Notes

Notes

This section allows for entry of any documentation or additional information about the attribute mapping. The value of this field is not used by Tasktop Sync directly.

Transition Attribute Mappings Table

Transition Attribute Mappings may need to be configured if a Status Transition caster has been configured. These mappings write to attributes required during a transition, such as a resolution attribute for a transition between the In Progress state and the Done state. As transition attributes are unique to a specific transition, there may be multiple mappings for a given transition attribute; one for each configured transition. For example, consider two configured transitions. The first is a transition between the New state and the Done state, the second is a transition between the In Progress state and the Done state, and both have the resolution transition attribute. Separate Transition Attribute Mappings are required for mapping the resolution attribute within the two transitions. Configuring the Transition Attribute Mappings, as described below, is more or less identical to configuring the Attribute Mappings.

Transition Attribute Mappings Table

The Transition Attribute Mappings table displays mappings between a task attribute and a transition attribute. The add button creates a new mapping for the selected transition within the dropdown. The dropdown is populated with all transitions within the current task mapping which are configured in a status mapping. All transition attribute mappings are unidirectional; the desired value will always be written into the transition attribute. The minus button will remove the selected transition attribute mapping.

Transition Attribute Mapping

Transition Attribute Mapping

Selecting a transition attribute mapping in the table will bring up the mapping editor, where the transition attribute mapping may be configured. The left and right columns display the attributes being mapped. One of the attributes is a transition attribute, and the other is a task attribute. The middle column displays the transition and the direction of the mapping. Casters may be configured for transition attribute mappings in the same way as the task attribute mappings. With the exception of the group casters, all casters may be used in transition attribute mappings. More information on casters can be found here.

Attribute Handlers Table

Attribute Handler Table

The Attribute Handlers table displays attributes that trigger scripted attribute handlers. The plus and minus buttons on the top right allow the addition and removal of attribute handlers. For details on how attribute handlers work, and on how to write attribute handlers, see Scripted Attribute Handlers.

Attribute Handler

Attribute Handler

The Attribute identifies an attribute in one of the repositories that will be associated with an attribute handler. When this attribute value changes, it will trigger the script. If an attribute with the chosen identifier exists in both repositories, changes in either repository will trigger the script. To select, choose the attribute from the dropdown list.

The Script Location points to the script file in the workspace that will be executed when the attribute changes. To change the file location, click Browse... and locate the file in the workspace. To see the contents of the chosen file, click Open.

Note that the Script Location may contain [ Embedded Script ], which indicates that the script is not in an external file, but instead inside the synchronizer.xml file.

For details on how to write attribute handlers, see Scripted Attribute Handlers.

Schema View

The Schema View can be accessed by selecting the links provided under the Schema section of the Task Mapping Editor. Tasktop Sync inspects both repositories to determine their schemas, including the attribute IDs, their labels, and their types. The Attribute Mapping Editor uses these schemas to populate the options for many attributes, including enumerated types used when producing value map casters and literal casters.

Schema viewer

If a change is made to the repositories, you need to click on the Refresh Schema button in the Actions section of the Schema View to update the repository schema to reflect the changes made. When clicked, you will be asked if you wish to refresh data from the repository before generating the schema. If you choose “Yes”, Sync will update the repository configuration, and it may also run the Initialization and Changes queries from the task repository and download a copy of all of the new data before generating the schema. This process may take a significant amount of time to complete, but it is required if the changes in the repository were made recently. Otherwise, you can choose “No”, and Sync will generate the schema more quickly using its local cache of data. If you are not sure, it is recommended that you choose “No” first, and review the updates in the Schema View. If your updates are not reflected, click the Refresh Schema button again and choose “Yes”.

Note that the Refresh Schema button will be disabled if a schema refresh is already in progress. Also note that refreshing the schema may refresh tasks from the repository. If the synchronizer is running, any changes found may be synchronized.

In addition to attribute IDs, labels, types and options, the schema contains information about the repository’s support for attachments, comments, time worked, and person search. This information is presented in the right side of the editor.

The schema view also displays which status transitions are available for a given status on the right hand side. This information may be helpful when configuring the Status Transition Caster. Some statuses may be missing from this table if no tasks with this status was present when the schema was generated. To ensure the schema is complete it is recommended that at least one task in each possible status be present during schema generation.

Source Tab

The Source Tab allows access to the XML file generated by the editor. It will display only the XML pertinent to the current configuration, including all the XML for the current task-mapping element being configured as well as the shared configuration of the enclosing sync-model element. Advanced configuration such as scripted attribute casters must be configured directly in the XML. See the manual configuration section for details.

Global Settings

To edit configuration that affects all task mappings, including Scheduled Jobs and Notifications, use the “Global Settings” editor.

Global Settings Editor

To access the Global Settings Editor, double-click on Global Settings in the Services view.

Notifications

Notifications section

There are three kinds of notification emails:

Details on configuring the jobs to run on different schedules can be found in the section Configuring Scheduled Jobs.

If an error happens while connecting to a repository, an additional error email will be sent. These will only be sent once per repository in error. These errors should be resolved as quickly as possible since they will block Tasktop Sync from operating correctly; Tasktop Sync will not attempt synchronizations involving repositories in error.

General Notification Settings

To configure the mail preferences, click on Open mail preferences....

Notification preferences

Enter the details of your email to the dialog that pops up. Tasktop Sync notifications will be sent from the address configured here.

If an instance name has been set, it will appear in the subject of the notification email. More information on instance names can be found here.

Clicking Send Usage Metrics email now. or Send Statistics email now. will send the respective email now to any users configured to receive them.

Error Notification Configuration

There are three different errors that may be contained within the Error email:

  1. Synchronization Errors: Errors that occurred during synchronization, which may include conditions such as: a proxy task has been deleted, a repository is offline, or a task submission has failed.
  2. Synchronization Conflicts: Conflicts that occurred during synchronization which resulted in the changed attribute not being synchronized.
  3. Query Errors: Errors that resulted from queries being run by Tasktop Sync.

Email Configuration

The Email Configuration section allows the configuration of email addresses which will receive emails from Tasktop Sync.

Once a valid email address has been added to the list, clicking on the check boxes under “Statistics”, “Errors”, and “Usage Metrics” will determine which type of reports the recipient receives. Notification emails will not be sent without a valid email address provided in the mail preferences.

Configuring Scheduled Jobs

The Schedule Jobs section allows the configuration of Tasktop Sync’s scheduled jobs. For details on Tasktop Sync’s usage of scheduled jobs see the section jobs.

All of Tasktop Sync’s scheduled jobs are displayed in the scheduled jobs table: the job’s name, type and schedule are all displayed. If a job is in error then a red x will be placed in the table next to the job.

Jobs may be added by clicking the “Add Job...” button. This will open a dialog to configure the new job. In this dialog the job’s type, name, schedule and parameters may be configured. For the job to be added the job’s configuration must be valid. Tasktop Sync will provide validation feedback as the job is configured.

Jobs may be edited by clicking the “Edit Job...” button with a job selected in the table, or double clicking a job in the table. This will open a dialog to configure the existing job. In this dialog the job’s name, schedule and parameters may be configured. For the job to be saved the job’s configuration must be valid. Tasktop Sync will provide validation feedback as the job is configured. A job’s type may not be changed in the edit dialog.

Jobs may be deleted by clicking the “Delete Job...” button, this will open a dialog to confirm the deletion. Deleting a job will remove it entirely from the configuration.

Configuration Templates

After creating a task mapping, you may decide that you want to apply this mapping to multiple other project/workspace pairs. Configuration templates can help simplify this process.

Creating a New Template from an Existing Mapping

To create a new template from an existing mapping:

  1. Find the task mapping from which you want to derive a template.
  2. Right-click on the mapping in the Services View.
  3. Select “Extract to Template”.
  4. Enter a name for the template in the dialog box that appears.
  5. To create the template using attribute labels as identifiers, check “Map Using Labels”. This is useful if attribute ids are not consistent between projects in a repository.

New Template

Note that the “Map Using Labels” checkbox may be disabled if it cannot be supported for the selected task mapping. To support labels, the task mapping must meet the following criteria:

Upon completion, the Templates bucket in the Services View will be populated with the new template.

Templates in Services View

The newly created template is shown in the Mapping Editor. Note that several fields are not editable.

Template Editor

Create a New Task Mapping from a Template

To create a new task mapping based on a template:

  1. Right-click on the template in the Services View and select “New Mapping from Template...”, or
  2. Click on “New Mapping from Template...” in the template editor.

In the dialog box that pops up:

  1. Designate a name for the new task mapping.
  2. Select the repositories where the projects or workspaces you are synchronizing reside.
  3. Define the queries and scope for the task mapping.

New Mapping From Template 1
New Mapping From Template 2
New Mapping From Template 3
New Mapping From Template 4
New Mapping From Template 5

The new task mapping will now be visible in the Services View and the editor for the mapping will be opened.

Mapping From Template in Services View

Mapping From Template Editor

Notice that its mappings icon varies slightly to denote that it was configured based on a template. You can repeat this process multiple times, using your template to configure an unlimited number of task mappings that require the same configuration.

Monitor Template Usage

In the Services View under Templates, you can see the templates that have been created and the number of task mappings that are using each template. Clicking on a template will open the template editor; there you can see mappings which use the template, as shown in the screenshot below.

Update Template 2

Alternatively, to see the template on which a task mapping is based, open the mapping in the editor, and click on the “Based on template” link.

Making Changes to Task Mappings that Are Based on the Same Template

After creating a template and applying it to task mappings, Tasktop Administrators often end up needing to change or expand that template and apply it to all of the affected task mappings. To accomplish this:

  1. Adjust the original task mapping that was used to create the template. This could include adding new attribute mappings, or configuring comment and attachment synchronization.
  2. Repeat the process of creating a new template.
  3. Right-click on the old template and select “Switch Mappings to another Template...”.
  4. In the dialog box, specify one or more task mappings to change and the new template to apply.

Update Template 1
Update Template 1
Update Template 2

After creating the new template, there is another way to change the template upon which a single task mapping is based:

  1. Select the task mapping which uses the old template.
  2. Right-click and select “Use another Template”.
  3. This will start a dialog similar to above, but without the need to select the mapping.

Disconnecting a Task Mapping from its Template

If a task mapping that was created using a template ever requires a unique synchronization configuration, Tasktop Sync administrators have the ability to disconnect it from a template:

  1. Right-click on the mapping.
  2. Select “Disconnect from Template”.

(This action is also available in the Mapping Editor of the Task Mapping.)

The attribute mapping for this task mapping will remain as it was defined under the template, but will now be editable so that administrators can change and update it freely.

Making Changes to a Task Mapping Based on a Template (Advanced)

Tasktop Sync administrators can add attribute mappings to a task mapping based on a template by editing the synchronizer.xml file. An attribute mapping defined in the task mapping can override an attribute mapping from the template, disable an attribute mapping from the template, or extend the template.

An attribute mapping defined in a task mapping will override an attribute mapping from the template if it involves at least one the same attribute as the attribute mapping from the template and it is a writable attribute (its strategy is not set to ignore). Note that this allows overriding the source attribute in a one-way attribute mapping from the template.

An attribute mapping in a task mapping will disable an attribute mapping from the template if it involves the same attributes as the attribute mapping from the template and neither attribute in the attribute mapping in the task mapping is writable (their strategies are set to ignore).

An attribute mapping defined in a task mapping will extend the template if it does not involve attributes present in the attribute mappings in the template, or it involves exactly one non-writable attribute from an attribute mapping in the template.

Renaming a Task Mapping

You can rename a Task Mapping or a Template from Sync Studio. Before renaming the mapping, make sure you have saved all changed in Sync Studio. To rename the mapping, right click on the Task Mapping or Template in the Services view and select “Rename Mapping...”.

Rename Mapping Menu

From the “Rename Task Mapping” dialog, enter the desired name and click “OK”.

Rename Mapping Dialog