Audit entities (technical preview)

Use the audits resource to review create, update, and delete operations across site, space, shared-area, and workspace contexts.

In this topic:

Overview

Audit data helps administrators track changes for security and compliance use cases.

The audits resource is cross-entity, so one request can return events for multiple entity types.

Because this is a technical preview resource, include the ALM-OCTANE-TECH-PREVIEW request header with the value true in all audits API requests.

Only users with the required admin roles and permissions in the target context can access audit data.

This resource is available to site and space admins, including admins with data-access restrictions.

URIs by context

Build audit queries

Use the query clause to filter results. Separate query conditions with semicolons (;), which act as logical AND.

Supported query items

Notes:

• If you omit query, the API can return all operations for all auditable entities in the context. Always filter to reduce payload size and improve performance.

• You can combine standard collection clauses, such as limit, offset, and fields, with query.

• Explicitly set the fields clause. If you omit fields, the response can return a minimal projection (for example, only "type": "audit" for each event).

• Users with data visibility restrictions, must include both entity_type and entity_id in the query.

• Only auditable entities and auditable fields are returned by this resource. To see whether an entity can be audited, check the non-auditable feature in Entity metadata reference. To see whether a field is auditable, check the non-auditable feature in Field metadata reference.

Request examples

The following examples show common audit request patterns with explicit fields and query clauses.

Audit all deletions since a specific date

GET .../audits?fields=action,entity_type,entity_id,timestamp,user_id,change_set&query="action EQ ^delete^;timestamp GE ^2019-01-01T20:59:59Z^"

Audit all operations for one entity (include both type and ID)

GET .../audits?fields=action,entity_type,entity_id,timestamp,user_id,user_name,workspace_id,entity_physical_id,session_id,change_set&query="entity_type EQ ^epic^;entity_id EQ 1125"

Audit one user

GET .../audits?fields=action,entity_type,entity_id,timestamp,user_id,change_set&query="user_id EQ 2002"

Audit multiple attributes in one request

GET .../audits?fields=action,entity_type,entity_id,timestamp,user_id,change_set&query="entity_type EQ ^story^;entity_id EQ 2004;field_name EQ ^severity^;action EQ ^update^;user_id EQ 8987"

Response field highlights

Each result is an audit event. Use fields to return only the fields you need.

A single response can include multiple audit events for the same entity, such as create, update, and delete operations.

Common fields returned in audit events: action, entity_type, entity_id, timestamp, user_id, user_name, workspace_id, change_set.

• Create actions: Each field that received a value during the create is listed in the change_set attribute.

• Update actions: Each field that was updated is listed in the change_set attribute. Fields receiving values for the first time during the update are listed with their current value. For fields whose values were modified, both the old and the current values are listed.

Common audit event schema

{
    "type": "audit",
    "workspace_id": 1002,
    "entity_physical_id": 1125,
    "entity_type": "epic",
    "user_id": 1001,
    "user_name": "user@thecompany.com",
    "action": "create",
    "session_id": "$1$XHYKNW1C$IhyU1Zzj7N0rlfLwoeWGQ0",
    "entity_id": "1125",
    "timestamp": "2018-12-13T11:18:42Z",
    "change_set": [
        {
            "field_name": "...",
            "value": "..."
        }
    ]
}

change_set patterns

Create pattern

"change_set": [
    {
        "field_name": "name",
        "value": "Epic 1"
    },
    {
        "field_name": "phase",
        "value": "phase.epic.new"
    }
]

Update pattern

"change_set": [
    {
        "field_name": "phase",
        "old_value": "phase.epic.new",
        "value": "phase.epic.inprogress"
    },
    {
        "field_name": "story_points",
        "value": "10"
    }
]

See also

• Retrieve metadata
• Entity metadata reference
• Field metadata reference