Task Session can bring data in and send data out through guided CSV, Excel, and (where supported) ZIP flows, plus a dedicated path for the Leads board. This guide is for product owners and managers: it explains who can open which screens, where each feature lives, and which permissions to assign. Replace https://yourdomain.com/ with your real installation URL throughout.
Table of Contents
- Prerequisites
- Where to find Import / Export
- Who can access the migration hub (admin vs staff)
- Data migration panel: import vs export
- Import: modules, URLs, and who they are for
- Export: modules, URLs, and who they are for
- Leads: dedicated import and export tools
- Import history and background jobs
- CSV and file best practices
- Role checklist for managers (permissions)
- Technical notes (code paths, cron, database)
- FAQ
Prerequisites
Before you plan a migration, ensure that:
- You can sign in to
https://yourdomain.com/admin/as an administrator, or as staff with the permissions described in Who can access the migration hub. - Database upgrades for import jobs are applied on your instance. Recent builds use
import_jobsandimport_job_errorsso large CSV imports can be queued and processed in the background (see Import history and background jobs). - Any module flags in System settings match what you want to import (for example Invoices for invoice CSV flows, Leads / Lead board for lead import and export cards) — see Module settings.
Module settings
Enable or disable each area under System settings so the hub’s cards match your subscription and workflow. If a module is off, the related import/export card is disabled or hidden with a short reason (for example invoices when the Invoices module is disabled, or leads when the lead board is off).
Where to find Import / Export
- Direct URL (hub home) —
https://yourdomain.com/import-export/migration/ - From System settings (admin) — the system navigation often includes an Import / Export entry that links to the same
import-export/migration/area so administrators can open the data migration panel without hunting for the path. - Key sub-pages (relative to the migration folder):
import.php— choose what to import and jump into the right wizard.export.php— choose what to export and download or open the target export.
- Import history (admin) —
https://yourdomain.com/import-export/history.php(see Import history and background jobs).
Who can access the migration hub (admin vs staff)
The product distinguishes administrators (full admin account) and staff (internal user with granular permissions).
- Administrators can open the migration hub and, subject to module settings, use most import and export cards (users as clients, staff, admins, projects, tasks, chats, invoices, notes, and the leads hand-off when the lead board is available).
- Staff are only allowed into the hub if they have at least one of:
lead_importorlead_export. If they have neither, they are redirected with a permission error. In practice, staff with lead import or export are expected to use the Leads area; the hub still opens so they can reach the dedicated lead tools from the same mental model as admins. - Client and other non-staff account types are not the audience for the migration UI.
Individual wizards and downloads may still require admin-only access even when the hub opens (see the tables below).
Data migration panel: import vs export
On import-export/migration/index.php (the hub) you will see two primary actions, plus an optional support card:
- Import — upload CSV or Excel (or follow the ZIP path for chats), map columns, preview, then run or queue the import.
- Export — download CSV (or a ZIP for chats) for backup, analysis, or moving data to another system.
- Support / migration team — external help link for large or complex moves (for example from another CRM).
Import: modules, URLs, and who they are for
All paths below are relative to https://yourdomain.com/ unless noted. “Admins only” means the card is shown for full administrators in the product configuration.
| Area | Typical entry path | Notes |
|---|---|---|
| Clients (users as clients) | import-export/users/index.php?type=client | CSV import for client-type users. Admins only in the hub card configuration. |
| Staff | import-export/users/index.php?type=staff | CSV import for staff accounts. Admins only. |
| Admins | import-export/users/index.php?type=admin | CSV import for administrator users. Admins only. |
| Projects | import-export/projects/ | Projects with related entities (for example clients, companies, team groups, custom fields). Admins only. |
| Tasks | import-export/tasks/ | Tasks (project or internal, assignees, custom fields). Admins only. |
| Chats | import-export/chats/ | Import from a ZIP package (1:1, project discussion, group, task threads as supported by your build). Admins only. |
| Invoices | import-export/invoices/ | Two-file model: one file for invoice header rows, one for line items linked by an external identifier. Requires the Invoices module enabled in settings; card is disabled with an explanatory message if the module is off. Admins only. |
| Notes & Docs | import-export/notes/ | Single wizard with tabs for private, profile, and project document/note CSV flows. Admins only. |
| Leads | import-export/leads/ (and tools under that tree) | Stays in the dedicated lead import experience. Shown on the import hub when the lead board is enabled and the user may import (admin, or staff with lead_import). Otherwise the card is disabled with “lead board disabled or no permission”. |
Export: modules, URLs, and who they are for
From import-export/migration/export.php each area links to a concrete download or to the same dedicated leads export.
| Area | Typical path or pattern | Notes |
|---|---|---|
| Clients | import-export/users/export.php?type=client | Admins only. |
| Staff | import-export/users/export.php?type=staff | Admins only. |
| Admins | import-export/users/export.php?type=admin | Admins only. |
| Projects | import-export/projects/export.php | Projects CSV. Admins only. |
| Tasks | import-export/tasks/export.php | Tasks CSV. Admins only. |
| Chats | import-export/chats/export.php | Manifest-style ZIP export. Your build may support a ?live=1 style parameter for including recent message data; confirm on your instance. Admins only. |
| Invoices | import-export/invoices/export.php?sample=1 (and related) | Sample and line-oriented CSV aligned with the import model; requires Invoices module enabled. Admins only. |
| Notes & Docs | import-export/notes/export.php?all=1 | Combined export of private, profile, and project documentation rows as one CSV. Admins only. |
| Leads | import-export/leads/export.php | Dedicated lead board export. Available when the lead board is enabled and the user is admin or has lead_export; otherwise the export card shows that lead export is not available. |
Leads: dedicated import and export tools
Leads are intentionally not buried only inside the generic “users” wizards. From the hub, the Leads row points to import-export/leads/ for import and the export card points to the dedicated export.php under that area.
- Enable the Leads / Lead board module in system settings if your organization uses the lead pipeline.
- Assign
lead_importto roles that may upload and map lead CSVs; assignlead_exportfor downloads. - Other lead permissions (for example
lead_view_all,lead_edit,lead_delete) control day-to-day board behavior onstaff/leads.phpand related screens—configure them under Admin ? Roles in the Lead Permissions group. - Staff who only need the board but not bulk import/export do not need migration hub access; those who do bulk work need the corresponding lead permission pair as described in Who can access the migration hub.
Import history and background jobs
Import history page
- URL:
https://yourdomain.com/import-export/history.php - Audience: administrators only (non-admin users are sent to the unauthorized page).
- Purpose: list recent import jobs (status, row counts, errors) so you can audit what ran and troubleshoot failed rows.
Background processing
- Large or queued flows are backed by the
import_jobspipeline; errors can be stored per job for support and retry analysis. - The scheduled worker
cron/import_jobs_worker.phpshould run on an interval (for example every 1–5 minutes) to drain pending work. If cron is not configured, long imports may sit in a queued state until the job runs or an operator investigates.
CSV and file best practices
- Prefer UTF-8 encoding for text and verify date formats match what the wizard expects.
- Use a small pilot file first, then run the full set after you validate column mapping and preview output.
- For invoice two-file imports, keep a stable external ID across header and line files so the system can join rows unambiguously.
- For chat ZIP flows, use the template or documentation that ships with your release so folder structure and metadata match the importer.
- After any application upgrade, re-check sample exports (where provided) in case new columns were added to the schema.
Role checklist for managers (permissions)
Use Admin ? Roles to align teams with the least privilege that still allows their work.
| Goal | Permission keys to consider |
|---|---|
| Full data migration and all hub cards (typical super-admin) | Administrator account; no extra keys required beyond module flags (Invoices, Leads, and so on). |
| Import leads from CSV from the dedicated tool | lead_import (and lead board enabled; hub access for staff per access rules). |
| Export leads to CSV | lead_export (and lead board enabled where applicable). |
| Manage clients, staff, projects, tasks, documents at record level (not covered by this guide in full) | Account and project groups such as client_view, client_create, staff_view, project_view_all, task_create — grant separately from import/export; bulk hub actions for those entities remain admin-only in the product layout described here. |
Technical notes (code paths, cron, database)
- Access control for the migration hub is centralized in
import-export/migration/_auth.php(admin vs staff and thelead_import/lead_exportcheck for staff). - Import/export business logic and job services are bootstrapped from
includes/import-export/bootstrap.phpand related classes. - Queued jobs are processed by
cron/import_jobs_worker.php, which calls the batch worker when theimport_jobstable exists. - After code or SQL migrations, clear opcode caches if you use them, verify cron, and test on a staging copy before production cutovers.
FAQ
Why can a staff user not open the migration panel?
Staff must have lead_import or lead_export to pass the hub guard. If they need bulk lead work, grant the appropriate key; if they should not use the hub, leave both unset.
Why are import cards for users, projects, and tasks visible only to admins?
Those cards are implemented as administrator flows in the hub configuration. Staff access is limited to the lead permissions path for the hub itself, not to those wizards.
Why is the Leads import or export card disabled?
Either the lead board module is off in system settings, or the signed-in user lacks lead_import (import) or the export rule for exports. Admins should verify settings and the user’s role.
Where do I see whether a long CSV finished?
Administrators should open Import history at import-export/history.php and confirm that cron is running the import jobs worker.
Do clients use the import/export hub?
No. The hub is for administrators and, under the rules above, certain staff. Client portals are out of scope for the migration panel.
With modules enabled, roles assigned, cron healthy for background jobs, and a clear plan per entity (users, projects, tasks, documents, leads, optional invoices and chats), Task Session’s import and export area supports controlled bulk moves and backups alongside day-to-day CRM and project work.
