Microsoft TFS 2015 for Work Items Installation & User Guide

Connector download

Log in to the CA Agile Central Community for support of this and all of our connectors. The CA Agile Central Community is your one stop shop for self service and support. Accessing the CA Agile Central Community is quick and easy:

  • Navigate to the CA Community.
    • If it's your first time to the site, click Don't have an account yet? Create one now!
    • Complete the self-service registration form to be automatically logged into the CA Agile Central Community.
  • In the Community, click the profile drop-down (top-right), and select My Downloads. The connector will be listed for eligible users.

Overview

The CA Agile Central Connector for TFS Work Items can synchronize work items in TFS with artifacts in CA Agile Central. The connector runs on either a Windows or non-Windows platform behind your firewall using Microsoft's TFS REST API and accesses CA Agile Central through the CA Agile Central Web Services API v2.0. Most work item artifact fields between the two systems can be reflected.

The connector is configured through an XML file. A log file is created to track all changes made in CA Agile Central and TFS by the connector. The connector requires that a custom field exists in each system to store the unique ID of the linked objects in the other system. The connector copies fields from CA Agile Central or TFS based on field mapping specified in the configuration file. Standard and custom fields can be mapped between the two systems.

Important: only certain item hierarchies are supported. TFS allows you to create arbitrary hierarchies of work items. For example, you could have user stories as children of bugs. Because of the domain model mismatch between these arbitrary hierarchies and the CA Agile Central object model, the connector in general does not support reflecting hierarchical relationships between work items. However, one exception is linking TFS tasks to their parent story. Learn how to Copy story-task bundles from CA Agile Central to TFS. So, while you can map any TFS work item type to a CA Agile Central story or defect, you cannot configure the connector to synchronize a work item's children or parents, unless you are specifically using stories and tasks.

The connector provides five services to synchronize objects between CA Agile Central and TFS:

  • Copy work items created in TFS to CA Agile Central (defects, user stories, or test cases only)
  • Copy work items created in CA Agile Central (defects, user stories, tasks, or test cases only) to TFS work items
  • Update CA Agile Central work items based on changes made in TFS
  • Update TFS work items based on changes made to CA Agile Central work items
  • Update CA Agile Central fields and TFS fields (may not be used in conjunction with the other update services)

The configuration file specifies which services to run, and in what order.

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields in to Rally.

This makes the chances of overwrites of data highly unlikely. The only scenario where an overwrite might occur is if Peter made changes in CA Agile Central and Al made changes in the other system for the same fields, the CA Agile Central information is copied over to the other system (possibly overwriting the data of the other system), then all data is copied over to the CA Agile Central system.

With the CA Agile Central Work Item Connector for TFS 2015 version 4.7.0, attachments are now supported. You can reflect TFS work item attachments in CA Agile Central and/or reflect CA Agile Central artifact attachments in TFS 2015. There is a tagset in the configuration that is new for TFS connectors to enable this.

It is important to recognize that the data models of CA Agile Central and TFS are not identical. The data models of the two connected systems are only partially compatible. We recommend that you take some time to identify the key data items that you want to track in both systems and what you want the policy to be as far as having a primary system of record. You'll see specific information later in this document discussing things to be considered and some potential approaches.

Known limitations

  • There are no RTF (rich text field) field handlers
  • Tasks can be copied from CA Agile Central to TFS (but not in the opposite direction)
  • Tasks can be updated from CA Agile Central to TFS or from TFS to CA Agile Central

Basic installation steps

  1. Download the installer .zip file. This .zip file contains an installer for the connector:
    • CAAgileCentralConnectorforTFS2015WorkItems-Ruby-4.7.0-master-25.zip
  2. Extract the contents of the .zip file in to a temporary folder.
  3. Run the TFS connector installer (CAAgileCentralConnectorforTFS2015WorkItems-Ruby-4.7.0-master-25.exe).
  4. Make the appropriate configuration changes in CA Agile Central and the TFS system.
  5. Edit the tfs_config.xml to reflect your environment.
  6. Run ca_agile_central2_tfs_connector to start the synchronization process.

This installation and user guide includes:

System setup

The following people should be involved in getting fields set up in both CA Agile Central and TFS:

  • A TFS administrator user who can create a custom field on the work items you want to synchronize with CA Agile Central
  • A CA Agile Central administrator user who can create a custom field on the CA Agile Central artifact you want to synchronize with TFS (this is only for initial setup; user access is all that's needed to run the connector).
  • Someone with access to the Windows machine described above to install and configure the connector

Consider the process you want to set up between CA Agile Central and TFS:

  • Where do objects start and end their lifecycle?
  • Which fields need to be updated?

You will also need to:

  • Identify a test project in TFS to use for testing the connector.
  • Identify a test CA Agile Central workspace or project to use for testing the connector.
  • Find a Windows machine to run the CA Agile Central connector.

Software and hardware requirements

  • A CA Agile Central subscription.
  • A Windows platform (server or VM) or a Linux/Mac OSX platform (server or VM).
  • A working instance of TFS 2015 accessible on the network from your selected connector platform.

Pre-installation checklist

  • Access to test projects in CA Agile Central and TFS.
  • A CA Agile Central account with administrator privileges is needed for setup (but only user access is needed to run the connector).
  • Proxy server details if the machine used to run the connector uses a proxy server to connect to CA Agile Central or TFS.
  • A TFS user with at least team project contributor (access, read, and write work items) permissions. A user with team project reader permissions is not sufficient to run the connector.

See CA Agile Central Integrations FAQ and Best Practices for useful information.

Download the connector

To download the connector, navigate to the CA Agile Central Community and access My Downloads from the profile menu.

Note: click here for instructions on how to sign up for the CA Agile Central Community.

Install the connector

(Optional) If you use a proxy server to access CA Agile Central, you will need to set the http_proxy environment variable.

  1. On Windows, right-click My Computer and select Properties.
  2. Select the Advanced tab, and then click Environment Variables.
  3. Click New under System Variables and enter http_proxy as the full HTTP URL, such as http://www-cache:8000.
  4. If your proxy sever requires username-password authentication, you could specify it in the http_proxy variable as such: http://Username:Password@www-cache:8000.
  5. You may need to restart your system in order for the change to take effect.

Installation for Windows

Double-click the RallyConnectorforTFS2015WorkItemsInstall-4.7.0-master-25.exe to open the install wizard. Follow the prompts to complete the installation.

The Windows installer will install the following files (by default in C:\Program Files\RallyConnectorforTFSWorkItems):

  • ca_agile_central2_tfs_connector.exe: Executable to run the connector
  • tfs_config.xml: Sample configuration file
  • WinTail.exe*: Utility to tail the log file output for debugging purposes
  • starttfs.bat: Batch file that automatically runs the connector and shows the log file; useful for testing

*WinTail is a free text file tail utility for Windows, generously made available by Bare Metal Software Pty Ltd. for redistribution without restriction. We have found it to be far superior to Notepad and other text editors for watching log files in real time as they are updated by the connector.

Installation for Linux and Mac

  • You'll need to have Ruby 2.x installed on your platform. CA certifies the use of Ruby 2.0.0-p247. It is very likely that the connector will work with Ruby 2.1.x versions, but we have not certified that.
  • Extract the contents of the zip file RallyConnectorforTFS-Ruby-4.7.0-master-25.zip locally on your machine (such as C:\rally on Windows or /Users/username/Downloads/ on a MAC).
  • Change the directory to the root of the connector installation:
    cd CAAgileCentralConnectorforTFS-Ruby-4.7.0-master-25
  • Run the installation shell script: ./install.sh

Sample output for revision 4.7.0-master-25 on a Mac:

$ sh install.sh
installing gem: ./rallyeif-wrk-1.1.1.gem
Fetching: mini_portile-0.5.3.gem (100%)
Successfully installed mini_portile-0.5.3
Fetching: nokogiri-1.6.1.gem (100%)
Building native extensions. This could take a while...
Successfully installed nokogiri-1.6.1
Fetching: httpclient-2.6.0.1.gem (100%)
Successfully installed httpclient-2.6.0.1
Fetching: rally_api-1.2.1.gem (100%)
Successfully installed rally_api-1.2.1
Successfully installed rallyeif-wrk-1.1.1
5 gems installed
installing gem: ./rally_tfs_api-1.0.0.gem
Fetching: multipart-post-2.0.0.gem (100%)
Successfully installed multipart-post-2.0.0
Fetching: faraday-0.9.0.gem (100%)
Successfully installed faraday-0.9.0
Successfully installed rally_tfs_api-1.0.0
3 gems installed
installing gem: ./rallyeif-tfs-4.7.0.gem
Fetching: xml-simple-1.1.2.gem (100%)
Successfully installed xml-simple-1.1.2
Fetching: mime-types-2.0.gem (100%)
Successfully installed mime-types-2.0
Successfully installed rallyeif-tfs-4.7.0
3 gems installed

Prior to revision 4.3.0 of the connector, the ca_agile_central2_tfs_connector.rb file was located within the install directory. With revision 4.3.0 and later, it is installed into one of the Ruby GEM directories which has been placed into your $PATH. To verify you have easy access to it, run this command:

$ ca_agile_central2_tfs_connector.rb --version
ca_agile_central2_tfs_connector.rb --version
Work Item Connector Hub version 1.1.1-947-master/master
Rally Spoke version 4.10.0 using rally_api gem version 1.2.1
TFSConnection version 4.7.0-25-master-4e5c53bfdf9f658f166116dc5ae9123320dc8e16

If you are using a proxy, you will need to set an environment variable PROXY with the proxyhost:portnumber prior to running the install.sh script. For example:

export PROXY=host17:8080

Assuming you have more than one version of Ruby and have a package manager, e.g. RVM, choose the desired Ruby version before running install.sh.

TFS setup

Create a custom field in TFS to contain CA Agile Central object IDs

See Microsoft instructions here.

We advise that you use the value 'Rally.Common.ExternalId' as the reference name of your custom field. You will need to add a custom field for the CA Agile Central ID for every work item type you intend to use with the CA Agile Central TFS work item connector (the types 'Bug', 'User Story', 'Task' and 'TestCase' are supported).

CA Agile Central setup

CA Agile Central accesses fields from their Display Name, not their Name. Spaces and underscores are removed, for example, Example Field becomes ExampleField.

Create a custom field in CA Agile Central to contain TFS work item IDs

  1. Log into CA Agile Central as a workspace or subscription administrator.
  2. Go to Setup → Workspaces & Projects.
  3. Click on the workspace that you wish to map to TFS. This will take you to the detail page for the given workspace.
  4. Click the Fields link in the sidebar and ensure the Work Item type selected is defect (or whatever work item you are mapping).
  5. Click Actions → New Field.
  6. Enter a Name of ExternalID, Display Name of ExternalID (name and display name must match), and type of String. You can choose a different name (such as TfsId) for the custom field in Rally, but the name you choose must conform to these rules:
    • Begin with an uppercase letter
    • Less than 41 characters (40 is the maximum for display name)
    • No underscores, dashes, or spaces
  7. Click Save & Close.

Make note of the name of this field. Once you start using the connector, this will contain the TFS ID of the TFS work item you are mapping between the two systems.

Connector configuration

Edit the configuration file

A sample configuration file, tfs_config.xml, is part of the installation and should be in the root directory of the installation. This is the directory you specified during the wizard-based Windows install (such as C:\Program Files\RallyConnectorforTFSWorkItems). We recommend making a backup copy of the tfs_config.xml in case you need to reference a valid configuration file later.

Edit tfs_config.xml and enter the appropriate values between each begin and end tag.

<Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
        <!-- You can use an APIKey in place of User and Password tags -->
        <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey> -->
    <ArtifactType>Defect</ArtifactType>
    <ExternalIDField>ExternalID</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
     <!--
    <CopySelectors>
        <CopySelector>Field_Name = Value</CopySelector>
    </CopySelectors>
    <UpdateSelectors>
       <UpdateSelector>Field_Name = Value</UpdateSelector>
   </UpdateSelectors>
-->
    <SuppressDeprecationWarning />
       
    <CopySelectors>
                <CopySelector>SyncStoryToTFS = True</CopySelector>
        </CopySelectors>

        <UpdateSelectors>
           <UpdateSelector>State != Closed</UpdateSelector>
        </UpdateSelectors>
  </RallyConnection>

  <TFSConnection>
     <Protocol>http or https</Protocol>    
    <Server>your_TFS2015_server_name</Server>    
    <Port>port_on_which_TFS_fields_requests</Port>    
    <Instance>tfs or other custom name for your TFS instance</Instance>    
    <Collection>collection_name</Collection>    
    <User>your TFS 2015 user name</User>    
    <Password>your TFS 2015 account password</Password>    
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>Bug</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>

  <!--  <CopySelectors>
     <CopySelector>System.AssignedTo = My User</CopySelector>
   </CopySelectors>
   <UpdateSelectors>
       <UpdateSelector>Field_Name = Value</UpdateSelector>
   </UpdateSelectors>
 -->
  </TFSConnection>

  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      <Field><Rally>Priority</Rally>  <Other>Microsoft.VSTS.Common.Priority</Other></Field>
    </FieldMapping>

    <OtherFieldHandlers>
      <OtherEnumFieldHandler>
        <FieldName>Microsoft.VSTS.Common.Priority</FieldName>
        <Mappings>
          <Field><Rally>Resolve Immediately</Rally> <Other>1</Other></Field>
          <Field><Rally>High Attention</Rally>    <Other>2</Other></Field>
          <Field><Rally>Normal</Rally>      <Other>3</Other></Field>
          <Field><Rally>Low</Rally>     <Other>4</Other></Field>
        </Mappings>
      </OtherEnumFieldHandler>
    </OtherFieldHandlers>
  </Connector>

  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Debug</LogLevel>
    <Services>UPDATE_TFS_TO_RALLY, COPY_TFS_TO_RALLY</Services>
  </ConnectorRunner>
</Config>

Each major section is surrounded by a tag to delineate that section. In the example above, here is a description of each section:

  • RallyConnection
    Defines the connection information for CA Agile Central, including CA Agile Central URL, username and password or APIKey.
  • TFSConnection
    Defines the connection information for TFS, including TFS Collection URL, project name, artifact type, user, and so on.
  • Connector
    Defines the field mapping between the two systems. Generally, strings should be mapped to strings, integers to integers, and so on. You can get a list of all the fields for a TFS team project collection with the command:
    witadmin listfields /collection:http://<server>:<port>/tfs/<collection_name>
  • ConnectorRunner
    Specifies parameters related to the services the connector is to run and how often to run the services.

Field Mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields map between the two systems.

For example, this definition sets up a mapping between the CA Agile Central field Name with the field Headline in the TFS system. On a create or update, the connector will only update the Name field in CA Agile Central and the Headline field in the TFS system.

<Connector>
  <FieldMapping>
    <Field>
      <Rally>Name</Rally>
      <Other>Headline</Other>
    </Field>
  </FieldMapping>
  .... </Connector>

When you set up your mapping between the two systems, ensure the fields are compatible between the two systems (an integer field should map to an integer field in the other system, a rich text field should map to a rich text field in the other system).

Otherwise, you might experience situations where information is not created or updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to post a string to a custom field of type integer in CA Agile Central.

You can add subsequent mappings by appending to this list. For example, this sets up a mapping of:
Rally Name → Headline
Rally Description → Description
Rally Priority → Priority

<Connector>
  <FieldMapping>
    <Field>
      <Rally>Name</Rally>
      <Other>Headline</Other>
    </Field>
    <Field>
      <Rally>Description</Rally>
      <Other>Description</Other>
    </Field>
    <Field>
      <Rally>Priority</Rally>
      <Other>Priority</Other>
    </Field>
  </FieldMapping>
  .... </Connector>

If you are mapping a drop-down value in Rally to the other system, be sure the drop-down values match. Otherwise, the connector will generate an error that the value was not found in the list. If the drop-down values are different between the two systems, see Mapping drop-down values section of the FAQ.

Individual fields may also have a directionality specified, whereby that specific field will be mapped in one direction only. For more information on this feature, see Field Directionality.

Field handlers

Mapping drop-down values
Mapping user names
Mapping reference fields from Rally (like Project, Release, Iteration)

XML tags

Definition of tags in configuration file

Below is a more detailed explanation of each tag section in the configuration file.

 

XML tags in the <RallyConnection> section:

Tag Name Description Sample Values
     
<RallyConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Server used to connect to Rally (excluding the HTTPS prefix, as the connector adds https:// to whatever is specified). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<User>
Required if no APIKEY specified
Login name for user to make the Web Services requests to create and update work items in Rally. user@company.com
<Password>
Required if no APIKey specified
Password associated with the above <User>. Note: The connector will encode this password string and update it in the configuration file as to avoid clear-text passwords being stored. mypassword
<APIKey> CA Agile Central APIKey (from CA Agile Central Application Manager) fro the account to be used to access CA Agile Central from the connector. If this is specified, you do not need to supply a username and password. You do not need to whitelist the user associated with the value of the APIKey used as a value. ABC123plmokn43315...
<WorkspaceName>
Required
Workspace in CA Agile Central you want to copy and update work items. My Workspace
MyWorkspace
<Projects>
Required
Contains a list of project tags. Each tag refers to one Rally project that will be used when finding new Rally work items to copy to the other system. For updating work items from Rally to the other system, all projects in <WorkspaceName> are considered. At least one Rally project must be specified in this tag. <Project>Rally1</Project>
<Project>Rally2</Project>
<ArtifactType>
Required
Type of artifact you want to create and update in CA Agile Central. (Defect, defect),
(story, userstory, hierarchicalrequirement),
test case
<ExternalIDField>
Required
CA Agile Central custom field of type string (name and display name must be identical) that stores the unique ID for the other system. Refer to the Create a custom field in CA Agile Central to contain TFS work item IDs section above. TFSID
<SuppressDeprecationWarning /> Prevents warning messages related to Rally WSAPI version deprecation from being generated in the logfile.  
<CrosslinkUrlField> A CA Agile Central custom field (of type String) which will be used to store a hyperlink to the corresponding artifact (bug or story) in TFS. TFSLink
<CopySelectors> Criteria to use when finding new CA Agile Central issues to copy to TFS. Multiple criteria are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
<field> is the name of a TFS work item field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
<CopySelector>Status = Open</CopySelector>
<CopySelector>Priority = Low</CopySelector>
<UpdateSelectors> Criteria to use when finding existing CA Agile Central issues to be updated in TFS. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
<field> is the name of a TFS work item field
<relation> is either = or !=
<value> is a valid value for the <field>.
<UpdateSelector>Release != alpha</UpdateSelector>
<FieldDefaults> Set a default value for a CA Agile Central field. <Field><Name>Rallyfieldname</Name><Default>defaultvalue</Default></Field>
<WorkProductType> The CA Agile Central Artifact Type name for the Task WorkProduct. At this time only the value of Story is valid. This limits Tasks copied from CA Agile Central to TFS to those Tasks whose WorkProduct is a Story. This tag is only relevant when the ArtifactType tag value is Task. Story
<WorkProductExternalIDField>

The field name in the WorkProductType that holds the value of the corresponding Story in CA Agile Central. This tag only relevant when the ArtifactType tag value is Task


TFSId
</RallyConnection>
Required
Closing parent tag for this section.  

Tip: Special characters contained in a Rally workspace or project name, which are markup sensitive, must be escaped as follows:

& ampersand becomes &amp;
> greater than becomes &gt;
< less than becomes &lt;

Example: Research & Development → Research &amp; Development

 

XML tags in the <TFSConnection> section:

Tag Name Description Sample Values
     
<TFSConnection>
Required
Opening parent tag for this section.  
<Protocol> http or https (defaults to http) https
<Server>
Required
your TFS server  
<Port> TFS REST API service port (defaults to 8080) 8080 or 443
<Instance> Name of your TFS instance (defaults to tfs) tfs
<User>
Required
Login name for user to make TFS REST API requests user@your_company.com
<Password>
Required
Password associated with the above User secret_password
<Collection>
Required
The URL of a team project collection CollectionName
<TeamProject>
Required
The TFS team project containing work items to be associated with CA Agile Central work items. Only one team project can be specified. If more than one team project is needed, use multiple configuration files. Test Project
<ArtifactType>
Required
TFS work item type for the work items you want to create and update in TFS. The exact set of default work item types that are available for your team project depends on the process template the team project was created with, along with any custom work item types that may have been imported. User story
Bug
Test case
Task
<IDField> TFS field used to store the unique ID of a work item, defaults to System.Id System.Id
<ExternalIDField>
Required
TFS custom field that stores the unique ID for a CA Agile Central work item. See Create a custom field in TFS to contain Rally object IDs. Rally.Common.ExternalId
<ExternalEndUserIDField> A custom user field in TFS of type String used to store the FormattedID of the Rally work item (DExx). See Create an External ID User Field in TFS. Note: Do not use the ExternalID for this custom field. Using the same value causes the connector to overwrite the ExternalIDField with the Rally Formatted ID and breaks the connector. Rally.Common.ExternalUserId
<CrosslinkUrlField> A TFS custom field (of type HTML) used to store a hyperlink to the corresponding artifact (bug or story) in CA Agile Central. TFSLink
<CopySelectors> Criteria to use when finding new issues to copy to CA Agile Central. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a TFS work item field,
<relation> is one of =, !=, gt, lt, gte, lte.
<value> is a valid value for the <field>.
<CopySelector>State = Open</CopySelector>
<UpdateSelectors> Criteria to use when finding existing issues in TFS that should be updated to CA Agile Central. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a TFS work item field,
<relation> is either = or !=, and
<value> is a valid value for the <field>.
<UpdateSelector>System.CreateDate gte 2011-10-23</UpdateSelector>
<FieldDefaults> Set a default value for a TFS field. <Field><Name>TFSfieldname</Name><Default>defaultvalue</Default></Field>
<ParentType> The TFS Artifact Type name for the Task Parent. At this time only the value of Story is valid. This tag is only needed when the UPDATE_TFS_TO_RALLY service is specified and is only relevant when the ArtifactType tag value is Task. User Story
<ParentExternalField> The field name in the ParentType that holds the value of the corresponding Story in TFS. This tag only relevant when the ArtifactType tag value is Task. TFSId
</TFSConnection>
Required
Closing parent tag for this section.  

 

XML tags in the <Connector> section:

Tag Name Description Sample Values
<Connector>
Required
Opening parent tag for this section.  
<FieldMapping>
Required
Determine what fields map between the two systems. See Field Mapping
<RallyFieldHandlers> (opening tag)  
   <RallyConcatFieldHandler>
      <FieldName>
         Dest-fieldname
      </FieldName>
      <ConcatFields>
         <Field>Src-fieldname1</Field>
         <Field>Src-fieldname2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </RallyConcatFieldHandler>
Using the contents of Dest-fieldname as the initial string, appends each additional Src-fieldnameN to Dest-fieldname, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
some other field
.....
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.
Other to Rally: The date string contained in the field which F1 is mapped to, is converted into a Rally ISO date (in accordance with (through Ruby's DateTime.parse) and stored in Rally's F1 field. Note that string S1 is not used in this case.

TestDate
%m-%d-%Y%H:%M:%S
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike drop-down values between the two systems. See Map Drop-Down Values.
   <RallyReferenceFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyReferenceFieldHandler>
Used to map a field from an object.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyUserEmailFieldHandler>
      <FieldName>Owner</FieldName>
   </RallyUserEmailFieldHandler>
Rally user to whom error and warning info will be emailed.
User,Owner,Tester,...
   <RallyUserFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map user names. See Map User Names.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyCSVUserMappingFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <FileName>
         name-of-file
      </FileName>
   </RallyCSVUserMappingFieldHandler>
Specifies the name of a field being mapped (name-of-field) and a CSV file where user mappings are stored (name-of-file). The CSV file is used to lookup and transform usernames based on the mappings specified within. See a more detailed explanation on the FAQ page or an example XML file.

SubmittedBy


MyUserMappings.csv
</RallyFieldHandlers> (closing tag)  

<OtherFieldHandlers>

  <TFSTreePathFieldHandler>
      <FieldName>
      Project or Iteration are common Treepath fields
      </FieldName>
      <Prefix>
      Customarily the TeamProject name
      </Prefix>
  </TFSTreePathFieldHandler>

  <OtherEnumFieldHandler>
  ...
  </OtherEnumFieldHandler>

</OtherFieldHandlers>

Allows stripping of leading path elements (TeamProject\SubGroup\MyProject) --> MyProject on the way out of TFS and augmenting a value with the Prefix on the way in to TFS.






Allows you to map drop-down values for a field between systems.

 

Example for Iteration of Swing4 --> MyProject\Swing4









See Map Drop-Down Values.

 

<RelatedObjectLinkers>     <TFSTaskToParentLinker />    <RallyTaskToWorkProductLinker />
   <RallyAttachmentLinker />
</RelatedObjectLinkers>

This is only relevant within a configuration for the Task artifact type.

Specifies that attachments will be reflected from each system in the other.
</Connector>
Required
Closing parent tag for this section.  

 

XML tags in the <ConnectorRunner> section:

Tag Name Description Sample Values
     
<ConnectorRunner>
Required
Opening parent tag for this section.  
<Preview> Allows you to enable a preview mode for testing where NO objects are copied and updated in either system. false (default)
true
<LogLevel> Determines what type of messages are written to the log file. The highest level is Debug where all messages are displayed. The default log level is Info. Fatal, Error, Warn, Info, Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally. This allows changes done in both systems to not cause overwrites of old data.

Copy services:

COPY_TFS_TO_RALLY
COPY_RALLY_TO_TFS

Update services:

UPDATE_TFS_TO_RALLY
UPDATE_RALLY_TO_TFS

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

<Emailer>
   <Level>value</Level>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
   <SMTPUser>value</SMTPUser>
   <SMTPPassword>value</SMTPPassword>
   <SMTPSec>value</SMTPSec>
</Emailer>
Opening tag for this feature.
Which logfile messages to email.








Closing tag for this feature.
See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
Username@Domain.com
Password
TLS
 
</ConnectorRunner>
Required
Closing parent tag for this section.  

 

Incrementally set up the connector!

Start with a basic configuration file, test that you can connect to TFS and CA Agile Central in a test environment. Once you validate this is set up correctly, then start customizing the field mapping and field handler sections.

Run the connector

The connector accepts these command-line flags:

ca_agile_central2_tfs_connector.rb -h
Usage: /Users/nmusaelian/.rvm/gems/ruby-2.0.0-p247/bin/ca_agile_central2_tfs_connector.rb
<options><config_filename> <interval_in_minutes>
where <options> are:
--version, -v:   Prints the revision number of the connector.
--precheck, -p:   Precheck, the connector will run in preview mode.
--run-on-validation-failure, -r:   Will ignore results of XSD Schema validation and run connector.
--log-file-size, -s <n>:   Set the size limit for a log file to <n> megabytes.
--max-log-files, -m <n>:   Set the maximum number of log files in log file rotation to <n>.
--help, -h:   Print this Usage message.
--cleartext, -c:   Bypass encrypting the credentials if they are already in clear text.
where <config_filename>
File system reference to an XML file specifying the connector configuration.  Usual extension is '.xml'.
where <interval_in_minutes>
The interval, in minutes, for which the connector will run after executing command the first time.
-1 will only run the connector once and will exit afterwards.

Once the tfs_config.xml configuration file is set up, you can start running the connector. To start the connector, use one of the following command lines:

For Windows:

ca_agile_central2_tfs_connector.exe tfs_config.xml -1

For Linux/Mac

ca_agile_central2_tfs_connector.rb tfs_config.xml -1

To stop the service, use Control-C in the command shell.

Next, double-click on WinTail.exe to run WinTail. In WinTail, open the file rallylog.log to watch the log messages generated by the connector. This is an easy way to confirm that the connector is working properly, or to discover any errors.

Use starttfs.bat

We ship a starttfs.bat file to make it easier to test. Double-click on the batch file to automatically run the connector and open the log file in WinTail.

Optionally, you can add a number to the end of the command line that specifies the time in minutes the connector should sleep between successive executions of all services. The default is 15 minutes. We recommend sleep intervals of no less than 10 minutes. For example:

  rally2_tfs_connector.exe  tfs_config.xml  10

To stop the service, use Control-C in the command shell.

Credential Encryption (added May 2015)

As of version 4.6.0 of the Connector, credentials occurring in the *Connection sections of the configuration file that are in clear-text are encrypted after the initial run using that config file. Credentials are identified as any configuration item tag appearing in a *Connection section whose name is '*User', or any '*Password' or 'APIKey'.

Credentials in the Emailer section (SMTPUser and SMTPPassword) will still be encoded. The credential encryption is localized for the installation of the connector and various aspects of the configuration file.

In practice, as long as the installation and execution folders are constant and the key CA Agile Central parameters in the configuration do not change, you are free to modify most of the contents of the configuration file without having to reset the credentials to their clear-text values. However, care must be taken in environments that do not have such stable characteristics to frequently check the log files for any entries that indicate environmental changes have taken place that prevent the connector from decrypting the encrypted values for use in the connector execution.

Modify the logging parameters

The connector logs messages as it is processing into a rallylog.log file in the current working directory. By default, the maximum size of a log file is 5 MB and the log rotation is limited to 10 files. You can adjust the maximum size of the log file and adjust the maximum count of log files in the log rotation by specifying command line arguments for this.

The -s <integer> option pair can be used to specify the maximum size of the log file in MB increments (up to 100 MB). This can also be expressed as --max-log-file-size <integer>.

The -m <integer> option pair can be used to specify the maximum count of files in the log file rotation scheme. This can also be expressed as --max-log-files-count <integer>.

Example: To set the log file max size to 50 MB and the maximum log file rotation count to 20 files for a single invocation of the connector:

rally2_xxx_connector -s 50 -m 20 xxx_config.xml -1

OR

rally2_xxx_connector --max-log-file-size 50 --max-log-files-count 20 xxx_config.xml -1

Multiple configuration files

For users who want to map to more than one workspace in CA Agile Central, need to map multiple artifact types, or need to map to multiple containers (such as domain/projects in TFS or ClearQuest databases) in the other system, setting up multiple configuration files may be a good option. CA Agile Central recommends naming the configuration files using descriptive names for easier troubleshooting.

To run multiple instances of the connector for different configuration files, pass in the list of config files as arguments to the rally2_tfs_connector.rb script or rally2_tfs_connector.exe.

  rally2_tfs_connector.exe  config_workspaceA.xml  config_workspaceB.xml

The connector will process the configuration files based on the command line argument order, and processes one file at at time.

Once it processes every configuration file, the connector will sleep based on the sleep value. The default is 15 minutes. To change the sleep value between runs, set this value (in minutes) as the last command line argument.

Windows command:

  ca_agile_central2_tfs_connector.exe  config_workspaceA.xml  config_workspaceB.xml  10

Non-windows command:

  ca_agile_central2_tfs_connector.rb  config_workspaceA.xml  config_workspaceB.xml  10

We recommend a sleep value of 10 minutes or more and advise against anything less than 5.

Note about rallylog file entries regarding updates

Currently Microsoft TFS 2015 REST API does not support time granularity for the ChangedDate field when querying for items that have been updated. To compensate for it the connector has to consider all work items that have been updated in a given day. As a side effect, the log file will contain an entry that an update was skipped:

"Skipped update for <id> since there was no change on non-external id fields".

This is a normal condition caused by connector discarding items whose mapped fields have not actually changed.

Copy story-task bundles from CA Agile Central to TFS

You can set up the connector to copy CA Agile Central stories and their associated tasks to stories and tasks in TFS while preserving the story-task relationships in TFS. In order to do this, you will need two configuration files, one for story and one for task, then you need to run the connector to operate using these configuration files in that sequence.

Example:

ca_agile_central2_tfs_connector.exe tfs_story_config.xml -1
ca_agile_central2_tfs_connector.exe tfs_task_config.xml -1

If the following statements are true, this section of the guide does not apply to you:

  • You are not copying CA Agile Central tasks to TFS tasks.
  • You do not require that the tasks in TFS be linked to your TFS stories.
  • You are only copying CA Agile Central tasks to TFS tasks and not copying CA Agile Central stories to TFS stories.

Create configuration files

Create a configuration file to work with the CA Agile Central story type and the TFS story type. The following is an example for story.

<Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
    <ArtifactType>Story</ArtifactType>
    <ExternalIDField>TFSId</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
  </RallyConnection>
  <TFSConnection>
    <Server>servername</Server>
    <Protocol>http</Protocol>
    <Port>8080</Port>
    <Instance>instance name</Instance>
    <Collection>collection name</Collection>
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>User Story</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>

  </TFSConnection>
  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      … other fields ...
    </FieldMapping>
   … any field handlers you need for mapped fields goes here ...
  </Connector>
  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Info</LogLevel>
    <Services>COPY_RALLY_TO_TFS</Services>
  </ConnectorRunner>
</Config>  

Task example:

     <Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
    <ArtifactType>Task</ArtifactType>
    <ExternalIDField>TFSTaskID</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
    <WorkProductType>Story</WorkProductType>
    <WorkProductExternalIDField>TFSId</WorkProductExternalIDField>
  </RallyConnection>
  <TFSConnection>
    <Server>servername</Server>
    <Protocol>http</Protocol>
    <Port>8080</Port>
    <Instance>instance name</Instance>
    <Collection>collection name</Collection>
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>Task</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>
   <!--  only needed when the UPDATE_TFS_TO_RALLY service is specified
   <ParentType>Story</ParentType>
   <ParentExternalIDField>Rally.Common.ExternalId</ParentExternalIDField>
 -->
  </TFSConnection>
  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      … other fields ...
    </FieldMapping>
   … any field handlers you need for mapped fields goes here …
   <RelatedObjectLinkers>
       <TFSTaskToParentLinker/>
      <RallyTaskToWorkProductLinker/>
   </RelatedObjectLinkers>
  </Connector>
  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Info</LogLevel>
    <Services>COPY_RALLY_TO_TFS</Services>
  </ConnectorRunner>
</Config>

You need to set up a custom field in CA Agile Central for the task that will hold the identity of the corresponding item in TFS after it has been copied, also called the ExternalIdField. Adding this custom field in CA Agile Central for the task type is similar to the directions in CA Agile Central Setup.

Note that in your configuration for task you need to have two additional tags in the RallyConnection section.

The <WorkProductType> tag value identifies the type the CA Agile Central WorkProduct that must be associated with the task in order for it to be copied to TFS. At this time only the story type is supported.

The <WorkProductExternalIDField> tag value is the name of the WorkProduct type field that holds the identity of the corresponding WorkProduct type in TFS. Normally, you would use the value from the <ExternalIdField> tag in your story configuration file. For the example configuration files in this section, the tag value for <WorkProductExternalIDField> is TFSId.

The CA Agile Central stories must be copied over to TFS first so that this first part of the story-task relationship is reflected on both sides of the connection. Then when the connector is run with the task configuration, the tasks can be linked to their associated stories in TFS.

You must have both configuration files in the same directory and you should run the connector naming the story configuration file on the command line first, followed by the name of the task configuration file to ensure this sequence of operation.

Example:

rally2_tfs_connector.exe  tfs_story_config.xml tfs_task_config.xml

The connector runs using the story configuration and copies the CA Agile Central story to a corresponding TFS story. 

The connector runs using the task configuration and copies the Rally tasks to corresponding tasks in TFS.

After the task is copied, the connector sets the links on the newly copied TFS tasks to have them parented by their associated TFS story.

Update stories and tasks

Over time, you may want to reflect any changes in TFS stories and tasks to CA Agile Central stories and tasks (and vice-versa).

In order reflect changes from CA Agile Central to TFS, your configuration will need to specify the following:

  • The <WorkProductType> and <WorkProductExternalIdField> in the <RallyConnection> section:
    <WorkProductType>Story<WorkProductType>
    <WorkProductExternalIDField>TFSId<WorkProductExternalIDField>
  • The relevant services as in the following example configuration file fragment:  <Services>UPDATE_TFS_TO_RALLY,  UPDATE_RALLY_TO_TFS,  COPY_RALLY_TO_TFS</Services>

In order to reflect changes from TFS to CA Agile Central, your configuration will need to specify the following:

  • The ParentType and ParentExternalIDField in the TFSConnection section:
    <ParentType>Story</ParentType>
    <ParentExternalIDField>RallyID</ParentExternalIDField>
  • The relevant services as in the following example configuration file fragment:
    <Services>UPDATE_TFS_TO_RALLY, COPY_RALLY_TO_TFS</Services>

For the scenario where you are tasking out stories and tasks in Rally and then copying them to TFS, where your developers and testers work on the tasks and provide updates that you then want reflected back in Rally, you will need to adjust your Services specification in the configuration file to:

<Services>UPDATE_TFS_TO_RALLY, UPDATE_RALLY_TO_TFS, COPY_RALLY_TO_TFS</Services>

You will also need the relevant XML tags as discussed in the RallyConnection and the TFSConnection sections.

Troubleshoot the connector

  • The connector logfile:

    Once the connector is running, all errors are written to a log file in the working directory where the rally2_tfs_connector.exe was invoked. Informational messages, warnings, and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the configuration file.

    To see the most recent log messages on Windows, rename the provided file WinTail.dat to WinTail.exe and then double-click on the WinTail.exe and browse to the rallylog.log file.

  • Order of operations: Before the connector starts synchronizing objects between the two systems, it performs the following steps:
    • Connecting to the TFS server is successful
    • Connecting to Rally is successful
    • Fields in the field mapping exist in Rally and in the TFS system
    • Ensures that each field handler has a corresponding field mapping section in the configuration file

  • Using preview mode:

    To make a test run of the connector (for example, without moving artifacts between the two systems), set the <Preview> tag in the configuration file to true. Use this technique to experiment with different configuration options to gain confidence or to debug a specific issue.

  • Using Reference Name: When creating the custom field for the <ExternalIDField> in the <TFSConnection> section of the configuration file, be sure to use the Reference Name as opposed to the Name field. If the name field used, it will generate an error as follows:
      INFO : Connector.copy_to_rally - Copy to Rally
     DEBUG : Connector.block in map_fields_to_rally -   Mapping System.Title(T1) - to - Name(T1)
      WARN : TFSConnection.initialize - Unable to obtain TFSEntity field value for: Rally.Common.RallyID
      WARN : ConnectorRunner.exception - Message Unable to obtain TFSEntity field value for: Rally.Common.RallyID

  • Log in to the CA Agile Central Success Community for support of this and all of our connectors. The CA Agile Central Success Community is your one stop shop for self service and support. Accessing the CA Agile Central Success Community is quick and easy!
  • Mapping CA Agile Central projects:

    If you are copying defects from TFS to CA Agile Central using the <RallyReferenceFieldHandler> with projects, you may see a Could not find Rally project with name ... error in the log file if the connector user does not have editor permissions to that project in CA Agile Central.

RallyReferenceFieldHandlers are for the most part deprecated. Prior to the 4.4.2 release, if multiple projects were specified in the config file Release or Iteration value was sometimes mapped incorrectly. By relocating some logic, that issue has been addressed as well as being able to handle the most common CA Agile Central Reference fields (Project, Release, Iteration) automatically without needing explicit notation in the configuration file. If the connector detects that are using a RallyReferenceFieldHandler for one of those aforementioned fields, the connector will emit a deprecation warning message into the log file and will not register the field handler as that logic is now handled automatically. The are some edge cases where the use of RallyReferenceFieldHandler may be necessary, for fields such as Parent, Child, WorkProject, Owner and other similar fields.

Revision history

  • 4.7.0-master-25 (TFS 2015) May-2016
    • Enhancements:
      • TFS 2015 support using the TFS REST API.
      • Connector can be run on a non-Windows platform.
      • Connector can be run on a machine other than the box where TFS is installed.
      • Attachment support:
        • can reflect attachments on a TFS Work Item in CA Agile Central.
        • can reflect attachments on a CA Agile Central artifact in TFS 2015.
  • 4.6.5-master-33 (TFS 2013) 24-Nov-2015
    • Enhancements:
      • Detecting duplicate CA Agile Central project names will now create an error log and exit condition.
      • Emailer functionality is now process prioritized to allow alert emails to send even if subsequent configuration validation fails.
      • Enhanced credential value encryption.
  • 4.6.5-master-72 (TFS 2012) 24-Nov-2015
    • Enhancements:
      • Detecting duplicate CA Agile Central project names will now create an error log and exit condition.
      • Emailer functionality is now process prioritized to allow alert emails to send even if subsequent configuration validation fails.
      • Enhanced credential value encryption.
  • 4.6.5-master-71 (TFS 2010) 24-Nov-2015
    • Enhancements:
      • Detecting duplicate CA Agile Central project names will now create an error log and exit condition.
      • Emailer functionality is now process prioritized to allow alert emails to send even if subsequent configuration validation fails.
      • Enhanced credential value encryption.

  • 4.6.4-master-32 (TFS 2013) 16-Nov-2015
    • Enhancements:
      • Brand redesign.
  • 4.6.4-master-71 (TFS 2012) 16-Nov-2015
    • Enhancements:
      • Brand redesign.
  • 4.6.4-master-70 (TFS 2010) 16-Nov-2015
    • Enhancements:
      • Brand redesign.

  • 4.6.2-master-69 (TFS 2013) 14-Aug-2015
    • Fixes:
      • Cleaned up log errors when the pre_copy method called on copy_to_rally/copy_to_other can not satisfy the necessary conditions which typically related to missing required fields or fields with a null/blank value.
      • XML include files containing Rally Url or Workspace or Project handled properly both before and after credential encryption.
      • Added better validation for RallyTaskToWorkProductLinker which identfies specific configuration items necessary for operation and provides log error entries if not present or not containing plausible values.
  • 4.6.2-master-69 (TFS 2012) 14-Aug-2015
    • Fixes:
      • Cleaned up log errors when the pre_copy method called on copy_to_rally/copy_to_other can not satisfy the necessary conditions which typically related to missing required fields or fields with a null/blank value.
      • XML include files containing Rally Url or Workspace or Project handled properly both before and after credential encryption.
      • Added better validation for RallyTaskToWorkProductLinker which identfies specific configuration items necessary for operation and provides log error entries if not present or not containing plausible values.
  • 4.6.2-master-31 (TFS 2010) 14-Aug-2015
    • Fixes:
      • Cleaned up log errors when the pre_copy method called on copy_to_rally/copy_to_other can not satisfy the necessary conditions which typically related to missing required fields or fields with a null/blank value.
      • XML include files containing Rally Url or Workspace or Project handled properly both before and after credential encryption.
      • Added better validation for RallyTaskToWorkProductLinker which identfies specific configuration items necessary for operation and provides log error entries if not present or not containing plausible values.

  • 4.6.0-master-27 (TFS 2013) 31-May-2015
    • Enhancements:
      • Credentials in the RallyConnection and TFSConnection sections are now encrypted.
  • 4.6.0-master-65 (TFS 2012) 31-May-2015
    • Enhancements:
      • Credentials in the RallyConnection and TFSConnection sections are now encrypted.
  • 4.6.0-master-65 (TFS 2010) 31-May-2015
    • Enhancements:
      • Credentials in the RallyConnection and TFSConnection sections are now encrypted.

  • 4.5.5-master-24 (TFS 2013) 25-Apr-2015
    • Enhancements:
      • Support for using APIKey in place of Rally username and password.
      • Better handling of FieldDefaults and values.
      • Bettrer logging of failed attempt to copy/update item from another system to Rally.
  • 4.5.5-master-62 (TFS 2012) 25-Apr-2015
    • Enhancements:
      • Support for using APIKey in place of Rally username and password.
      • Better handling of FieldDefaults and values.
      • Bettrer logging of failed attempt to copy/update item from another system to Rally.
  • 4.5.5-master-62 (TFS 2010) 25-Apr-2015
    • Enhancements:
      • Support for using APIKey in place of Rally username and password.
      • Better handling of FieldDefaults and values.
      • Bettrer logging of failed attempt to copy/update item from another system to Rally.

  • 4.5.4-master-21 (TFS 2013) 02-Apr-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to Rally Name, Description, Notes that contain non-ASCII characters.
      • Added support for running against TFS2013 on a server on which only VS2013 has been installed
  • 4.5.4-master-60 (TFS 2012) 02-Apr-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to Rally Name, Description, Notes that contain non-ASCII characters.
  • 4.5.4-master-60 (TFS 2010) 02-Apr-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to Rally Name, Description, Notes that contain non-ASCII characters.

  • 4.5.3-master-20 (TFS 2013) 10-Mar-2015
    • Enhancements:
      • Updated to use Rally WSAPI v2.0.
      • Added a RallyBooleanFieldHandler.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.
  • 4.5.3-master-59 (TFS 2012) 10-Mar-2015
    • Enhancements:
      • Updated to use Rally WSAPI v2.0.
      • Added a RallyBooleanFieldHandler.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.
  • 4.5.3-master-59 (TFS 2010) 10-Mar-2015
    • Enhancements:
      • Updated to use Rally WSAPI v2.0.
      • Added a RallyBooleanFieldHandler.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.

  • 4.4.12-maintenance-23 (TFS 2013) 22-Jan-2015
    • Enhancements:
      • Support added for a RallyReferenceAttributeLookupFieldHandler intended to be used primarily with Release and Iteration fields where the attribute used for the lookup is other than the 'Name'.
      • This release is likely to be the last for the 4.4.x line that uses Rally WSAPI 1.43.
  • 4.4.12-maintenance-102 (TFS 2012) 22-Jan-2015
    • Enhancements:
      • Support added for a RallyReferenceAttributeLookupFieldHandler intended to be used primarily with Release and Iteration fields where the attribute used for the lookup is other than the 'Name'.
      • This release is likely to be the last for the 4.4.x line that uses Rally WSAPI 1.43.
  • 4.4.12-maintenance-54 (TFS 2010) 22-Jan-2015
    • Enhancements:
      • Support added for a RallyReferenceAttributeLookupFieldHandler intended to be used primarily with Release and Iteration fields where the attribute used for the lookup is other than the 'Name'.
      • This release is likely to be the last for the 4.4.x line that uses Rally WSAPI 1.43.

  • 4.4.11-maintenance-15 (TFS 2013) Dec-2014
    • Enhancements:
      • Updated TFSBridge to enable connector to also run on a platform with only VS2013 installed.
  • 4.4.11-maintenance-92 (TFS 2012) Dec-2014
    • No effective changes for TFS2012, changes in codebase for TFS2013.
  • 4.4.11-maintenance-43 (TFS 2010) Dec-2014
    • No effective changes for TFS2010, changes in codebase for TFS2013.

  • 4.4.10-master-12 (TFS 2013) Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
      • Added support for command line arguments to specify log file max size and file count.
  • 4.4.10-master-53 (TFS 2012) Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
      • Added support for command line arguments to specify log file max size and file count.
  • 4.4.10-master-53 (TFS 2010) Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
      • Added support for command line arguments to specify log file max size and file count.

  • 4.4.4-master-8 (TFS 2013) Sep-2014
    • Enhancements:
      • Improved semantic comparison of Rally boolean values to strings ('true' / 'false') should result in fewer unnecessary updates.
      • Improved semantic comparison of Rally decimal values to integers/strings (1.0 should equal 1 or "1") should result in fewer unnecessary updates.
      • Improved comparison of Rally User to user identifier from TFS 2013 should result in fewer unnecessary updates. This also applies to TFS 2010 and 2012.
  • 4.4.3-master-7 (TFS 2013) Sep-2014
    • Enhancements:
      • Modifications to make parsing RevisionHistory Revision records more robust, especially the Notes field.
  • 4.4.2-master-6 Jul-2014
    • Enhancements:
      • Common Rally Reference fields (Project, Release, Iteration) no longer need to have a RallyReferenceFieldHandler configured in the Connector - RallyFieldHandlers section of the config file.
      • Mapping of Rally Reference fields such as Release and Iteration is fully project scoped to ensure that if the DisplayName of multiple Release items is identical, the artifact contains the link to the item associated with the Project setting in the artifact.
      • Introduction of the TFSTreePathFieldHandler (for the TFS Iteration field (System.IterationPath)) that can also be used in place of the ProjectPathFieldHandler for the TFS Project Field (System.AreaPath).
  • 4.3.0-master-8 Jan-2014
    • Enhancements:
      • Upgrade from Ruby 1.9.2-p290 to Ruby 2.0.0-p247.
      • Performance improvement gained by using rally_api rather than rally_rest_api.
      • Added more build tests.
      • Connector would validate only the first config file on command line (DE17492).
      • Added <SuppressDeprecationWarning/> XML tag.
      • Added support for TFS 2012.
      • Support for Task Items.
      • Upgrade to version 1.42 of the WSAPI.
      • Note: For the 4.3.0 version of this connector, any custom code (such as a custom field handler) will require modifications. A working example (using the QC connector) can be found here.

        Previous method for doing requires:
        require 'yeti/field_handlers/other_field_handler'
        require 'rexml/document'

        class MyCustomFieldHandler < ....FieldHandler
          ....
        end
        New way of doing requires:
        require 'rallyeif/wrk/field_handlers/field_handler'

        module RallyEIF
          module WRK
            module FieldHandlers

              class MyCustomFieldHandler < ....FieldHandler
                # See example code in installation directory:
                # ./field_handlers/my_custom_field_handler.rb
              end
            end
          end
        end
  • 4.0.2-master-520 Dec-2013
    • Enhancements:
      • Support for task/story linking on items copied from Rally to TFS (and subsequent updates)
    • Known issues:
      • None
  • 2.10.0-master-6 - 07-Oct-2013
    • Enhancements:
      • Support for TFS2012
    • Known issues:
      • (none)
  • 2.8.9-master-2 - 20-May-2013
    • Enhancements:
      • Support for TFS2012
    • Known issues:
      • (none)
  • 2.8.6-144 - 17-Oct-2012
    • Enhancements/Fixes:
      • Added artifact ID to message string
      • Added more debug output in Rally connection section
      • Improved performance by removing refresh on workspace read in find-workspace loop
      • Updated to rally_api 0.6.0 gem
    • Known issues:
      • The version of this connector is erroneously reported as 2.7.7
  • 2.7.4-129 - 13-May-2012
    • Enhancements/Fixes:
      • Added ability for FormattedID in TFS system to have lower or lower case prefix (us/US)
      • Added subfield specifications on CopySelectors from Rally using the precopy feature
      • Added XML include capability so common text can be included as a separate file
      • Installer now has both the TFS Connector and TFS Bridge in the same installer package
      • Added project path Field Handler
English

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.