Timedoctor

TimeDoctor Skill

Interact with TimeDoctor API for employee time tracking, activity logs, productivity statistics, and workforce analytics using simple Python CLI commands.

What This Skill Does

Provides direct access to TimeDoctor's time tracking API through a Python CLI tool. Execute commands, get JSON data, present formatted results to users.

Setup Instructions

For Users: Getting TimeDoctor Credentials

Option 1: Easy Setup (Recommended)

Just provide your TimeDoctor email and password:

python3 timedoctor.py login --email "your-email@company.com" --password "your-password"

This returns a JWT token valid for 6 months. Copy the token and set it:

export TIMEDOCTOR_TOKEN="your-jwt-token-from-login-response"

Option 2: Manual Token Setup

If you already have a token or prefer manual setup:

# Required
export TIMEDOCTOR_TOKEN="your-jwt-token"

# Optional (can be discovered via get_authorization)
export TIMEDOCTOR_COMPANY_ID="your-company-id"

For Multiple Accounts: Users can switch accounts by changing the token:

# Account 1
export TIMEDOCTOR_TOKEN="token-for-account-1"
export TIMEDOCTOR_COMPANY_ID="company-id-1"

# Account 2  
export TIMEDOCTOR_TOKEN="token-for-account-2"
export TIMEDOCTOR_COMPANY_ID="company-id-2"

Quick Setup Workflow:

# 1. Login to get token
python3 timedoctor.py login --email "user@company.com" --password "password"

# 2. Copy token from response and set it
export TIMEDOCTOR_TOKEN="1jxExVs9WGsWccrq2ysMKMZVZlTVyTZc15tlgcWF_Qns"

# 3. Discover available companies
python3 timedoctor.py get_authorization

# 4. Set company ID (optional)
export TIMEDOCTOR_COMPANY_ID="aFtR8crWxHTeLzIm"

# 5. Start using commands
python3 timedoctor.py get_today_worklog --company-id $TIMEDOCTOR_COMPANY_ID

How to Use This Skill

Core Command Pattern

All commands follow this pattern:

python3 timedoctor.py COMMAND [--company-id ID] [OPTIONS]

The script is located in the skill directory and returns JSON output.

Key Commands

Login (Get JWT Token):

python3 timedoctor.py login --email "user@company.com" --password "password"

Returns: JWT token valid for 6 months

Discover Available Companies:

python3 timedoctor.py get_authorization

Returns: User info and list of accessible companies with IDs

Today's Activity:

python3 timedoctor.py get_today_worklog --company-id COMPANY_ID

This Week's Stats:

python3 timedoctor.py get_this_week_stats --company-id COMPANY_ID

This Month's Stats:

python3 timedoctor.py get_this_month_stats --company-id COMPANY_ID

Custom Date Range:

python3 timedoctor.py get_worklog \
  --company-id COMPANY_ID \
  --from-date "2024-03-01T00:00:00Z" \
  --to-date "2024-03-31T00:00:00Z"

List Users:

python3 timedoctor.py get_users --company-id COMPANY_ID

List Projects:

python3 timedoctor.py get_projects --company-id COMPANY_ID

Filter by Users:

python3 timedoctor.py get_today_worklog --company-id COMPANY_ID --user-ids "123,456,789"

Understanding TimeDoctor Account Structure

Account Hierarchy

TimeDoctor User Account (requires TIMEDOCTOR_TOKEN)
  └── Company A (ID: 12345)
      ├── User 1
      ├── User 2
      └── Projects...
  └── Company B (ID: 67890)
      ├── User 3
      ├── User 4
      └── Projects...
  └── Company C (ID: 11111)
      └── Users...

Key Concepts

1. One Token = One User Account

   • Each TIMEDOCTOR_TOKEN represents one TimeDoctor user login
   • Example: john@acme.com has one token

2. One Account Can Access Multiple Companies

   • A user can be part of multiple companies
   • Same token works for all companies they have access to
   • Switch companies using different --company-id

3. Different User Accounts Need Different Tokens

   • john@acme.com has token A
   • jane@beta.com has token B
   • To switch from John to Jane, change TIMEDOCTOR_TOKEN

Example Scenarios

Scenario 1: User with Multiple Companies

User: "Show my companies"
Agent: Runs get_authorization
Response shows:
  - Acme Corp (12345)
  - Beta Startup (67890)
  - Gamma LLC (11111)

Agent: "You have access to 3 companies. Which one?"
User: "Acme Corp"
Agent: Uses --company-id 12345 for all subsequent requests

Scenario 2: Switching Companies

User: "Now show me Beta Startup's data"
Agent: Remembers Beta Startup = 67890 from earlier
Agent: Uses --company-id 67890
No token change needed!

Scenario 3: Switching User Accounts

User: "I want to use my other TimeDoctor account"
Agent: "You need to update your token. Run:
        export TIMEDOCTOR_TOKEN='your-other-token'"
User: Updates token
Agent: Runs get_authorization with new token
Agent: Shows new list of companies for that account

Agent Instructions

When User Asks About TimeDoctor Data

Follow this workflow:

1. Check if User Has Token

   • If TIMEDOCTOR_TOKEN is not set, help them login:

     "To get started, I need your TimeDoctor credentials.
     
     I'll run: python3 timedoctor.py login --email YOUR_EMAIL --password YOUR_PASSWORD
     
     What's your TimeDoctor email and password?"
     

   • After getting credentials, run login command
   • Extract token from response
   • Tell user to set: export TIMEDOCTOR_TOKEN="extracted-token"
   • Explain token is valid for 6 months

2. Discover and Present Available Companies

   • ALWAYS run get_authorization first if company_id is not known
   • Parse the response to extract all accessible companies
   • Present to user in a clear format:

     You have access to these TimeDoctor companies:
     1. Company A (ID: 12345)
     2. Company B (ID: 67890)
     3. Company C (ID: 11111)
     
     Which company would you like to use?
     

   • Wait for user to select
   • Remember the selected company_id for subsequent requests in this session

3. Execute Appropriate Command

   • Match user's request to the right command
   • Use convenience commands when possible (get_today_worklog, get_this_week_stats, etc.)
   • Always include --company-id parameter with the selected company

4. Handle Multiple Accounts

   • One TIMEDOCTOR_TOKEN = One user account
   • One user account can have access to multiple companies
   • To switch to a completely different TimeDoctor user account, user must update TIMEDOCTOR_TOKEN
   • To switch between companies under same account, just use different --company-id

5. Parse and Format Output

   • Check for {"error": "..."} first
   • Convert JSON to readable format (tables, lists, summaries)
   • Highlight key metrics (total hours, productive time, etc.)
   • Format durations as "X hours Y minutes"

6. Error Recovery

   • "TIMEDOCTOR_TOKEN environment variable not set" → Help user login with email/password
   • "company_id required" → Run get_authorization to discover companies
   • "401 Unauthorized" → Token expired, user needs to login again (6-month validity)

Date Format Rules

ALWAYS use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Examples:

• Start of day: 2024-03-22T00:00:00Z
• End of day: 2024-03-23T00:00:00Z
• For single day: from 2024-03-22T00:00:00Z to 2024-03-23T00:00:00Z

Calculating Dates:

• Today: Use get_today_worklog (automatic)
• This week: Use get_this_week_stats (automatic, Monday to today)
• This month: Use get_this_month_stats (automatic, 1st to today)
• Custom: Calculate dates and use get_worklog or get_stats_total

Response Formatting Guidelines

For Worklogs:

• Show as table: User | Start Time | End Time | Duration | Activity
• Group by user or by date depending on context
• Summarize total hours at bottom

For Statistics:

• Show key metrics: Total Time, Productive Time, Unproductive Time, Idle Time
• Calculate percentages (e.g., "75% productive")
• Highlight outliers or unusual patterns

For Lists (users, projects, tasks):

• Show as numbered or bulleted list
• Include relevant IDs for follow-up queries
• Limit to top 10-20 unless user asks for more

Common Workflows

Workflow 0: First Time Setup - Login and Get Token

User: "I want to use TimeDoctor"

Steps:
1. Check if TIMEDOCTOR_TOKEN is set
2. If not, ask for credentials:
   
   "To get started, I need your TimeDoctor login credentials.
   
   What's your TimeDoctor email and password?"

3. User provides: "email@company.com" and "password123"
4. Run: python3 timedoctor.py login --email "email@company.com" --password "password123"
5. Parse response and extract token
6. Tell user:
   
   "Great! I got your token. It's valid for 6 months (until September 2026).
   
   Please set it in your environment:
   export TIMEDOCTOR_TOKEN='1jxExVs9WGsWccrq2ysMKMZVZlTVyTZc15tlgcWF_Qns'
   
   Once set, I can pull your TimeDoctor data."

7. After user confirms, proceed to Workflow 1 to discover companies

Workflow 1: First Time Setup - Discover Companies

User: "Show me today's activity"

Steps:
1. Check if you know the company_id for this session
2. If not, run: python3 timedoctor.py get_authorization
3. Parse response and present companies:
   
   "I found these TimeDoctor companies you have access to:
   
   1. Acme Corp (ID: 12345) - 45 users
   2. Beta Inc (ID: 67890) - 12 users
   3. Gamma LLC (ID: 11111) - 8 users
   
   Which company would you like to check?"

4. User responds: "Acme Corp" or "1" or "12345"
5. Remember company_id = 12345 for this session
6. Run: python3 timedoctor.py get_today_worklog --company-id 12345
7. Parse JSON and create table:
   | User | Hours Worked | Productive % | Projects |
8. Add summary: "Total: X hours across Y users"

Workflow 2: Daily Team Report (Company Already Known)

User: "Show today's activity for the team"

Steps:
1. Use remembered company_id from session
2. Run: python3 timedoctor.py get_today_worklog --company-id COMPANY_ID
3. Parse JSON and create table:
   | User | Hours Worked | Productive % | Projects |
4. Add summary: "Total: X hours across Y users"

Workflow 3: Switching Between Companies

User: "Show me stats for Beta Inc instead"

Steps:
1. Run: python3 timedoctor.py get_authorization
2. Find "Beta Inc" in the companies list
3. Extract company_id (67890)
4. Update session to remember new company_id
5. Confirm: "Switched to Beta Inc (ID: 67890)"
6. Run requested command with new company_id

Workflow 4: Individual User Report

User: "Show today's activity for the team"

Steps:
1. Check if TIMEDOCTOR_COMPANY_ID is set in environment
2. If not, run: python3 timedoctor.py get_authorization
3. Extract company_id from response
4. Run: python3 timedoctor.py get_today_worklog --company-id COMPANY_ID
5. Parse JSON and create table:
   | User | Hours Worked | Productive % | Projects |
6. Add summary: "Total: X hours across Y users"

Workflow 2: Individual User Report

User: "How much did John work this week?"

Steps:
1. Run: python3 timedoctor.py get_users --company-id COMPANY_ID
2. Find John's user_id in response
3. Run: python3 timedoctor.py get_this_week_stats --company-id COMPANY_ID --user-ids "JOHN_ID"
4. Parse and present:
   - Total hours: X
   - Productive time: Y (Z%)
   - Top projects: ...
   - Daily breakdown: Mon: X hrs, Tue: Y hrs, ...

Workflow 5: Project Time Analysis

User: "How much time was spent on Project Alpha last month?"

Steps:
1. Run: python3 timedoctor.py get_projects --company-id COMPANY_ID
2. Find "Project Alpha" and get its project_id
3. Calculate last month's date range (1st to last day)
4. Run: python3 timedoctor.py get_stats_total \
   --company-id COMPANY_ID \
   --from-date "YYYY-MM-01T00:00:00Z" \
   --to-date "YYYY-MM-31T23:59:59Z" \
   --project-id PROJECT_ID
5. Present breakdown by user and total

Workflow 6: Switching TimeDoctor User Accounts

User: "I want to use my other TimeDoctor account"

Steps:
1. Explain: "To switch to a different TimeDoctor user account, you need to update your token."
2. Provide instructions:
   
   "Please run these commands with your other account's token:
   
   export TIMEDOCTOR_TOKEN="your-other-account-token"
   
   Then let me know when you're ready."

3. After they confirm, run: python3 timedoctor.py get_authorization
4. Present available companies for the new account:
   
   "Now connected as [User Name]. You have access to:
   
   1. Company X (ID: 99999)
   2. Company Y (ID: 88888)
   
   Which company would you like to use?"

5. Remember the selected company_id for this session

Session Management

Remember Company Selection

Once a user selects a company, remember it for the entire conversation session:

Session State:
- current_company_id: 12345
- current_company_name: "Acme Corp"
- current_token_user: "john@acme.com"

When to Re-prompt for Company

Ask user to select company again when:

• First request in a new session
• User explicitly asks to switch companies
• User says "use a different company"
• Error indicates wrong company access

Don't Re-prompt When

• User makes multiple requests in same session
• Company is already known and working
• User hasn't indicated they want to change

Presenting Company Lists

Format 1: Numbered List (Preferred)

You have access to these TimeDoctor companies:

1. Acme Corporation (ID: 12345)
   - 45 active users
   - Role: Admin

2. Beta Startup (ID: 67890)
   - 12 active users
   - Role: Manager

3. Gamma Consulting (ID: 11111)
   - 8 active users
   - Role: User

Which company would you like to use? (Enter number, name, or ID)

Format 2: Simple List

Available companies:
• Acme Corporation (12345)
• Beta Startup (67890)
• Gamma Consulting (11111)

Which one?

Format 3: Single Company

You have access to: Acme Corporation (ID: 12345)

I'll use this company for your requests.

Handling User Selection

Accept any of these formats:

• Number: "1" or "2"
• Name: "Acme Corporation" or "Acme" or "acme"
• ID: "12345"

Match flexibly:

• Case-insensitive name matching
• Partial name matching (if unambiguous)
• Direct ID matching

Available Commands Reference

Authentication

• login - Login with email/password to get JWT token (valid 6 months)
• get_authorization - Get user info and available companies
• get_companies - List all accessible companies
• get_company - Get specific company details

Users

• get_users - List users in company
• get_user - Get specific user details
• get_managed_users - Get users managed by a manager

Activity & Worklogs

• get_activity_worklog - Detailed work activity log
• get_activity_timeuse_stats - Time usage statistics
• get_disconnectivity - Offline/disconnected periods
• get_today_worklog - Today's worklog (convenience)

Statistics

• get_stats_total - Aggregated total statistics
• get_stats_category - Stats by productivity category (4=Productive, 3=Neutral, 2=Unproductive, 0=Unrated)
• get_stats_summary - Summary stats over time
• get_stats_work_life - Work-life balance stats
• get_stats_shift - Shift compliance stats
• get_stats_outliers - Unusual activity patterns
• get_this_week_stats - This week's stats (convenience)
• get_this_month_stats - This month's stats (convenience)

Timesheet

• get_timesheet_total - Timesheet totals
• get_timesheet_summary - Timesheet summary

Projects & Tasks

• get_projects - List projects
• get_project - Get project details
• get_tasks - List tasks
• get_task - Get task details

Groups & Schedules

• get_groups - List groups/teams
• get_group - Get group details
• get_work_schedules - List work schedules
• get_work_schedule - Get schedule details
• get_work_schedule_issues - Schedule violations
• get_leave_stats - Leave/time-off stats

Payroll & Files

• get_users_payroll - User payroll info
• get_company_payroll_settings - Company payroll settings
• get_files - Screenshots/screencasts
• get_categories - Productivity categories
• get_unrated_categories_count - Count of unrated items

Command Options

Common options across commands:

• --company-id COMPANY_ID - Required for most commands
• --user-ids "123,456" - Filter by specific users (comma-separated)
• --from-date "2024-03-01T00:00:00Z" - Start date (ISO 8601)
• --to-date "2024-03-31T00:00:00Z" - End date (ISO 8601)
• --project-id PROJECT_ID - Filter by project
• --page 1 - Page number for pagination
• --limit 100 - Results per page (max 1000)

Tips for Effective Use

1. Always check for errors first - Look for {"error": "..."} in JSON output
2. Use convenience commands - get_today_worklog is easier than calculating today's dates
3. Cache company_id - Once discovered, remember it for the session
4. Format for readability - Convert JSON to tables, charts, or summaries
5. Provide context - When showing stats, explain what they mean
6. Handle pagination - For large datasets, use --page and --limit
7. Multiple accounts - Each token accesses one user account, but can access multiple companies under that account

Troubleshooting

Author

JehadurRE (Jehadur Rahman Emran)

• Student, Developer, and Learner
• GitHub: https://github.com/JehadurRE
• Created simple Python CLI tool for TimeDoctor API integration

License

MIT