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

One Token = One User Account

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

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

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:

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

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:

Company A (ID: 12345)
Company B (ID: 67890)
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

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

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

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"

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

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

Troubleshooting

Error	Cause	Solution
-------	-------	----------
`TIMEDOCTOR_TOKEN environment variable not set`	Token not configured	User needs to set `export TIMEDOCTOR_TOKEN="..."`
`company_id required`	Missing company ID	Run `get_authorization` to discover company_id
`401 Unauthorized`	Token expired or invalid	User needs new token (6-month validity)
`httpx module not found`	Dependencies not installed	Run `pip3 install -r requirements.txt`
No data returned	No activity in date range	Check date range and verify users have activity

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

Timedoctor

概述