history

The history API command returns all the changes to item records, from a specified point in time to the current time.

SYNTAX

http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&password=password
&statevar=history
&cutoff=timestamp
[&cutoff_end=timestamp]
&evhist_sellist=selectionList
[&hist_range_end=timestamp]
[&hist_range_start=timestamp]
[&username_display=ID | LAST | FIRST]
[&dd_name_n=value]
[&show_attributes=YES | NO]

NOTES

The timestamp refers to the ITEM.LAST_DATE_UPDATED and the ITEM_HIST.LAST_DATE_UPDATED fields in the database. It is provided within the command in a value of any valid format allowed by ExtraView. If the value supplied can be misconstrued, the user’s locale is used to determine the meaning of the date.

The cutoff timestamp provides the current value of the fields. The cutoff timestamp value is not included in the issues generated by this command; that is, the comparison is item timestamp is greater than cutoff timestamp. The cutoff parameter is required.

The cutoff_end parameter is optional. If omitted, there all issues up until the current time are retrieved. If provided, the value must be greater than the value of cutoff. This can be used to limit the items for which history is generated to a specific time period.

The evhist_sellist parameter is a comma-delimited list of field names. This is an optional parameter, and if provided is a list of the fields that are output by the command. If it is not provided, the field list is taken from the detailed report of the user’s current business area and project.

hist_range_start and hist_range_end are optional parameters. If omitted, then the items retrieved are generated based upon updates that occured between these times. If provided then the query becomes a range query, where hist_range_start is the beginning time and hist_range_start is the end time of the updates to the records retrieved.

The optional parameter username_display may be used to override the behavior setting named USERNAME_DISPLAY, for the duration of the execution of a single API call. This allows the developer to return the user names in a different format than the system-wide default.

dd_name_n=value represents an optional list of name value pairs to be used as filters on the query that returns results for the command.

The fields returned by the command are formatted as XML data.

The fields returned in the XML data are subject to two restrictions. The user must have read permission for the field, and the field must exist on the detailed report layout for the user’s current area and project settings.

The item fields returned by the command are in the same XML format as those returned by the API get command.

The optional access_token parameter allows you to use a valid OAuth2 token obtained with the get_token command.  If you provide the access_token parameter, then the user_id and password parameters should not be provided.  This prevents the password being sent in clear text over your network connection.

The item fields returned may contain repeating row data within the XML. If a deleted item record is encountered in the returned data, this will be shown in the XML as follows –

<DELETED_RECORD ID=’item id’ FULL_TIMESTAMP=’issue timestamp’/>

This command provides a convenient method of determining all changes to the ExtraView database since a point in time, to be used to synchronize data with another ExtraView instance, or with a completely separate application (For example, ExtraView enables the synchronization of data with the Perforce SCM system with this command).