Agile Central - WSAPI: How to create and query Changesets

Document ID : KB000047772
Last Modified Date : 14/02/2018
Show Technical Document Details
Introduction:

Summary

An overview of creating changesets via the Web Services API (WS API), as well as querying changesets via the UI such as the Custom List app or via WS API.

Issue

I. How to query Changesets?
A user can access Changesets related to an artifact by clicking on the "Change Sets" on the artifact's details page:

User-added image

which takes the user to the summary page of the Changesets associated with this particular artifact:

User-added image
However there is no custom view in the UI that would query all Changesets by artifact.

II. How to create Changesets in CA Agile Central?
There is no UI to create changesets.

Resolution

I. HOW TO QUERY CHANGESETS

1. Changesets in a Custom List (formerly Custom Grid)


Changesets column cannot be added to a summary view or a custom view of defects, user stories and other artifacts in the UI.
However a custom grid can be added to a custom page(dashboard) and it may further be filtered by the commit message containing a FormattedID of the related aftifact.

Select "Changeset" in the Object dropdown and click "Save".

User-added image

Note that custom grids are limited to the max 200 results. Only first 200 results will be displayed.

User-added image

Below is an example of a query that can filter by a specific artifact. In the absence of the direct way of filtering by artifacts, we can filter by Message attribute using contains operator.

In this example (Message contains TA1) query returns the only changeset associated with task TA1:

User-added image


User-added image
2. Overview of WS API Changeset queries

More extensive Changeset data can be accessed through Web Services API.

A Changeset object in WS API has an attribute which references a collection of Artifacts related to this changeset.
Artifact is a parent of such objects as Defect and HierarchicalRequirement, and those objects inherit certain attributes from Artifact such as FormattedID. It is possible to identify the defects or user stories indirectly.

Here is a Changeset endpoint that fetches Artifacts attribute:

https://rally1.rallydev.com/slm/webservice/v2.0/changeset?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/12345&query=&pagesize=200&fetch=Artifacts

Obviously your workspace ObjectID /workspace/12345 will be different from the one used in this example.

Here is the json of the Artifacts collection that is returned:

Artifacts: {
_rallyAPIMajor: "2",
_rallyAPIMinor: "0",
_ref: "https://rally1.rallydev.com/slm/webservice/v2.0/Changeset/6789/Artifacts",
_type: "Artifact",
Count: 1
}


Again, the ObjectID in /Changeset/6789 will be different in your environment.

Note that we get back a reference to the Artifacts collection and not the actual hydrated collection. It means that we need to make a separate request to get to the elements of this collection.

Next we paste this Artifacts endpoint in another tab of the same browser

https://rally1.rallydev.com/slm/webservice/v2.0/Changeset/6789/Artifacts

and get back the details of the collection. For brevity we fetch only FormattedID:

https://rally1.rallydev.com/slm/webservice/v2.0/Changeset/6789/Artifacts?fetch=FormattedID

Here is a fragment of the result:

Results: [
{
_rallyAPIMajor: "2",
_rallyAPIMinor: "0",
_ref: "https://rally1.rallydev.com/slm/webservice/v2.0/defect/16953278630",
_refObjectUUID: "ed66f202-031b-478d-887c-a63b8691887b",
_objectVersion: "2",
_refObjectName: "1234",
FormattedID: "DE282",
_type: "Defect"
}
]


Notice that FormattedID: "DE282" is returned along with the reference to the actual object:
https://rally1.rallydev.com/slm/webservice/v2.0/defect/777

Go to WS API interactive document and click Changeset object in the Object Model in the left frame.
Click on the Query button in the main frame without typing anything in the Query String box. It will return 20 changesets. 20 is a default page size in WS API.
Notice that in the example above pagesize=200. That is the max page size. WS API interactive document dose not page automatically.
If the TotalResultCount of your query exceeds 200 you may issue a separate query using the start parameter: start=201
Assuming that the pagesize is 200, next 200 results will be returned.

While in the WS API document, see other attributes of Changeset object, e.g. Author, Message.
Changeset inherits from WorkspaceDomainObject. Through the inheritance chain, Changeset inherits CreationDate, so the query's fetch may include CreationDate

&fetch=Artifacts,CreationDate

We can also filter by CreationDate:

https://rally1.rallydev.com/slm/webservice/v2.0/changeset?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/12345&query=(CreationDate%20%3E%202014-01-01)&pagesize=200

Let's say we have two changesets in our workspace: one is associated with a CA Agile Central work item (user story in this example), the other is not associated with any CA Agile Central work item.

This endpoint (with empty query string) returns both:

https://rally1.rallydev.com/slm/webservice/v2.0/changeset?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/33663719110&query=&fetch=Artifacts&pagesize=200

User-added image
The returned json includes a reference to Artifacts collection. The first result shows that Artifacts collection's Count is 0, the second result shows the Artifacts collection's Count is 1.

If we want to filter in only the Changesets where Artifacts collection is not empty, this query will do that: (Artifacts.ObjectID != null):

https://rally1.rallydev.com/slm/webservice/v2.0/changeset?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/33663719110&query=(Artifacts.ObjectID != null)&fetch=Artifacts&pagesize=200

The TotalResultCount is now 1, and the result shows that Artifacts collection's Count is 1:

User-added image
If we want to filter in only the Changesets that are not associated with any CA Agile Central work item, (Artifacts collection is empty) this query will filter in (Artifacts.ObjectID = null):
only unlinked Changesets:

https://rally1.rallydev.com/slm/webservice/v2.0/changeset?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/33663719110&query=(Artifacts.ObjectID = null)&fetch=Artifacts&pagesize=200

User-added image

In case you want to write a custom javascript app that works with changesets, see an example of an AppSDK2 app that builds a grid of completed stories without changesets. Even if you do not plan to use javascript the syntax may still be useful since other API toolkits, e .g. CA Agile Central REST toolkit for Java, or CA Agile Central REST toolkit for .NET all sit on top of the same WS API object model.

This app example's source code is available in this github repo.

Please note this is not a supported app. It was written as an example only. It is outside of CA Agile Central support's scope to write or debug custom code.

II. HOW TO CREATE CHANGESETS

Normally a changeset is created in CA Agile Central via integration with version control systems. It cannot be created in the UI. It can however be created directly in Web Services API, without using version control integration.
In WS API, Changeset object has a couple of required fields, one of them an SCMRepository.
SCMRepository is also an object in WS API. It does not have to represent an actual version control repository, e.g, a Git repository
.
In this example a browser REST client is used to create an SCMRepository and a Changeset on a defect.


1. Authentication:

In production use API Key.
On rally1.rallydev.com set zsessionid header to API Key. See
Api Key and Oauth Client FAQ for details.
See WS API request examples using curl and browser REST client article for details on how to GET and POST CA Agile Central artifacts.

OnPremises and Sandbox only use Security Token
On sandbox.rallydev.com or on premises follow the steps below

Method: Get
URL:
https://rally1.rallydev.com/slm/webservice/v2.0/security/authorize

The response will include the token that will be used in the next step:
{"OperationResult": {"_rallyAPIMajor": "2", "_rallyAPIMinor": "0", "Errors": [], "Warnings": [], "SecurityToken": "73bd3465-...."}}


2. Create a required SCMRepository object if it does not exist.

Method: Post
URL:
https://rally1.rallydev.com/slm/webservice/v2.0/scmrepository/create

If OnPremises or Sandbox, append the key to the request as in: https://rally1.rallydev.com/slm/webservice/v2.0/scmrepository/create?key=73bd3465-...

Payload (request body):

{"SCMRepository":{
"Name":"repo1",
"Description":"created with wsapi",
"SCMType":"sometype",
"Uri":"http://localhost:8080",
"Projects":{"Project":"/project/12527515559"}}
}
}


Notice that SCMRepository object has attribute Projects which is a collection of projects, hence this syntax:

"Projects":{"Project":"/project/12527515559"}}

After SCMRepository is created find out its reference. A query on SCMReposotory objects in WS API will return existing repositories. Here is an example of a return:

{
_rallyAPIMajor: "2",
_rallyAPIMinor: "0",
_ref: "https://rally1.rallydev.com/slm/webservice/v2.0/scmrepository/16953479942",
_refObjectUUID: "dff6670a-aedc-4c2b-bd13-16191623c860",
_refObjectName: "repo1",
_type: "SCMRepository"
}


We need to use /scmrepository/16953479942 in the next step when creating a changeset.


2. Create a changeset.

Changest object in WS API has required fiels: CommitTimeStamp, Revision, SCMRepository. Artifacts attribute, which is a collection of artifacts with which changeset is associated is not a required field.

Method: Post
URL:
https://rally1.rallydev.com/slm/webservice/v2.0/changeset/create

Payload (request body):

{"Changeset":{
"Revision":"1",
"SCMRepository":"/scmrepository/16953479942",
"CommitTimestamp":"2014-02-11",
"Artifacts":{"Artifact":"/defect/16953278630"}}
}
}


Here is an example of creating a changeset with a curl command:
?
curl --header "zsessionid:_abc123" -H "Content-Type: application/json" -d"{\"Changeset\":{\"Revision\":\"1\",\"SCMRepository\":\"/scmrepository/16953479942\",\"CommitTimestamp\":\"2014-12-17\",\"Message\":\"test\",\"Artifacts\":{\"Artifact\":\"/defect/12353153797\"}}}" https://rally1.rallydev.com/slm/webservice/v2.0/changeset/create

Here is an example of creating a changeset in a browser REST client:

User-added image

Notice that in this example the workspace is set explicitly by using workspace parameter in the endpoint because the user that creates a changeset (whose API Key are used in the zsessionid header) has a different default workspace than the workspace for which this changeset is intended:

https://rally1.rallydev.com/slm/webservice/v2.0/changeset/create?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/33663719110

Screenshot below shows the outcome of this POST request:

User-added image

3. Author field

Changeset's Author field is not populated automatically. In WS API, the Author attribute on Changeset is a reference to a valid CA Agile Central user

Here is an example of creating a changeset in a browser REST client when Author is set in the payload:

{"Changeset":{
"Revision":"1",
"SCMRepository":"/scmrepository/34727401854",
"CommitTimestamp":"2015-07-27",
"Author":"/user/32429145056",
"Artifacts":{"Artifact":"/hierarchicalrequirement/40036167664"}}}



User-added image

Screenshot below shows the outcome of this POST request. The author is set correctly. Note the the user whose credentials (API Key) are used to create a changeset does not have to be the same user referenced in the Author field.

User-added image

Since in WS API, the Author attribute on Changeset is a reference to a valid CA Agile Central user, and not a Git (or any other source control system) user, it is often useful to map a CA Agile Central user to a source control system's user. The mapping cannot be done when creating changesets using curl or a browser REST client, but it can be done programmatically in a custom integration.

To illustrate the distinction we will consider the following scenario when a CA Agile Central Git Connector is used to create changesets in CA Agile Central.
See the connector User Guide for information on how to create changesets in CA Agile Central form git commits (those details are outside of this article's scope). The screenshot below shows the outcome of git commits. Each commit was followed by a CA Agile Central Git Connector run that created a corresponding changeset in CA Agile Central:

User-added image

In this example only the last changeset has Author field populated (nick-denver).The Message field of the last changeset also shows the same CA Agile Central user.
Compare that to all previous changesets that have no Author. The Message field of those changesets shows a Git user.

Since in WS API the Author is a reference to a valid CA Agile Central user and not a Git user, the Author field remains empty in the absence of the proper mapping in the connector's configuration file .
In this example the first four changesets were created while no mapping between CA Agile Central and Git users was specified. (See the "User-Mapping-Strategies.txt file in the connector's installation directory).
The following changes are made in this example to the connector's configuration:

In the connector's configuration yaml file the appropriate option is selected for the mapping (there are 7 options):

User-added image

and the actual mapping is done in user_map.txt file, with the Git user on the left side of the colon, and the CA Agile Central user on the right side.

User-added image
After the mapping is configured, the connector will start mapping a Git user to a CA Agile Central user.

4. Uri field

Setting the Uri field to a valid URL in the payload links the Name to the source as in the example below:

{"Changeset":{
"Revision":"1",
"SCMRepository":"/scmrepository/34727401854",
"CommitTimestamp":"2015-07-27",
"Author":"/user/721165372",
"Uri":"https://github.com/RallyCommunity/rally-java-rest-apps/commit/da2a892361fe15c18c1e7d7275cb81965597e30a",
"Artifacts":{"Artifact":"/hierarchicalrequirement/40036167664"}}}


User-added image


?
Instructions:
Please Update This Required Field