Easy Time Manager - API & Automation

REST API reference for reports, projects, tasks, and time types. Cron setup for automated missing reports email notifications

Table of Contents

• REST API
  • Enabling the API
  • Authentication
  • Endpoints
  • Report Endpoints
  • Project Endpoints
  • Task Endpoints
  • Time Type Endpoints
  • Missed Reports
  • Error Codes
• Cron — Missing Reports Notifications

---

REST API

The Easy Time Manager REST API allows external applications to interact with work entries, projects, tasks, and time types programmatically. All responses are JSON.

Enabling the API

1. Go to Components > Easy Time Manager > Options.
2. Open the API tab.
3. Set Enable API to Yes.
4. Save.

The API is disabled by default.

Base URL

All API requests use the following base URL format:

https://your-site.com/index.php?option=com_easytimemanager&view=api

Authentication

You must authenticate before making API calls. The API uses Joomla session-based authentication.

Login:

POST /index.php?option=com_easytimemanager&view=api&task=auth

Parameters:
  username  — Joomla username
  password  — user password
  remember  — "true" or "false" (optional, enables remember-me)

Successful response:

{
  "result": {
    "message": "Login successful",
    "username": "John Smith",
    "useremail": "This email address is being protected from spambots. You need JavaScript enabled to view it."
  }
}

Logout:

POST /index.php?option=com_easytimemanager&view=api&task=auth

Parameters:
  logout — 1

Endpoints

The API accepts a target parameter to specify the resource type. Available targets:

Target	Resource	Supports
report	Work log entries	GET (list + single), POST/PUT (create/edit), DELETE
project	Projects	GET (list only)
task	Tasks	GET (list only, requires project_id)
type	Time worked types	GET (list only)

Pagination

List endpoints accept these parameters:

Parameter	Default	Description
page	1	Page number
size	20	Items per page

List responses include a pages_total field indicating the total number of pages.

---

Report Endpoints

List reports:

GET /index.php?option=com_easytimemanager&view=api&target=report

Optional filters:

Parameter	Description
date_month	Filter by month (format depends on configuration)
project	Filter by project ID
client	Filter by client ID
task	Filter by task

Optional ordering:

Parameter	Values
order	project_name, date, company, task
dir	asc or desc (default: asc)

Response:

{
  "result": {
    "items": [...],
    "pages_total": 5,
    "time_total": "120:30"
  }
}

Get single report:

GET /index.php?option=com_easytimemanager&view=api&target=report&id=123

Returns the entry if the user owns it, or has report management permissions.

Create a report:

POST /index.php?option=com_easytimemanager&view=api&target=report

Parameters:
  projectid         — project ID (required)
  task              — task name
  taskid            — task ID (if task lists are enabled)
  date              — date of work (YYYY-MM-DD)
  time              — hours worked (HH:MM format)
  easytimemanagerid — time worked type ID
  performed_work    — description of work done
  ticket_numbers    — issue/ticket numbers

The userid is automatically set to the authenticated user.

Edit a report:

POST /index.php?option=com_easytimemanager&view=api&target=report

Parameters:
  id — the report ID to edit (include in POST data)
  ... (same fields as create)

When editing, the original entry's userid is preserved. Requires Edit or Edit Own permission.

Delete a report:

DELETE /index.php?option=com_easytimemanager&view=api&target=report&id=123

Requires Delete permission, and the user must own the entry (or be an admin).

---

Project Endpoints

List projects:

GET /index.php?option=com_easytimemanager&view=api&target=project

Returns projects the authenticated user is assigned to.

Response:

{
  "result": {
    "items": [...],
    "pages_total": 1
  }
}

---

Task Endpoints

List tasks for a project:

GET /index.php?option=com_easytimemanager&view=api&target=task&project_id=5

The project_id parameter is mandatory. Returns tasks linked to the specified project.

---

Time Type Endpoints

List time worked types:

GET /index.php?option=com_easytimemanager&view=api&target=type

Returns all configured time worked types.

---

Missed Reports

Get dates with missing reports:

GET /index.php?option=com_easytimemanager&view=api&task=missed

Returns an array of dates where the authenticated user has not logged the required hours. Requires the Missing Reports Notifications feature to be enabled.

---

Error Codes

When an error occurs, the response includes an error object:

{
  "error": {
    "message": "Error description",
    "code": 1
  }
}

Code	Meaning
1	Not authenticated — login required
2	Unauthorized — insufficient permissions for this action
3	Incorrect target — the target parameter is not valid
4	Action not permitted — the HTTP method is not supported for this target
5	Object ID not specified — DELETE requires an id parameter
6	Project ID is mandatory — task listing requires project_id
7	Login failed — incorrect credentials
8	Logout failed
9	Auth credentials empty — username or password missing
11	API disabled — enable the API in component settings
1000	Other error — validation errors or storage failures (details in message)

---

Cron — Missing Reports Notifications

The cron feature sends automated email reminders to employees who haven't logged enough hours on working days.

How It Works

1. The cron checks the last N working days (configurable via "Notification days count").
2. For each employee who has project assignments, it compares their logged hours against the "Number of required hours" threshold.
3. Days where the employee was on approved leave are excluded.
4. Weekend days (as configured) are skipped.
5. If an employee has any days with insufficient hours, they receive an email listing the dates.

Prerequisites

Before setting up the cron, configure these settings in Options > Missing Reports Notifications:

1. Set Enable notifications to Yes
2. Set Number of required hours (e.g., 8 for a standard workday)
3. Set Notification days count (how many past days to check, e.g., 5)
4. Set Weekends (select which days are non-working)
5. Set Check today's hours to Yes or No depending on whether you want to include the current day

Cron URL

The component auto-generates a cron URL displayed (read-only) in the settings. The URL format is:

https://your-site.com/index.php?option=com_easytimemanager&view=cron&salt=XXXXXXXXXX

The salt parameter is a CRC32 hash of your Joomla site's secret key. This prevents unauthorized triggering of the cron.

Setting Up the Cron Job

Using a web-based cron (e.g., cPanel, Plesk):

Copy the Cron URL from the component settings and set it to run at your desired interval (e.g., daily at 6 PM).

Using the command line:

Use the Cron path shown in the settings. For example:

# Run daily at 18:00
0 18 * * * /usr/bin/php /path/to/your/joomla/cli/joomla.php easytimemanager:cron

Or use wget/curl with the cron URL:

0 18 * * * curl -s "https://your-site.com/index.php?option=com_easytimemanager&view=cron&salt=XXXXXXXXXX" > /dev/null

Duplicate Run Protection

The cron has built-in protection against overlapping runs. It records each execution in the #__tw_notifications table and skips execution if another run started within the last 5 hours.

Email Content

The notification email sent to employees includes:

• A greeting with the employee's name
• A list of dates where hours were missing or below the threshold
• The email is sent as plain text from the Joomla site's configured sender address