SIGNALS Docs
Exit Reader View
100%
Theme

Imports

Bring records in from spreadsheets or another system with the Import Guide, the import wizard, import profiles and migration plans.

Overview

Imports bring your records into Signals from CSV, XLSX or JSON files — one list at a time, or a whole business moving across from another system. Every import is checked in a dry run before anything is saved, and imported records are created through the same actions as records added by hand, so validation, history, search and notifications all behave the same way.

Where it lives

Open Admin → Data → Imports. The section has four tabs:

Tab Route What it is for
Import Guide /admin/settings/imports/guide (admin.settings.imports.guide) Which way to import, how each works, every record type with its template
Imports /admin/settings/imports (admin.settings.imports.index) Past imports, their status and results
Migration Plans /admin/settings/imports/plans Multi-step moves in dependency order
Profiles /admin/settings/imports/profiles Saved column mappings for files in a repeatable shape

New Import (shortcut N) on the Imports tab opens the import wizard at /admin/settings/imports/create.

Permission Grants
imports.access See Imports in the admin navigation
imports.view View the Import Guide, import batches, plans and profiles
imports.create Upload imports, set mappings, manage profiles and execute plans
imports.undo Undo a completed import plan by deleting the records it created

Availability

Imports are off by default on self-hosted installations. An administrator can turn them on from the Turn On Imports button shown on the Imports page while they are off, or by setting SIGNALS_IMPORTS_ENABLED=true in .env; an explicit imports.enabled tenant setting takes priority over the environment value. While imports are off, the import API, the other import pages and the top-level import URLs are unavailable. Permissions still apply.

The Import Guide

Until anything has been imported — no import, profile or migration plan exists — the Imports table shows a short Start your first import panel with New Import and Open Import Guide. The Import Guide tab is always available and holds the full guide. It asks what you want to do and explains each option:

Option Use it when How it works
Set up import profiles Your files come out of another system in the same shape every time, and you will import them more than once. A profile remembers how the file's columns match Signals fields, which fields spot duplicates and what to do with records you already have. Pick it on the mapping step and the mapping is applied for you.
Create a migration plan You are moving everything from your source system in one go. A plan runs one import per record type in dependency order so references resolve, tracks progress across every step, and can undo what it created.
Run a one-off import You have one spreadsheet of one record type, such as your customer list or a price update. The import wizard takes you from choosing the record type to the finished import.

Below the options, the guide lists every record type you can import, grouped by area, with XLSX Template and CSV Template downloads and a link that opens the wizard with that type chosen. Download Full Migration Workbook gives one spreadsheet with a sheet per record type, in migration order.

The list comes straight from the import target registry, so record types added by Signals or by a plugin appear automatically.

The import wizard

The wizard has six steps, shown across the top with your progress. Finished steps can be revisited until the import starts. On a phone the steps collapse to "Step 2 of 6" with a progress bar.

  1. Record type — choose what the file holds from cards grouped by area. Use the arrow keys to move between cards and Enter to continue. A link from the guide or a list page (?target=accounts) skips this step, and a migration plan step sets the type itself.
  2. Upload — drop or choose a CSV, XLSX or JSON file whose first row holds the column headings. The What your file needs panel lists the required columns, the optional ones and tips, with template downloads for the chosen type. Change next to the record type goes back to step 1 until a file is uploaded. Reading the file happens in the background; you can leave the page while it runs.
  3. Map — match each column to a Signals field. Matches the system is sure of are filled in; Auto-Map and Accept all suggestions fill in the rest. Pick a saved profile to apply its mapping, set what happens when a record already exists, choose the fields used to spot duplicates, and save the mapping as a new profile. The Live preview shows the first rows of your file under the fields they will fill (before transforms) and updates as you change matches; it also lists required fields that no column fills yet. Unmatched columns are ignored.
  4. Dry run — every row is checked with the same rules as the rest of Signals. Nothing has been saved yet. Filter the results by warnings or errors and open a row to compare its raw and mapped values. Rows with errors can be skipped by acknowledging them, or fixed in the file and uploaded again.
  5. Preview — records exactly as they will be saved, plus any possible duplicates to confirm or reject.
  6. Import — start the import. You can pause, resume or cancel while it runs; the report shows created, updated, skipped and failed rows, and failed rows can be downloaded as a CSV.

Templates

Each record type has a template in XLSX and CSV. A template has the right column headings from the type's field catalogue (custom fields included), a row of notes on what each column takes (required or optional, formats, allowed values) and a few example rows to replace. The full migration workbook has one sheet per record type in dependency order.

Templates are also available from the API: GET /api/v1/import-targets/{target}/template.{csv|xlsx} and GET /api/v1/import-targets/migration-template.xlsx.

Supported record types

Record types are grouped as they appear in the guide and the wizard. A migration plan runs them in exact dependency order — records that others point to (warehouses, catalogue items, accounts) arrive first.

Group Record types
Setup & tax Warehouses, facilities, users, custom field groups, custom fields, tax zones, tax categories, tax rates, tax rules, customer tax profiles, item tax codes
Pricing Rate specifications, rate bands, discount groups, discount rules, surcharge groups, surcharges, bundle rules, catalogue item prices
Catalogue & stock Catalogue item groups, catalogue tags, catalogue items, services, assets, vehicles, catalogue item suppliers
People & CRM Accounts, addresses, emails, phones, links
Rentals Rental projects, rentals, rental lines
Finance history Purchase orders, invoices, payments, credit notes — brought in as history from your source system
Activity Activities, repairs, equipment tests

References to other records use their name, code or reference — for example a warehouse name on an asset row, or an account name on a rental. Keep an ID column from your source system: the Spreadsheet migration preset maps it to migration_ref, so a second import of the same file updates records instead of duplicating them.

Use ordinary field headings in your spreadsheet. Matching ignores case and surrounding spaces, and treats underscores as spaces. For example, account_type and Account Type both map to account_type.

Record type Example supported headings
Accounts Name, Email, Account Type, Description
Catalogue items Name, SKU, Barcode, Weight, Replacement Value
Assets Asset Number, Serial Number, Quantity, Catalogue Item Name, Warehouse, Purchase Price, Purchase Date

For asset rows, Catalogue Item Name and Warehouse resolve existing records by name; Quantity, Purchase Price and Purchase Date populate quantity_on_hand, purchase_cost and acquired_at.

How user passwords work

User imports never accept passwords in plain text. A file with a column that looks like a plain password is refused, with the reason.

  • By default, each imported user is created without a usable password and gets an invitation to set their own. Choose to send the invitations straight away or later, and send them in bulk afterwards.
  • Optionally, and only for the owner, existing password hashes from another system can be brought across when they are a format Signals can check (bcrypt or Argon2id). Each row is checked, and the password is re-hashed the first time that person signs in. Any row whose hash cannot be used falls back to an invitation.
  • Roles are matched by name and must already exist. The owner cannot be imported, and making someone an administrator needs an explicit confirmation in the plan.
  • Passwords and hashes never appear in logs, previews, dry-run results, error messages or exports. Every imported user is recorded in the audit log.

Import profiles

A profile is a saved mapping for one record type: the columns it expects and the Signals field each fills (with any transforms), the file format, what to do when a record already exists, and the fields used to spot duplicates. Profiles are private to the person who made them until shared with the team.

The profile page shows these details, the column mappings and the profile's activity. Edit Profile (shortcut E) is the main action; Actions holds Start an Import, Share With Team / Stop Sharing and Delete Profile. Deleting a profile does not affect imports that already used it.

Migration plans

A migration plan is a list of import steps, one per record type, run in dependency order. Start from the full migration template and switch off the steps you do not need, or build a blank plan. Each step opens the import wizard with its record type set; upload one file per step. The plan page shows overall progress and each step's status; Execute, Pause and Resume control the run, and Actions → Undo Plan deletes the records the plan created where that is safe.

Possible duplicates

On the wizard's preview step, rows that resemble records you already have are listed under Possible duplicates for accounts and catalogue items.

  • An exact match on the batch's duplicate fields follows its conflict strategy: skip leaves the record unchanged, flag marks the row for review, overwrite updates mapped fields, and merge fills empty mapped fields.
  • Normalized or similar matches can be offered as candidates. Similarity alone does not authorize an update or an account identity merge. Review the badge and candidate rather than assuming punctuation or case makes two identities interchangeable.
  • Choose Treat as duplicate to select the existing record for the batch's conflict strategy, or Not a duplicate to reject that candidate. A row with no exact match or accepted candidate is imported as new, subject to validation.

For accounts, both update strategies use the normal guarded account update action. The import strategy named merge is a fill-empty update, not the account lifecycle merge: it does not create a source alias, transfer associations or issue an account merge receipt. Use the separate account merge preview and execution workflow when combining two existing account identities. Import matching does not grant primary-company, credit or privacy authority.

Each candidate carries a badge showing why it was offered. Saying "not a duplicate" is remembered for that batch and row — the same candidate is never offered again.

Addresses use exact matching only.

API

Batch upload, mapping, validation, and commit live on /api/v1/imports. Upload using multipart/form-data with a binary file field and a target_model set to a record type key from GET /api/v1/import-targets (for example accounts, catalogue_items, assets or rental_projects). A JSON request containing a filename cannot upload a file. Saved mapping profiles and migration plans have their own collections.

Set builtin_profile to spreadsheet_migration when uploading a file to apply the preset.

Uploading is asynchronous. POST /api/v1/imports records the file, creates the batch in the parsing phase and answers 202 Accepted with data.job_id (the batch UUID) and data.status_url. Reading the file happens on the imports queue, so background processing can continue beyond the request timeout.

Poll GET /api/v1/imports/{import}/parse until data.status is:

  • completed — the batch is in mapping with detected_columns populated, and the mapping endpoints are ready.
  • failed — data.error_code carries the structured taxonomy code (empty_file, ragged_rows, unparseable_json, archive_not_supported, unparseable_spreadsheet) and the batch status is failed.

A malformed file is a terminal outcome, not a retry: the queue does not attempt it again. The wizard polls the same state and shows a Parsing badge until the worker finishes — the page can be left and returned to.

Import profiles

Endpoint Purpose
GET /api/v1/import-profiles List mapping profiles visible to the caller (api.v1.import-profiles.index)
POST /api/v1/import-profiles Create a mapping profile (api.v1.import-profiles.store)
GET /api/v1/import-profiles/{import_profile} Show one profile (api.v1.import-profiles.show)
PUT /api/v1/import-profiles/{import_profile} Update a profile (api.v1.import-profiles.update)
DELETE /api/v1/import-profiles/{import_profile} Delete a profile (api.v1.import-profiles.destroy)
POST /api/v1/import-profiles/{import_profile}/share Share or unshare a profile (api.v1.import-profiles.share)
POST /api/v1/import-profiles/{import_profile}/apply Apply saved mappings onto a batch (api.v1.import-profiles.apply)

Import plans

Endpoint Purpose
GET /api/v1/import-plan-templates List registered plan templates (api.v1.import-plan-templates.index)
GET /api/v1/import-plans List migration plans (api.v1.import-plans.index)
POST /api/v1/import-plans Create a plan from a template or explicit steps (api.v1.import-plans.store)
GET /api/v1/import-plans/{import_plan} Show a plan and job progress (api.v1.import-plans.show)
POST /api/v1/import-plans/{import_plan}/execute Queue plan execution (api.v1.import-plans.execute)
POST /api/v1/import-plans/{import_plan}/pause Pause a running or queued plan (api.v1.import-plans.pause)
POST /api/v1/import-plans/{import_plan}/resume Resume a paused plan (api.v1.import-plans.resume)
POST /api/v1/import-plans/{import_plan}/undo Undo created records from the plan manifest (api.v1.import-plans.undo)

Import API discovery and invitations

GET /api/v1/import-targets lists supported targets, record counts, fresh_install, unsupported targets and migration_template_url. GET /api/v1/import-targets/{target} returns the target's key, label, duplicate_fields and fields catalogue. Use duplicate_fields to understand the target's natural-key matching.

Download a CSV or XLSX template from GET /api/v1/import-targets/{target}/template.{format}, or a complete workbook from GET /api/v1/import-targets/migration-template.xlsx. These are binary downloads.

POST /api/v1/import-targets/users/send-invitations accepts {"user_ids":[12,34]} and returns {"data":{"queued":2}}. It accepts an idempotency key and has request weight 5. Use it after reviewing imported users.

All import routes return 404 when imports are disabled. Malformed import profile or plan UUIDs return 422. Import plans accept type: full_migration alongside migration and bulk_import, plus user_import and skipped_steps. Each steps item is a closed object with name, target_model, depends_on and skip; unknown keys are rejected.