Share this page

# 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.

In this topic:

## 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.

Back to top

## 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, 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 | 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.

Back to top

## 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
    }

The response in the ALM Octane user interface

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

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^"

Back to top

See also:

- Retrieving metadata
- Auditing entities (technical preview)
- History

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 15.1.90 All View Local Help Center View Online Help Center back Go back in browser history forward Go forward in browser history Remove search highlights next topic Go to next topic previous topic Go to previous topic Print the current topic Version: