This page is designed as a supplement to our connector specific Install and Usage guides. Let us know if you have a additional topic we should cover here.
Getting Started with Enterprise Integration Framework
Welcome to working with the CA Agile Central Enterprise Integration Framework (EIF). When integrating two systems, we have found one recommendation that holds true for all connectors: Start simple.
If you are looking at a connector, the first thing we advise is to define the problem you are trying to solve.
Once you know what team and subset of work items you want to move, you can start to look at what the minimum set of information you would want to map would be. To get things going, we usually recommend starting with something as simple as Name, Description, Owner and then figure out what CA Agile Central projects those work items would go to.
Debugging Create and Update Services
Review Field-level updates from CA Agile Central in this document for additional information regarding services.
|Service Name in Config
||Searches CA Agile Central 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 CA Agile Central.
||In your config.xml, locate the <ConnectorRunner> tag (usually at the bottom of your config file). Inside of the <Services> tag, list UPDATE_RALLYFIELDS_AND_OTHER and remove the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY service(s).
The previous version of services is described below. However, we recommend using the new service described above, UPDATE_RALLYFIELDS_AND_OTHER. The connectors run four basic services to move information between CA Agile Central and other systems:
|Service Name in Config
||Find new work items in CA Agile Central and copy them to the other system
||Query CA Agile Central where (ExternalID = null) AND (work item project is in projects listed in RallyConnection) AND (all RallyConnection CopySelectors conditions are satisfied)
||Find new work items in the Other system an copy them to CA Agile Central
Query Other system where (RallyID is null) AND (all OtherConnection CopySelectors conditions are satisfied, like MoveToRally = Yes).
NOTE: The JIRA connector queries for "-1" (minus one) instead of null.
||Find work items in CA Agile Central that are connected to the Other system and move updates
||Query CA Agile Central where (ExternalID != null) AND (LastUpdateDate is updated since last connector run time) AND (all RallyConnection CopySelectors conditions are satisfied)
||Find work items in the Other system connected to CA Agile Central work items and move updates
||Query Other system where (RallyID is not null) AND (Other system's work item updated timestamp is since last connector run time) AND (all OtherConnection CopySelectors conditions are satisfied)
In your configuration file, the <ConnectorRunner> tag contains the <Services> tag where you can specify which services to run. There are four services to chose from; multiple services can be specified:
Note: The connector will run the services in the order listed in the configuration file.
We generally recommend the following when listing multiple services:
- When you are setting up the connector, start with just the creation services to get connections working, then add the update services
- List the update services first, then the creation services
- The connector is not finding all of my work items:
All three systems (the CA Agile Central server, the Other server and the connector server), should have times synchronized fairly closely (within a couple minutes). This can be accomplished through NTP (Network Time Protocol).
- The connector is not finding any work items with the Copy service:
- ExternalID custom field issues:
- Check the Type on the ExternalID custom field in CA Agile Central. It must be of type String. (NOTE: If it is of type Text, no work items will be found on a query.)
- Check the spelling of the ExternalID names in the configuration file and ensure they match what you have setup in the CA Agile Central system or the Other system.
- CA Agile Central accesses a custom field through its "Display Name" (not its "Name"). Also, spaces and underscores are stripped, so something like "External ID" becomes "ExternalID".
- Check the custom field in the other system that is to hold the RallyID Be sure it is really "empty". For some of the Other systems, empty is "null", for JIRA empty is a minus one (-1). Run a test query in other system, assuming it has a query feature.
- Check the <CopySelectors> (assuming you are using them) to be sure they do not cause your work items to get excluded (from the compound AND criteria).
- When running the Copy service, the query is Project scoped. Therefore only the projects declared in the <Projects> element of the configuration file will be searched.
- When running the Update service, the query is Workspace scoped. Therefore all projects in the workspace will be searched
- The connector is not finding any work items with the Update service:
- Be sure you have done an update since the connector was last run. For each configuration file, the connector stores a time file, and it contains the time of the last successful run of the Update services. If you made an update 10 minutes ago and the connector ran in the last 5 minutes, that update may not show up – this sometimes happens when you are debugging. The time file is named "<Config-File-Name>time.file", and it contains one line as follows:
2012-05-24 17:18:58 UTC
- Check the timezone that your Other system stores the last updated date and time – is it in the same timezone as the connector or offset?
- Check that the ExternalID or RallyID was really stored between the two systems.
- Check the <UpdateSelectors> (assuming you are using them) to be sure they do not cause your work items to get excluded (from the compound AND criteria).
- Check for errors or warnings in the log file – you may need to turn up the level of logging. One of the two systems may have failed on a POST in trying to update.
Managing the Logger and Log Files
As the connectors are running, they will log messages into a file named rallylog.log 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 as follows:
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 log-file-size <integer>.
The -m <integer> option pair can be used to specify the maximum number of files in the log file rotation scheme. This can also be expressed as --max-log-files <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
rally2_xxx_connector --log-file-size 50 --max-log-files 20 xxx_config.xml -1
The connector uses multiple logging levels, each increasing in the level of detail. Note in the table below that each level includes all higher level information (for example, WARNING includes all warnings, errors and fatals).
||Level of Detail
||Example of Detail
||Display Field mapping values
||Connection / Disconnection Info
||Failed to Map field
||Failed Create work item Messages
||...(shows as ANY in the log file)
These levels are documented at http://corelib.rubyonrails.org/classes/Logger/Severity.html.
In your configuration file, the <ConnectorRunner> tag is where the <LogLevel> setting is declared, as follows:
We generally recommend the following:
- When you are setting up the connector, leave the <LogLevel> at Debug
- When you are up and running with the connector, set the <LogLevel> to Warning
If you use Debug, you will get the values the connector tries to map for fields along with other debug information.
If you want to leave the connector at Info, you will also see information for when the connector is connected to each system on wake and sleep.
We also recommend checking the log on a daily or weekly basis to look for exceptions or errors to resolve.
Multiple Configuration Files
Multiple configuration files may be needed if your setup requires:
- Mapping to more than one workspace in CA Agile Central
- Mapping multiple work item types
- Mapping to multiple containers in the other system, such as:
- domain/projects in Quality Center
- databases in ClearQuest
- team projects in TFS
Note: We recommend naming the configuration files using descriptive names for easier troubleshooting.
To run the connector with multiple configuration files, it is recommend to invoke it once per configuration file. For example:
rally2_xxx_connector.exe config_workspaceA.xml -1
rally2_xxx_connector.exe config_workspaceB.xml -1
rally2_xxx_connector.rb config_workspaceA.xml -1
rally2_xxx_connector.rb config_workspaceB.xml -1
To have the above invocation repeated at regular intervals, define a Windows Scheduled Task (or a cron job in Linux) which will be invoked at regular intervals. We recommend such a task be repeated every 10 minutes or more and advise against anything less.
When to Use Multiple Configuration Files
We designed this to be fairly flexible to meet various needs among our connectors. The information below covers some scenarios that can help clarify when and how to use multiple configuration files.
One Directory, Multiple Configuration Files
For running in one process with multiple configuration files as noted above - we usually recommend or require this setup if any of the following are true:
- If you are connecting multiple Quality Center Projects, you will need one config.xml for each QC Project
- If you are connecting multiple JIRA Projects, you will need one config.xml for each JIRA Project
- If you are connecting multiple CA Agile Central Workspaces, you will need one config.xml for each CA Agile Central Workspace
- If you are connecting more than one ClearQuest Schema, you will need a config.xml for each CQ Schema
- If you are connecting multiple work item types, one config.xml will be needed for each work item type (Defect, User Story, Test Case)
You can also install and setup the connector in multiple parallel directories, for example:
Defects in C:\Program Files\RallyConnectorFor<othersystem>\Defects\ all EIF files
Stories in C:\Program Files\RallyConnectorFor<othersystem>\Stories\ second copy of all EIF files
In this case, you can call the rally2_*connector.exe config.xml in two different processes. Each process can then have its own timer interval.
You could, for example, run every 10 minutes for Defects and every 30 minutes for stories.
This setup will also allow you to have two different rallylog.log files for the two work items which may help with monitoring of the log files.
How to Include Other XML Files
Within a configuration file, it is possible to have other files of XML text included, resulting in all the files being treated as one XML file. This is accomplished by making use of the XML External Entities feature. For example, the normal user mapping in the <OtherEnumFieldHandler> section of a configuration file could be removed from the main XML configuration file and pasted into a new XML file named "users.xml". It might look something like this:
File name: users.xml
In the main configuration file, include the following as the first 4 lines:
<!DOCTYPE config SYSTEM "config.dtd" [
<!ENTITY usersFile SYSTEM "users.xml">
Then, in your main configuration file, where ever the text should occur, enter the string &usersFile;. For example:
Known limitations with XML include:
- When this feature is used to include a file which contains the user's clear-text password, the connector rewrites the password as an encoded (not encrypted) string. However, the connector will write the encoded string into the main XML file instead of the included password file (and thus overwriting the "include" line). Workaround: If the included file contains the encoded password, the connector will not attempt to rewrite the string.
- When specifying the full path to the include file, use slashes (/) instead of backslashes (\). For example, this would be a valid path designation: "C:/Users/jpkole/RallyQC/x073-Entity-Test-RALLYstory.xml"
Using Field Handlers
A field that has been mapped in the <FieldMapping> section can have a "field handler" registered against either field (the CA Agile Central field or the "Other" field"). Once done, the field handler is invoked each time that mapping occurs.
WARNING: It is not supported to register two different field handlers on the same field name. While the connector will silently ignore such a situation and the connector will normally remember only the last one registered, the results are unpredictable (and this is not a supported configuration).
Selecting a Subset of Work Items Through <CopySelectors> and <UpdateSelectors>
The connector can be instructed to select a subset of work items from either CA Agile Central or the Other system when performing the COPY or UPDATE service. Selecting only a few of your work items is helpful when setting up the connector for the first time.
Copy and Update selection criteria are configured in the <RallyConnection> and <OtherConnection> elements of your configuration file.
Please note that the QC connector has both some limitations and extensions to the selector syntax where other connectors do not. The details can be found in our FAQ here.
An example of the selector syntax:
<CopySelector>FormattedID = DE351</CopySelector>
<CopySelector>SyncToJIRA = "True"</CopySelector>
<CopySelector>State = "Open"</CopySelector>
<CopySelector>Priority != "Normal"</CopySelector>
<CopySelector>Priority != Low</CopySelector>
You can have multiple <CopySelector> elements and <UpdateSelector> elements contained within the <CopySelectors> container and <UpdateSelectors> container, respectively. Multiple selector elements are ANDed together. If you need an OR capability, we suggest using multiple configuration files to effect that result, or possibly using the not-equal on all the values you don't want selected.
A selector element must have a field name, a space, a relation operator, a space and then your target value. If your target value contains spaces, you do not need to quote the value. For example:
<UpdateSelector>AssignedTo = John Q. Public</UpdateSelector>
The selector syntax supports evaluating a field against a value with a relational operator. The value must be non-null and non-blank. The following is an example of syntax that is NOT supported:
<!-- Invalid syntax: -->
<CopySelector>X_FIELD = </CopySelector>
As a general rule, a selector element supports the =, !=, <, >, <= and >= relational operators. However, because the configuration file is in XML, the '<' and '>' characters are problematic and confuse the XML parser. Therefore, use the alphabetic abbreviation equivalents shown in the following table:
<CopySelector>LastModified gte 2011-04-05</CopySelector>
Tip: Another way to move a smaller set of work items from the other system to CA Agile Central is to create a custom field named "Move to CA Agile Central?" that is a Yes/No drop-down or checkbox. The connector can then select and move only those work items where the custom field is "Yes".
NOTE: When using <CopySelectors>, the query is Project scoped. Therefore only the projects declared in the <Projects> element of the configuration file will be searched.
Using Selectors on Reference Fields
Reference fields, which is any field in a work item that actually points to another object (as opposed to containing a simple value) in the OTHER system are not supported.
Fields in a CA Agile Central referenced object can be used in the selector elements. For example:
<CopySelector>Project.Name = MyNewProj1</CopySelector>
<CopySelector>Iteration.Name = Iter2</CopySelector>
Upgrading a CA Agile Central Connector
Upgrading instructions are unique to your system environment.
Upgrading on Windows
Follow these steps:
- Back-up your configuration file(s) and any custom field handlers. The best practice is to ALWAYS rename your configuration files and never use the default <connector_name>_config.xml files as the uninstall (step 2) will delete those files permanently.
- Go to the directory where you installed the CA Agile Central Connector (by default C:/Program Files/RallyConnectorfor<connector_name>) and double-click the unins000.exe.
- Run the installer, RallyConnectorfor<connector_name>Install-<version>.exe, for the latest CA Agile Central Connector version.
Upgrading on Non-Windows (Using rally2*.rb Script)
Follow these steps:
- Back-up your configuration XML file(s) and any custom field handlers. Best practice is to ALWAYS rename your configuration files and never use the default <connector_name>_config.xml files.
- Un-install the current gem. Open a console shell and type:
gem uninstall yeti
- Once you have saved the gem locally. CD to the directory where the gem resides.
- Install the latest gem. Open a console shell and type:
gem install yeti*.gem
How to Map Fields
When transferring work items from CA Agile Central, to another system (or vice versa), the configuration file must specify which fields of the work items in CA Agile Central are to be mapped to which fields in the other system. This is done within the <FieldMapping> XML element in the configuration file. When the connector performs a create or update, only the fields specified in this section will be modified.
When you set up your mapping, ensure the fields are compatible between the two systems (for example, an integer field should map to an integer field, or a rich text should map to a rich text in the other system. Otherwise, you might experience situations where information is not created/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 map a string field to a custom field of type integer in CA Agile Central.
When specifying CA Agile Central field names, the "Display Name" must be used (as opposed to the "Name"). Also, when specifying the Display Name in the <FieldMapping> section, if there are spaces in the Display Name, they should be removed (i.e. a Display Name of "Foo Bar" would be declared as <Rally>FooBar</Rally>....).
If you are mapping a drop-down value in CA Agile Central to the other system, the drop-down values match. Otherwise, the connector will generate an error letting you know the value was not found in the list. If your drop-down values are different between the two systems, see the next section Mapping drop-down values.
In the above example, the CA Agile Central "State" field will be mapped to the other system's "Status" field, "Severity" to "Importance", and "Priority" to "Urgency".
Mapping Rally ID Fields
CA Agile Central Objects have two identifiers, one which is unique across all CA Agile Central Entities (the ObjectID) and the other which is only unique inside a workspace (the FormattedID). These can be viewed by going to a CA Agile Central defect's detail page (using the CA Agile Central GUI) and near the top left corner, you should see the FormattedID listed as something like DE42. And if you click on the chain link icon to the left of the bold name and ID, you will go to a specific URL for that defect, which is something like: https://rally1.rallydev.com/#/3026904716ud/detail/defect/3026966119. The number at the end of the URL (3026966119 in this example) is the ObjectID for the Defect.
The mappings for both of these ID fields can be set up in the <RallyConnection> and the <OtherConnection> elements of your configuration file.
The following example XML shows a QC Connection where both the CA Agile Central ObjectID and CA Agile Central FormattedID are being mapped to the Quality Center custom fields named in the <ExternalIDField> and <ExternalEndUserIDField> tags, respectively. The connectors for JIRA, TFS, and ClearQuest can also recognize these tags.
<!-- This first line is an XML comment -->
<!-- The following custom field will contain the Rally ObjectID -->
<!-- The following custom field will contain the Rally FormattedID -->
CA Agile Central Text Field Considerations
CA Agile Central has a 32k character limit for rich text fields. Examples are the Summary, Description and Notes fields. Other systems such as Quality Center support a limit beyond 32k for text fields which causes data constraint inconsistencies.
How does the connector handle text greater than 32k in CA Agile Central?
If you copy/update a work item from the target system to CA Agile Central, the connector will warn you that the text is beyond the 32k limit and not copy/update the particular work item. The warnings will not prevent the connector from running as it will continue to copy/update the next work item that needs processing.
How to prevent this from happening?
If you want to avoid warnings for the 32k limit, CA Agile Central advises that you enforce this limit on the connection target system. For example, if you are using Quality Center, you can write a custom script that is executed when the user saves the bug or requirement that automatically restricts any text field to the 32k limit. Please speak to your system administrator to explore solutions that ensure consistency between text fields in each system when different character limits exist.
Another alternative is to only map the field in one direction. For example, if CA Agile Central restricts the field to 32k, then only allow the copy/update from CA Agile Central to the other system. This ensures that the text for that field is never too big.
To restrict when a particular field is copied or updated, add a Direction tag to the FieldMapping section for that field.
Specify TO_OTHER (upper or lower case) if you want CA Agile Central to be the source of record, meaning changes from the other system are never pushed to CA Agile Central. Specify TO_RALLY (upper or lower case) if you want the other system to be the source of record, meaning changes from CA Agile Central are never pushed to the other system.
Mapping Required Fields and Field Defaults
When you want to copy work items (such as user stories, defects, test cases) from one system to another (CA Agile Central, QC, JIRA, CQ) and the destination system has required fields defined on the work item, you can use one (not both) of the following two methods:
- Use the <FieldMapping> element described above in How to map fields.
- If you do not use field mappings, and you want a required field in the destination system to always have the same default value, use the <FieldDefaults> XML element. For example:
In the above example, the XML element <QCConnection> could be something like <RallyConnection> or <CQConnection>, depending on which connector you are using. In this example, the QC field "Severity" is automatically assigned the default string value of "Rally-Severity" for any work item created in the QC system. The QC field "Status" automatically gets a string value of "Rally-Status".
Mapping Fields With Null Values
If a value of a mapped field on one side of the connection is set to null, the connector does not nullify the corresponding field's value on the other side. Update for this field will be skipped. If it is the only update to the underlying artifact, the rallylog.log will say Skipped update for <id> since no fields changed.
Different systems treat null or empty values for given field types inconsistently, so we chose not to nullify values during updates due to this disparity. Reflection of null values is further complicated by the fact that users are able to map a field of one type in one system to a field of another type in the other system.
Field-Level Updates From CA Agile Central
A service is available for updates with the work item EIF connectors. UPDATE_RALLYFIELDS_AND_OTHER has been introduced to help the connector deal with updates in both systems. The service will override the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY services.
This service first searches CA Agile Central for updates and pushes only the recently-changed fields (that were mapped) to the other system. It then searches the other system for updates and pushes all mapped fields into CA Agile Central. This reduces the chance of overwriting data when work items are modified in both systems.
The connector runs and a work item is copied and up to date in both systems.
- In CA Agile Central, a user changes Severity to Low
- In QC, a user updates the Description
With the older services, the first update service listed would take precedence. For example, if UPDATE_RALLY_TO_OTHER were listed first, the connector would copy all the CA Agile Central data to the other system and the Description change would not be processed.
Now, however, the connector will search CA Agile Central for updates and check what mapped CA Agile Central fields have changed. In this example, only Severity changed and the connector will send only the Severity change over to the other system instead of all of the mapped fields. Then the connector will search the other system for updates and the Description change will be pushed to CA Agile Central, along with all other mapped fields.
Configuring the new service:
In your config.xml, locate the <ConnectorRunner> tag (usually at the bottom of your config file).
Inside of the <Services> tag, list UPDATE_RALLYFIELDS_AND_OTHER and remove the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY service(s).
A warning is logged if the old update services are listed with the new one, noting that the old update services will be skipped.
Field Level <Direction> tag mappings are still respected.
If you wish to configure a one-way feed of data and updates from another system to CA Agile Central, we recommend still using COPY_OTHER_TO_RALLY and UPDATE_OTHER_TO_RALLY.
Mapping Drop-Down Values
If you have different drop-down values between the two systems, you can setup up another type of field handler in your configuration file which defines the mapping. For example:
<Field><Rally>Crash Data/Loss</Rally> <Other>S1</Other></Field>
<Field><Rally>Major Problem</Rally> <Other>S2</Other></Field>
<Field><Rally>Minor Problem</Rally> <Other>S3</Other></Field>
The above sets up a mapping of the values from the CA Agile Central field Priority to the other systems field of BG_PRIORITY. The value in the <FieldName> element should be the name of the field being mapped.
The <Mappings> element defines the CA Agile Central value within the <Rally> tags and the corresponding other system's value within the <Other> tags. In the above example, in the <OtherEnumFieldHandler> for BG_PRIORITY, the value Resolve Now in CA Agile Central maps to a value of 1 in the other system and High in CA Agile Central maps to a value of 2 in the other system.
IMPORTANT: The connectors are not able to handle drop-down fields in CA Agile Central which have a <<No Entry>> value in the UI (for example, the field is empty).
IMPORTANT: Multi-value drop-down fields are not supported.
Note: This field handler allows for both many-to-one (or many-to-fewer) value mappings. However, for any field which has many-to-one mapping defined, the inverse operation, one-to-many (or fewer-to-many) is undefined. For instance, given this configuration file syntax:
When mapping from CA Agile Central to Other, a CA Agile Central value of "Submitted" will produce unpredictable results. Also, when mapping from Other to CA Agile Central, a Other value of "FIXED" will produce unpredictable results.
There is also a <OtherConditionalEnumFieldHandler>, which is very similar to the <OtherEnumFieldHandler> except only the exceptions need to be declared, such as corresponding entries in the pull-down lists of both system which are identical, need not be declared.
Mapping User Names
To map CA Agile Central fields which reference a user name, add a field mapping to the <FieldMapping> section (within the <Connector> section) as in one or both of the following examples:
Note: We currently recommend that all users which are expected to be mapped between the two systems be created in CA Agile Central before you start using the connector. Even for those users of the Other system which do not intend to use CA Agile Central, there should be an account created for them in CA Agile Central so that the system can have a valid user reference in the copied work items. You may however, mark those users as inactive in CA Agile Central if you do not wish them to ever be active users. In this case, the connector will still be able to set the fields to point to these inactive users.
In CA Agile Central, the Owner and SubmittedBy fields on an work item (HierarchicalRequirement, Defect, Test Case, and so on) are "reference" fields. This means they do not contain a simple string value, but rather they are pointers to yet another object (the User object in these examples). When the connector is updating or copying an work item from the Other system to CA Agile Central, it must translate the Other system's user name into a valid CA Agile Central user name. To accomplish this task, the connector can use one of the four methods for mapping user names between CA Agile Central and the Other system, as follows:
- Using the <Domain> XML tag
If you want to map users between CA Agile Central and the Other system, you can specify a <Domain> XML tag in the <Connector> section as follows:
The <FieldName> XML tag contains the name of the field in the Other system and the <Domain> XML tag specifies the expected domain for user names in CA Agile Central. In the above example, peter in the Other system would be mapped to [email protected] in CA Agile Central.
- Using the MiddleName (or other) field on the User object.
On each User profile in CA Agile Central, you could assign the MiddleName (or other unused field on the User object) field to be the exact ID of the user in the Other system. When the connector is copying a work item, it will search CA Agile Central for a User object whose MiddleName (or whichever field is specified in the <ReferenceFieldLookupID> tag) matches the Other system's user name string. When a match is found, this CA Agile Central user will be used in the field mapping for this new CA Agile Central work item. Valid fields are User, Owner, SubmittedBy and Tester. Example configuration file syntax:
- Using an <OtherEnumFieldHandler> XML tag
User name mapping may be done the way it is described in "Mapping drop-down values" section of our help. This is basically a method where every user is explicitly mapped between systems. Example configuration file syntax:
- NOTE 1: The drawback to this approach is that it may require a very long list of users. If two different "username" fields need to be mapped, rather than repeating the above <OtherEnumFieldHandler> mapping, you could also use the XML entity feature described above under How to include other XML files.
- NOTE 2: When using the Quality Center connector with this method of user name mapping, the "User Name" field from both CA Agile Central and Quality Center are to be used in the above example (as opposed to the "Email Address" fields).
- Using a <RallyCSVUserMappingFieldHandler> XML tag
User name mapping can be done using a CSV file. See example configuration file here.
Mapping Reference Fields From CA Agile Central
In CA Agile Central, some fields within a work item are string or number values while other fields are actually pointers (called a "reference") to other objects. For the most commonly used reference fields, no additional syntax is required to properly map these fields. For some of the more infrequently used CA Agile Central reference fields, the connector has special syntax when they are listed as fields to be mapped. More advanced and simple reference field handling was introduced with the 4.4.12 release.
- No FieldHandler is necessary if the intended attribute value desired for the mapping is the Name field. RallyReferenceFieldHandler for the Project, Release, and Iteration fields has been deprecated (since 4.4.2). When you need to map an attribute other than Name for (Project, Release or Iteration), you'll need to use a <RallyReferenceAttributeLookupFieldHandler>(see below).
- Advanced field handling for other Reference fields.
These fields are found in CA Agile Central work items, including HierarchicalRequirement, Defect, and TestCase.
Use a RallyReferenceFieldHandler with a <ReferencedFieldLookupID> tag for the intended lookup attribute. The lookup attribute should be a non-reference field. Examples of such attributes are "Name" and "ObjectID".
- Project, Release or Iteration with an intended lookup attribute other than the "Name" field: use <RallyReferenceAttributeLookupFieldHandler> for this with a corresponding <ReferencedAttributeLookupID> tag for the specific attribute to be used as the map value.
- Within the <Connector> section of the configuration file, specify the field to be mapped in the <FieldMapping> section.
- Also within the <Connector> section of the configuration file, create a <RallyFieldHandlers> section.
- Within this section, specify the field in a <RallyReferenceFieldHandler> element as <FieldName>the_name_of_the_field</FieldName>.
- If no <ReferencedFieldLookupID> tag and value is specified, the "Name" attribute is used by default.
- If the default value is not suitable for your purposes, explicitly provide a <ReferencedFieldLookupID> tag and value, where the value is a CA Agile Central work item attribute such as "DisplayName", "FormattedID", "ObjectID".
When running any WorkItem Connector 4.4.0 or beyond (4.4.x, 4.5.x, ...), if the connector detects the use of a <RallyReferenceFieldHandler> for one of the Project, Release or Iteration fields, a deprecation notice (warning) will be written to the log file and the field handler for that particular field will not be registered. The field will be mapped using the referenced item's Name field.
Note: If there are multiple CA Agile Central projects listed in the <Projects> element under <RallyConnection>, then the work items from the other system will be copied to CA Agile Central and placed in the first CA Agile Central project listed.
Mapping Boolean Fields To and From CA Agile Central
In CA Agile Central, some fields within a work item have boolean values. These fields can be mapped to Jira Radio Buttons or HP ALM Boolean fields. They can also be mapped to Jira Check Box fields, however, we do not recommend this as the Jira Check Box fields are multi-value fields. This field handler will map the fields in both directions.
- Within the <Connector> section of the configuration file, specify the field to be mapped in the <Fieldmapping> section.
- Also within the <Connector> section of the configuration file, create a <RallyFieldHandlers> section.
- Within this section, specify the field in a <RallyBooleanFieldHandler> element as <FieldName>the_name_of_the_Rally_field</FieldName>
- Specify the values to map in the <Mappings> section.
Whenever the connector runs, it will create a lockfile (in the working folder) named LOCK.tmp. This file will exist until the connector terminates, at which time the lockfile is deleted. The contents of the lockfile is one line of the form:
<PID> <DATE> <TIME> <TIMEZONE> <CONFIG-FILE-NAME> <DELAY-ARGUMENT>
1684 2012-06-20 16:24:00 Z MyConfig.xml -1
Each time the connector is invoked, it will check for the existence of a lock file in the working folder, and:
This prevents more than one instance of the connector being invoked from the same working folder.
Running as a Scheduled Task on Windows XP
When you are ready to deploy to production, you may want to consider running as a scheduled task. You can set up a scheduled task on Windows (this example assumes Quality Center).
Follow these steps:
- Create a batch file (such as the following example rallyWin7-qc.bat). Note in the following script there are two variables defined:
- Select Start, then select All Programs. Accessories, System Tools, Scheduled Tasks.
- In the Scheduled Tasks window, double-click Add Scheduled Task.
- In the Scheduled Task Wizard window, select Next.
- In the next window (where you are to select the program to run), select Browse... and find the batch file created above (such as rallyWInXP-qc.bat), select it (highlight) and select Open. Then:
- In the next window, give the task a name of your choosing (or use the default).
- Under Perform this task: selection, select Daily and select Next.
- In the next window (the heading is Select the time and day you want this task to start):
- In the Start time: box, select 12:00 AM.
- Select Every Day
- Select a Start date: (or use the default).
- Select Next
- In the next window, enter the username and password of the user the scheduled task should run as (this should be a valid user on the windows box), then select Next.
- In the next (and final) window (You have successfully scheduled the following task:), select the box Open advanced properties for this task when I click Finish, then select Finish.
- In the next window, verify the following:
- Under the Task tab, the Run: box should contain the correct path name to your BAT script created previously.
- The Start in: box should contain the correct path name to the folder where you wish this script to run.
- The box Run only if logged on should NOT be checked.
- Under the Schedule tab, select Advanced.
- In the next window, Advanced Schedule Options, check the box labeled Repeat task.
- In the Repeat task: section:
- In the Every: boxes, enter 15 and minutes.
- In the Until: box, select Time: and enter 11:59 PM.
- Select OK.
- Select OK again.
The above procedure configures the task to run every day (from 12:00am to 11:59pm) at an interval of every 15 minutes. If you review the list of Scheduled Tasks, under the Schedule column, you should see Every 15 minute(s) from 12:00 AM for 1439 minutes every day, starting MM/DD/YYYY and the Next Run Time column should show a time stamp in less than 15 minutes or so. If the list does not display an upcoming time stamp, please review the steps again or refer to the Microsoft documentation for information on setting up Windows scheduled tasks (for example, for WindowsXP or for Windows7).
Running as a Scheduled Task on Windows 7
The following is a real world example of setting up a scheduled task on Windows 7. This example was done for CA Agile Central's Quality Center connector.
Follow these steps:
- Create a simple batch file (such as the example startqc-simple.bat on the QC help page).
- Select Start, select All Programs, select Accessories, System Tools, Task Scheduler.
- In the Task Scheduler window, select Action, Create Task....
- The Create Task window opens into the first tab, "General":
- In the Name: box, enter "RallyQCconnector".
- In the Description box, enter "CA Agile Central's HP ALM/QC connector".
- Select the Run whether the user is logged in or not option.
- Mark the check box labeled Do not store password.
- NOTE: If using the TFS WorkItem Connector, then leave this box unchecked as the password should be stored to allow the connector to run unattended.
- Select the "Triggers" tab:
- Select New... (near bottom left) and a window called New Trigger opens.
- In the Begin the task: pull-down, select "At task creation/modification".
- Mark the check box labeled Repeat task every:, and select 15 minutes in the pull-down.
- Select Indefinitely in the pull-down labeled for a duration of:
- Check the Activate: box (the current date and time should already be present).
- Check the "Enabled" box (it's probably already checked).
- Select OK.
- Select the Actions tab:
- Select New... (near bottom left again) and a new window called New Action opens.
- In the box labeled "Action:", select "Start a program" (it's probably already selected).
- Under the box labeled "Program/script:", select "Browse..." and find your BAT file. Possibly located at: C:\Users\jpkole\MyQCfiles\startqc-simple.bat
- Under the box labeled "Start in (optional):", enter the folder name "C:\Users\jpkole\MyQCfiles".
- Select "OK".
- Under the Conditions tab, I left the defaults in place.
- Under the Settings tab, I left the defaults in place.
- Select OK at the bottom of the "Create Task" window.
- The task should run.
Email Notification of Errors and Warnings
The connectors can send email when errors or warnings occur in the logfile. With this feature enabled, the connectors can send a summary email for each configuration file used, and the subject line of the email will contain the name of the configuration file. To send email to multiple emails use a semi-colon to delimit each email address. All errors and warnings encountered during the connector run for that configuration file will be collected and reported in an email as follows:
- If the level is set to Error, then a summary email containing all the ERRORs is sent.
- If the level is set to Warning, then a summary email containing all the ERRORs and WARNINGs is sent.
NOTE: Only these two values for the <Level> tag are supported:
Here are two examples of the configuration file syntax required to enable this feature:
Standard SMTP server - No Authentication:
SMTP server - with TLS and Authentication:
Sample Configuration Files
Test the <Emailer> feature of CA Agile Central's JIRA (and others) connector. This will send a non-authenticated email to the designated user only when ERRORs or WARNINGs occur.
Test the <Emailer> feature of CA Agile Central's JIRA (and others) connector. This will send an email to the designated user only when ERRORs or WARNINGs occur.
Used to copy Discussions or Comments between CA Agile Central and JIRA.
A simple configuration file which will connect to JIRA and CA Agile Central, thus providing proof the client has:
- Ruby is installed and accessible;
- all Ruby gems are in place;
- there is connectivity to both systems;
- the config file syntax is correct;
- pathnames to files are correct;
Test the <RelatedObjectLinkers> feature of CA Agile Central's JIRA connector. This will copy a Bug from JIRA, which has attachments, to a Defect in CA Agile Central with attachments.
A configuration file used to copy CA Agile Central UserStories to JIRA Tasks.
A simple configuration file which will connect to JIRA5 and CA Agile Central, thus providing proof the client has:
- Ruby is installed and accessible;
- all Ruby gems are in place;
- there is connectivity to both systems;
- the config file syntax is correct;
- pathnames to files are correct;
A simple configuration to copy CA Agile Central Defects to JIRA5 bugs.
A configuration which can be used to copy Bugs from JIRA to Defects in CA Agile Central. When copy has completed, both the Bug in JIRA and the Defect in CA Agile Central will have a clickable link to the work item in the other system.
Test the <RallyAttachmentLinker /> feature of CA Agile Central's JIRA connector. This will copy a Story from JIRA, which has attachments, to a Story in CA Agile Central with the attachments, and vice versa.
Demonstrate coping CA Agile Central's "CreationDate" (a read-only field) to JIRA's "Due Date" (this is a one-way copy).
Used to copy and update CA Agile Central Tags with JIRA Labels, in both directions (with caveats).
Test the <Emailer> feature of CA Agile Central's QC (and others) connector. This will send a non-authenticated email to the designated user only when ERRORs or WARNINGs occur.
This configuration file will COPY (in one direction only) from Quality Center to CA Agile Central, in this fashion:
To connect to the Quality Center system and the CA Agile Central system, thus providing proof the client has:
connectivity to both systems;
the config file syntax is correct;
pathnames to files are correct;
To copy a QC Bug, which contains a custom field containing a CA Agile Central UserStory FormattedID, to a CA Agile Central Defect such that the "Requirement" Field on the new CA Agile Central Defect will contain a pointer to the CA Agile Central UserStory.
A simple QC connector configuration file which will copy Defects from CA Agile Central to Bugs in QC.
A simple QC connector configuration file which will copy Bugs from QC to Defects in CA Agile Central.
A configuration file used to copy QC Requirements to CA Agile Central User Stories.
A configuration file which will perform a one-time COPY (only) of CA Agile Central TestCases and Steps --to-- QC Tests and TestSteps.
NOTE: UPDATE is not supported.
A configuration file which will perform a one-time COPY (only) of QC Tests and TestSteps --to-- CA Agile Central TestCases and Steps.
NOTE: UPDATE is not supported.
This is two configuration files which will:
- Copy QC Tests to CA Agile Central TestCases
- Copy QC Runs to CA Agile Central TestCaseResults
Test a custom field handler which will be used by the QC connector to translate all occurrences of a given text string in "Description".
A custom field handler (named <RallyUsernameToQcUserFieldHandler>) used by the QC connector to map CA Agile Central's "SubmittedBy" and "Owner" fields on a Defect to QC's fields "BG_DETECTED_BY" and "BG_RESPONSIBLE" (respectively), when the only difference between the CA Agile Central's Username field and QC's User field is the at-sign (@) versus the underscore (_).
Used to copy CA Agile Central's "Test Cases" and "Steps" to QC, and to copy QC's "Tests" and "Design Steps" to CA Agile Central.
Used to copy QC requirements from a specific QC folder, and copy CA Agile Central UserStories into the same QC folder.
- QC-config-concat.pxml (contains 2 configuration files)
Used to demonstrate <OtherConcatFieldHandler> and <RallyConcatFieldHandler>
- QC-config-ReqTest-2-StoryTestcase.pxml (contains 2 configuration files)
These two configuration files will copy QC Requirements and QC Tests (under Test Plan in QC) in a way which will preserve the relationship between the QC Requirement and QC Test.
NOTE: This functionality works in the direction of QC to CA Agile Central only.
An example configuration file used to copy CA Agile Central Defects to/from QC Bugs, while mapping the CA Agile Central's Owner and SubmittedBy fields to QC's BG_RESPONSIBLE and BG_DETECTED_BY fields, using a CSV file to define the relationship between CA Agile Central Usernames and QC Usernames.
A minimal configuration file used to connect to both CA Agile Central and TFS, then exit (tested on TFS2010 & TFS2012)
A configuration file used to copy CA Agile Central UserStories to TFS Requirements.
A configuration file used to test the TFS2012 <CrosslinkUrlField> feature.
Used to copy CA Agile Central Stories and their associated tasks, to TFS2012 (maintaining the association in TFS2012. This example uses <TFSTreePathFieldHandler> and the two <RelatedObjectLinkers> elements called <TFSTaskToParentLinker/> and <RallyTaskToWorkProductLinker/>.
Finding XML Syntax Errors
The XML configuration files can get rather lengthy and cumbersome, hindering the hunt for syntax errors. For such issues, this web page can be used for XML validation: http://www.w3schools.com/xml/xml_validator.asp.
Copy your XML text and paste it into the window and click the "Validate" button.
Also note that syntax errors in the configuration file are typically logged in the rallylog.log file. For example:
- Special characters in the <WorkspaceName> or <Project> tags:
If these fields contain special characters, the characters must be escaped as in:
- "&" (ampersand) must be entered as "&",
- ">" (greater than) must be entered as ">",
- "<" (less than) must be entered as "<",
Example1: Note the following (invalid) configuration file snippet, and the logfile output:
<Project>JP & Nick Project</Project>
ERROR : Class.initialize - xmlParseEntityRef: no name
ERROR : ConnectorRunner.initialize - xmlParseEntityRef: no name
ERROR : Object.exception - Message xmlParseEntityRef: no name
ERROR : Object.exception - Stack Trace
Example2: Note that with a small change, the error report is different:
ERROR : Class.initialize - EntityRef: expecting ';'
ERROR : ConnectorRunner.initialize - EntityRef: expecting ';'
ERROR : Object.exception - Message EntityRef: expecting ';'
ERROR : Object.exception - Stack Trace
Known Limitations of the EIF Connectors
There are five 5 connectors built upon a common library called EIF (Extensible Interface Framework): Atlassian JIRA, IBM ClearQuest, HP Quality Center (ALM), and TFS. Below is a list of known limitations in these connectors.
- Using the Tag object in CA Agile Central
Only the following connectors support CA Agile Central Tags:
- JIRA (see example here)
- SSO not supported
The CA Agile Central WorkItem Connectors (and the CA Agile Central SCM connectors) are not compatible with the SSO feature; however, these connectors can be used in SSO Exception Mode.
- Some new fields on CA Agile Central work items are not available
In previous versions of the EIF connectors, the framework upon which the connectors were built, was tied to the CA Agile Central WSPAI version 1.42. Because of this, new fields in the most current version of the CA Agile Central WSAPI (v2.0 at the time of this writing) were not available in those older versions of the connectors. Some commonly desired "new" fields that are not available in the older versions of the connectors are:
- Connectors will not copy mapped fields which are empty.
When a mapped field is manually cleared by a user, this "clearing" will not be copied to the Other system by the connectors (for example, the field in the Other system will not be cleared). This was a design feature in the connectors and the reasons for it are varied. A possible work-around is to define a string value in each system which essentially represents "unset", and map those values together.
Generic Errors Generated by the EIF Connectors
- Control-C If control-C is hit while the connector is running, it is likely to generate the following error in the logfile:
ERROR : ConnectorRunner.initialize -
ERROR : Object.exception - Message
ERROR : Object.exception - Stack Trace
ERROR : Object.block in exception - /Users/..../yeti-2.8.8/lib/yeti/connector_runner.rb:170:in `sleep'
ERROR : Object.block in exception - /Users/..../yeti-2.8.8/lib/yeti/connector_runner.rb:170:in `run'
ERROR : Object.block in exception - ./rally2_<connector>_connector.rb:30:in `<main>'