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 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 must add several offset parameters. For details, see:

Back to top

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:

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: 

  • create

  • update

  • delete

user_id

Changes made by a specific user.

Enter the user ID without quotes, as user IDs are integers.

Note: Every user 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.

Back to top

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.

{
"total_count": -1,
"data": [
{
"type": "history_record",
"timestamp": "2018-12-16T12:49:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4277",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "release"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5923",
"originated_by": null,
"request_id": "835y6j2d30lm7iyvlo8nxpk2d",
"value": "2002"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "author"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "2002"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "detected_by"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "2002"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "estimated_hours"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "0.0"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "parent"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "1001"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "invested_hours"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "0.0"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "name"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "Defect2"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "phase"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": "phase.defect.new"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "release"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": 1001"
},
{
"type": "history_record",
"timestamp": "2018-12-16T12:48:47Z",
"session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
"entity_physical_id": 1005,
"entity_id": "1005",
"mode": null,
"field_name": "remaining_hours"
"workspace_id": 1002,
"entity_type": "defect",
"user_id": 2002,
"action": "create",
"old_value": null,
"user_name": "Marta Santora",
"history_log_id": "5922",
"originated_by": null,
"request_id": "zpqw8mdo0jnoeip9womop8xv5",
"value": 0"
}
],
"exceeds_total_count": false,
"total_error_count": 0
}

The corresponding view in the user interface would look like this: 

Viewing a defect's history in the UI.

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: 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/history_records?query="entity_type EQ ^defect^;user_id EQ 2002"

View the history of deleted spaces

This example demonstrates how to see all spaces that were deleted.

GET .../admin/history_records?query="action EQ ^delete^;entity_type EQ ^shared_space^"

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: 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/history_records?query="user_id EQ 2002;action EQ ^delete^;timestamp GE ^2019-01-01T20:59:59Z^""

Back to top

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 .

Back to top

See also: