Rally Data Source

Print this topicEmail this topicSave as PDF

The Rally Data Source component provides an intuitive interface to your Rally Data.
It supports querying for batches of items in addition to individual item creates, updates, and reads.

Creating a Rally Data Source

First include the App SDK javascript:

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

Instantiate a new RallyDataSource:

var rallyDataSource = new rally.sdk.data.RallyDataSource("__WORKSPACE_OID__",
                 "__PROJECT_OID__",
                 "__PROJECT_SCOPING_UP__",
                 "__PROJECT_SCOPING_DOWN__");

The parameters for rally.sdk.data.RallyDataSource are as follows:

Parameter Description Example(s)
workspace The workspace context for all query operations.
(Default is profile/session default). 		Hangman variable: "__WORKSPACE_OID__"

Workspace OID:

"1234567"
project The project context for all query operations.
(Default is profile/session default). 		Hangman variable: "__PROJECT_OID__"

Project OID:

"1234567"
scopingUp The scopingUp context for all query operations.
(Default is profile/session default). 		Hangman variable: "__PROJECT_SCOPING_UP__"

Specific value:

false
scopingDown The scopingDown context for all query operations.
(Default is profile/session default). 		Hangman variable: "__PROJECT_SCOPING_DOWN__"

Specific value:

true
* = required parameter

Hangman variables are automatically given values based on the currently logged in user and their selected workspace, project, project scope up ('Show Parent Projects') and project scope down ('Show Children Projects') settings. If running outside Rally, see the Running an App Outside Rally section for more information as these hangman variables are not available in that context.

Public Methods
Method Name Parameters Description Example
find queryObj*, callback*, errorCallback Search Rally for items matching the specified query. Only the first page of results will be returned. function onComplete(results) {
   for(var i = 0; i < results.mydefects.length; i++) {
     var mydefect = results.mydefects[i];
  }
}

function onError(response){
   // An array of errors returned from Rally.
   var errors = response.Errors;
   // An array of warnings returned from Rally.
   var warnings = response.Warnings;
}

rallyDataSource.find({
     key: "mydefects",
     type: "defect",
     query: '(Name = "My Defect")',
     fetch: true,
     pagesize:10
     }, onComplete, onError);
findAll queryObj*, callback*, errorCallback Search Rally for items matching the specified query. All results will be returned.
function onComplete(results) {
   for(var i = 0; i < results.mydefects.length; i++) {
     var mydefect = results.mydefects[i];
   }
}

function onError(response){
  // An array of errors returned from Rally.
   var errors = response.Errors;
   // An array of warnings returned from Rally.
   var warnings = response.Warnings;
}

rallyDataSource.findAll({
     key: "mydefects",
     type: "defect",
     query: '(Name = "My Defect")',
     fetch: true
     }, onComplete, onError);
getAttributesByType typeName*, callback*, errorCallback Returns an array of attribute definition objects for the specified type. Note: typeName should be the Name of the type- not the ElementName.
Example: "Hierarchical Requirement" instead of "hierarchicalrequirement". 		function onSuccess(attributes) {
     //Process attributes
}
var attributes =
rallyDataSource.getAttributesByType("Defect", onSuccess);
getRallyObject ref*, callback*, errorCallback Retrieve the Rally object represented by the specified ref.
Upon successful completion the specified callback will be invoked with the retrieved object.
If an error is encountered the errorCallback will be called instead. 		function onComplete(obj) {
   var defectName = obj.Name;
}
function onError(response){
   // An array of errors returned from Rally.
  var errors = response.Errors;
   // An array of warnings returned from Rally.
  var warnings = response.Warnings;
}
rallyDataSource.getRallyObject(
"https://rally1.rallydev.com/slm/webservice/1.26/defect/12345", onComplete,onError);
create type*, object*, callback*, errorCallback, queryParams Create an object of the specified type with the specified data in Rally.
Upon successful completion the specified callback is invoked.
If an error is encountered the errorCallback will be called instead.
queryParams is an optional object of key value pairs that will be included in the request: {fetch: "FormattedID"} 		function onCreateComplete(object, warnings) {
  //The object created
   var createdObject = object;
  //An array of warnings that were returned from Rally
   var myWarnings = warnings;
}
function onError(response){
  // An array of errors returned from Rally.
  var errors = response.Errors;
  // An array of warnings returned from Rally.
  var warnings = response.Warnings;
}
rallyDataSource.create("defect", {"Name": "My Defect"}, onCreateComplete,onError);
update object*, callback*, errorCallback, queryParams Update the specified object in Rally.
Upon successful completion the specified callback is invoked.
If an error is encountered the errorCallback will be called instead.
queryParams is an optional object of key value pairs that will be included in the request: {fetch: "FormattedID"} 		function onUpdateComplete(object, warnings) {
  //The updated object
  var updatedObject = object;
  //An array of warnings that were returned from Rally
  var myWarnings = warnings;
}
function onError(response){
  // An array of errors returned from Rally.
  var errors = response.Errors;
  // An array of warnings returned from Rally.
  var warnings = response.Warnings;
}
rallyDataSource.update({"_ref":
"https://rally1.rallydev.com/slm/webservice/1.26/defect/12345.js",
"Name": "My Updated Defect"}, onUpdateComplete,onError);
* = required parameter

For more detailed information see Querying Rally Data and Processing Query Results.

Example

Copy and paste the following into a Rally Custom App Tab to see it in action!

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- Copyright (c) 2010 Rally Software Development Corp. All rights reserved -->
<html>
<head>
  <title>Rally Data Source Example</title>
  <meta name="Name" content="App Example: RallyDataSource"/>
  <meta name="Version" content="2010.4"/>
  <meta name="Vendor" content="Rally Software"/>
  <script type="text/javascript" src="/apps/1.26/sdk.js?debug=true"></script>
   <script type="text/javascript">
    rally.addOnLoad(function() {

      var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__',
                                                    '__PROJECT_OID__',
                                                    '__PROJECT_SCOPING_UP__',
                                                    '__PROJECT_SCOPING_DOWN__');

      var itemRef;

       //Create an item
      function createItem() {
        function onCreateComplete(object, warnings) {
           itemRef = object._ref;
           updateItem();
         }

        rallyDataSource.create("defect", {Name: "My Defect"}, onCreateComplete);
      }

      //Update an item
      function updateItem() {
         function onUpdateComplete(object, warnings) {
           getItem();
         }

         rallyDataSource.update({"_ref":itemRef, Description:"This is my defect"}, onUpdateComplete);
      }

      //Get an item
      function getItem() {
        function onGetComplete(item) {
          var itemName = item.Name;
          var itemDescription = item.Description;
          findItems();
        }

         rallyDataSource.getRallyObject(itemRef, onGetComplete);
      }

      //Find some items
       function findItems() {
        function onFindComplete(results) {
          var defects = results["mydefects"];
          for(var i = 0; i < defects.length; i++) {
            var defectName = defects[i].Name;
           }
        }

        rallyDataSource.findAll({
          key: "mydefects",
          type: "defect",
          query: '(Name = "My Defect")',
          fetch: true
         }, onFindComplete);
      }

      //Start the chain of operations
      createItem();
    });
   </script>
</head>
<body>
</body>
</html>

Querying Rally data

The find and findAll methods in RallyDataSource are based on the batch query API and allow a user to make multiple web services queries without multiple requests. Both methods expect a Javascript object or an array of Javascript objects to define the query criteria. For example, these are simple examples for findAll:

For a single query:

var queryConf = { type: 'defect',
         key : 'defects'
       };

findAll(queryConf, dataRetrievedCallback)

For an array of queries:

var queryArray = [];
queryArray[0] = { type: 'defect',
         key : 'defects'
       };

queryArray[1] = { type: 'hierarchicalrequirement',
         key : 'stories'
       };

findAll(queryArray, dataRetrievedCallback)

Use find to return only the first page (defaults to 200 items) of results. findAll returns all results.

find(queryArray, dataRetrievedCallback)

data Retrieved Callback is the callback function you want called once the query has finished. Your dataRetrievedCallback function will be called with the query results object as the only function parameter.

A more complete example with a query, ordering, and fetching:

{
  'type' : 'defect',
  'key' : 'defects',
  'fetch': 'Name,ObjectID,Description',
  'query': '(Release.Name = "My Release")',
  'order': 'Name desc'
};

The example above is based on some of the query parameters. The list below includes all available query parameters:

Parameter Description Required? Defaults
type The type of Rally object you are querying for. It must be a valid object, such as defect or test case. Y NA
key The name of the query. This name can be referenced in the query results returned. Y NA
query A filter query to narrow the results of the search. This may be a Query object or a string of the same form as the general web service API queries such as '(State = Open)'. N All objects of the above type are returned
fetch Which fields of the Rally object should be returned. There are three possibilities: 1) false (returns only the shell object); 2)true (returns all fields); 3) A comma separated list of field names returns just the fields needed. N true
order The order in which the results should be returned. The string ' desc' can be appended to a list of fields to return the objects in descending order. N By default, the Rally web service API returns objects order by ascending ObjectID
attribute Returns the values for the named attribute. N
placeholder References results of another batch query executed within the same app. N
pagesize How many objects from the query result to return per web service request. This parameter is useful primarily for the find method. Specifying pagesize for findAll will still return all objects, and making it smaller than the default of 200 items is almost always less efficient. Pagesize cannot be larger than 200. N 200
start The start index (1-based) for the query result. This parameter is useful only for the find method. For example, calling find with a query object specifying start: 223 and pagesize: 20 will return the 223rd through 252nd elements from the query result. Specifying start with findAll is an error. N 1
workspace The workspace to query for results. This is usually defaulted but can be specified in the form "workspace/oid" where oid is the ObjectID of the workspace in Rally. N When running an app inside Rally, this parameter is defaulted to the chosen workspace.
project The project to query for results. This is usually defaulted but can be specified in the form "project/oid" where oid is the ObjectID of the workspace in Rally. N When running an app inside Rally, this parameter is defaulted to the chosen project.
projectScopeUp For the query, whether results should be included from parent projects. This is usually defaulted but can be specified as either true or false. N When running an app inside Rally, this parameter is defaulted to the 'Also show items from: Parent projects' section of the project chooser.
projectScopeDown For the query, whether results should be included from child projects. This is usually defaulted but can be specified as either true or false. N When running an app inside Rally, this parameter is defaulted to the 'Also show items from: Child projects' section of the project chooser.

Processing query results

The query result is the object returned from find and find All where the outermost objects are encoded as key/value pairs and the keys are the actual keys sent into find or find All. The inner objects define the query result for each key.

Other properties of the results returned include:

errors- array of errors for each key/value pair, empty array if no errors returned. If the query attempt encountered an error condition, the "errors" property will have descriptive text regarding the error condition.

warnings- array of errors for each key/value pair, empty array if no warnings returned.

In the example result below, the user defined two query objects with keys of "defects" and "stories". An empty array is returned for errors and warnings which confirms the query was successful. You'll note that each object in the sequence of objects for a query key contains _rallyAPIMajor, _rallyAPIMinor, _objectVersion, _ref and _refObjectName properties along with the properties that were either explicitly requested or returned as a result of a fetch : true specification.

{ "errors" : [],

"warnings" : [],

"defects" : {
        {
          "_rallyAPIMajor": "1",
          "_rallyAPIMinor": "23",
          "_type" : "Defect"
          "_ref" : "https://preview.rallydev.com/slm/webservice/1.26/defect/721106.js",
          "_objectVersion": "24",
          "_refObjectName": "My First Defect",
          "ObjectID" : 721106,
          "FormattedID" : "DE100"
        },
        {
          "_rallyAPIMajor": "1",
           "_rallyAPIMinor": "23",
           "_type" : "Defect"
          "_ref" : "https://preview.rallydev.com/slm/webservice/1.26/defect/721108.js",
          "_objectVersion": "5",
          "_refObjectName": "My Second Defect",
          "ObjectID" : 721108,
          "FormattedID" : "DE101"
        }
      },

"stories" : {
         {
          "_rallyAPIMajor": "1",
          "_rallyAPIMinor": "23",
          "_type" : "HierarchicalRequirement"
          "_ref" : "https://preview.rallydev.com/slm/webservice/1.26/hierarchicalrequirement/721110.js",
          "_objectVersion": "1",
          "_refObjectName": "My First Story",
          "ObjectID" : 721110,
          "FormattedID" : "US100"
        },
        {
          "_rallyAPIMajor": "1",
           "_rallyAPIMinor": "23",
           "_type": "HierarchicalRequirement"
          "_ref" : "https://preview.rallydev.com/slm/webservice/1.26/hierarchicalrequirement/721111.js",
          "_objectVersion": "3",
          "_refObjectName": "My Second Story",
          "ObjectID" : 721111,
          "FormattedID" : "US101"
        }
       }
}

The results object is passed to the call back that the user passes into find or findAll. As discussed above, each query object is returned as key/value pairs based on the key name specified.

function showResults(results){
    alert("Returned " + results.defects.length + " defects");
    alert("Returned " + results.stories.length + " stories");
}
rallyDataSource.find(queryConfig, showResults)
© 2012 Rally Software Development Corp | Legal