Usage

After deploying BookYourPTO, follow this guide to create your first organization, manage users, and configure leave policies.

First Time Setup

Create Your Organization

1. Navigate to http://{serverip}:3010 (or your configured URL)
2. Click Register to create the first administrator account
3. Fill in your organization details:
   • Organization name
   • Admin email and password
   • Time zone and country (for holiday detection)

Configure Leave Types

BookYourPTO includes 8+ pre-configured leave types, including:

• Annual Leave
• Sick Leave
• Maternity/Paternity Leave
• Unpaid Leave
• Remote Work Days
• Custom leave types

Navigate to Settings > Leave Types to enable, disable, or customize leave types for your organization.

Managing Users

Adding Users

Individual Users:

1. Go to Users > Add User
2. Enter employee details (name, email, department, role)
3. Set initial leave balance
4. Click Create User

Bulk Import:

1. Go to Users > Import
2. Download the CSV template
3. Fill in user details
4. Upload the completed CSV file

User Roles

BookYourPTO supports five role levels:

• Employee: Can request leave and view their own records
• Department Head: Can approve department-wide requests
• HR: Full access to leave records and reporting
• Administrator: Complete system access including organization settings

Leave Management

Requesting Time Off

Employees can submit leave requests by:

1. Navigating to Calendar or Dashboard
2. Clicking Request Leave
3. Selecting leave type, dates, and duration (full, half, or quarter-day)
4. Adding optional notes
5. Submitting for approval

Approval Workflows

Configure multi-level approval chains in Settings > Workflows:

Employee → Department Head → Administrator

You can customize approval paths based on:

• Leave type (e.g., sick leave requires only department head approval)
• Duration
• Department structure

Balance Tracking

Leave balances are automatically calculated based on:

• Accrual schedules: Monthly, yearly, or custom
• Carry-forward policies: How unused leave transfers to next year
• Expiry rules: When unused leave expires

Configure these in Settings > Leave Policies.

Calendar Integration

Connect Google Calendar

1. Go to Settings > Integrations
2. Click Connect Google Calendar
3. Authorize BookYourPTO to access your calendar
4. Approved leave will automatically sync as calendar events

Connect Outlook

1. Go to Settings > Integrations
2. Click Connect Outlook
3. Sign in with your Microsoft account
4. Calendar events will be created for approved leave

Multi-Tenancy Setup

If you're hosting multiple organizations:

Create New Tenant

1. Navigate to System Admin > Organizations
2. Click Add Organization
3. Configure tenant-specific settings:
   • Custom branding (logo, colors)
   • Subdomain or custom domain
   • Isolated database schema

White-Labeling

Customize each organization's appearance:

1. Go to Settings > Branding
2. Upload custom logos (light and dark mode)
3. Configure custom domain (requires DNS setup)

Reporting and Analytics

Generate Reports

Access reports from Reports section:

• Leave balance reports (by department, user, or leave type)
• Approval history and audit trails
• Team availability forecasts
• Trend analysis (peak leave periods)

Export Options

All reports can be exported in:

• CSV format (for Excel/Google Sheets)
• PDF format (for printing or sharing)
• JSON format (for custom integrations)

App Configuration

BookYourPTO uses app.config.ts for UI customization powered by Nuxt UI.

Header Configuration

export default defineAppConfig({
  header: {
    title: 'BookYourPTO',
    to: '/',
    logo: {
      alt: 'BookYourPTO',
      light: '/logo-light.svg',
      dark: '/logo-dark.svg'
    },
    search: true,
    colorMode: true,
    links: [{
      icon: 'i-simple-icons-github',
      to: 'https://github.com/anhourtec/BookYourPTO',
      target: '_blank',
      aria-label: 'GitHub'
    }]
  }
})

Theme Customization

Customize colors in app.config.ts:

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'slate'
    }
  }
})

Available color options: blue, green, red, yellow, purple, pink, indigo, cyan, slate, zinc, gray

Footer Configuration

export default defineAppConfig({
  footer: {
    credits: `Open-source by AnHourTec -  © ${new Date().getFullYear()}`,
    colorMode: false,
    links: [{
      icon: 'i-simple-icons-github',
      to: 'https://github.com/anhourtec/BookYourPTO',
      target: '_blank',
      aria-label: 'BookYourPTO on GitHub'
    }]
  }
})

Email Notifications

Configure SMTP

Set up email notifications in .env:

SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="noreply@yourdomain.com"

Notification Types

BookYourPTO sends automated emails for:

• Leave request submissions
• Approval/rejection notifications
• Balance low warnings
• Upcoming leave reminders
• Approval timeout escalations

Customize email templates in Settings > Email Templates.

Security Best Practices

Regular Backups

Backup your PostgreSQL database regularly:

docker exec bookyourpto-postgres pg_dump -U postgres bookyourpto > backup.sql

Access Control

• Review user roles quarterly
• Disable inactive user accounts
• Enable two-factor authentication (if available)
• Monitor audit logs for suspicious activity

Data Retention

Configure data retention policies in Settings > Compliance:

• How long to keep historical leave records
• Audit log retention period
• User data deletion policies (GDPR compliance)

Getting Help

• Documentation: Browse this documentation site
• GitHub Issues: Report bugs or request features at github.com/anhourtec/BookYourPTO/issues
• Community: Join discussions and get support from other users
• AnHourTec: Visit forum.bookyourpto.com for support forum or raise issue on github.