Clocky Duty Log

Dependency Required.

This resource requires Clockify (Web Service) to function. It will not operate without this dependency. Please note that support will not be provided for the use of this resource if the required dependency is not installed and properly configured.

Overview

Clocky is a FiveM resource designed to track player work sessions and integrate with Clockify, a popular time-tracking API. It is intended for roleplay servers or organizations that need department-based work tracking.

Key Features:

• Tracks start/stop of work sessions for players.

• Integrates with Clockify API to log time to your workspace/project.

• Supports ACE permissions per department.

• Automatically stops timers on player disconnect if enabled.

• Fully configurable database tables for storing users and sessions.

Dependencies:

• Clockify account (workspace and project setup required).

• Internet access for API calls to https://api.clockify.me/api/v1.

---

Requirements

1. A Clockify account with workspace and project IDs.

2. ACE permissions configured for restricted departments (optional).

3. Database tables (clocky_users and clocky_sessions) for storing local session data.

---

Workflow

1️⃣ Starting a Timer

• Player runs the in-game command (configured in main script).

• The script:

  • Verifies department and permissions.

  • Starts a timer locally and via Clockify API (POST /workspaces/{workspaceId}/time-entries).

  • Logs session start in database table clocky_sessions.

2️⃣ Stopping a Timer

• Player runs the command again to stop.

• The script:

  • Stops the timer locally and via Clockify API (PUT /workspaces/{workspaceId}/time-entries/{entryId}).

  • Updates database session with duration and timestamp.

  • Optionally logs reason/notes for roleplay purposes.

3️⃣ Disconnect Handling

• If Config.StopOnDisconnect = true, the timer automatically stops when the player leaves the server.

• Ensures time is synced with Clockify even if a player leaves mid-session.

---

Configuration (config.lua)

Debug and Auto-Stop

Config.Debug = false
-- Set to true to enable console logging for debugging

Config.StopOnDisconnect = true
-- Automatically stop player timers when they disconnect

Clockify API

Config.ClockifyBase = "https://api.clockify.me/api/v1"
-- Base URL for all API requests to Clockify

Database Tables

Config.DB = {
    usersTable = "clocky_users",      -- Stores player user data
    sessionsTable = "clocky_sessions" -- Stores active/completed sessions
}

---

Departments

• Each department represents a group in your server (e.g., Law Enforcement, Civilian).

• Use lowercase department keys only.

• Example configuration:

Config.Departments = {
    civ = {
        enabled = true,
        aceEnabled = false, -- If true, restrict access using ACE
        ace = "civ",        -- ACE permission: clocky.department.<ace>

        workspaceId = "",   -- Clockify workspace ID
        projectId = ""      -- Clockify project ID
    }
}

Notes on Workspace & Project IDs:

1. Workspace ID: Found in Clockify workspace settings URL: https://app.clockify.me/workspaces/YOUR_WORKSPACE_ID_HERE/settings#settings

2. Project ID: Found in Clockify project URL: https://app.clockify.me/projects/YOUR_PROJECT_ID_HERE/edit

---

Adding More Departments

• Copy the existing department block and add a comma after the previous block.

• Replace civ with the lowercase department name.

• Fill in workspaceId and projectId for each department.

Example:

leo = {
    enabled = true,
    aceEnabled = true,
    ace = "leo",
    workspaceId = "workspace123",
    projectId = "project456"
}

---

Clockify API Integration

Clocky interacts with Clockify using these endpoints:

API Endpoint	Method	Purpose
/workspaces/{workspaceId}/time-entries	POST	Start a new time entry for a user
/workspaces/{workspaceId}/time-entries/{entryId}	PUT	Stop or update a time entry
/workspaces/{workspaceId}/projects	GET	Retrieve projects for a workspace
/workspaces/{workspaceId}/users	GET	Retrieve users in a workspace
/workspaces/{workspaceId}/clients	GET	Retrieve clients associated with the workspace

Headers:

Content-Type: application/json
X-Api-Key: YOUR_CLOCKIFY_API_KEY

All time tracking is done per department, mapping a player to a Clockify project automatically.

---

ACE Permissions

• Optional: Restrict department access using ACE permissions.

• Permission format: clocky.department.<department>

• Example: For the civ department:

add_ace group.admin clocky.department.civ allow

---

Debugging

• Enable Config.Debug = true to log API calls, timer starts/stops, and session details to the server console.

• Helps diagnose issues with API calls or permissions.

---

Notes & Best Practices

• Always keep workspaceId and projectId private.

• Ensure players have correct ACE permissions if aceEnabled = true.

• Use StopOnDisconnect = true to prevent lost time entries.

• Verify Clockify API key has sufficient permissions for workspace/projects.

• Recommended to use database tables for auditing and restoring sessions.