Skip to content

activity_feed.md

Latest commit

 

History

History
301 lines (236 loc) · 8.68 KB

activity_feed.md

File metadata and controls

301 lines (236 loc) · 8.68 KB
Raw

Activity Feed Widget

The Activity Feed Widget provides real-time visibility into team activities and creates a comprehensive audit trail for your TimeTracker instance.

Overview

The Activity Feed automatically tracks and displays all major actions performed in the system, including:

  • Project management (create, update, delete, archive)
  • Task operations (create, update, delete, status changes, assignments)
  • Time tracking (start/stop timer, manual entries, edits)
  • Invoice activities (create, send, mark paid)
  • Client management
  • And more...

Features

Dashboard Widget

The Activity Feed Widget appears on the main dashboard in the right sidebar, displaying:

  • Recent Activities: Last 10 activities by default
  • User Attribution: Shows who performed each action
  • Timestamps: Displays how long ago each action occurred
  • Action Icons: Visual indicators for different types of actions
  • Entity Details: Clear description of what was done

Filtering

Click the filter icon (🔽) to filter activities by type:

  • All Activities
  • Projects only
  • Tasks only
  • Time Entries only
  • Invoices only
  • Clients only

Real-time Updates

The activity feed automatically refreshes every 30 seconds to show the latest team activities.

User Permissions

Regular Users

  • See their own activities
  • View activities related to projects they have access to

Administrators

  • See all activities across the entire organization
  • Access to advanced filtering and export options
  • View activity statistics

API Endpoints

Get Activities

GET /api/activities

Query Parameters:

  • limit (int): Number of activities to return (default: 50)
  • page (int): Page number for pagination (default: 1)
  • user_id (int): Filter by specific user (admin only)
  • entity_type (string): Filter by entity type (project, task, time_entry, invoice, client)
  • action (string): Filter by action type (created, updated, deleted, started, stopped, etc.)
  • start_date (ISO string): Filter activities after this date
  • end_date (ISO string): Filter activities before this date

Response:

{
  "activities": [
    {
      "id": 123,
      "user_id": 5,
      "username": "john.doe",
      "display_name": "John Doe",
      "action": "created",
      "entity_type": "project",
      "entity_id": 42,
      "entity_name": "New Website",
      "description": "Created project \"New Website\"",
      "extra_data": {},
      "created_at": "2025-10-30T14:30:00Z"
    }
  ],
  "total": 150,
  "pages": 3,
  "current_page": 1,
  "has_next": true,
  "has_prev": false
}

Get Activity Statistics

GET /api/activities/stats?days=7

Query Parameters:

  • days (int): Number of days to analyze (default: 7)

Response:

{
  "total_activities": 342,
  "entity_counts": {
    "project": 45,
    "task": 128,
    "time_entry": 156,
    "invoice": 13
  },
  "action_counts": {
    "created": 89,
    "updated": 167,
    "deleted": 12,
    "started": 42,
    "stopped": 32
  },
  "user_activity": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "count": 156
    }
  ],
  "period_days": 7
}

Action Types

The system tracks the following action types:

Action Description Used For
created Entity was created Projects, Tasks, Clients, Invoices
updated Entity was modified Projects, Tasks, Time Entries
deleted Entity was removed Projects, Tasks, Time Entries
started Timer started Time Entries
stopped Timer stopped Time Entries
completed Task marked as done Tasks
assigned Task assigned to user Tasks
commented Comment added Tasks
status_changed Status modified Tasks, Invoices
sent Invoice sent to client Invoices
paid Payment recorded Invoices
archived Entity archived Projects
unarchived Entity unarchived Projects

Entity Types

Activities can be tracked for the following entity types:

  • project - Project management
  • task - Task operations
  • time_entry - Time tracking
  • invoice - Invoicing
  • client - Client management
  • user - User administration (admin only)
  • comment - Comments and discussions

Integration Guide

For Developers

To add activity logging to new features, use the Activity.log() method:

from app.models import Activity

Activity.log(
    user_id=current_user.id,
    action='created',  # Action type
    entity_type='project',  # Entity type
    entity_id=project.id,
    entity_name=project.name,
    description=f'Created project "{project.name}"',
    extra_data={'client_id': client.id},  # Optional metadata
    ip_address=request.remote_addr,  # Optional
    user_agent=request.headers.get('User-Agent')  # Optional
)

Best Practices:

  1. Always log after successful operations - Log after the database commit succeeds
  2. Provide clear descriptions - Make descriptions human-readable
  3. Include relevant metadata - Use extra_data for additional context
  4. Store entity names - Cache the entity name in case it's deleted later
  5. Handle failures gracefully - Activity logging includes built-in error handling

Already Integrated

Activity logging is already integrated for:

  • ✅ Projects (create, update, delete, archive, unarchive)
  • ✅ Tasks (create, update, delete, status changes, assignments)
  • ✅ Time Entries (start timer, stop timer, manual create, edit, delete)
  • ❌ Invoices (create, update, status change, payment, send) — not yet in main activity feed
  • ❌ Clients (create, update, delete) — not yet in main activity feed
  • ⏳ Comments — integrated in client portal activity feed only; main activity feed comment logging still planned

Use Cases

Team Visibility

  • See what your team members are working on
  • Track project progress in real-time
  • Understand team activity patterns

Audit Trail

  • Compliance and record-keeping
  • Track who made what changes and when
  • Identify suspicious or unusual activity

Project Management

  • Monitor task completion rates
  • Track project milestones
  • Review team productivity

Troubleshooting

  • Investigate issues by reviewing recent changes
  • Identify when problems were introduced
  • Track down missing or deleted items

Configuration

No special configuration is required. The Activity Feed is enabled by default for all users.

Database Indexes

The Activity model includes optimized indexes for:

  • User-based queries (user_id, created_at)
  • Entity lookups (entity_type, entity_id)
  • Date range queries (created_at)

Performance

  • Activities are paginated to prevent slow page loads
  • Old activities are automatically retained (no automatic cleanup)
  • Database queries are optimized with proper indexes
  • Widget auto-refreshes are throttled to every 30 seconds

Privacy & Security

Data Retention

  • Activities are stored indefinitely by default
  • Administrators can manually delete old activities if needed
  • Consider implementing a retention policy for compliance

Access Control

  • Users can only see their own activities (unless admin)
  • Administrators see all activities system-wide
  • Activity logs cannot be edited or tampered with
  • IP addresses and user agents are stored for security auditing

GDPR Compliance

When a user requests data deletion:

  1. Their activities are preserved for audit purposes
  2. User information can be anonymized
  3. Activities show "Deleted User" for anonymized accounts

Troubleshooting

Activities not appearing?

  1. Check permissions - Regular users only see their own activities
  2. Verify integration - Ensure the route has Activity.log() calls
  3. Database issues - Check logs for database errors
  4. Browser cache - Clear cache or hard refresh the dashboard

Widget not loading?

  1. Check API endpoint - Visit /api/activities directly
  2. JavaScript errors - Check browser console for errors
  3. Authentication - Ensure user is logged in
  4. Network issues - Check network tab in dev tools

Missing activities for certain actions?

Some features may not have activity logging integrated yet. Check the "Already Integrated" section above.

Future Enhancements

Planned improvements for the Activity Feed:

  • Export activities to CSV/JSON
  • Email notifications for specific activities
  • Advanced search and filtering
  • Activity feed for specific projects/tasks
  • Webhook integration for external systems
  • Custom activity types and actions
  • Activity trends and analytics dashboard

Support

For issues or questions about the Activity Feed: