Configure a codebeamer Tracker for Export of EA Elements

This guide describes how to configure a tracker in codebeamer, in order to support the export of elements from Enterprise Architect.

Template for Enterprise Architect exports

codebeamer offers the functionality to create projects based on templates. Project templates can contain multiple trackers, which can be serve as templates. With the templates it is easier to create trackers, especially for exports from Enterprise Architect, which have to be configured accordingly. To create a template project with template trackers for EA imports and exports, follow the steps listed below.

Download the template: LemonTree.Connect_Template_Project.zip
In codebeamer, navigate to "Projects" and create a new project:
Click "Attach a file" and select the archive "Connector_Template.zip:
Provide a name and a key for your project.
Click "Finish".
A new project based on the template will be created.
Navigate to "Trackers" and create a new tracker:
Select the Type "Requirement".
In the template combobox you will now see the templates "System Requirement Specification" and "Export Tracker Template".
1. If you want to create a new tracker for importing to EA, select the template "System Requirement Specification".
2. If you want to create a new tracker for exporting from EA, select the template "Export Tracker Template".
Make sure the checkbox "Inherit template configuration" is checked.
Provide a name, key (short name) and description for the new tracker and finish with "Save".
If you want to, you can rename both template trackers.

You can now easily create new trackers based on templates, which can be directly used for importing and exporting with LemonTree.Connect.

Used codebeamer Version

Note that the templates provided in this guide were created with the codebeamer version 21.09

Steps for manually configuring a codebeamer tracker for export

If you want to manually configure a tracker without having a tracker template, follow the steps described below:

Create a new tracker of type "Requirement".
Navigate to the tracker's field settings page.
Add a new custom text field called "ea_guid". This field is mandatory in order to support synchronization of EA elements in codebeamer.
Add a new custom text field called "my_uml_type". This field is mandatory in order to support synchronization of EA elements in codebeamer.

Hide connector internal fields

If you do not want to show LemonTree.Connect internal fields (like ea_guid and my_uml_type) to the user, it is possible to hide this field by checking the "hidden" checkbox.

Further configurations and possible errors

Usage of codebeamer "type" (categories field)

If the mapping configuration used for the export (see Mapping Configuration) used the "Categories" (or "Type") field from codebeamer, make sure that only existing "Category" values are used.
Otherwise the export will abort or create duplicate elements.

Furthermore, writing the field "type" during an export can cause issues if your user does not have the proper permissions to write the field. Please see the FAQ entry "field id not writable" for more information.

Displaying the Classifier of an exported element in codebeamer with a calculated field

If you want to export the classifier on an element and display it properly in codebeamer, you have to add two custom fields to the tracker. Follow the steps listed below:

Navigate to the tracker's field settings page.
Add a new custom text field, for example called "Classifier_internal". This field will hold the "raw" classifier data. Optionally, you can mark the field as hidden, so users won't see the internal field.
After adding the field, click on the field to edit it.
Check the name of the custom field (for example customField[7]) and memorize it for later:
Add another custom field, for example called "Classifier". This field will display the actual name of the referenced classifier element.
After adding the field, click on the field to edit it.
In the settings of the field, enter the following script in to the "Computed As" property:

Computed As for Classifier display
```
customField[7].split(";")[0]
```
Replace the number in the [] by the number you memorized from step 4.
Save the settings and don't forget to save the tracker configuration as well (at the top of the fields page).

If you now want to export the classifier to codebeamer, you have to use the internal field in the mapping. The normal classifier field will automatically display the classifier value.
For more information on the mapping of the classifer, check the guide "Mapping the Classifier of exported elements".

Missing permissions for the "Parent" field

To properly recreate the structure from EA in codebeamer, the field "Parent" must be configured with the proper permissions. If the permissions for the "Parent" field are not set accordingly, the export will fail.
For more information please see the FAQ entry Insufficient Parent Field Permission.

Export of traceability links

If you want to export Trace Links to codebeamer (see Export of Traceability Links between codebeamer Requirements and EA Architecture Elements) to codebeamer, make sure that the assigned field for the reference has a valid link type.
If you are linking architecture elements to work items of type "Requirement" from a certain tracker, the "subject" field must have the according configuration.

Detection of deleted elements from EA

If you want LemonTree.Connect to detect elements during export, which were deleted in EA, check out the guide "Detect deleted elements from EA during Export to codebeamer".

"Invalid state transition" or "item is not closed yet" error when exporting

If you start an export from EA to codebeamer and the export is aborted with an error message similar to "Invalid state transition" or "item is not closed yet", you are trying to set a status value in codebeamer, which does not correspond with the tracker configuration.
How status values are set, is configured in a state machine in the tracker's configuration. If the export violates the definition of the state machine and sets an invalid status value, one of the previous error messages will be shown after the export was aborted.

You can fix this kind of error with two possible approaches:

Configuring the state transitions:
1. Navigate to the tracker configuration and open the tab "State Transitions".
2. At the bottom, you will see a diagram that shows you all allowed state transition.
3. If you want to set the status from EA, add a state transitions from the status "Unset" to each other status value:
4. If you also want to support other transitions, make sure to also add all other possible transitions (from each state to any other).
Make sure only allowed states values are transferred from EA to codebeamer:
1. If you perform an initial export, make sure that all elements that are exported to codebeamer have a status value that is allowed coming from the status value "Unset".
2. Most of the time, this is the status value "New".