Activity & Audit Logs

Overview

The Activity Log system provides a comprehensive audit trail of all significant actions in the EMS platform. Administrators can view, search, and export activity logs for compliance, security, and operational monitoring.

Audit Trail

All actions are immutably logged with timestamp, user, action type, entity, and outcome.

Get Activity Logs

Retrieve paginated activity logs with sorting options.

Endpoint

GET /api/admin/activity/logs

Authorization

Required Role: ADMIN

Query Parameters

page

integer

default:"0"

Page number (zero-based)

size

integer

default:"15"

Number of records per page

sortBy

string

default:"timestamp"

Field to sort byCommon values: timestamp, userEmail, action, entityType

direction

string

default:"desc"

Sort direction: asc or desc

Request Example

curl -X GET "http://localhost:8080/api/admin/activity/logs?page=0&size=20&sortBy=timestamp&direction=desc" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "statusCode": 200,
  "message": "Logs fetched",
  "data": {
    "content": [
      {
        "logID": 1523,
        "userID": 42,
        "userEmail": "[email protected]",
        "action": "PROPOSAL_SUBMITTED",
        "entityType": "Proposal",
        "entityID": 15,
        "outcome": "SUCCESS",
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0...",
        "timestamp": "2024-03-15T10:30:45"
      },
      {
        "logID": 1522,
        "userID": 5,
        "userEmail": "[email protected]",
        "action": "PROPOSAL_APPROVED",
        "entityType": "Proposal",
        "entityID": 14,
        "outcome": "SUCCESS",
        "ipAddress": "192.168.1.50",
        "userAgent": "Mozilla/5.0...",
        "timestamp": "2024-03-15T09:15:22"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20
    },
    "totalElements": 1523,
    "totalPages": 77,
    "last": false,
    "first": true,
    "numberOfElements": 20
  },
  "timestamp": "2024-03-15T14:00:00"
}

Response Fields

content

array

Array of audit log entries

logID

long

Unique log entry identifier

userID

long

ID of user who performed the action

userEmail

string

Email of user who performed the action

action

string

Type of action performed (see Action Types below)

entityType

string

Type of entity affected (Proposal, Event, Registration, etc.)

entityID

long

ID of the affected entity

outcome

string

Result of the action: SUCCESS or FAILURE

ipAddress

string

IP address of the user

userAgent

string

Browser/client user agent string

timestamp

LocalDateTime

When the action occurred (ISO 8601 format)

Export Activity Logs

Export all activity logs as a JSON file for archival or analysis.

Endpoint

GET /api/admin/activity/export

Authorization

Required Role: ADMIN

Request Example

cURL

curl -X GET http://localhost:8080/api/admin/activity/export \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o ems_audit_export.json

Response

Content-Type: application/json Content-Disposition: attachment; filename=ems_audit_export.json

[
  {
    "logID": 1523,
    "userID": 42,
    "userEmail": "[email protected]",
    "action": "PROPOSAL_SUBMITTED",
    "entityType": "Proposal",
    "entityID": 15,
    "outcome": "SUCCESS",
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "timestamp": "2024-03-15T10:30:45"
  },
  {
    "logID": 1522,
    "userID": 5,
    "userEmail": "[email protected]",
    "action": "PROPOSAL_APPROVED",
    "entityType": "Proposal",
    "entityID": 14,
    "outcome": "SUCCESS",
    "ipAddress": "192.168.1.50",
    "userAgent": "Mozilla/5.0...",
    "timestamp": "2024-03-15T09:15:22"
  }
]

The export includes ALL log entries, sorted by timestamp (most recent first). Use this for compliance archival or offline analysis.

Action Types

The system logs the following action types:

Proposal Actions

Action	Description
`PROPOSAL_SUBMITTED`	Organizer submitted a new proposal
`PROPOSAL_APPROVED`	Admin approved a proposal
`PROPOSAL_REJECTED`	Admin rejected a proposal
`PROPOSAL_RESUBMITTED`	Organizer resubmitted after rejection

Event Actions

Action	Description
`EVENT_CREATED`	Event created from approved proposal
`EVENT_UPDATED`	Event details modified
`EVENT_CANCELLED`	Event cancelled

Registration Actions

Action	Description
`REGISTRATION_CREATED`	Student registered for event
`REGISTRATION_CANCELLED`	Student cancelled registration

Report Actions

Action	Description
`REPORT_SUBMITTED`	Organizer submitted post-event report
`REPORT_APPROVED`	Admin approved report
`REPORT_REJECTED`	Admin rejected report
`CERT_EXPORT_DOWNLOADED`	Organizer downloaded certificate template

Action	Description
`USER_REGISTERED`	New user account created
`USER_STATUS_CHANGED`	Account status modified by admin
`USER_ROLE_CHANGED`	User role modified by admin

Update Request Actions

Action	Description
`UPDATE_REQUEST_SUBMITTED`	Organizer submitted event modification request
`UPDATE_REQUEST_APPROVED`	Admin approved modification request
`UPDATE_REQUEST_REJECTED`	Admin rejected modification request

Use Cases

Security Monitoring

Track suspicious login patterns, unauthorized access attempts, or unusual activity:

# Monitor failed actions
Filter logs where outcome = "FAILURE"

Compliance Auditing

Generate audit trails for regulatory compliance:

# Export all logs for audit period
GET /api/admin/activity/export

User Activity Tracking

Monitor specific user actions for investigation:

# Sort by user and review their actions
GET /api/admin/activity/logs?sortBy=userEmail&direction=asc

System Health Monitoring

Identify system errors or performance issues:

# Look for patterns in FAILURE outcomes
Filter by outcome = "FAILURE" and analyze timestamps

Event Timeline Reconstruction

Trace the complete lifecycle of a proposal/event:

# Filter by entityType and entityID
Review all actions for Proposal ID 15

Pagination Best Practices

Start with Recent Logs: Use default sortBy=timestamp and direction=desc to see latest activity first.

Adjust Page Size: Increase size parameter for bulk analysis, keep small (15-20) for UI display.

Export for Deep Analysis: Use the export endpoint for searching, filtering, or analysis in external tools.

Sorting Options

You can sort by any of these fields:

timestamp - When the action occurred (default)
userEmail - Who performed the action
action - Type of action
entityType - What was affected
outcome - Success or failure
ipAddress - Source IP address

GET /api/admin/activity/logs?sortBy=userEmail&direction=asc

Security Considerations

Access Control: Only administrators can access activity logs. These logs contain sensitive information about system operations.

Immutable Records: Log entries cannot be modified or deleted. This ensures audit trail integrity.

IP Tracking: IP addresses are logged for security monitoring and incident investigation.

User Agent Logging: Browser information helps identify automated vs. manual actions.

Integration Examples

JavaScript - Recent Activity Dashboard

async function fetchRecentActivity() {
  const response = await fetch(
    'http://localhost:8080/api/admin/activity/logs?page=0&size=10&sortBy=timestamp&direction=desc',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const result = await response.json();
  return result.data.content;
}

// Display in dashboard
const activities = await fetchRecentActivity();
activities.forEach(log => {
  console.log(`${log.timestamp}: ${log.userEmail} - ${log.action} on ${log.entityType}`);
});

Python - Export and Analyze

import requests
import json

# Export logs
headers = {'Authorization': f'Bearer {token}'}
response = requests.get(
    'http://localhost:8080/api/admin/activity/export',
    headers=headers
)

logs = response.json()

# Analyze failure rate
failures = [log for log in logs if log['outcome'] == 'FAILURE']
failure_rate = len(failures) / len(logs) * 100
print(f"Failure rate: {failure_rate:.2f}%")

# Find most active users
from collections import Counter
user_activity = Counter(log['userEmail'] for log in logs)
print("Top 5 most active users:")
for user, count in user_activity.most_common(5):
    print(f"  {user}: {count} actions")

Admin Guide

Administrator workflows and best practices

Security Architecture

System security design

User Management

User and account management endpoints

Events API

Event management endpoints

Overview

Endpoints

Overview

Audit Trail

Get Activity Logs

Endpoint

Authorization

Query Parameters

Request Example

Response

Response Fields

Export Activity Logs

Endpoint

Authorization

Request Example

Response

Action Types

Proposal Actions

Event Actions

Registration Actions

Report Actions

User Actions

Update Request Actions

Use Cases

Sorting Options

Security Considerations

Integration Examples

JavaScript - Recent Activity Dashboard

Python - Export and Analyze

Admin Guide

Security Architecture

User Management

Events API

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

Audit Trail

​Get Activity Logs

​Endpoint

​Authorization

​Query Parameters

​Request Example

​Response

​Response Fields

​Export Activity Logs

​Endpoint

​Authorization

​Request Example

​Response

​Action Types

​Proposal Actions

​Event Actions

​Registration Actions

​Report Actions

​User Actions

​Update Request Actions

​Use Cases

​Pagination Best Practices

​Sorting Options

​Security Considerations

​Integration Examples

​JavaScript - Recent Activity Dashboard

​Python - Export and Analyze

​Related Documentation

Admin Guide

Security Architecture

User Management

Events API

Build docs developers (and LLMs) love

Overview

Get Activity Logs

Endpoint

Authorization

Query Parameters

Request Example

Response

Response Fields

Export Activity Logs

Endpoint

Authorization

Request Example

Response

Action Types

Proposal Actions

Event Actions

Registration Actions

Report Actions

User Actions

Update Request Actions

Use Cases

Pagination Best Practices

Sorting Options

Security Considerations

Integration Examples

JavaScript - Recent Activity Dashboard

Python - Export and Analyze

Related Documentation