Viewing history (technical preview)

Use the history_logs resource to view history of a single entity, or across multiple entities (cross-entity history). This resource enables you to retrieve more audit information than is available in the History tabs in the ALM Octane user interface.

Note: As a technical preview, this resource is subject to change.

Overview

Using the REST API, you can view the history of all changes made to any entity, as opposed to the subset of the history available using the ALM Octane user interface.

For viewing cross-entity history, you must either be a space admin, or be a user with no data access restrictions. If you have data access restrictions, you can, however, view the history of a single entity.

To determine the entities for which you can view history, see the history feature under Entity metadata reference.

Adding queries to history requests

We add queries to filter the information that is returned by the history_logs resource.

You can query on the changes made to the entities. You cannot query on the values that were changed. For example, you can query the number of defects whose phase changed, but you cannot query which defects' phases changed to Closed.

The following clauses are available:

How the returned data are paged. See Page data (limit, offset, total_count).
Retrieving only the fields you need by using a fields clause. See Select fields (fields)
Filtering the instances to be returned with a query clause. See Query.

Use a semicolon to separate the clauses in the query. This represents the And relational operator.

You can query on the following items:

Query item	Description
entity_type	You can view history by entity type, such as teams, features, pipelines, and so on. 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	You can view history by the ID of the entity. Mandatory for users with data access restrictions.
field_name	You can view changes made to a specific field of an entity. To see which entities are available, see the history feature under Entity metadata reference.
action	You can view the history for the following actions: create update delete
user_id	You can request the changes made by a specific user. Enter the user ID without quotes, as user IDs are integers. Note: Every user in ALM Octane 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.

Examples

Here are some examples for working with the history_logs resource.

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 in addition to the ID to make sure you get the history only for the relevant entity.

Example of viewing the history of a defect

This example demonstrates how to view the history for a specific defect whose ID is 1005.

Request

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/history_logs?query="entity_type EQ ^defect^;entity_id EQ 1005"

Response

{
  "total_count": 10,
  "data": [
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "estimated_hours",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": null,
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "new_value": "<html><body>\n0\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "remaining_hours",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": null,
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "new_value": "<html><body>\n0\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "invested_hours",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": null,
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "new_value": "<html><body>\n0\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "name",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": null,
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "new_value": "<html><body>\nDefect2\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "new_entity_id_es": "2002",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "author",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "2002",
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "old_entity_id_es": null,
      "new_value": "<html><body>\nMarta Santora\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "new_entity_id_es": "2002",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "detected_by",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "2002",
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "old_entity_id_es": null,
      "new_value": "<html><body>\nMarta Santora\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "new_entity_id_es": "1001",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "release",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "1001",
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "old_entity_id_es": null,
      "new_value": "<html><body>\nRelease1\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "new_entity_id_es": "1001",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "phase",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "1001",
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "old_entity_id_es": null,
      "new_value": "<html><body>\nNew\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:48:47Z",
      "new_entity_id_es": "1002",
      "audit_action": "CREATE",
      "session_id": "64bfa46b-ff6a-48a2-95f2-bd0091db10d6",
      "old_entity_id": null,
      "entity_id": "1005",
      "property_name": "parent",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "1002",
      "action": "Created",
      "old_value": null,
      "user": "Marta Santora",
      "old_entity_id_es": null,
      "new_value": "<html><body>\nFeature1\n</body></html>"
    },
    {
      "type": "history",
      "creation_time": "2018-12-16T12:49:47Z",
      "new_entity_id_es": "2001",
      "audit_action": "DELETE",
      "session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4991",
      "old_entity_id": "1001",
      "entity_id": "1005",
      "property_name": "release",
      "workspace_id": 1002,
      "entity_type": "defect",
      "user_id": 2002,
      "new_entity_id": "2001",
      "action": "Deleted",
      "old_value": "<html><body>\nRelease1\n</body></html>",
      "user": "Marta Santora",
      "old_entity_id_es": "1001",
      "new_value": "<html><body>\nRelease2\n</body></html>"
    }
  ],
  "exceeds_total_count": false,
  "total_error_count": 0
}

Viewing the history of defects that a specific user modified

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_logs?query="entity_type EQ ^defect^;user EQ ^marta@thecompany.com^"

Cross-entity history view of entities that a specific user deleted in a specific time period

This example demonstrates how to view the history for any entity that user ID 2002, Marta Santora, deleted since the beginning of 2019.

Request:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/history_logs?query="user EQ ^marta@thecompany.com^;action EQ ^delete^;timestamp GE ^2019-01-01T20:59:59Z^"

Viewing the history of deleted spaces

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

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

Viewing history (technical preview)

Overview

Adding queries to history requests

Examples

Send Help Center Feedback