View history (technical preview)
Use the history_records resource to view the history of an entity.
Note: As a technical preview, this resource is subject to change.
Overview
A history log is created when you create a new item or when you save changes to an existing item.
The following is a list of common use cases:
- Stories moved between sprints
- Stories in a release
- Events where the sprint field was changed to a story
- Changes done on a specific field or set of fields
- Events where fields A, B, or C were changed
- Original plan of sprint X
- All the user stories in a release
- Events where the sprint was changed from X to Y
Using the history_records resource, you can view the history of all changes made to any entity, whereas the ValueEdge user interface's History tab only show partial audit information. The history_records entity is parsed from the history log. For details, see History.
To determine the entities for which you can view history, see the history feature under Entity metadata reference.
Note:
-
The history_records resource is currently only supported on the workspace level. The API also allows you to fetch history using the history_logs entity. However, we recommend using the history_records entity which provides broader capabilities, as shown in the examples below.
-
To prevent retrieving huge numbers of records the resource is limited by default to 10,000 records. This limit can be lowered using the configuration parameter MAX_LIMIT_ELASTIC. The limit cannot be raised.
History offset
To retrieve a specific history record with the relevant information, you need to add several offset parameters. For details, see:
-
For OData, see Specify an offset within history records - OData (technical preview).
-
For REST, see Specify an offset within history records -REST (technical preview).
Add queries to history requests
You add queries to history requests in order to filter and limit the information returned by the history_record resource.
The following clauses are available:
-
Set the paging for the returned data. As long as a next page exits, each request returns a next-page link. For details, see Specify an offset within history records -REST (technical preview).
-
Retrieve only the fields you need by using a fields clause. For details, see Select fields (fields)
-
Filter the instances to be returned with a query clause. For details, see Query.
Use a semicolon to separate the clauses in the query. The semicolon represents the And relational operator.
You can query the following items:
Query item | Description |
---|---|
entity_type |
History by entity type, such as teams, features, or pipelines. To see the entities for which you can view history, see the history feature under Entity metadata reference. Mandatory for users with data access restrictions. |
entity_id |
History by the ID of the entity. Mandatory for users with data access restrictions. |
history_log_id |
The ID of a history log entity. Use this item to query the changes made in a specific history log. |
action |
History for the following actions:
|
user_id |
Changes made by a specific user. Enter the user ID without quotes, as user IDs are integers. Note: Every user in ValueEdge has two IDs. If you are on the viewing history on the site level, specify the site user ID. If you are viewing history on the space or workspace level, make sure to specify the space user ID. |
View history examples
This section provides some examples for working with the history_record resource to view audit information.
Note: If you specify an entity_id, the response includes all entities with the same ID. If you specify an entity ID of 3001, for example, you could get the history for the user story, defect, epic, and feature with an ID of 3001. Specify the type of the entity together with the ID to make sure you only get the history for the relevant entity.
View the history of a defect
This example demonstrates how to view the history for a specific defect whose ID is 2002.
The corresponding view in the ValueEdge user interface would look like this:
View the history of defects modified by a specific user
This example demonstrates how to view the history for any defect that user ID 2002, Marta Santora, created, changed, or deleted.
Request:
View the history of deleted spaces
This example demonstrates how to see all spaces that were deleted.
View the cross-entity history view of entities that a specific user deleted over a specific time period
This example demonstrates how to view the history for any entity that the user with ID 2002, deleted since the beginning of 2019.
Request:
Specify an offset within history records -REST (technical preview)
A history log is created when a new item is created or when you click Save after changing item fields.
You can use the offset parameter to specify a location within the history log. The history_records resource is a parsed version of the history_log entity, where each history log can contain multiple history records. Therefore, when using the offset parameter with the history_records entity, you must add two additional parameters: originalSkip and innerOffset to indicate which record and the offset within the record:
- originalSkip. How many history logs to skip.
- innerOffset. How many records to skip within the specified history log.
These parameters are calculated on the server side, and they are automatically added to the "next-page" link in a response, if a next page exists. Manually changing these parameters in the link, could result in inconsistent data fetching.
The total_count value for this entity returns a value of -1.
Note: The history_records REST call is limited to fetching up to 10,000 history logs. If your results exceed this amount, you will receive a warning asking you to filter the request. You can filter by time/date, entity_ID, user_id, action, or entity_type. For details, see Add queries to history requests.
The following example skips to record 17 within history log 99:
https://host.name/api/shared_spaces/1001/workspaces/1002/history_records?offset=1000&originalSkip=98&innerOffset=16
For details about the offset parameter, see Offset: Specifying where to start a page .
See also: