1. In Item connector client, there are two implementation choices : as a 'plain java application' or as an 'eclipse plug-in'. Which of these two implementations we should follow? Any idea how is it done in CQ connector ? Note that as per jazz tutorial it is recommended that we should go for 'java application' implementation.

This is really your choice, depending on your defect tracking system implementation. For example, if your system has an Eclipse client that accesses the repository, you might want to add the code to send data to RTC to your client. Or, you might want to create a separate, standalone Java application, or already have such an application (e.g. a server for your repository) to add the code to. The CQ Connector is an example of the latter - a separate, plain Java application.

2. While synchronizing from Jazz to External repository (NOT from External repository to jazz), the synchronization process can be started either explicitly or after a fixed interval of time. Is there any other other way to invoke synchronization process e.g. on the basis of event etc. (as this can done while synchronizing from external repository to Jazz).

No, not unless you implemented such a thing yourself.

3. We are not able to find javadoc/code for 'Jazz Plain Java Client libraries'. It would be helpful if we can have some link for it.

The source code for the client is available as a separate download from the "All Downloads" page for the release you're interested in. For the 1.0 release, the link is

https://jazz.net/downloads/rational-team-concert/releases/1.0/TeamConcert-Source-1.0.zip

The javadoc exists as comments in the source (mainly the public interfaces). There is no separate javadoc download at this time.

John
Jazz ClearQuest Connector Team

The synctool utility that comes with the ClearQuest Connector is specific to ClearQuest. Normal use of the CQ Connector is to set up "continuous synchronization" by applying a package to your CQ schema (that's what "connector-enabled" means) and by setting up the CQ Connector Gateway. But we also provide the option to run the synctool utility to find records in a CQ database and import data from them into RTC work items, without having to enable your CQ database for continuous synchronization. This is not the "main" part of the CQ Connector, but just an extra feature to get some existing CQ data imported into RTC.

You don't have to implement anything like that for your connector. And if you did want to implement a manual synchronizer program like we did, you don't have to implement it the same way. We chose to implement it as an Eclipse application using the RCP framework. The "connector-enabled" and "non-connector-enabled" modes are entirely an artifact of the way we implemented synchronization for ClearQuest. None of this may have any similarity to the system that you want to implement a connector for.

For more information on how the synctool utility is used, please see

https://jazz.net/jazzdocs/topic/com.ibm.team.connector.cq.doc/topics/t_importing_batch.html

John
Jazz ClearQuest Connector Team

Hi John

Thanks for your earlier reply. I have some more queries regarding Item connector framework. I came across following two terms -
i. non-connector-enabled schema
ii. connector-enabled schema
In non-connector-enabled schema we need to give 'query' parameter while in connector-enabled schema we need not to give this parameter. As I could understand this 'query' parameter is used for retrieving 'some particular records' from external repository.

So my doubts are -
1. Are these 'some particular records' the one which needs synchronization? Does this 'query' decide which records in external repository needs to be synchronized ?

2. How does things work in connector-enabled schema (i.e. where there is no 'query' parameter)? Can you provide me some details about this?

3. In CQ connector, I think both options are implemented. Is it necessary to implement both options? If yes, then why? If not, then out of the above two options which one is preferred and why?

Also I have doubt regarding invoking incoming synchronization process in file 'com.ibm.rational.connector.cq.synctools.SyncTool.java'. This is the file which is responsible for incoming synchronization.
4. The above class implements IApplication interface. Why do we need to implement this interface?
5. How exactly in CQ connector, the start() method of above file is invoked for incoming synchronization?

There are actually three different ways to map something to the Filed Against (Category) property of a work item. They are described in the online help at

https://jazz.net/jazzdocs/topic/com.ibm.team.connector.cq.doc/topics/t_edit_synch_rules_for_categories.html

Briefly, you can

1. Connect an external record to a work item Category. If there is an external record type that closely corresponds with work item Categories, then you can set up synchronization of those objects. In that case, the "parent" record would contain a reference to a record that is being synchronized with a category, and would specify the synchronization rule to use for it. That's what we call a "reference synchronization rule".

2. Map one or more string-valued fields to Category names. If the "parent" record contains fields that can be interpreted as the names of work item categories, then synchronization will use the fields values to find or create categories by the same name, and use the "leaf" category as the Filed Against value for a work item. In this case, there is no reference synchronization rule, but there is a special transformer that must be used.

3. Map string-valued fields in other referenced records to Category names. This is a combination of the first two scenarios, where the "parent" record contains a reference to another type of record, but where it doesn't make sense to synchronization that record type with work item categories. Instead, the record contains string-valued fields that can be interpreted as the names of categories. In this case, a reference synchronization rule is used, as well as the special transformer.

Basically, a reference synchronization rule is always used when the value of a field is a reference to another record.

Also, for cases 2 and 3, the "Work Item Category Transformer" must be specified for the property mapping; it implements the string-value-to-Category-name transformation.

Hope this help.

John
Jazz ClearQuest Connector Team

Hi John

In sync rule editor I was trying to map item property 'Filed Against' (Category) for a Defect, against its counter part in external repository. But in the process of incoming synchronization it gives incoming sync error - java.lang.illegalArgument Invalid UUID.
Then I tried to look how this particular field is mapped in CQ connector sync rule. There in Mapping details 'Reference synchronization rule' (another sync rule defined for Item type Project) is defined for this particular mapping of Category Item property.
I did something similar in our case and the error of Invalid UUID was gone, BUT then it showed some blocking proxies, which to my understanding, were due to some pending outgoing sync in referenced sync rule. Now I am not able to figure out how to handle this reference sync rule.
Can you tell me when and how do we use a reference Sync Rule? or may be 'Filed Against' item property can be mapped without doing all this?

-Ankur

I'm not sure I understand your question. Let's say you have a mapping for the Priority property that maps a single external value (e.g. "Important") to three work item values (e.g. "Low", "Medium", "High"), and you marked one of those values as the default (say "High"). That means that when a work item Priority value of Low, Medium, or High is synchronized out to the external system, the external value will be set to Important, and when the external value of Important is received for a work item, if not already set to one of the mapped values (Low, Medium, or High), High will be chosen.

So are you saying that sometimes, for incoming synchronization, if a mapping defines multiple possible values, you want different values to be chosen at different times? If so, based on what criteria? There is no built-in way to do that, but you can always create your own value transformer that can do anything it wants (as far as transforming property values).

John
Jazz ClearQuest Connector Team

Hi John

Thanks for your always quick replies. I have some more queries here. In synchronization rule, I have defined a value mappings for 'itemProperty' and 'extProperty' in such a manner so that one value of extProperty is mapped to three different values of itemProperty. I have choosen one of the three values as default. Now how do I tell the workitem externalProxies not to use default value but other values ?

-Ankur

It sounds like this is the same issue as described in

https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/33783

And you're right, we have no solution at this point. If you wrote your own value transformer, it would have to be able to determine the action that was used to cause the state transition.

John
Jazz ClearQuest Connector Team

Hi John

I have defined the value mapping for state property. There is extState of external defect 'Open' which is possible whenever a new defect is created or an already closed defect is reopened. But in jazz for a newly created defect the state is 'New' while for a reopened defect state is 'Reopened'. So depending upon which 'action' in ext repository is responsible for 'Open' state of defect, I want to choose either 'New' or 'reopened' state in jazz.

But I guess you have answered the question already that I have to write a value transformer. There is no other way to do this or is there any?

- Ankur

I'm not sure I understand your question. Let's say you have a mapping for the Priority property that maps a single external value (e.g. "Important") to three work item values (e.g. "Low", "Medium", "High"), and you marked one of those values as the default (say "High"). That means that when a work item Priority value of Low, Medium, or High is synchronized out to the external system, the external value will be set to Important, and when the external value of Important is received for a work item, if not already set to one of the mapped values (Low, Medium, or High), High will be chosen.

So are you saying that sometimes, for incoming synchronization, if a mapping defines multiple possible values, you want different values to be chosen at different times? If so, based on what criteria? There is no built-in way to do that, but you can always create your own value transformer that can do anything it wants (as far as transforming property values).

John
Jazz ClearQuest Connector Team