CA Agile Central Add-in for Excel Installation & User Guide

Important: If you have an older version of the Excel plugin, you will need to uninstall the older version prior to installing the new version. We recommend you view the Installation instructions for additional information.

The CA Agile Central Add-in for Excel provides a quick and easy way to import or export data from your CA Agile Central subscription for tracking, reporting, or sharing:

  • Organize data in a pivot table or display data using Excel's built-in charting capabilities.
  • Export multiple CA Agile Central object types into multiple tabs and cross reference the data for more complex needs.
  • Import multiple CA Agile Central object types into CA Agile Central.
  • Use the add-in to export all work items from a project , then import new items to another project.
  • Create (not just update) new users as a bulk upload.

You can download the latest connector here: CA AgileCentralAddinForExcel_2.4.4.msi

Note: The add-in is capable of importing and exporting data. It cannot update the fields or statuses of existing work items. If you export an existing item, change a field , and then import, you will see a new copy of the existing work item. This also applies to user upload.

This installation and user guide includes:

Important: The add-in is not supported with the Mac version of Excel.

Install the Add-In

Before you install the add-in, be sure your system meets the following requirements.

Note: Microsoft frequently updates the download location for the latest version of Microsoft Visual Studio 2010 Tools for Office Runtime. If the link provided above does not direct you to the correct location, you can search for Runtime and download the latest version from the Microsoft website:
  • Windows Vista/7/8/10
  • Runs on 32 and 64-bit systems
  • Microsoft Office 2007, 2010, 2013
  • Microsoft .NET Framework 4.5 (download)
  • Microsoft Visual Studio 2010 Tools for Office Runtime (download)
Follow these steps:
  1. If you have an existing version of the add-in, uninstall it before installing a newer version.
  2. Download the add-in: CA AgileCentralAddinForExcel_2.4.4.msi
If the machine on which you are installing the add-in does not meet all the prerequisites, the installation will fail.

Sample Workbook

A sample workbook is included in the installer. You can access this sample workbook after you have installed the add-in. Note that this workbook is meant to serve as an example only and may not be importable to your CA Agile Central workspace .

  • For Windows 64-bit: the sample file is in %PROGRAMFILES(x86)%\Rally Software, Inc\Rally Add-in for Excel\Sample.xlsx
  • For Windows 32-bit: the sample file is in %PROGRAMFILES%\Rally Software, Inc\Rally Add-in for Excel\Sample.xlsx

Note: Credentials are not stored in the Excel file—they are stored in the CA Agile Central plugin configuration settings file.

Set up the Add-In in Excel

Once you install the Add-In, a new CA Agile Central tab displays in the Excel ribbon.

Most functionality will be disabled because no connection to CA Agile Central is available at this point of configuration.

Follow these steps:
  1. Open Microsoft Excel.
  2. Selecting the Connect to CA Agile Central icon in the Configuration area.
  3. Complete the fields on the CA Agile Central Connection Settings dialog and select Save.

Important: For On-Premises customers, you will need to select the Trust all SSL Certificates option and be working in your corporate network to connect to CA Agile Central from the Excel Add-in.


You can use single sign-on or a proxy with your Excel add-in.

SSO Authentication

Note: SSO is not currently supported for On-Premises users.
Note: There is a known issue with Excel version 2.1.2 (and higher) and SSO that we are working to resolve. Select here to learn more.

CA Agile Central follows the SAML specification for SSO authentication . This specification requires that a value called the RelayState be passed among the participants in an SSO authentication handshake. The RelayState specifies the final destination that the user wants to visit after being authenticated and is always a URL All SAML SSO providers allow the user to set this value. Usually this is done by appending an additional URL parameter to the normal SSO connection URL. Be aware that different SSO providers use different parameter names to set this value.

In order to successfully login using SSO and the Excel Add-in, you must be running a supported version of Internet Explorer. Check with your internal IT department to update to the latest version of IE.

Excel may show an expected identifier script error or un-supported browser message when attempting to login using SSO if you are using an unsupported version of IE. The Excel add-in uses a .NET 4.5 webform component to display the browser-interactive aspects of a successful SSO IdP/Rally login action. By default, .NET will always use the current version of IE installed on the user's computer when displaying a webform.

Important Notes:

In order to connect to CA Agile Central using SSO, you must provide an SSO URL that will set the SAML RelayState to the following URL value:


The normal SSO URL in CA Agile Central's internal environment looks like this:


A complete Excel SSO URL in the CA Agile Central's internal environment looks like this:


In CA Agile Central's internal environment we use a URL parameter named TargetResource to set the RelayState. In other environments that we have tested, the SAML RelayState is set using RelayState or Target. Your environment may use one of these parameter names or something completely different.

Contact your internal CA Agile Central administrator or CA Agile Central Success if you are having trouble constructing a URL that correctly sets the SAML RelayState.

Basic Authentication

The proxy settings are not required for most users. However, if your network traffic is routed through a proxy you will need to provide a valid proxy server address. If your proxy is authenticated, a username and password should also be specified.

Follow these steps:
  1. Enter your CA Agile Central server (default is, username and password.
  2. Select Save. Follow either the export or import instructions below to complete the process.

Export Data from CA Agile Central to Microsoft Excel

You can export data from CA Agile Central to Excel.

Note: Date and time fields are stored in UTC format and exported in UTC format.
Important: The only way to specify subfields is to type manually. Adding subfields manually and then selecting items from the chooser erases manually entered subfields. Use caution when switching back and forth between manual entry and the column chooser. AND/OR statements must be added manually to the Filter field.
Follow these steps:
  1. Open Microsoft Excel.
  2. Select the Export option in Excel.

  3. Define the Workspace and Project that you want to export. Otherwise, the default workspace and project will be used for the export process.
  4. Select the Manage Queries button to launch the Queries dialog.
  5. Select New to create a new query.

  6. Specify the type of CA Agile Central object to export and choose a sort order for the data.
  7. Select the Choose button to select fields to export to Excel.

    The fields to export are specified as a comma-separated list in the Columns text box.

    You can also enter sub-object fields in the text box. For example, you could add Release .ReleaseStartDate or Parent.Project.Name to the comma-separated list of fields as well. Leaving Columns empty or specifying True will cause all fields to be returned.
  8. Optionally, specify a filter to be applied to the query. The filter syntax is that used by the CA Agile Central WSAPI and is documented here, for example: (ScheduleState = Accepted).
    The Choose button launches a Filter dialog to make it easy to select a basic filter:
    {user} is a special macro that will automatically be replaced with your user ref when the query is run.
    Subfields can be used in query clauses: (Release.Name contains "2011 Q2")
    More than one query clause can be combined using ANDs or ORs: ((ScheduleState = Accepted) AND (Release.Name Contains "2011 Q2"))
    Note: When using a query that looks for user stories and displays the parent of the story, you can use the value of the portfolio item in the column field to view portfolio item parent information.

    Once you have defined one or more queries, you are ready to export CA Agile Central data.
  9. Select a worksheet and then select a query from the Query drop-down.

  10. Select Run Selected Query to populate the current worksheet with data.
    Note: You can set the query row limit, up to a value of 2,147,483,647. The default value is 200 rows.

You can embed queries in worksheets when you save a workbook. The Refresh All Queries button runs all queries embedded in a saved workbook. Any pivot charts or tables based on the data are automatically refreshed.

Export Test Case Steps

Important: To ensure that test case steps are exported correctly, verify the following:

  • Test case Input and Expected Result fields are populated for the test cases you want to export.
  • Ensure that test case steps are not just listed in the Validation Input and Validation Expected Result fields. These fields export from the Add-In using the Test Case type.

Select here to learn more about using Excel for test cases and test case steps.

Import Data from Excel to CA Agile Central

You can import defects, iterations, portfolio items (features, initiatives , and themes), releases, tasks, test cases, test case results and steps, test folders, test sets, users, and user stories.

Note: All columns in an importable spreadsheet must map to a valid attribute . If there are extra columns created by an export, remove those columns before importing.

The Import to CA Agile Central feature displays a list of importable artifact types available for your CA Agile Central workspace. Imported text fields with XML are undefined in CA Agile Central unless you follow the technique described below.

Important: If you import a text field with XML and want the XML displayed as text in CA Agile Central (such as documentation with notes), you will need to add div tags as defined below:

<tag> text </tag>

Should be written as:

<div><tag> text </tag></div>

CA Agile Central has tested and successfully imported 500,000 rows of data. The number of rows you can import may be dependent upon your version of Excel (2007 or 2010). When upgrading to a new version of Excel, the old version needs to be uninstalled and the new version installed. This process will delete log files, but configuration files will remain. Connection information and queries will be available after upgrading to a new version of Excel.

  1. After connecting to CA Agile Central in Excel, select Import to CA Agile Central in the Excel ribbon.
  2. On the Choose Import window, select the workspace in CA Agile Central that you wish to import artifact types, then select the type of artifact that you want to import to your designated workspace. The last workspace and artifact type used during the session are selected by default.
    Note: If there are duplicate names for the parent, associated requirement, or test case, select the Project scope all lookups checkbox to associate the work item to the parent in the same project. If you have multiple work items with the same name in different projects, selecting this checkbox prevents you from having to enter a FormattedID or OID to identify which item you want to associate to when there are duplicate named work items.
  3. Select Schema to view the schema for the chosen artifact type.
    The schema lists details about the importable values of the chosen artifact type. For example, the defect schema lists all valid fields in a defect. The schema is a subset of all article types available in the system with associated types in CA Agile Central.

    Field schema columns can be modified as needed. For example, you might want to have the Required field located to the left of all columns so you can see at a glance the required field for the schema. Drag and drop column headers as needed.
    You can save the schema as a PDF for reference by selecting Save PDF.

Important notes regarding schemas:

  • There are three ways to specify an object reference: Name (not all object types have this), OID, and Formatted ID (not all object types have this).
  • Acceptable boolean values include Yes/No, True/False, or 1/0.
  • For date fields, the date must be specified in the date format designated on your computer.
  • The Exists column denotes whether the artifact type value occurs in the current version of the spreadsheet.
  • For the Release Artifact Type, ensure that the spreadsheet is valid prior to importing as releases are not deletable from the undo feature in the CA Agile Central Excel Add-in and must be deleted manually in CA Agile Central.
  • The following values are not supported in the current Excel Add-in: Collections, Attachments, Links, and Read-Only.
  • When downloading the schema for any artifact type where the artifact type includes the Owner value, the valid value listed in the schema is the Owner display value and not the Owner Login Username.

For an import to succeed, the spreadsheet needs to contain a column for all required fields. Columns for all other fields are optional.

Note: When importing user stories, if the Rank Method on the destination workspace is set to drag-and-drop , the Rank attribute is ignored. Imported stories are ranked in reverse order of their order in the source spreadsheet. For example, the last story in the spreadsheet ends up with the highest ranking.

Artifact Value Field Validation

Validate that the spreadsheet is ready for import by selecting Validate. This option reads the data from the spreadsheet, ensures that it is valid based on the constraints listed in the schema, and searches any OBJECT references specified as names or formatted IDs. If a validation error occurs, a pop-up window will provide you with information regarding the nature of the error and the column or row where the error occurred in the spreadsheet. You can save the file as PDF.

Select the Import button to pass artifact data to CA Agile Central. During the import you will have the capability to pause and resume the import process as needed. The import progress window also details the elapsed time, items remaining, average elapsed time, estimated total time, estimated remaining time, and estimated completion time.

The Import feature also allows you to undo a successful import if needed for any reason, with the exception of releases. Releases must be manually deleted in CA Agile Central.

In the example below, is a spreadsheet of user stories that needs to be imported to CA Agile Central. We reviewed the schema for the User Story artifact type and validated. Then, we selected Import for the User Story artifact type.

After importing, there is a pop-up window confirmation that our user stories have been imported.

Upon checking the workspace in CA Agile Central, the new user stories have been successfully added.

Import Users

Administrators can import multiple users with the Excel Add-in.

Note: If a network issue occurs during the import process, it is possible that a user may be partially provisioned. If this occurs, the import screen will display the number of successful and unsuccessful imported users to aid in troubleshooting. If you decide to undo or remove all users after a network issue, this action will remove all successfully imported users except for any partially created users. The undo screen will list the number of successfully and unsuccessfully removed users to assist in troubleshooting any remaining users that have not been removed.

To import users, select the User type. Workspace is grayed out as it cannot be selected when importing users.

User Import Type

You can view the schema for the user attribute. The schema defines valid values for each importable field.

User Schema

Important: Custom drop-down fields, including Cost Center, Department, and Office Location, must be defined in CA Agile Central to import the values from Excel. The number of custom fields is limited to five.

Important notes:

2000 Users Validation Error

Select Import to import users into CA Agile Central. When the import is complete, a pop-up displays import and undo statistics. For example, the number of successful imports and undos, number of unsuccessful imports and undos, users imported, users undone, time of import, and undone duration.

Troubleshooting and Log Files

If you receive this error Value cannot be null. Parameter name: obj in Excel upon export, it means that there was no active spreadsheet for the Excel Add-in to write to. There must be an active spreadsheet for the add-in to work properly.

System Event Logging

Errors for both importing and exporting are always logged. More detailed logging is enabled when the Log Details option is selected. Logs can be viewed as soon as a transaction occurs. Double-click on any entry in the log field to view additional details for any transaction that has been performed. The plugin issues several different kinds of requests to the CA Agile Central server (gets, puts, and so on) and communicates with the CA Agile Central server in many different ways during each operation.

Select an individual log to display the entire log entry in a Log Message pop-up.

You can delete all generated request logs from the system for the CA Agile Central Excel Add-in. select the Purge and Close button and all logs will be deleted from the Log Viewer and also from the RallyAddInForExcelLog in the Windows System Events logs. Once the logs have been purged, the dialogue window closes automatically.

You can save logs to a file if you need to send logs to CA Agile Central for troubleshooting.

Important: In order to purge log files, you must be running the Excel add-in as an administrator. Right-click the Excel app and select Run as administrator.

International Usage

Some countries use a comma (,) in lieu of a period (.) to represent nominal values.

There have been issues with European customers using the Excel Add-in (and import templates) with respect to the decimal point separator and the list separator in Windows 7 Ultimate in combination with MS Excel 2007 or 2010.

Workaround: Changing the list separator in Windows into a comma does not work if the decimal point separator in Excel is also set to comma. European users will need to change to US number settings: Decimal (. Iso ,) and thousands separator: , iso .) This allows you to change the list separator in windows (from ; to ,).

After these changes are in place to import, the templates and Excel should work as expected.

Sample Files

The sample files below can be used to import users, user stories, releases, or portfolio item features into a default CA Agile Central instance scoped to Workspace → Sample Project. Each file contains the required columns and fields for the specified CA Agile Central artifact.

Uninstall the Add-In

You should uninstall the add-in if you no longer need it or before you install an updated version.

Verify the Current Version

If you have previously installed the CA Agile Central Add-in for Excel, you can determine the current version installed.

Follow these steps:
  1. In Windows, go to Start, Control Panel, Programs and Features, CA Agile Central Add-in for Excel. Note that the path location may be slightly different based on your version of Windows but can be located in the Control Panel.

Note: If you have an older version of the CA Agile Central Add-in for Excel and want to update to the latest version, you will need to uninstall the current version before installing the latest version. When uninstalling and upgrading to a newer version, not all files are deleted. The following file remains after an uninstall:

  • Windows XP: %USERPROFILE%\Application Data\Rally\ExcelAddIn\rallyExcel.xml
  • Windows Vista, 7, 8, and 10: %USERPROFILE%\AppData\Roaming\Rally\ExcelAddIn\rallyExcel.xml

This file is used to store the previous Excel add-In configurations. This file is created when the add-in connects to CA Agile Central. After updating to a newer version, this file will remain in the system, and it will contain the previous configuration. When Excel is then started, the old configuration will be loaded and displayed in the CA Agile Central login screen after selecting the CA Agile Central Connect button. Solution: Rename this file before updating (it may contain saved queries you want to re-use).

Uninstall the Add-In

You need to disable and then uninstall the add-in.

Follow these steps:
  1. Disable the add-in in Excel from the File, Options, Addins dialog.
  2. To completely uninstall the add-in, remove it from the Add/Remove Programs or Programs and Features portion of the Control Panel.

Revision History

  • 2.4.4 - May-2018
    • Enhancements:
      • TLS 1.2 support
      • Additional security fixes
  • 2.4.3 - Apr-2016
    • Enhancements:
      • New and improved error message states that Excel user must run the add-in as an administrator in order to purge log files.
  • 2.4.2 - Mar-2016
    • Enhancements:
      • Updated to correct workspace scoping for querying Portfolio Items when switching workspaces.
  • - Nov-2015
    • Enhancements:
      • Brand redesign.
  • 2.3.3 - Mar-2015
    • Fixes:
      • Unable to specify Project when creating Releases and Iterations.
      • Unable to import Users.
      • HtmlAgilityPack error.
  • 2.3.2 - Mar-2015
    • Enhancements:
      • Updated the add-in with the new Rally logo.
  • - Nov-2014
    • Fixes:
      • When trying to connect to Rally using SSO, the following error was received: Error connecting to Rally: Could not load file or assembly 'HtmlAgilityPack, Version=, Culture=neutral, PublicKeyToken=bd319b19eaf3b43a' or one of its dependencies. The system cannot find the file specified.
  • 2.3 - Oct-2014
    • Enhancements:
      • On the Import dialog, the last workspace and artifact type used during the session are selected by default
      • You can save logs to a file in case you need to send logs to Rally for troubleshooting
    • Fixes:
      • Badly formatted Rich Text Fields (such as Description and Notes) when exported to Excel
      • Failure importing artifacts with special characters in the Project or Name fields
      • Importing stories with numeric names that contained dots (for example, 2014.09) failed
  • 2.2.1 - Jul-2014
    • Fixes:
      • Fixed a problem with the formatting of rich text fields when exporting to Excel.
  • 2.2 - Jul-2014
    • Enhancements/Fixes:
      • Import/Export Mode removed from the Excel ribbon.
      • Added Favorites and Recent Queries drop-down menus to the ribbon.
      • Added drag-and-drop order and select functionality for the Columns selector.
    • Known Issues/Limitations:
      • If downgrading from 2.2 version to the 2.1.2 version, be aware that some queries may not work and may need to be deleted.
  • 2.1.2 - Apr-2014 
    • Enhancements/Fixes:
      • Support new Project Admin privilege when importing a User
      • Users can be imported without defining any privileges
      • Plugin tested successfully on Excel 2013
      • Project scoping for duplicate parents, associated requirements or test cases
      • Time zone allowed values now correct
      • Properly handles queries containing special characters such as "&"
      • Will create a new spreadsheet if necessary during export
      • Properly handles saving schemas to .pdf
      • Able to strip xml/html from exported text fields
      • Fixed user import bug
    • Known Issues/Limitations:
      • If you are using SSO for logging into Rally with the Excel plugin please note: After an upgrade of our internal Single-Sign-On server, we discovered an issue with HTML Form submission through Javascript embedded into Identity Provider (IDP) login pages. IDP login pages containing Javascript must be compatible with Internet Explorer 7 Javascript usage for the Rally Excel plugin to work with SSO.
  • 2.1.1 - Jan-2014
    • Enhancements/Fixes:
      • Supports 1,000+ projects and workspaces
  • 2.1.0 - Dec-2013
    • Enhancements/Fixes:
      • Users can now use Single sign-on (SSO) for Excel
      • Users can now be specified by username or OID
      • Supports the latest 1.43 version of Web Services API
  • 2.0.0 - Aug-2013
    • Enhancements/Fixes:
      • Bulk upload of new users, but it does not allow update on existing users.
      • Removed 10,000 row query limit.
      • Validation error files can now be saved as a PDF.
      • Supports the latest 1.42 Web Services API (1.30, 1.37).
    • Known issues/limitations:
      • When importing a large number of objects, the duration of the import is directly correlated with the number of objects to import. The more objects to import, the longer the duration of the import process.
      • The validation step does not correctly identify duplicate users that are listed in a different subscription than the subscription the user running the connector is listed in. However, duplicate users are listed at the end of the import process.
      • If a massive network failure interrupts the Import Users process, you may need to manually remove a partially provisioned user. The final import screen displays any unsuccessfully imported users to aid in troubleshooting partially created users. If you choose to remove all users using the undo option, the final screen will display users that have not been successfully removed. Other helpful statistics on this screen include number of successful imports/undos, number of unsuccessful imports/undos, users imported, users undone, time of import, undone duration and more.
  • 1.11 - Jan-2013
    • Enhancements/Fixes:
      • Fixed issue with ribbon tab label not showing when there is no configuration file.
  • 1.10 - Dec-2012
    • Enhancements/Fixes:
      • Updated to support importing from Excel.
    • Known issues/limitations:
      • When uninstalling then upgrading to a newer version, not all files are deleted. The following file remains after an uninstall:
        Windows XP: %USERPROFILE%\Application Data\Rally\ExcelAddIn\rallyExcel.xml
        Windows Vista & 7 %USERPROFILE%\AppData\Rally\ExcelAddIn\rallyExcel.xml
        This file is used to store the previous Excel add-In configurations. This file is created when the add-in connects to Rally. After updating to a newer version (for example, uninstall, reinstall), this file will remain on the system, and it will contain the previous configuration. When Excel is then started, the old configuration will be loaded and displayed in the Rally login screen after selecting the Rally Connect button. Solution: Rename this file before updating (it may contain saved queries you want to re-use).
  • 1.09 - Aug-2012
    • Enhancements/Fixes:
      • Updated to work with Excel 2007 as well as Excel 2010.
      • Supports UTF-8 character set.
      • No longer requires installation of PIAs.
      • Includes ObjectID in query sorts if not already present in order to mitigate an issue (DE14047 - when a query uses an Order by value that is not a unique value, the data returned could have duplicates and/or missing records).
    • Known issues/limitations:
      • none
  • 1.08 - Jan-2011
    • Enhancements/Fixes:
      • Fixed missing data issue when refreshing a previously run query
    • Known issues/limitations:
      • none


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.