/admin/paper_trail_versions

Path: /admin/paper_trail_versions
Namespace: admin
Resource: paper_trail_versions

Overview

The PaperTrail Version resource provides complete audit trail functionality, tracking all changes to resources including who made the change, when it was made, and what changed. Versions support reverting to previous states and viewing complete change history.

Relationships

Version connects to:

• User (whodunnit) - User who made the change
• Item (item_type, item_id) - Polymorphic association to the versioned resource
• Domain (host_id) - Tenant domain

Key Features

• Complete Audit Trail: Tracks all changes to versioned resources
• Change Tracking: Records what changed, who changed it, and when
• Revert Functionality: Support for reverting to previous versions
• Polymorphic Association: Can track versions for any resource
• Event Types: Tracks create, update, and destroy events

Available Operations

List Versions (GET)

Endpoint: GET /admin/paper_trail_versions.json

Query Parameters:

• q[field_predicate]=value - Ransack query filters for advanced filtering
• page=N - Page number for pagination
• per_page=N - Items per page (default: 25)

Request Examples:

curl -X GET "https://your-company.erpax.com/admin/paper_trail_versions.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

curl -X GET "https://your-company.erpax.com/admin/paper_trail_versions.json?q[item_type_eq]=Invoice&q[item_id_eq]=123" \
  -H "Accept: application/json"

JavaScript Example:

const response = await fetch('/admin/paper_trail_versions.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const data = await response.json();

Response (200 OK):

{
  "paper_trail_versions": [
    {
      "id": 1,
      "item_type": "Invoice",
      "item_id": 123,
      "event": "update",
      "whodunnit": "1",
      "object_changes": {
        "total_amount_cents": [100000, 120000],
        "updated_at": ["2024-01-15T10:00:00Z", "2024-01-15T11:00:00Z"]
      },
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 5,
    "total_count": 125
  }
}

Show Version (GET /:id)

Endpoint: GET /admin/paper_trail_versions/:id.json

Request Example:

curl -X GET "https://your-company.erpax.com/admin/paper_trail_versions/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "paper_trail_version": {
    "id": 1,
    "item_type": "Invoice",
    "item_id": 123,
    "event": "update",
    "whodunnit": "1",
    "object": "...",
    "object_changes": {
      "total_amount_cents": [100000, 120000],
      "updated_at": ["2024-01-15T10:00:00Z", "2024-01-15T11:00:00Z"]
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Create Version (POST)

Note: Versions are typically created automatically by PaperTrail when resources are modified. Manual creation is usually not necessary.

Endpoint: POST /admin/paper_trail_versions.json

Request Example:

curl -X POST "https://your-company.erpax.com/admin/paper_trail_versions.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "paper_trail_version": {
      "item_type": "Invoice",
      "item_id": 123,
      "event": "update",
      "object_changes": {...}
    }
  }'

Update Version (PATCH /:id)

Note: Versions are typically read-only. Updates are usually not allowed.

Endpoint: PATCH /admin/paper_trail_versions/:id.json

Request Example:

curl -X PATCH "https://your-company.erpax.com/admin/paper_trail_versions/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "paper_trail_version": {
      "object_changes": {...}
    }
  }'

JavaScript Example:

const response = await fetch('/admin/paper_trail_versions/1.json', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    paper_trail_version: {
      object_changes: {}
    }
  })
});
const data = await response.json();

Response (200 OK):

{
  "paper_trail_version": {
    "id": 1,
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Version (DELETE /:id)

Endpoint: DELETE /admin/paper_trail_versions/:id.json

Request Example:

curl -X DELETE "https://your-company.erpax.com/admin/paper_trail_versions/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

JavaScript Example:

const response = await fetch('/admin/paper_trail_versions/1.json', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});

Response (204 No Content):

(empty response)

Scopes

No custom scopes are configured (uses default 'all' scope).

Filters

Available filters for searching and filtering versions:

• item_type - Select filter - Filter by versioned resource type
• item_id - Filter by versioned resource ID
• event - Select filter - Filter by event type (create, update, destroy)
• whodunnit - Filter by user who made the change
• created_at - Date filter - Filter by creation date

Filtering Examples:

# Filter by resource type and ID
GET /admin/paper_trail_versions.json?q[item_type_eq]=Invoice&q[item_id_eq]=123

# Filter by event type
GET /admin/paper_trail_versions.json?q[event_eq]=update

# Filter by user
GET /admin/paper_trail_versions.json?q[whodunnit_eq]=1

Business Rules

• Automatic Creation: Versions are automatically created when versioned resources are modified
• Immutable History: Version history is typically immutable (versions should not be modified)
• Polymorphic Association: Versions can track changes to any resource type
• Change Tracking: Versions record complete change information including before/after values

Related Resources

• Invoices - Invoice changes are tracked via versions
• Addresses - Address changes are tracked via versions
• Items - Item changes are tracked via versions
• Users - Users who made changes (whodunnit)