# TAF ERP

This repository contains the ERP system used across multiple councils.

## Environment Variables

Certain modules require environment variables. For Microsoft 365 integration,
set the following variables before running the application:

- `M365_TENANT_ID` – Azure tenant identifier.
- `M365_CLIENT_ID` – application client ID.
- `M365_CLIENT_SECRET` – application client secret.
- `M365_GRAPH_URL` – Microsoft Graph API base URL (optional, defaults to
  `https://graph.microsoft.com/v1.0`).

Copy `config/m365.php.dist` to `config/m365.php` and ensure these environment
variables are present in your deployment environment.

The Outlook calendar integration and Teams meeting links used by the Interview
module depend on these credentials. Provide your tenant ID, client ID and
client secret obtained from Azure AD. The file `config/m365.php` is loaded by
`OutlookCalendarService` and `TeamsService` to connect to Microsoft Graph.

## Deduction Settings

Payroll deductions can be configured by administrators. Visit
`views/hr/deduction_settings.php` and use the interface to add or edit rules.
The page communicates with the `/api/deduction_settings` endpoints. Each rule
specifies a salary range, fixed amount, percentage of gross pay and optional
employer contribution. Rules may optionally include a start and end date and
an "applies to" designation of Resident, Non-Resident or Everyone. These amounts are automatically applied by
`PayrollProcessor` during pay runs.

### Country vs Company Rules

Deduction settings can be defined globally for a country or specifically for a
single company. Country level rules require the
`country_deductions.manage` permission and apply automatically to all companies
in that country. Company specific rules still use the
`deduction_settings.manage` permission. Both sets of rules are visible in the
same interface &ndash; country rules appear in a read&ndash;only table for most
users, while company rules can be added or edited if the user has the proper
permission.
Country holiday dates are managed with the `country_holidays.manage` permission. Super admins can add or edit holidays through the **Country Holidays** module on `FrontEnd/Dashboard.html`.

## CLI Jobs

Two command line scripts are intended to run on a schedule:

1. **Payroll Scheduler** – `api/jobs/schedule_payroll.php` should run daily via
   cron. It checks `pay_cycles.next_run_date` and queues payroll runs when due.
2. **Email Ingest** – `cli/email_ingest.php` processes configured mailboxes and
   stores attachments in the Documents module. Run it every 15 minutes or as
   needed.

Ensure `config/mailboxes.php` contains your IMAP connection details before
running the email ingest job.

## Time Clock API

The `timeclocks` resource tracks employee clock ins and outs. To fetch records
within a specific period, call:

```
GET /api/timeclocks/by-range?start=YYYY-MM-DD&end=YYYY-MM-DD
```

Parameters:

- `start` – inclusive lower bound timestamp (YYYY-MM-DD or full datetime).
- `end` – inclusive upper bound timestamp.

The response is filtered based on the caller's permissions and returns an array
of matching time clock rows.
