216 lines
7.0 KiB
Markdown
216 lines
7.0 KiB
Markdown
# Employee Workstation Activity Tracking System
|
|
|
|
A comprehensive system for tracking user activity on Windows workstations and reporting it to a central server. The system logs user logon events and monitors active/inactive periods, providing detailed reports through a web dashboard.
|
|
|
|
## Overview
|
|
|
|
This system consists of two main components:
|
|
|
|
1. **Client Agent**: A PowerShell script that runs on Windows workstations to detect user idle time and report activity state changes.
|
|
2. **Server Application**: A Flask-based web application that receives activity reports, stores them in a database, and provides reporting capabilities.
|
|
|
|
The system tracks when users are "working" or "stopped" based on a 5-minute inactivity threshold, allowing organizations to measure effective working time.
|
|
|
|
## Client-Side Setup
|
|
|
|
### Prerequisites
|
|
|
|
* Windows 10/11 workstations
|
|
* PowerShell 3.0 or higher
|
|
* Administrative access (for setting up scheduled tasks)
|
|
|
|
### Installation
|
|
|
|
1. Copy the `report.ps1` script to a secure location on the workstation (e.g., `C:\Scripts\`)
|
|
|
|
2. Copy `config.env` to the same location as the PowerShell script, or set the following environment variables:
|
|
- `API_ENDPOINT`: URL of the server's reporting endpoint
|
|
- `IDLE_THRESHOLD_MINUTES`: Inactivity threshold in minutes (default: 5)
|
|
- `POLL_INTERVAL_SECONDS`: How often to check for idle state (default: 60)
|
|
|
|
3. Run the `schedule_task.ps1` script with administrative privileges to create the scheduled task:
|
|
|
|
```powershell
|
|
.\schedule_task.ps1 -ScriptPath "C:\Scripts\report.ps1"
|
|
```
|
|
|
|
The script will automatically run when users log on to the workstation.
|
|
|
|
## Server-Side Setup
|
|
|
|
### Prerequisites
|
|
|
|
* Python 3.9 or higher
|
|
* SQLite (development) or PostgreSQL (production)
|
|
* pip (Python package manager)
|
|
|
|
### Installation
|
|
|
|
1. Clone this repository to your server
|
|
|
|
2. Create and activate a virtual environment:
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. Install the required packages:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. Create a configuration file:
|
|
|
|
```bash
|
|
cp config.env.example config.env
|
|
```
|
|
|
|
5. Edit `config.env` with your specific settings:
|
|
- `DATABASE_URI`: Connection string for your database
|
|
- `API_ENDPOINT`: URL for the reporting endpoint
|
|
- Other configuration parameters
|
|
|
|
6. Set up the database:
|
|
|
|
```bash
|
|
# For SQLite
|
|
sqlite3 work_events.db < create_db.sql
|
|
|
|
# For PostgreSQL
|
|
psql -U username -d database_name -f create_db.sql
|
|
```
|
|
|
|
7. Run the application:
|
|
|
|
```bash
|
|
# Development
|
|
python run.py
|
|
|
|
# Production (with Gunicorn)
|
|
gunicorn -w 4 -b 0.0.0.0:5000 "app:create_app()"
|
|
```
|
|
|
|
## System Architecture
|
|
|
|
### Client Agent
|
|
|
|
The PowerShell script:
|
|
- Is launched at user logon via Task Scheduler
|
|
- Monitors user idle time using the `quser` command or Win32 API calls
|
|
- Reports state changes to the server via HTTP POST requests
|
|
- Uses the built-in `Invoke-RestMethod` cmdlet for API communication
|
|
- Implements error handling and local logging
|
|
- Supports configuration via environment variables or config.env file
|
|
|
|
### Server Application
|
|
|
|
The Flask application:
|
|
- Uses a modular structure with separate components for models, views, and API endpoints
|
|
- Exposes a RESTful API endpoint at `/api/report`
|
|
- Stores activity events in a relational database
|
|
- Provides reporting functionality via SQL aggregation
|
|
- Includes a web dashboard for visualizing activity data
|
|
- Supports SQLite for development and PostgreSQL for production
|
|
|
|
#### Application Structure
|
|
|
|
```
|
|
user_work_tracking/
|
|
├── app/ # Application package
|
|
│ ├── api/ # API endpoints
|
|
│ │ ├── events.py # Event reporting endpoints
|
|
│ │ └── reports.py # Data reporting endpoints
|
|
│ ├── utils/ # Utility functions
|
|
│ │ ├── formatting.py # Data formatting functions
|
|
│ │ └── queries.py # SQL query functions
|
|
│ ├── views/ # Web views
|
|
│ │ └── dashboard.py # Dashboard views
|
|
│ ├── models.py # Database models
|
|
│ └── errors.py # Error handlers
|
|
├── instance/ # Instance-specific data
|
|
├── static/ # Static files
|
|
│ ├── css/ # CSS stylesheets
|
|
│ └── js/ # JavaScript files
|
|
├── templates/ # HTML templates
|
|
├── create_db.sql # Database schema creation script
|
|
├── config.env # Configuration file
|
|
├── report.ps1 # Client-side PowerShell script
|
|
├── schedule_task.ps1 # Task scheduler setup script
|
|
├── requirements.txt # Python dependencies
|
|
└── run.py # Application entry point
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Report Activity Endpoint
|
|
|
|
**URL**: `/api/report`
|
|
**Method**: `POST`
|
|
**Auth**: None (LAN-restricted)
|
|
|
|
**Request Body**:
|
|
```json
|
|
{
|
|
"user": "username",
|
|
"state": "working",
|
|
"ts": "2023-07-08T12:30:45Z"
|
|
}
|
|
```
|
|
|
|
Fields:
|
|
- `user`: Windows username
|
|
- `state`: Either "working" or "stopped"
|
|
- `ts`: ISO 8601 timestamp (optional, defaults to server time)
|
|
|
|
**Success Response**:
|
|
```json
|
|
{
|
|
"success": true
|
|
}
|
|
```
|
|
|
|
## Reporting
|
|
|
|
Access the dashboard by navigating to `http://your-server-address:5000/` in a web browser.
|
|
|
|
The system provides:
|
|
- Daily, weekly, and monthly summaries of working time
|
|
- First login time tracking
|
|
- User activity breakdowns with detailed logs
|
|
- Interactive date navigation
|
|
|
|
## Troubleshooting
|
|
|
|
### Client Issues
|
|
|
|
- Check the log file at `%USERPROFILE%\AppData\Local\Temp\user_work_tracking_client.log`
|
|
- Verify the scheduled task is configured correctly in Task Scheduler
|
|
- Test the script manually: `.\report.ps1`
|
|
- Make sure the `config.env` file or environment variables are correctly set
|
|
|
|
### Server Issues
|
|
|
|
- Check the application logs in the `instance` directory
|
|
- Verify database connectivity
|
|
- Ensure the server is accessible from client workstations
|
|
- When using PostgreSQL, ensure column names are properly quoted (especially "user" which is a reserved keyword)
|
|
- If users appear incorrectly in the dashboard, check the SQL queries to ensure proper schema specification (e.g., "public.work_events")
|
|
|
|
### PostgreSQL-Specific Issues
|
|
|
|
- **Reserved Keywords**: Be careful with reserved keywords like "user". Always quote them with double quotes in SQL queries.
|
|
- **Schema Specification**: Explicitly reference the schema (e.g., "public.work_events" instead of just "work_events") to avoid potential naming conflicts.
|
|
- **Connection String**: Ensure the database URI in config.env uses the correct username, password, and database name.
|
|
- **Database vs Login Role**: The PostgreSQL username used to connect to the database is separate from the usernames stored in the "user" column of work_events table.
|
|
|
|
## Security Considerations
|
|
|
|
- The system is designed for internal LAN use only and lacks authentication
|
|
- Ensure the server is not exposed to the public internet
|
|
- Consider implementing network-level access controls
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details. |