Enterprise Tester supports importing requirements directly from JIRA or TFS.  If you are using JIRA or TFS for both requirements capture and defect management, Enterprise Tester is fully integrated with JIRA and TFS to support the synchronization of both requirements and issues.  Synchronization is manually initiated and occurs in a single direction, either from the defect tracker to Enterprise Tester or Enterprise Tester to the defect tracker.

If you have already configured a JIRA or TFS connection for your defect management you can proceed to creating your project link for requirements.

  1. Click on the ‘Resources’ tab in your tree navigator and click to expand ‘Project Link’.
  2. Right click on your project and select ‘Add New Project Link’, the Add Link screen will appear.
  3. Enter in the Name for the link, and select from the dropdowns:
    1. Connection is a JIRA or TFS connection that has already be configured
    2. Type is Requirements
    3. Select the project to synchronize requirements with
  4. Once complete, click ‘Save’.

Once the project requirement link is set up, you will be displayed the screen below and will need to perform additional configuration.

From the Edit Synchronization Configuration screen, click on the ET Configuration tab. Select the ET requirements package you wish to synchronize with.  Here you can also select the filter criteria when synchronizing from ET to JIRA.  Once you have completed your configuration, click ‘Save’.

Next, click on the External System Configuration.  Select the entity type(s) (requirement, stories, epics etc.) to synchronize with Enterprise Tester and click ‘Save’. For TFS you must select “Requirement” or any Work Item you wish to synchronize.

Here you can also select additional criteria including Statuses, Priorities, Components, Affected and Fixed Versions.

Note that by default all entities will be synchronized if criteria are not specified.  If the JIRA or TFS field values do not appear in the field drop down list, you may need to initiate a refresh lookups which will refresh the JIRA metadata.

Next, click on the Mapping tab. 

This screen displays two tabs for outlining and configuring the steps undertaken when synchronization is initiated. 

  • One tab for mapping fields from Enterprise Tester to the defect tracker
  • One tab for mapping fields from the defect tracker to Enterprise Tester

Task

Configurable

Description

Map Fields

Yes

Allows a set of mappings to be configured to transfer information between the source and destination system.

Map Attachments

No

Synchronizes the set of attachments between Enterprise Tester and External System (e.g. JIRA).  This will add new attachments that have not been synchronized previously, and remove previously synchronized attachments that have since been removed.

Create Trackback Comment

No

Adds a comment to the synchronized JIRA requirement with the following text:

 
Linked to Enterprise Tester requirement - Requirement: http://server/EnterpriseTester/#/requirement/edit/04e7f9e5-5784-4e94-a863-9ef600f0a935 (Name: <requirement name>)

 If a comment already exists with the same value, then the comment is not added.

Next, set the field mappings in the direction of Enterprise Tester to the defect tracker.  In the screen below, the Field Mapping is not currently configured. Please note that Enterprise Tester will prompt the administrator when a refresh lookups is either in progress or is required.  This must be completed before configuring your field values.  Refresh looksups will ensure that all the custom fields from your defect tracker and associated field values are up-to-date during field mapping. Please refer to Section 6.4 Refresh Lookups for more information.

You do not need to edit the mappings from the defect tracker to Enterprise Tester as they are already complete, however you can edit them if required.

  1. Click to highlight and select ‘Map Fields’ and click on ‘Configure’ from the toolbar. Please note that Enterprise Tester may need to Refresh Lookups before you can proceed with your field configuration. Please refer to Section 6.4 Refresh Lookups for more information.

    From the Configure Fields mapping screen, several configurations are automatically created consisting of Copy Field type mappings and direct Map field type mappings. 

    The Copy Field type mappings are already configured and the value will be copied from Enterprise Tester to JIRA on Synchronization:

    Copy Field – Copy from ET: Name (field) to External System: Summary (field)
    Copy Field – Copy from ET: Description to External System: Description (field)
    Copy Field – Copy from ET: Created By (field) to External System: Reporter (field)
    Copy Field – Copy from ET: Assigned To (field) to External System: Assignee (field)

    The Map field type mappings require the field values to be mapped. You can see under the column “Configured = False” that the value for these fields has not yet been mapped:

    Map Field – Map from ET: Type to External System: Type
    Map Field – Map from ET: Priority to External System: Priority

  2. To complete the field mappings, click on the “Type” Map field and select ‘Edit’ from the tool bar.
  3. Complete mapping Enterprise Tester field values to JIRA field values.
  4. Click “save”. 
  5. Complete mapping field values for “Priority”.

Mapping for TFS

Requirement synchronization with TFS will require some configuration to ensure that it works well.  This is due to the different ways in which requirements / user stories are represented depending on the project template being used.

The level of configuration required is dependent on your project template set up. For example, when synchronizing requirements (work item type) from TFS where there is a Requirement Type custom field, the following mappings need to be made:

ET to External System Mapping

  1. Add a Set field to value type mapping as follows:
  2. Add a Map field type mapping as follows:
  3. Delete the default mapping type Map Field – Map from ET: Type to External System Type.

The ET to External System Mapping screen should now look like the screenshot below:

External System to ET Mapping

  1. Add an Auto Map field type mapping as follows:
  2. Delete the default mapping type AutoMap –Auto Map from External System: Type to ET Type.

The ET to External System Mapping screen should now look like the screenshot below:

Optional Field Mappings

You can add additional field mappings if you choose. Below is a list of Map Field Configurations:

Mapping

Description

Example

Automap field

This mapping is configured between two picklist / multi-select fields, if the destination picklist/multi-select field does not contain a matching value, it will be automatically added to the destination field.

Automap custom field "Requirement Area" to JIRA inbuilt field "Component".

Copy Field

For non-picklist values, copy field allows you to copy the value from a source field to a field in the destination - this will happen automatically translating between certain values (so for example you can copy the text-based "Reporter" field to a "CreatedBy" user field in Enterprise Tester, and it will attempt to automatically look a match up by username).

Copy "CreatedBy" to "Reporter"
Copy "Description" to "Description"
Copy"Summary" to "Name"

Map Field

For picklist/multi-select values this provides a mechanism for synchronizing between the source and destination entities and for each value in the picklist the user must configure an equivalent mapped value in the destination.  When creating mapped values, until one or more mappings have been created, the field will have a value of "false" for the "Configured" column (and will display in red).  If when mapping, if no mapping exists for the source value, this mapping type will attempt to make a match based on the text of the item (requires an exact match).

Map "Type" to "Type"
Map "Priority" to "Priority"

Set field to value

This allows setting the value of a destination field using a provided "String" value.  The value will automatically translate to the correct type in the destination system, as long as it conforms to the correct format.  Here are the values to use for different types:

  • String - all values are treated as strings by default.
  • Picklist/single-select values - enter the name of the option or it's unique identifier.
  • Multi-select values - enter the name or ID of each option, separated by a semicolon i.e. V1;V2;V3
  • Users - enter the username of the user.
  • Integers - just enter an integer value and it will be automatically parsed.
  • Timespans - enter timespans as either an integer number, representing the number of minutes, or use the Enterprise Tester "timespan" format i.e. 2d 3h 2m
  • Boolean values - use "true" and "false"
    As support is extended for more products such as Enterprise Architect, this information will be expanded on to handle other types of field.
  • Date - any date/time value that can be parsed by .Net - we suggest using a universal time format such as yyyy-mm-dd hh:mm:ss.  See here for information on format options: http://msdn.microsoft.com/en-us/library/az4se3k1(v=vs.71).aspx

Set "Type" to value: "Requirement"
Set "AffectsVersion" to value: V2;V2.1

Set field to value (if it's null or empty)

This field behaves in the same way as the "set field" mapping, but will only be applied if the value of the destination field is considered null or empty, this means:

  • For single-select / multi-select options, if no option is selected;
  • Users/usernames which are null;
  • Null or empty (zero-length) string values; and
  • Nullable values.

Values which are never considered null include:

  • Non-nulIable integer values; and
  • Boolean values.

Set if empty "Reporter" to value: "joeb"

Here is a list of fields that can be synchronized by entity:

Source Type

Field

Type

Read/Write

Supported mapping types

Notes

ET Requirement

AssignedTo

User

Read/Write

Copy,Set,Set If Empty

Nullable (requirements do not have to be assigned to a user, unlike incidents)

ET Requirement

ChangeComment

String

Read/Write

Copy, Set, Set If Empty

Change comment is viewable from History and Version tabs of the ET requirement

ET Requirement

CreatedAt

DateTime

Read/Write

Copy, Set, Set If Empty

Assigned at creation of requirement, cannot be updated after creation.

ET Requirement

CreatedBy

User

Read/Write

Copy, Set, Set If Empty

Assigned at creation of requirement, cannot be updated after creation.

ET Requirement

Description

String

Read/Write

Copy, Set, Set If Empty

Supports unlimited text length.

ET Requirement

EstimatedDuration

TimeSpan

Read/Write

Copy, Set, Set If Empty

 

ET Requirement

Id

Guid

Read

Copy

Generated unique identifier for requirement, assigned at creation and cannot be set.

ET Requirement

LastUpdatedAt

DateTime

Read/Write

Copy, Set, Set If Empty

 

ET Requirement

LastUpdatedBy

User

Read/Write

Copy, Set, Set If Empty

 

ET Requirement

Name

String

Read/Write

Copy, Set, Set If Empty

Name has a max length of 255 characters

ET Requirement

Number

Nullable Integer

Read/Write

Copy, Set, Set If Empty

 

ET Requirement

VersionNumber

Non-nullable Integer

Read

Copy

Auto-incrementing version number, read-only.

ET Requirement

DifficultyLevel

PickList

Read/Write

Set, Set If Empty, Map, Automap

 

ET Requirement

Priority

PickList

Read/Write

Set, Set If Empty, Map, Automap

 

ET Requirement

Status

PickList

Read/Write

Set, Set If Empty, Map, Automap

 

ET Requirement

Type

PickList

Read/Write

Set, Set If Empty, Map, Automap

 

ET Requirement

Custom - XXX

Single Select / Multi Select Custom Fields

Read/Write

Set, Set If Empty, Map, Automap

 

ET Requirement

Custom - XXX

Non-selectable field (what we call a field that does not support "HasValidSetOfValues" in ET codebase)

Read/Write

Set, Set If Empty

 

JIRA Issue/ TFS Work Item

AffectedVersions

Multi-select list

Read/Write

Set, Set If Empty, Map, Automap

When auto-mapping both affected versions and fixed versions add to the same the list of versions associated with the JIRA project.

JIRA Issue/ TFS Work Item

Assignee

string

Read/Write

Copy, Set, Set If Empty

The username of the user in JIRA to assign this issue to.  If no match user is found, this will default to the project lead and failing that will fall back to the user configured as the login/password for the defect tracker connection.

JIRA Issue / TFS Work Item

Components

Multi-select list

Read/Write

Copy, Automap, Set, Set If Empty

Components supports auto-mapping (one of only two inbuilt JIRA fields, along with versions, that supports auto-mapping).

JIRA Issue/ TFS Work Item

Created

DateTime

Read

Copy

Read-only value assigned when an issue is created in JIRA.

JIRA/ TFS Work Item Issue

Description

Description

Read/Write

Copy, Set, Set If Empty

 

JIRA Issue/ TFS Work Item

FixedVersions

Multi-select list

Read/Write

Copy, Automap, Set, Set If Empty

 

JIRA Issue/ TFS Work Item

Id

String

Read

Copy

This is an auto-generated integer identifier for the JIRA issue (unique to the whole of the JIRA instance, not just the project) Note: though an integer value, for mapping purposes it's treated as a string, through Enterprise Testers defect tracker abstraction layer).

JIRA Issue/ TFS Work Item

Key

String

Read

Copy

The issue key i.e. "DEV-1234"

JIRA Issue / TFS Work Item

Priority

Single-select

Read/Write

Map, Set, Set If Empty

Does not support auto-mapping currently.

JIRA Issue/ TFS Work Item

Reporter

String

Read/Write

Copy, Set, Set If Empty

Username (like assignee) with the same fall-back logic if the specified username cannot be resolved (project lead then connection user)

JIRA Issue/ TFS Work Item

Resolution

Single-select

Read/Write

Copy, Set, Set If Empty

Does not support auto-mapping.  Also unless the issue is in a workflow stage that supports assigning a resolution, this value will not be applied to the JIRA issue.

JIRA Issue/ TFS Work Item

Status

Single-select

Read/Write

Copy, Set, Set If Empty

Does not support auto-mapping.  Status is not particularly useful when mapping from ET -> JIRA, as JIRA normally ignores this value (because we don't invoke the necessary workflow transitions to change the state of the issue).  
RE: JIRA, the simple version is that we don't invoke workflow transitions, the longer explanation is that we do attempt to invoke a workflow transition if we can find an action (workflow transition) who's name's stem matches the target status - so if for example there is an action with "close" in the name, and the user has changed the status to "close" from say "resolved", ET will attempt to invoke the transition, in the "hope" that it will result in the status we want (there's no guarantee, we are only matching on name, not any stronger workflow metadata).

This functionality will not work if you set the status to "resolved" right away. The  issue in JIRA still has to move from state to state - it generally cannot go straight to closed for example, i.e. needs to start as open.

JIRA Issue/ TFS Work Item

Summary

string

Read/Write

Copy, Set, Set If Empty

Summary in JIRA is by default a max of 250 characters.  It can be changed to be a large value, but requires database changes and is not really supported.

JIRA Issue/ TFS Work Item

Type

Single-select

Read/Write

Copy, Set, Set If Empty

Does not support auto-map.  Updating the type of an issue once created may not always work either due to the need to potentially map Statuses to different statuses etc.

JIRA Issue/ TFS Work Item

Updated

DateTime

Read

Copy

Updated is a read-only value (assigned by JIRA when updating an issue)

JIRA Issue/ TFS Work Item

Url

String

Read

Copy

Absolute Hyper-link to the JIRA issue.

JIRA Issue/ TFS Work Item

Custom Field - XXX

Custom field with 1 or more options

Read/Write

Set, Set If Empty, Map, Automap

Custom fields with 1 or more options are treated as a multi-select field (JIRA will take care of mapping this onto a single-select field as necessary).

Multi-cascade fields are not currently supported.

Once complete click ‘save and close’.

Scheduling Requirement Synchronization

Now that your configuration and field mappings are complete you are ready to synchronize.  The synchronization frequency can also be configured from the Schedules tab. There are 3 options that can be configured:

  1. Adhoc
  2. Periodic
  3. Daily

Type

Scope

Direction

Period

Time

Adhoc

You can choose to only update entities since the last synchronization or synchronize all.

Four options:

  • To External System ( From ET)
  • From External System ( To ET)
  • Bi-Directional ( External System changes will synch first)
  • Bi-Directional (ET changes will synch first).

 

N/A

N/A

Periodic

You can choose to only update entities since the last synchronization or synchronize all.

Four options:

  • To External System ( From ET)
  • From External System ( To ET)
  • Bi-Directional ( External System changes will synch first)
  • Bi-Directional (ET changes will synch first).

 

Specify the synchronization frequency in minutes

N/A

Daily

You can choose to only update entities since the last synchronization or synchronize all.

Four options:

  • To External System ( From ET)
  • From External System ( To ET)
  • Bi-Directional ( External System changes will synch first)
  • Bi-Directional (ET changes will synch first).

 

N/A

Specify the time using the (24hr clock) when the synchronization will occur daily.

Once you have configured your synchronization frequency, a summary of the configured synchronization schedules is available.  You can see the time of the Last Run, the Next Run (if applicable), whether the schedule is enabled or not and the current Synchronization Status.

You can use the tool bar to add a new scheduled synchronization, delete an existing configuration, enable or disable an existing schedule, configure an existing schedule or manually initiate a synchronization.

Synchronization History

You can view the Synchronization history from both the synchronization configuration screen and the individual synchronized entities.  From the configuration screen you can view all synchronization events, select to only view errors, export the synchronization events to a csv file or clear the history.

Limitations

  • When synchronizing from ET to JIRA
    • Nested requirements will be synchronized, but will not be created as sub tasks in JIRA
    • Relationships in ET between requirements will not be synchronized to JIRA
  • When synchronizing from JIRA to ET
    • Sub tasks are never synchronized to ET
    • Links between issues in JIRA are never synchronized to relationships in ET
  • Currently synchronization will halt after an error occurs (so it won't continue processing the remaining entities).  
  • Requirement Synchronization to JIRA does not currently support mapping to/from cascading select fields.
    When synchronizing from ET to JIRA, if you see an error message similar to this with the error "is an invalid parent option" this suggests you have tried mapping to a cascading select field:
    System.ServiceModel.FaultException: com.atlassian.JIRA.rpc.exception.RemoteValidationException: Fields not valid for issue: Errors: {customfield_10130=The option '1' is an invalid parent option} Error Messages: []
    Remove the mapping to allow synchronization to work once again.
    Auto-map in the TFS -> ET direction is fine, but auto-mapping in the other direction, even for custom fields, is not currently implemented.

Deleting requirement project links will stop the synchronization between Enterprise Tester and your external system.  When deleting the link you will have the option to delete the link and remove all external link references or to retain these references.  These include the trackback comments and the defect issue link placed in Enterprise Tester.  Note that if you chose to delete the references.  This will only affect Enterprise Tester.  References to Enterprise Tester in your external system cannot be removed, but all references in Enterprise Tester to your external system will be removed.

  • No labels