Agile Central - WSAPI: How to create and query Changesets
Article ID: 47772
Updated On:
Products
Issue/Introduction
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 WSAPI.
Resolution
How to create Changesets in CA Agile Central:
There is no UI to create changesets.
How to query Changesets:
A user can access Changesets related to an artifact by clicking on Connections and then Changesets on the artifact's details page. However there is no custom view in the UI that would query all Changesets by artifact. More information here.
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 List can be added to your dashboard or custom page and it may further be filtered by the commit message containing a FormattedID of the related artifact.
Select "Changeset" in the Object dropdown and click "Save".
Note that custom grids are limited to the max 200 results. Only first 200 results will be displayed.
We can filter for 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:
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/<Workspace_OID>&query=&pagesize=200&fetch=Artifacts
Replace <Workspace_OID> with your actual workspace Object ID.
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/<Changeset_OID>/Artifacts",
_type: "Artifact",
Count: 1
}
Again, enter your actual <Changeset_OID>.
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/<Changeset_OID>/Artifacts
and get back the details of the collection. For brevity we fetch only FormattedID:
https://rally1.rallydev.com/slm/webservice/v2.0/Changeset/<Changeset_OID>/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/<Defect_OID>",
_refObjectUUID: "<Object_UUID>",
_objectVersion: "2",
_refObjectName: "<Object_Name>",
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/<Defect_OID>
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/<Workspace_OID>&query=(CreationDate%20%3E%202014-01-01)&pagesize=200
Let's say we have two changesets in our workspace: one is associated with a Rally work item (user story in this example), the other is not associated with any Rally work item.
This endpoint (with empty query string) returns both:
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/<Workspace_OID>&query=(Artifacts.ObjectID != null)&fetch=Artifacts&pagesize=200
If we want to filter in only the Changesets that are not associated with any Rally 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/<Workspace_OID>&query=(Artifacts.ObjectID = null)&fetch=Artifacts&pagesize=200
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.
HOW TO CREATE CHANGESETS
Normally a changeset is created in Rally 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/<Project_OID>"}}
}
}
Notice that SCMRepository object has attribute Projects which is a collection of projects, hence this syntax:
"Projects":{"Project":"/project/<Project_OID>"}}
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/<Object_OID>",
_refObjectUUID: "<Object_UUID>",
_refObjectName: "repo1",
_type: "SCMRepository"
}
We need to use /scmrepository/<Object_OID> 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/<Object_OID>",
"CommitTimestamp":"2014-02-11",
"Artifacts":{"Artifact":"/defect/<Defect_OID>"}}
}
}
Create a changeset with more than one artifact :
{"Changeset":{
"Revision":"1",
"SCMRepository":"/scmrepository/<Object_OID>",
"CommitTimestamp":"2014-02-11",
"Artifacts":[{"_ref":"/defect/<Defect_OID>"},{"_ref":"/defect/<Defect_OID>"},{"_ref":"/defect/<Defect_OID>"}]
}
}
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/<Object_OID>\",\"CommitTimestamp\":\"2014-12-17\",\"Message\":\"test\",\"Artifacts\":{\"Artifact\":\"/defect/<Defect_OID>\"}}}" https://rally1.rallydev.com/slm/webservice/v2.0/changeset/create
Here is an example of creating a changeset in a browser REST client:
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/<Workspace_OID>
Here is the output for that Changeset
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/<Object_OID>",
"CommitTimestamp":"2015-07-27",
"Author":"/user/<User_OID>",
"Artifacts":{"Artifact":"/hierarchicalrequirement/<Story_OID>"}}}
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.
Here is the output for the above
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:
In this example only the last changeset has Author field populated.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):
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.
Example: [email protected] : [email protected]
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/<Object_ID>",
"CommitTimestamp":"2015-07-27",
"Author":"/user/<User_OID>",
"Uri":"https://github.com/RallyCommunity/rally-java-rest-apps/commit/<OBJECT_OID>",
"Artifacts":{"Artifact":"/hierarchicalrequirement/<Story_OID>"}}}
Additional Information
https://ca-broadcom.wolkenservicedesk.com/external/article?articleId=57528
Feedback
