Module · Catalog Tools

Catalog Tools: settings and screens

Where: ExpertPress → Settings → Catalog CSV (Каталог CSV), or ExpertPress → Catalogue → Import / export (Імпорт / експорт). Both lead to the same screen.

Who can open it: accounts with expertpress_operate (Administrator, ExpertPress Manager).

The screen has five parts, top to bottom: CSV format (saved settings), the current job panel (when you open a job), Column mapping (after an upload), Export, Import and Recent jobs. Refresh reloads the screen.

Options locked by the site

A theme or site plugin can fix the delimiter, BOM, encoding or service import mode with filters. A fixed field is greyed out and shows “Set by site policy.” The value you see is the one in use.


CSV format

All options in this block are saved with Save CSV settings (Зберегти налаштування CSV). Export always uses the saved delimiter, BOM and encoding. Import detects the delimiter from the file unless you choose one on the upload form.

Delimiter

  • Where: Catalog CSV → CSV format
  • What it does: The character that separates columns in exported files and templates. It is also the tie-breaker when an uploaded file could use two delimiters equally.
  • Default: Semicolon (;).
  • Values / limits: Semicolon (;), Comma (,), Tab.
  • When to change it:
    • Excel in an English locale opens comma files directly: choose Comma.
    • Your descriptions contain many commas and semicolons: choose Tab to avoid quoting problems.
  • Related: Delimiter for this file

UTF-8 BOM for Excel

  • Where: Catalog CSV → CSV format
  • What it does: Adds an invisible byte-order mark at the start of exported UTF-8 files so that Excel recognises Cyrillic and other non-Latin text.
  • Default: on.
  • Values / limits: on / off. Has no effect when the output encoding is Windows-1251.
  • When to change it:
    • Turn it off if the file goes to a script or another system that treats the BOM as part of the first header.
    • Keep it on if your team edits files in Excel.
  • Related: Output encoding

Output encoding

  • Where: Catalog CSV → CSV format
  • What it does: Character encoding of exported files. On import, files that are valid UTF-8 (with or without BOM) are always read as UTF-8; other bytes are converted from Windows-1251 only when this option is Windows-1251.
  • Default: UTF-8.
  • Values / limits: UTF-8, Windows-1251. Windows-1251 is offered only when the server has mbstring or iconv; otherwise the screen says “Windows-1251 is unavailable on this server (needs mb_convert_encoding or iconv). Exports stay UTF-8.” If a value cannot be converted, the export is cancelled instead of producing a mislabelled file.
  • When to change it: an older Excel or accounting tool on Windows shows Cyrillic as garbage even with the BOM.
  • Related: UTF-8 BOM for Excel

Service import mode

  • Where: Catalog CSV → CSV format
  • What it does: What happens to service rows when they are written. Draft (Чернетка) saves them as working drafts. Submit for moderation (Надіслати на модерацію) sends them to the moderation queue. CSV import never publishes a service directly.
  • Default: Submit for moderation.
  • Values / limits: Draft, Submit for moderation.
  • When to change it:
    • You are preparing services for specialists who should review and submit them themselves: choose Draft.
    • You are moving a ready catalog from another site and want moderators to approve it in bulk: keep Submit for moderation.
  • Related: Check services before publishing

Enable CSV cover downloads (off by default)

  • Where: Catalog CSV → CSV format
  • What it does: Allows service imports to download a cover image from the cover_url column. Even when this is on, each import must also tick Import covers from cover_url for this job.
  • Default: off.
  • Values / limits: on / off. Downloads need Action Scheduler. Limits: JPEG, PNG or WebP; up to 5 MiB per file; up to 100 MiB and 200 covers per job. A failed download or an invalid image rejects the whole row.
  • When to change it: you migrate services from an old site and want their images to come along without uploading each one by hand.
  • Related: Allowed cover hosts, Covers

Allowed cover hosts

  • Where: Catalog CSV → CSV format
  • What it does: The only host names the site may download covers from.
  • Default: empty (no host allowed).
  • Values / limits: exact host names, one per line (for example images.example.com). HTTPS only; redirects are not followed.
  • When to change it:
    • Your old site keeps images on old-site.example.com: add that host for the migration, then remove it.
    • Images sit on a CDN such as cdn.example.net: add the CDN host, not the main domain.
  • Related: Enable CSV cover downloads

Export

Entity (export)

  • Where: Catalog CSV → Export
  • What it does: Chooses which list to download: directions, languages, services or attributes.
  • Default: directions (first in the list).
  • Values / limits: the four entities above.
  • When to change it: pick the list you want to edit or back up.
  • Related: —

Download CSV (Завантажити CSV) downloads the current data. Download CSV template (Завантажити шаблон CSV) downloads only the header row for the chosen entity, including cover_url for services.

Columns per entity:

Entity Columns
directions, languages external_key, slug, label, one label column per site language, status
attributes external_key, entity_kind, slug, field_type, label, label columns per language, description, is_required, visibility, editable_by, searchable, filterable, show_in_card, show_in_detail, sort_order, status, type_config_json, options_json
services external_key, id, slug, title, description, service_type, meeting_format, duration_minutes, capacity, price_minor, currency, pricing_unit, language_slugs, direction_slugs, outcomes, preparation, specialist_external_key, cover_key, status_export, plus one attr:<slug> column per active service custom field

Notes:

  • id and status_export are informational. They never select a record and never publish it.
  • Exporting services gives each specialist who owns a service a key of the form sp-<user ID> in specialist_external_key. Use that value when you add new services for the same specialist. Specialists themselves cannot be imported, and the code does not offer another way to create a specialist key, so a specialist without any exported service has no key yet.
  • price_minor is the price in the smallest currency unit (for example 1500 for 15.00).

Import

Entity (import)

  • Where: Catalog CSV → Import
  • What it does: Tells the plugin which kind of rows the file contains.
  • Default: directions.
  • Values / limits: directions, languages, services, attributes.
  • When to change it: always match it to the file you upload.
  • Related: —

Delimiter for this file

  • Where: Catalog CSV → Import
  • What it does: Overrides delimiter detection for this upload only.
  • Default: Auto-detect (Автовизначення). The plugin counts semicolons, commas and tabs in the header line; on a tie it prefers the saved Delimiter.
  • Values / limits: Auto-detect, Semicolon (;), Comma (,), Tab.
  • When to change it: the header line has no delimiter characters at all (one column), or detection picks the wrong one because headers contain commas.
  • Related: Delimiter

After choosing the file, press Upload CSV. Limits: up to 20,000 data rows, 80 columns and 20,000 characters per cell. Only one import may own the import slot at a time; if another job is still running or waiting for staff, the upload is refused with “Another import owns the slot, possibly waiting for an operator.”


Column mapping

Shown after a successful upload, while the job is in the awaiting_mapping state.

  • Each File column has a drop-down with the ExpertPress field it should fill, or — ignore —. The plugin pre-selects matching names. Two columns cannot target the same field.
  • Required: external_key, and also specialist_external_key for services.
  • Preview (first rows after mapping) shows up to five rows.
  • Saved presets lists mappings saved earlier for the same entity. Click a name to apply it; Delete removes it. Reset to auto-match discards changes. A job keeps its own copy of the mapping, so editing or deleting a preset later does not change past jobs.

Import covers from cover_url for this job

  • Where: Column mapping (services only)
  • What it does: Downloads covers for this job from the cover_url column.
  • Default: off.
  • Values / limits: needs Enable CSV cover downloads, at least one allowed host and Action Scheduler. An explicit cover_key wins over cover_url. Sites that allow only library covers reject uploaded covers. Dry-run never downloads images.
  • When to change it: tick it on the real import (not the dry-run) of a services file that contains image links.
  • Related: Covers

Dry-run (validate only, no writes)

  • Where: Column mapping
  • What it does: Checks every row and produces a report with errors and warnings, without writing anything.
  • Default: on.
  • Values / limits: on / off. To apply after a dry-run, upload the same file again and clear this box.
  • When to change it: clear it only after a clean dry-run report.
  • Related: Recent jobs

Also save as preset

  • Where: Column mapping
  • What it does: Saves the current mapping under the name typed in Preset name for later uploads of the same entity.
  • Default: off.
  • Values / limits: any short name.
  • When to change it: you import from the same external system every month, for example “Old site services”.
  • Related: —

Press Run import (Запустити імпорт) to start. Up to 200 rows run immediately; larger files are queued in Action Scheduler and processed in batches of 40 rows.


The job panel

Open a job from Recent jobs to see Job #N — status — processed X / Y, the totals (created, updated, skipped, errors), cover download progress and up to 50 row results (Line, Key, Outcome, Message, Media).

  • Stop job (Зупинити завдання) is available while a job is queued, running, waiting for mapping or waiting for staff. Rows already applied stay applied.
  • Operator action required. If the plugin cannot tell whether a row was saved (for example, the request was interrupted), it stops and keeps its slot. The panel shows the object and key. If the record exists and is complete, Bind key (Прив’язати ключ) attaches the key to it and the import continues. Otherwise, stop the job and check the record by hand. Automatic runs never replay such a row.

Recent jobs

The last 15 jobs with entity (marked “(dry-run)” for checks), status, short totals (c: created, u: updated, s: skipped, e: errors) and a Report link. Download reports within 14 days.


Typical workflow

  1. Set CSV format to match your spreadsheet program and save.
  2. Export the entity, or download its template.
  3. Edit the file. Keep external_key values unchanged for rows you want to update; use new unique keys for new rows.
  4. Import in this order when lists depend on each other: directions and languages, then attributes, then services.
  5. Upload, check the mapping and preview, and run a dry-run.
  6. Read the report, fix the file, upload again with Dry-run cleared.
  7. For services in Submit for moderation mode, approve them under Check before publishing.