Add New

Deprecation Warning! The content below is only applicable for use within deprecated 1.x versions of CA Agile Central's App SDK. Use of the component(s) and/or code on this page is not supported. To develop custom apps within our current environments, please see App SDK 2.1 documentation.

Add New includes the following topics:

The Add New component provides a way to create new items. It initially displays the + Add New button, and when clicked it expands with more options for creating items. Currently, only HierarchicalRequirement, Defect , DefectSuite, TestCase, Iteration , and Release types can be passed through the configuration. If only one item type is provided in the configuration, it will display without a type drop-down.

add new

To directly add a new item (for types that that only require a name), select the type, enter the name, and click Add.

To add a new item using the editor window, click + Add New, select the type, and then Add with Details.

Create an Add New

First include the App SDK javascript :

<script type=text/javascript" src=/apps/[version]/sdk.js"></script>

Instantiate a new Add New:

var addNew = new rally.sdk.ui.AddNewArtifact(config, rallyDataSource);

The parameters for rally.sdk.ui.AddNewArtifact are as follows:

Parameter Description Example
config* An add new configuration object
{ types: ["HierarchicalRequirement",
"Defect","DefectSuite"] }
rallyDataSource* An instance of


* = required parameter

The Add New configuration object supports the following properties:

Parameter Description Example
types* An array of Rally artifact types (defaults to ["HierarchicalRequirement", "Defect"] if not provided).

* = required parameter

Display an Add New

After you create an add new, use the display method to show the add new:

addNew.display(domElement, callback);
Parameter Description Example
domElement* The element in which to display the add new; may be either an element or an element ID
document. getElementById("addNewDiv")
callback An optional function that will be called after the component displays itself
function(addNew, eventArgs){ console.log (eventArgs.selectedItem);

* = required parameter


The Add New component defines the following methods:

Method Name Parameters Description Example
display domElement*, callback Displays the add new; the callback function is called after the add new component displays itself
"addNew.display(domElement, function(){ // after display callback }); 
destroy - Removes this component
getValidEvents - Returns a map of events this component supports

* = required parameter


Events are used to notify consumers of a component when actions occur.

The following methods are provided in order to interact with this component's events:

Method Parameters Description Example
addEventListener eventName*, listener*, scope

Registers the specified listener with the component's queue for the specified event and returns an object which can be used to remove the event listener later. The listener parameter should be a function with two parameters:

1) the component that fired the event;

2) an eventArgs object with properties specific to the event being fired. This function will be called by the component when the event occurs.

If the optional scope parameter was specified the function will be called on that object (such as scope.listener(sender, args);).

function listener(sender, eventArgs) {

//Respond to event


var eventObj = component.addEventListener (eventName, listener);


removeEventListener eventObj* Unregisters the specified event from the component.

The eventObj parameter should be the return value of addEventListener() when the listener was originally registered.

var eventObj = component.addEventListener (...); component.removeEventListener (eventObj);
getValidEvents -- Returns an object with a property for each event name supported by the component. This is useful for passing as the first parameter to addEventListener().
var eventName = component.getValidEvents ().onClick;

* = required parameter

The Add New component supports the following events:

Event Name Description Event Arguments Example
onAdd Fired when Add is selected and results in item creation

The eventArgs object contains a single property:

Item: the item the user created directly.

function onAddNewAdd(addNew, eventArgs) {
var createdItem = eventArgs.item; } addNew.addEventListener("onAdd",onAddNewAdd);
onAddWithDetails Fired when Add with Details is clicked and editor window is opened No args passed to the function.
function onAddNewAddWithDetails(addNew){
//addNew add with details button clicked



("onAddWithDetails", onAddNewAddWithDetails);


onCollapse Fired when Close button is clicked and the display is collapsed No args passed to the function.
function onAddNewCollapse(addNew) { //addNew display collapsed

} addNew.addEventListener("onCollapse", onAddNewCollapse);


onError Fired when the component warns about a known error

The eventArgs object contains a single property:

Message: the message the user receives for known error.

function onAddNewError(addNew, eventArgs) {

var message = eventArgs.message;


addNew.addEventListener("onError", onAddNewError);


onExpand Fired when + Add New is clicked and the display is expanded No args passed to the function.
function onAddNewExpand(addNew) { //addNew display expanded


addNew.addEventListener("onExpand", onAddNewExpand);


onPreCreate Fired before the item is created when Add button is selected or the editor window is opened

The eventArgs object passed to any event listeners contains the following properties:

  • Item: The object fields to be created.
  • withDetails: Boolean stating the Add With Details button was selected if true, otherwise the Add button was selected.
function onAddNewPreCreate(addNew, eventArgs)


eventArgs.item["field1"] = "value1";

} addNew.addEventListener ("onPreCreate", onAddNewPreCreate);



Copy and paste the following into a Rally custom app.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<!-- Copyright (c) 2011 Rally Software Development Corp. All rights reserved -->
    <title>Component Example: Add New</title>
    <meta name="Name" content="Component Example: Add New" />
    <meta name="Version" content="2011.2" />
    <meta name="Vendor" content="Rally Software" />
    <script type="text/javascript" src="/apps/1.26/sdk.js"></script>
    <script type="text/javascript">

       function reloadPage(){

       function onLoad() {

           var rallyDataSource = new'__WORKSPACE_OID__',

           var addNewConfig = {
             types : ["HierarchicalRequirement","Defect","DefectSuite"]

           var addNew = new rally.sdk.ui.AddNewArtifact(addNewConfig, rallyDataSource);

           addNew.addEventListener('onAdd', reloadPage);



<div id="addNewDiv"></div>


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.