WoPora
Request access
Getting Started

First Setup

Complete your initial Timesheet setup by creating admin users, locations, roles, and basic configuration.

First Setup

After installing and configuring Timesheet, this guide will walk you through the initial setup process to get your workforce management system ready for use.

Initial Database Setup

1. Run Database Migrations

# Run database setup and migrations
npm run db:setup

# This will:
# - Create database indexes
# - Set up initial collections
# - Create default categories
# - Run any pending migrations

2. Verify Database Connection

# Test database connectivity
npm run db:check

# Expected output:
# ✓ Database connection successful
# ✓ Collections created
# ✓ Indexes created

Create Your First Admin User

  1. Start the Application

    npm run dev

  2. Access Setup Wizard

    • Navigate to http://localhost:3000/setup
    • The setup wizard will guide you through creating your first admin user

  3. Complete Admin Setup

    • Enter admin details (name, email, password)
    • Set company information
    • Configure basic settings

Option 2: Command Line Setup

# Create admin user via CLI
npm run setup:admin

# Follow the prompts:
# - Admin name: John Smith
# - Email: admin@yourcompany.com
# - Password: [secure password]
# - Role: super_admin

Option 3: Database Direct Insert

If other methods fail, you can create an admin user directly:

// Connect to MongoDB and run this script
use timesheet

db.users.insertOne({
  name: "System Administrator",
  email: "admin@yourcompany.com",
  password: "$2b$10$hashedPasswordHere", // Use bcrypt to hash
  role: "super_admin",
  isActive: true,
  createdAt: new Date(),
  updatedAt: new Date()
})

Configure Basic Categories

Categories are the foundation of Timesheet's organisation system. Set up these essential categories:

1. Create Employers

Employers represent the different business entities or departments:

# Via API or admin interface
POST /api/categories
{
  "name": "Main Company Pty Ltd",
  "type": "employer",
  "color": "#3b82f6"
}

Common Employer Examples:

  • Main Company Pty Ltd
  • Subsidiary Company
  • Franchise Location A
  • Department - Sales
  • Department - Operations

2. Create Locations

Locations are physical places where employees work:

# Create location with geofencing
POST /api/categories
{
  "name": "Head Office",
  "type": "location",
  "address": "123 Collins Street, Melbourne VIC 3000",
  "lat": -37.8136,
  "lng": 144.9631,
  "radius": 100,
  "geofenceMode": "soft",
  "openingHour": 8,
  "closingHour": 18,
  "workingDays": [1, 2, 3, 4, 5]
}

Location Configuration:

  • Address: Full street address
  • Coordinates: Latitude and longitude for geofencing
  • Radius: Geofence radius in metres (typically 50-200m)
  • Geofence Mode:
    • soft: Warning when outside radius
    • hard: Block clock-in when outside radius
  • Working Hours: Opening and closing times (24-hour format)
  • Working Days: Array of days (0=Sunday, 1=Monday, etc.)

3. Create Roles

Roles define what employees can do and their pay rates:

# Create employee role
POST /api/categories
{
  "name": "Casual Employee",
  "type": "role",
  "color": "#10b981",
  "defaultScheduleTemplate": {
    "standardHoursPerWeek": 20,
    "shiftPattern": {
      "dayOfWeek": [1, 2, 3, 4, 5],
      "startHour": 9,
      "endHour": 17,
      "description": "Standard weekday shifts"
    }
  }
}

Common Role Examples:

  • Casual Employee
  • Part-time Employee
  • Full-time Employee
  • Manager
  • Supervisor
  • Team Leader

Set Up Your First Employee

1. Create Employee Record

# Create employee via API
POST /api/employees
{
  "name": "Jane Smith",
  "pin": "1001",
  "email": "jane.smith@yourcompany.com",
  "phone": "0412 345 678",
  "employer": ["Main Company Pty Ltd"],
  "role": ["Casual Employee"],
  "location": ["Head Office"],
  "employmentType": "casual",
  "standardHoursPerWeek": 20
}

2. Assign Role and Location

Employee role assignments link employees to specific roles at specific locations:

# This is automatically created when using the role/location fields above
# Or create manually via EmployeeRoleAssignment
{
  "employeeId": "employee_object_id",
  "roleId": "role_category_id", 
  "locationId": "location_category_id",
  "validFrom": "2024-01-01T00:00:00Z",
  "validTo": null,
  "isActive": true
}

Configure Awards (Australian Compliance)

If you're operating in Australia, set up award wages:

1. Create Basic Award

POST /api/awards
{
  "name": "Retail Industry Award 2020",
  "description": "Modern award for retail employees",
  "isActive": true,
  "levels": [
    {
      "label": "Level 1 - Retail Employee",
      "conditions": [
        {
          "employmentType": "casual",
          "breakPolicy": "auto",
          "breakRules": [
            {
              "label": "Unpaid meal break",
              "minHours": 5,
              "maxHours": null,
              "breakMinutes": 30,
              "paid": false
            }
          ],
          "payRule": {
            "type": "hourly",
            "rate": 25.50,
            "currency": "AUD"
          },
          "penaltyRules": [
            {
              "label": "Weekend penalty",
              "triggerType": "day_of_week",
              "days": ["Saturday", "Sunday"],
              "rateType": "multiplier",
              "rateValue": 1.25,
              "stackable": false
            }
          ]
        }
      ]
    }
  ]
}

2. Assign Award to Employee

# Update employee with award assignment
PATCH /api/employees/{employeeId}
{
  "awardId": "award_object_id",
  "awardLevel": "Level 1 - Retail Employee",
  "employmentType": "casual"
}

Set Up Device Management

If you're using kiosk devices for clock-in/out:

1. Register Device

POST /api/devices
{
  "deviceName": "Kiosk 1 - Head Office",
  "locationName": "Head Office",
  "locationAddress": "123 Collins Street, Melbourne VIC 3000",
  "status": "active"
}

2. Generate Activation Code

The system will generate an activation code that employees can use to activate the device on first use.

Configure System Settings

1. Company Information

Update company details in the admin interface:

  • Company name and logo
  • Contact information
  • Default timezone
  • Date/time formats

2. Notification Settings

Configure email notifications:

  • Late arrival alerts
  • Overtime notifications
  • System error alerts
  • Admin notification email

3. Security Settings

Review and configure:

  • Password requirements
  • Session timeout
  • Rate limiting
  • Audit logging

Test Your Setup

1. Test Employee Clock-In

  1. Access Clock Interface

    • Navigate to http://localhost:3000/clock
    • Or use the PIN entry at http://localhost:3000/pin

  2. Enter Employee PIN

    • Enter the PIN you created (e.g., "1001")
    • Allow camera and location permissions

  3. Clock In

    • Take a photo (if face detection enabled)
    • Verify location is detected
    • Click "CLOCK IN"

2. Verify Timesheet Data

  1. Check Dashboard

    • Navigate to http://localhost:3000/dashboard/timesheet
    • Verify the clock-in entry appears

  2. Test Clock Out

    • Return to clock interface
    • Enter same PIN
    • Click "CLOCK OUT"

3. Test Admin Functions

  1. Employee Management

    • Add/edit employee details
    • Assign roles and locations
    • Upload employee photos

  2. Reporting

    • Generate timesheet reports
    • Export CSV data
    • View analytics dashboard

Backup and Security

1. Set Up Database Backups

# Create backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mongodump --uri="$MONGODB_URI" --out="/backups/timesheet_$DATE"

2. Configure SSL/HTTPS

For production environments:

  • Obtain SSL certificate
  • Configure reverse proxy (Nginx/Apache)
  • Update NEXTAUTH_URL to use HTTPS
  • Set SECURE_COOKIES=true

3. Review Security Settings

  • Change default passwords
  • Enable two-factor authentication
  • Configure firewall rules
  • Set up monitoring and alerts

Troubleshooting Common Issues

Admin User Creation Fails

# Check database connection
npm run db:check

# Verify environment variables
echo $MONGODB_URI

# Check for existing admin users
mongosh $MONGODB_URI --eval "db.users.find({role: 'super_admin'})"

Clock-In Not Working

  • Verify camera permissions in browser
  • Check location services are enabled
  • Ensure geofencing is configured correctly
  • Check browser console for JavaScript errors

Email Notifications Not Sending

  • Test SMTP configuration
  • Check spam/junk folders
  • Verify email credentials
  • Review application logs

Next Steps

After completing the first setup:

  1. Employee Onboarding - Add all your employees and configure their roles
  2. Schedule Setup - Create rosters and shift patterns
  3. Award Configuration - Set up detailed award wages and penalty rates
  4. Device Deployment - Set up kiosk devices at work locations
  5. Training - Train managers and employees on using the system

Congratulations! Your Timesheet system is now ready for use. Employees can start clocking in/out, and you can begin tracking time and generating reports.

Getting Help

If you encounter issues during setup:

  • Check the application logs for error messages
  • Verify all environment variables are correctly set
  • Ensure database connectivity
  • Review the troubleshooting section in each guide
  • Contact support with specific error messages and logs

Configuration

Complete guide to configuring environment variables and external services for Timesheet.

Employee Management

Complete guide to managing employees, roles, assignments, and profiles in Timesheet.

On this page

First SetupInitial Database Setup1. Run Database Migrations2. Verify Database ConnectionCreate Your First Admin UserOption 1: Setup Wizard (Recommended)Option 2: Command Line SetupOption 3: Database Direct InsertConfigure Basic Categories1. Create Employers2. Create Locations3. Create RolesSet Up Your First Employee1. Create Employee Record2. Assign Role and LocationConfigure Awards (Australian Compliance)1. Create Basic Award2. Assign Award to EmployeeSet Up Device Management1. Register Device2. Generate Activation CodeConfigure System Settings1. Company Information2. Notification Settings3. Security SettingsTest Your Setup1. Test Employee Clock-In2. Verify Timesheet Data3. Test Admin FunctionsBackup and Security1. Set Up Database Backups2. Configure SSL/HTTPS3. Review Security SettingsTroubleshooting Common IssuesAdmin User Creation FailsClock-In Not WorkingEmail Notifications Not SendingNext StepsGetting Help