Import and export
Large imports and exports run as data-processing jobs: the request returns at once with a job, a queue worker does the work, and the client polls the job for progress and a download.
Users: the built-in example
| Endpoint | Does |
|---|---|
POST /api/v1/user/import-template |
download a template spreadsheet (user.import) |
POST /api/v1/user/import-background |
upload .xlsx or .csv; starts a user.import job |
POST /api/v1/user/export-background |
starts a user.export job with the list filters |
GET /api/v1/data-processing/jobs/user |
the caller’s jobs |
GET /api/v1/data-processing/job/{jobId} |
status, progress and per-row errors |
GET /api/v1/data-processing/job/{jobId}/download |
the export file — only when COMPLETED |
{ "type": "user.import", "status": "COMPLETED", "total_items": 250, "processed_items": 250, "success_count": 247, "error_count": 3, "progress_percentage": 100, "errors": [{ "row": 14, "errors": { "email": ["The email has already been taken."] } }]}- Honest status: progress is real, and a failure is a
FAILEDjob with a message — never a silent success. - Formats:
.xlsxand.csv. Legacy.xlsis rejected. - Safe cells: exported values that start with
=,+,-or@are neutralised, so a spreadsheet can’t run a formula a user typed in. - Bounded: imports stream rows instead of loading gigabytes into memory.
- Files live on
DATA_PROCESSING_DISK(private by default). - Retention: completed jobs are deleted after the tenant’s
data_processing_job.cleanup_dayssetting (default 30) by thedataprocessing.cleanup-completedtask.
Building your own
identity.ExchangeService is the pattern to copy: register two queue jobs (…import,
…export), create a job row with dataprocessing.Service, enqueue with the tenant scope, then
report progress with UpdateProgress as rows are processed. The
feature.data_processing flag gates the whole feature.