History Command
The history request asks for the SCM history, both the total file changes and any comments associated with these changes, from the SCMI. The request always includes a lastFilesCheckpoint and may also include a lastHistoryCheckpoint. These checkpoints specify the bounds of the request. If the lastHistoryCheckpoint element is missing, the response should be composed of all the SCM history from the start of the project up to and including the lastFilesCheckpoint. If the lastHistoryCheckpoint is present, the history response will include the history from just after the lastHistoryCheckpoint up to and including the lastFilesCheckpoint.
The lastFilesCheckpoint is the token returned to Krugle Enterprise during the last files response, the lastHistoryCheckpoint is the checkpoint token returned to Krugle Enterprise in the last history response, if one has been made for this project.
The response provides a list of changeSet objects, where a changeSet represents a batch of file changes. Each changeSet has an id field which can be any string to uniquely identifies the changeSet in the context of the project in Krugle Enterprise. In SVN this would be a revision. Each changeSet has a date and author field, which would be the date and author of the revision used for the id field. Inside of each changeSet is a list of file elements which will enumerate every file change that occurred in the revision specified by the id element. Things are more complicated for a SCM such as CVS which does not have a concept of changeSets, but instead gives every file its own revision count. For CVS you could either create a changeSet for every single file change, or better yet group comments together that were made at the same time by the same author. The id of the changeSet in this case should be the commit number, which isn’t tracked by CVS but could be inferred during this comment grouping process.
Use UTF-8 encoding for all XML communications between Krugle Enterprise and the SCMI script.
Call
- xml
- Comments
<history-request version=”1”>
<project>
<serverUid>Server1</serverUid>
<projectUid>Project1</projectUid>
<location>svn://svn.host.net/repo</location>
<params>u$3rn4m3 p4$$w0rd</params>
</project>
<lastHistoryCheckpoint>2311</lastHistoryCheckpoint>
<lastFilesCheckpoint>2601</lastFilesCheckpoint>
</history-request>-
The
“lastHistoryCheckpoint”is equal to the historyCheckpoint returned from the SCMI on the last history response for this project, if one has been sent yet.The
“lastFilesCheckpoint”is equal to the filesCheckpoint token returned from the SCMI on the last files response from this project.
Response
- xml
- Comments
<?xml version=”1.0” encoding=”UTF-8”?>
<history-response version=”1”>
<project>
<serverUid>Server1</serverUid>
<projectUid>Project1</projectUid>
<location>svn://svn.host.net/repo</location>
<params>u$3rn4m3 p4$$w0rd</params>
</project>
<changeSets>
<changeSet>
<id>2312</id>
<date>2001-10-26T21:32:52+02:00</date>
<comment>check-in comment</comment>
<author>The change author</author>
<files>
<fi le>
<action>ADDED</action>
<name>/path/to/fi le.txt</type>
</fi le>
</files>
</changeSet>
<changeSet>
...
</changeSet>
</changeSets>
<complete>false</complete>
<historyCheckpoint>new _TOKEN_</historyCheckpoint>
</history-response>-
The
“historyCheckpoint”element contains a string indicating the latest checkpoint that this response has information about.The
“complete”element may contain either “true” or “false”. If “false” the appliance will process the response and then immediately send a history request with the new historyCheckpoint. This should be used to breakup huge histories.Zero or one
“changeSets”elements may be present.Zero or more
“changeSet”elements may be present.The
“id”is unique text (in the scope of a project) that identifies this history event.The
“date”element contains a xsd:dateTime formated date.The
“comment”element contains text describing the change, typically a check-in comment.The
“author”element identifies the author of the change.Zero or one
“files”elements may be present within each “changeSet” element.Zero or more
“file”elements may be present within the “files” element.The
“action”must be “Added”, “Removed” or “Updated”.The
“name”element contains the path to the file relative to the project root.