Agile Central: Excel Add-In - version: 2.4.4 and lower

Products

Rally On-Premise Rally SaaS

Issue/Introduction

This is a known issue with CA Agile Central Excel Add-in version 2.4.4 and lower. This will not be fixed in this version although it is planed to be included in future versions.

This is only a limitation of the Excel Add-In, not for Agile Central's user interface or service.

This version of Excel Add-In has a limitation whereas it will have problems if any of your portfolio hierarchy names matches a name of an existing REST Endpoint. Your portfolio hierarchy names are defined in a field called: Portfolio Item Type on your workspace or project. When creating your portfolio hierarchy you will edit this field, and add your portfolio item type values and their hierarchical order.

Below is an example of the problem. The hierarchy used in this example is:
Business Initiative > Investment > Epic > Feature

In this example we will import Features, then Epics, then Investments. Note the checkbox indicating: "Project scope all lookups of Portfolio Item <TYPE> references?" (where <TYPE> points to the upper level of the level that's being imported).

- You can see that when importing Features then this checkbox refers to Epics (one level above Features) and the import works.
- You can see that when importing Investments then this checkbox refers to Business Initiatives (one level above Investments) and the import works.
- However, notice that when importing Epics then this checkbox is missing. Also, importing Epics will not work!

Further clicking the Validate button on Epics will also fail;

Environment

Release:
Component: ACSAAS

Cause

This problem occurs because the word: "Investment" as used in the hierarchy in this example is a word that's already used as a REST Endpoint for CA Agile Central.
This out-of-the-box Agile-Central-internal object also has a REST Endpoint called: "Investment".

The problem stems from the fact that when defining the portfolio hierarchy then Agile Central generates REST Endpoints for each of your portfolio item types under /PortfolioItem. In the above example there will be new endpoints as follows:
/PortfolioItem/Business Initiative
/PortfolioItem/Investment
/PortfolioItem/Epic
/PortfolioItem/Feature

The Excel Add-In is using WSAPI to contact the REST Endpoints when importing your spreadsheet. When importing a portfolio item type the Excel Add-In will find it in the hierarchy, then look for his parent type and display the checkbox previously mentioned for scoping the references. The problem is that the Add-In looks for the parent type not only within the scope of /PortfolioItem but in the entire scope of Agile Central's REST Endpoint. Therefore, when looking for Epic's parent it will look for Investment and it will find two REST Endpoints for Investment: The out of the box one as well as the custom portfolio type. Conflicted how to join the hierarchy levels (in this case which of these Investment REST Endpoints to link the Epic with) the Add-In will fail the validation as well as the import.

Resolution

There is no workaround to this issue at this time. It is a current limitation of the Excel Add-In.

1. You can not modify the name of a type if your hierarchy is already populated.
In that page it says: "You can modify the name and ID prefix of a type, but not the order in the hierarchy".

When changing a portfolio item type's name then Agile Central will replace its REST Endpoint under /PortfolioItem with another. If a change is made to a Portfolio Item Type, edited "Investment" and changed it to "BusinessInvestment" then the /PortfolioItem/Investment endpoint will be replaced with /PortfolioItem/BusinessInvestment.

Existing objects of "Investment" will be lost. They will not show up in Agile Central as well as not be found by WSAPI. The objects are already under /PortfolioItem/Investment and once replaced they will no longer be accessible.

If you have no previously created objects of that type (Investment) then the conflict can be avoided by not creating a type of Investment.

2. The best way to avoid this issue is to NOT use names in your Portfolio Hierarchy that match any existing REST Endpoint, in this example: not to use the 'Investment' string/name. There are two issues around that:

a. If you already have objects created under that name (see #1 above).

b. Agile Central adds new objects along with their matching REST Endpoint names. Even if you choose hierarchy names that are safe, you must consider that these names will be 'taken' later. So, for example, if you created your hierarchy with the word "Investment" even before Agile Central had its own object then you would be okay until Agile Central introduced its own object. Once introduced, the conflict will happen.

Therefore, the best way for you to secure your portfolio item types is to prefix them by "PortfolioItem" or another prefix, i.e: Instead of "Investment" , use: "PortfolioItemInvestment" , instead of 'Epic' use: "PortfolioItemEpic" and so forth. The implication of that though is that these will now be your real names of your types, they will be displayed in all screens and reports.

3. If you are in a situation where you already have portfolio items, also linked with User Stories and other artifacts and such a conflict arises then you may want to manually create your additional portfolio items and not use the Excel Add-In. The only other alternative will be to export your data, then renaming your conflicting portfolio item type, then importing it under the new name, then proceeding with your original import. However, this may be risky, especially if there is a large amount of data.

Should there be doubt about any on this a support case should be opened.

Appendix
To know all of CA Agile Central's REST endopints, you can refer to: https://rally1.rallydev.com/slm/doc/webservice/
Under the "Object Model" section you will see the list of all REST Endpoints of the given workspace you're examining.

This page is specific to a workspace which is highlighted at the top-left corner. To change the workspace, log into Agile Central, then change to the workspace you are exploring, then click that link.