CQ Connector value mapping GUI details?

Hi Ralph,

The "StateResolution" property is not really supported (you'll notice it isn't documented anywhere). It was an early experiment as a technique for connecting a CQ schema to a Team Concert process spec that had significantly different state models for CQ records and work items, but it doesn't generalize well. Instead, we say that you should map State and Resolution properties separately, and if necessary, you'll have to tweak either the CQ schema or the Team Concert process spec to make the state transition (workflow) models similar enough for the mapping to be straightforward. Support for the StateResolution property may be dropped in a future release.

The meaning of the "default" attribute in value mappings is explained in the "Creating synchronization rules" topic in the online help. It says,

"If there is not a one-to-one mapping of all values, designate one as the default value. For example, the ClearQuest Priority field might have four values (1, 2, 3, and 4) and the Team Concert Priority property might have three values (High, Medium, and Low). If you map High to both 1 and 2, select 1 or 2 as the Default external value."

In other words, it's only used if a single value on one side is mapped to multiple values on the other. In that case, one of the values must be designated the default, or the mapping is ambiguous. Whether the default is for the CQ (external) value or Team Concert (item) value depends on the direction of the mapping. If a single CQ value maps to multiple Team Concert values, then one of those values must be set to be the default item value, and if a single Team Concert value maps to multiple CQ values, then one of them must be the default external value.

If you make more than one value a default, there will be a run-time error if that mapping is ever triggered during synchronization. There is a defect logged to make feedback like that available in the editor; it's

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

John
Jazz ClearQuest Connector Team

:oops: tried to find something in the help but failed

I am trying to setup a connector at a customer and have it running but I am missing information how to interpret and use the value mapping e.g. for StateResolution.

How do I have to interprete the UI and what does the connector do with it, especially the defaults for both RTC item and external value.

What does it mean if I select a value to be default on the RTC side compared to when I select a value on the external side.
What rules apply? Why can I set more than one value as default on either side? Rules here if I do that?

Examples

new submitted
Im Progress oepned
resolved/fixed completed

Thanks,

Ralph

Hi Ralph,

Are you trying to use the sample sync rules that comes with the CQ Connector or are you trying to create your own sync rules? If the latter, then we recommend that in your sync rule you create separate property mappings for the CQ state and resolution fields.

I found the following information in the online doc regarding value mappings:

Use the Value mappings section to specify values to map from items to records. Click Add. Enter an item value and the corresponding ClearQuest record field value. If there is not a one-to-one mapping of all values, designate one as the default value. For example, the ClearQuest Priority field might have four values (1, 2, 3, and 4) and the Team Concert Priority property might have three values (High, Medium, and Low). If you map High to both 1 and 2, select 1 or 2 as the Default external value. To specify a value of empty for a ClearQuest record field, leave the value blank. Rather than adding value mappings one at a time, you can click Initialize to create an initial set of mappings based on matching, or partial matching, value names. You can then go through the list and remove or edit value mappings as necessary.

The default value is used to resolve the one-to-many situation. For example, the Jazz status value of New can map to the CQ state values of Submitted or Assigned. If Submitted is designated as the default value, then when the Jazz work item is synced out to CQ, the CQ defect will have the Submitted state value.

Lorelei
Jazz CQ Connector Team

Hello John,

thanks for your answer, I will modify the shema accordingly.
The default behavior you describe below was my expectation, but somehow I
must have missed the part in the description and sometimes it is hard to
get a grip at the info even if it is there.

I already dropped the stateresolution on the QC side because the shema is
modified and I will modify the rule accordingly on the RTC side.

While trying to create the mapping several other questions arise, would it
be possible to discuss issues with you directly if neccessary?
Here some of the things that happened:

- I used the synctool to test my mapping and after I got the first successfull
import I changed the mappings to remove issues.
Unfortunately one change modified the RTC workitem values in a way that would
be hard to fix manually. Since RTC workitems can not be deleted I have to
throw away the project.
How do you propose to start such a project? Create the RTC project users
and structure and then backup before you try to import/synchronize? Restore
after an unsuccessfull try?

- Is it possible to set imported workitems to "dirty" to allow to do another
reimport and mapping the external values untill you are sure that the mapping
works or does it only work one time? The behavior I saw was unclear to me,
I imported several times and values chaged, but a final import (that changed
the workitem type) would not revert, whatever I tried

Thanks,

Ralph

Hi Ralph,

The "StateResolution" property is not really supported
(you'll notice it isn't documented anywhere). It was an early
experiment as a technique for connecting a CQ schema to a Team
Concert process spec that had significantly different state models
for CQ records and work items, but it doesn't generalize well.
Instead, we say that you should map State and Resolution properties
separately, and if necessary, you'll have to tweak either the CQ
schema or the Team Concert process spec to make the state transition
(workflow) models similar enough for the mapping to be
straightforward. Support for the StateResolution property may be
dropped in a future release.
The meaning of the "default" attribute in value mappings is explained
in the "Creating synchronization rules" topic in the online help. It
says,

"If there is not a one-to-one mapping of all values, designate
one as the default value. For example, the ClearQuest Priority field
might have four values (1, 2, 3, and 4) and the Team Concert Priority
property might have three values (High, Medium, and Low). If you map
High to both 1 and 2, select 1 or 2 as the Default external
value."
In other words, it's only used if a single value on one side is mapped
to multiple values on the other. In that case, one of the values must
be designated the default, or the mapping is ambiguous. Whether the
default is for the CQ (external) value or Team Concert (item) value
depends on the direction of the mapping. If a single CQ value maps to
multiple Team Concert values, then one of those values must be set to
be the default item value, and if a single Team Concert value maps to
multiple CQ values, then one of them must be the default external
value.

If you make more than one value a default, there will be a run-time
error if that mapping is ever triggered during synchronization. There
is a defect logged to make feedback like that available in the editor;
it's

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

John
Jazz ClearQuest Connector Team
rschoonwrote:

:oops: tried to find something in the help but failed

I am trying to setup a connector at a customer and have it running

but I am missing information how to interpret and use the value
mapping e.g. for StateResolution.

How do I have to interprete the UI and what does the connector do

with it, especially the defaults for both RTC item and external value.

What does it mean if I select a value to be default on the RTC side

compared to when I select a value on the external side.

What rules apply? Why can I set more than one value as default on

either side? Rules here if I do that?

Examples

new submitted
Im Progress oepned
resolved/fixed completed
Thanks,

Ralph

Hello Lorelei,

thaks for your answer. As I answered John this helps especially the StateResolution
where I already use the State field (becaue resolution is customized out).

Thanks again,

Ralph

Hi Ralph,

Are you trying to use the sample sync rules that comes with the CQ
Connector or are you trying to create your own sync rules? If the
latter, then we recommend that in your sync rule you create separate
property mappings for the CQ state and resolution fields.

I found the following information in the online doc regarding value
mappings:

Use the Value mappings section to specify values to map from items to
records. Click Add. Enter an item value and the corresponding
ClearQuest record field value. If there is not a one-to-one mapping of
all values, designate one as the default value. For example, the
ClearQuest Priority field might have four values (1, 2, 3, and 4) and
the Team Concert Priority property might have three values (High,
Medium, and Low). If you map High to both 1 and 2, select 1 or 2 as
the Default external value. To specify a value of empty for a
ClearQuest record field, leave the value blank. Rather than adding
value mappings one at a time, you can click Initialize to create an
initial set of mappings based on matching, or partial matching, value
names. You can then go through the list and remove or edit value
mappings as necessary.

The default value is used to resolve the one-to-many situation. For
example, the Jazz status value of New can map to the CQ state values
of Submitted or Assigned. If Submitted is designated as the default
value, then when the Jazz work item is synced out to CQ, the CQ defect
will have the Submitted state value.

Lorelei
Jazz CQ Connector Team

While trying to create the mapping several other questions arise, would it be possible to discuss issues with you directly if neccessary?

We like to try and keep such discussions in the forum, so that other users can benefit from them, and we have a searchable archive of them. But if there's some reason why you'd rather discuss them directly, feel free to contact me.

Here some of the things that happened:

- I used the synctool to test my mapping and after I got the first successfull
import I changed the mappings to remove issues.
Unfortunately one change modified the RTC workitem values in a way that would
be hard to fix manually. Since RTC workitems can not be deleted I have to
throw away the project.
How do you propose to start such a project? Create the RTC project users
and structure and then backup before you try to import/synchronize? Restore
after an unsuccessfull try?

I suppose you could do that, but that presumes that there is no other state in your repository that you would want to preserve. If you or others are also experimenting with source control or other functionality, you might not want to throw away your entire repository. I would suggest just creating a test project area. Even though you can't delete it or the work items, you can archive the project area which will remove it from being normally visible.

- Is it possible to set imported workitems to "dirty" to allow to do another
reimport and mapping the external values untill you are sure that the mapping
works or does it only work one time? The behavior I saw was unclear to me,
I imported several times and values chaged, but a final import (that changed
the workitem type) would not revert, whatever I tried

If you are using synctool to do the import, then it always imports whatever records it finds using the CQ query you specify; there is no notion of being "dirty" on the CQ side. When the CQ field data is received in Team Concert, only values that have changed since the last time data was received are applied to work items. I'm not sure what you mean by "final import ... would not revert". Could you be more specific about what was different between what you expected and what actually happened?

John
Jazz ClearQuest Connector Team

Hi,
I read this discussion about using state and resolution as seperate properties to map when developing a connector.
I have an issue here.I have mapped all resolution states to my external repository states but when i try to create a new work item and sync it with external repository i get outgoing error which states that

com.ibm.team.repository.common.TeamRepositoryException: There is no mapping defined for value "null" of property "Resolution" in synchronization rule com.example.myrepository.defectWorkitemInterop.Defect

The new work item created has "new" state and blank as resolution state because of which i am getting this error but i couldnt decide how to solve it.Is there any default state of resolution which is set in case of states which dont include resolution field .

Just add a value mapping to the resolution property to handle the null value. Both the item value and external value should be null. The xml source of the sync rule should look like the following:

<valueMapping>
<externalValue></externalValue>
<itemValue>Unassigned</itemValue>
<defaultExternalValue>false</defaultExternalValue>
<defaultItemValue>false</defaultItemValue>
</valueMapping>

Lorelei
Jazz CQ Connector team

Hi,
I read this discussion about using state and resolution as seperate properties to map when developing a connector.
I have an issue here.I have mapped all resolution states to my external repository states but when i try to create a new work item and sync it with external repository i get outgoing error which states that

com.ibm.team.repository.common.TeamRepositoryException: There is no mapping defined for value "null" of property "Resolution" in synchronization rule com.example.myrepository.defectWorkitemInterop.Defect

The new work item created has "new" state and blank as resolution state because of which i am getting this error but i couldnt decide how to solve it.Is there any default state of resolution which is set in case of states which dont include resolution field .

Oops. The snippet is a little off. The unassigned value should be replace with an empty value. It should be this instead:

<valueMapping>
<externalValue></externalValue>
<itemValue></itemValue>
<defaultExternalValue>false</defaultExternalValue>
<defaultItemValue>false</defaultItemValue>
</valueMapping>

Lorelei
Jazz CQ Connector team

Thanks.

Oops. The snippet is a little off. The unassigned value should be replace with an empty value. It should be this instead:

<valueMapping>
<externalValue></externalValue>
<itemValue></itemValue>
<defaultExternalValue>false</defaultExternalValue>
<defaultItemValue>false</defaultItemValue>
</valueMapping>

Lorelei
Jazz CQ Connector team