# Hesk 3.x import

One-time historical migration of tickets (with full reply/note history) from a
Hesk 3.x helpdesk database into this app, restricted to a single e-mail
domain. Read-only against the Hesk database — never writes there.

This is **not** an ongoing sync. Run it once to backfill history from an
old Hesk install; it doesn't pick up edits made in Hesk afterward.

## What it does

- Matches Hesk tickets by requester e-mail domain (`--domain=firma.pl`).
- Imports each ticket's subject/body, status, priority, and full reply +
  internal-note history, converting Hesk's `<br />`-laden "plain" text into
  real line breaks.
- Maps Hesk categories to this app's categories by exact (case/whitespace-
  insensitive) name match. A Hesk category with no match is skipped by
  default — pass `--include-unmapped-categories` to import those tickets
  anyway, uncategorized.
- Auto-assigns a team when every subcategory under the matched category
  routes to the same single team (same rule `TicketService::autoAssignTeam()`
  uses for normal ticket creation); ambiguous categories are left unrouted.
- Finds or creates a client account per requester e-mail, reusing an existing
  account (adding the `client` role if it doesn't have it yet) rather than
  duplicating.
- Hesk staff replies are **not** linked to a real operator account (this
  script never creates operator accounts) — the reply still shows the
  correct staff name and "operator" badge via `author_name`, just without a
  clickable user behind it.

## Setup

```bash
cp scripts/hesk-import/.env.example scripts/hesk-import/.env
```

Fill in `scripts/hesk-import/.env` with the Hesk database's
host/port/database/username/password. That file is gitignored — it holds
real credentials for a database this app otherwise has no access to.

## Usage

Always dry-run first — it reports what *would* happen without writing
anything:

```bash
scripts/hesk-import/hesk-import.sh --domain=firma.pl
```

Try a small batch for real before committing to the whole thing:

```bash
scripts/hesk-import/hesk-import.sh --domain=firma.pl --limit=10 --commit
```

Then the full import:

```bash
scripts/hesk-import/hesk-import.sh --domain=firma.pl --commit
```

Safe to re-run (including after an interrupted/crashed run): already-imported
Hesk ticket ids are tracked in `storage/app/hesk-import-state.json` inside the
app container and skipped on subsequent runs.

### Backfilling team assignment

If tickets were already imported before team-by-category mapping existed (or
teams/subcategories changed since), backfill `team_id` on existing imported
tickets without importing anything new:

```bash
scripts/hesk-import/hesk-import.sh --assign-teams --commit
```

## How it's wired up

`hesk-import.sh` is a thin wrapper: it loads `.env` in this folder, then runs
`php artisan hesk:import` inside the `app` container via `docker compose
exec`, passing the Hesk DB credentials as one-off environment variables (they
never touch the app's own `.env` or get persisted anywhere but the state
file). The actual import logic lives in
[`../../src/app/Console/Commands/ImportHeskTickets.php`](../../src/app/Console/Commands/ImportHeskTickets.php).