CA Agile Central Web Services API

See the following topics for more details on the CA Agile Central Web Services API:

The 2.0 version of the CA Agile Central API is REST based and uses the JSON format.

In general, you will edit one object at a time. For example, to create two defects and specify defect A as a duplicate of defect B, do the following:

  1. Create defect A.
  2. Create defect B.
  3. Update defect A adding defect B as a duplicate.

Or:

  1. Create defect B.
  2. Create defect A adding defect B as a duplicate.

The distinction is that defect A cannot be created with a description of defect B in the duplicates list before defect B has been created. Any referenced object must already exist before it can be referenced.

Differences Between Reference Objects and Full Objects

A reference object is a key:value pair with _ref as the key and a metalink to the full object as the value. The metalink returns the full object that may be the object itself, such as a defect, hierarchical requirement , or a collection of objects (for example, a list of child defects). A collection of children of a hierarchical requirement can be fetched with the example below.

https://rally1.rallydev.com/slm/webservice/v2.0/HierarchicalRequirement/‹ObjectID›/children

A reference appears in the example below next to the _ref key.

   Defects: {
           _rallyAPIMajor: "2",
           _rallyAPIMinor: "0",          
           _ref:"https://rally1.rallydev.com/slm/
                  webservice/v2.0/HierarchicalRequirement/
                   12345/defects",          
           _type: "Defects"  

Query Parameters

Query URLs may use the following parameters. Use the & character to concatenate multiple parameters together to form a more sophisticated query.

Parameter Description
query The query string is query=(FormattedID%20%3D%20S40330) in the example below.

Example: https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?query=(FormattedID%20%3D%20S40330)

order A sort string which determines the order of the data returned. desc will present the data in descending order.

Example: order=Name desc

pagesize Number of results to display on the page. Must be greater than 0 and less than or equal to 100. The default is 20.

Example: pagesize=30

start The start index for queries, which begins at 1. The default is 1.

Example: start=1

fetch A string value which determines the attributes present on the objects returned.

Example: fetch=FormattedID,Name,Project,Parent

workspace This parameter limits the search space to a specific workspace. If not specified, then the query will search the user's default workspace. When used, the workspace parameter is set to the URL of the workspace to be searched as shown in the example below. ‹Workspace ObjectID› should be set to the Object ID of the workspace .

Example: workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/‹Workspace ObjectID›

project This parameter limits the search space to a specific project. If not specified, then the query will run in the user's default project. The workspace parameter is not necessary when project is specified because the workspace will be inherited from the project. When used, the project parameter is set to the URL of the project to be searched as shown in the example below. ‹Project ObjectID› should be set to the Object ID of the project .

Example: project=https://rally1.rallydev.com/slm/webservice/v2.0/project/‹Project ObjectID›

projectScopeUp Include parent projects above the one specified. Default is true.

Example: projectScopeUp=false

projectScopeDown Include child projects below the specified one. Default is true.

Example: projectScopeDown=true

PUT/POST Parameters

The following parameters only have an effect for PUT and POST requests.

Parameter Description
rankAbove, rankBelow Set the value to an object reference URL to cause the created or modified object to be ranked in relation to the referenced object.

Example: rankAbove=/slm/webservice/v2.0/defect/<Defect ObjectID>

Example: rankBelow=/slm/webservice/v2.0/defect/<Defect ObjectID>

Query Syntax

A query is composed of a left-hand-side (LHS), an operator and a right-hand-side value (RHS). The LHS can either be the name of an object attribute (for example, "Name") or it can be another query. If the LHS of a query is an attribute name, the RHS must be a value that is valid to compare to that attribute.

For instance, the defect type has the attributes Name and TargetBuild. The following are examples of valid queries:

(Name contains "foo")
(TargetBuild = "12345")
((Name contains "foo") and (TargetBuild = "12345"))

However, you cannot simply chain expressions together with operators, like this:

((Name contains "foo") AND (Notes contains "bar") AND (Description contains "baz"))

The expression above must be formed with parentheses enclosing each evaluated LHS-operator-RHS grouping:

(((Name contains "foo") AND (Notes contains "bar")) AND (Description contains "baz"))

The following are some grammar rules and operators for queries:

QueryString  →  (AttributeName SPACE AttributeOperator SPACE AttributeValue )
AttributePath SPACE AttributeOperator SPACE AttributeValue )
QueryString SPACE BooleanOperator SPACE QueryString )
AttributeOperator  →  =
!=
>
<
>=
<=
contains
!contains
BooleanOperator  →  AND
OR
AttributeName  →  The name of the attribute being queried, for example, Name, Notes, and so on.
AttributePath  →  The path to an attribute. For example, when querying for defects in an iteration use the path "Defect.Iteration" because defect has an Iteration attribute.
AttributeValue  → The value of the attribute. Strings with spaces must use double-quotes, not single-quotes. Object references should be expressed as the REST URL for the object. Use "null" (double quotations optional) to query for a null value in an object reference, integer, decimal, or date attribute. Arguments are not case-sensitive.

Some query examples are:

Query Result Ordering

Query result ordering is specified with the order parameter in a comma-separated list of attribute names followed by desc for descending order. For example, to order by name then creation date (descending):

order=Name,CreationDate desc

Not all attributes are sortable; sorting by a non-sortable attribute will return an error.

Fetch Syntax

The fetch parameter provides the ability to control the amount of data present on the objects returned. The following example illustrates the syntax needed to retrieve data for a user story. The desired data is the FormattedID, Name, Project, and Parent user story . The FormattedID and Name for the Parent user story are also desired.

fetch

This syntax is a comma-separated list of the attributes to be returned on the objects being queried. In the example below the data returned will consist of each of the applicable attributes in the list. The values will also be applied to attributes that are objects.

Example: https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/18532?fetch=FormattedID,Name,Project,Parent

Response: Observe that the Parent attribute on the Project and the Project attribute on the Parent user story are also defined.

{"HierarchicalRequirement": {     
        "_rallyAPIMajor": "2",     
        "_rallyAPIMinor": "0",     
        "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/18532",     
        "_refObjectUUID": "712d18f8-f975-4f15-9f7e-e4ee45526698",     
        "_objectVersion": "3",     
        "_refObjectName": "story in child project",     
        "FormattedID": "US18",     
        "DirectChildrenCount": 0,     
        "Name": "story in child project",     
        "Project":     {         
        	"_rallyAPIMajor": "2",         
            "_rallyAPIMinor": "0",         
            "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/18489",         
            "_refObjectUUID": "ecf403f3-83bd-44a9-80a4-c9d95e40b711",         
            "_objectVersion": "1",         
            "_refObjectName": "child project",         
            "Name": "child project",         
            "Parent":         {             
            	"_rallyAPIMajor": "2",             
            	"_rallyAPIMinor": "0",             
            	"_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/12402",             
            	"_refObjectUUID": "4b810825-4beb-4abc-8be0-017136be49bb",             
            	"_objectVersion": "1",             
            	"_refObjectName": "Sample Project",             
            	"Name": "Sample Project",             
            	"_type": "Project"         
        	},         
        	"_type": "Project"     
      },    
      "Parent":     {         
      		"_rallyAPIMajor": "2",         
            "_rallyAPIMinor": "0",         
            "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/17019",         
            "_refObjectUUID": "62abff8e-edda-4bf7-9f1e-97c1e1c10aac",         
            "_objectVersion": "2",         
            "_refObjectName": "a story",         
            "FormattedID": "US10",         
            "DirectChildrenCount": 1,         
            "Name": "a story",         
            "Project":         {             
            	"_rallyAPIMajor": "2",             
                "_rallyAPIMinor": "0",             
                "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/12402",             
                "_refObjectUUID": "4b810825-4beb-4abc-8be0-017136be49bb",             
                "_objectVersion": "1",             
                "_refObjectName": "Sample Project",             
                "Name": "Sample Project",             
                "_type": "Project"         
             },         
             "_type": "HierarchicalRequirement"    
      },     
      "Errors": [ ],     
      "Warnings": [ ] 
}}

Responses

Object read requests return a document representing the object. If there is an error reading the object, an <OperationResult> document is returned with a list of errors. Update and delete operations also return this document. Warnings can be ignored, but errors indicate that the requested operation has failed.


  {      
  	  operationresult:{         
  		  _rallyAPIMajor: "2",         
          _rallyAPIMinor: "0",          
          errors:{               
          			operationresulterror:'Some error text here'          
          },          
          warnings:{               
          			operationresultwarning:'Some warning text here'          
          }      
      } 
  } 

Create operations return a <CreateResult> document. This document inherits the errors and warnings from <OperationResult>.


{      
	createresult:{          
    	_rallyAPIMajor: "2",          
        _rallyAPIMinor: "0",           
        object:{                
        	ref:'https://rally1.rallydev.com/slm/webservice/v2.0/defect/12345',                
            type:'Defect'           
        }      
    } 
} 

Query operations return a <QueryResult> document. This document inherits the errors and warnings from <OperationResult>.


{      
	queryresult:{          
    	_rallyAPIMajor: "2",          
        _rallyAPIMinor: "0",           
        totalresultcount:2,           
        startindex:1,           
        pagesize:20,           
        results:{                
        	object:[                     
            	{                         
                	_rallyAPIMajor: "2",                         
                    _rallyAPIMinor: "0",
                    ref:'https://rally1.rallydev.com/slm/webservice/v2.0/defect/12345',                          
                    type:'Defect'                     
                },                     
                {                      
                	_rallyAPIMajor: "2",                        
                    _rallyAPIMinor: "0",         
                    ref:'https://rally1.rallydev.com/slm/webservice/v2.0/defect/12345',                          
                    type:'Defect'                     
                }                
            ]           
        }     
    } 
 } 
 

Null References

A query that has an attribute set to null uses this syntax:

(AttributeName = null)

This works for integer, decimal, date, and object reference attributes.

An example of setting the value of an object reference attribute to null (for instance, setting the Iteration reference on a HierarchicalRequirement to null):

Java:


 HierarchicalRequirement hierarchicalRequirement = ...          
 		
        Iteration nullIterationRef = new Iteration();         
        nullIterationRef.setRef("null");          
        
        hierarchicalRequirement.setIteration(nullIterationRef);          
        
        service.update(hierarchicalRequirement);      

C#:


 HierarchicalRequirement hierarchicalRequirement = ...          
 
 		Iteration nullIterationRef = new Iteration();         
        [email protected] = "null"; 
        
        hierarchicalRequirement.setIteration(nullIterationRef);          
        
        service.update(hierarchicalRequirement);     
 

REST (post this document to the HierarchicalRequirement's identifier URL):


{      
	hierarchicalRequirement:{
          _rallyAPIMajor: "2",
          _rallyAPIMinor: "0",   
          ref:'hierarchicalRequirement-identifier-reference-url',           
          iteration:{                
          		ref:'null'           
          }      
     } 
} 

Custom Field Names

Custom fields can be created for objects such as defects or hierarchical requirements. When created, the custom field is given a name, for example MyCustomField. The name MyCustomField will be displayed in the graphical applications. The API, however, refers to custom fields with a c_ concatenated to the beginning of the name, c_MyCustomField in this example. When using the custom field in an API call, such as making a query, use the c_ form.

API Deprecation Policy

CA Agile Central may, from time to time, modify, discontinue, or deprecate any APIs, language-specific toolkits, and SDKs, but will use commercially reasonable efforts to support the previous version of any APIs, toolkits, or SDKs for one year. This is referred to as the deprecation period (except where doing so (i) would create a security threat or intellectual property issue, (ii) is financially or technically unfeasible, or (iii) is necessary to comply with applicable laws or governmental requests).

After the one year deprecation period expires for that product it is no longer supported, maintained, or assumed to be in a state that is usable by the customer . CA Agile Central has the right to terminate versions where the deprecation period has expired.

Requests against deprecated and unsupported versions of the API will return a warning indicating that the state is either Deprecated or Unsupported.

CA Agile Central reserves the right to modify this API deprecation policy at any time in its sole discretion.

Feedback

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.