Skip to main content

Friend Import & Mapping

Overview​

There are two mechanisms for bringing external data in and attaching it to LINE friends.

  1. LINE user import — upload a CSV containing LINE userIds to create new rows in line_user. Used when migrating from another system, or when a list of userIds already exists.
  2. Import mapping — upload a CSV of customer data and map it onto friends who already exist, matching on a chosen key such as mobile_no or a key of the form custom.<key>.

Both run asynchronously in worker-go and record their outcome statistics in JSONB columns.

Core Data Structure​

line_user_import (model LineUserImport)​

One row per uploaded file, holding title, file_name, file_path, archive_path along with the progress counters total_records, total_processed and process_attempt.

Job state lives in status (enum LineUserImportStatus: new, processing, completed, failed), accompanied by summary_stats JSONB, note, line_oa_id and organization_id.

line_user_import_detail (model LineUserImportDetail)​

One row per CSV line, keyed by UUID and linked back through import_id (FK to line_user_import.id).

It stores line_user_id (the LINE userId read from the file), line_user_profile JSONB, status (enum LineUserImportDetailStatus: new, insert, exist, undefined, error_format) and error_message.

import_mapping_job​

Created through manual SQL only and absent from Prisma, this table drives the import-mapping flow.

  • file_name, file_path and status (pending, processing, success, partial, failed)
  • unique_key JSONB — the matching key, e.g. {"field":"mobile_no","csvColumn":"Phone Number"}
  • mappings JSONB — the column-to-target mapping, e.g. [{"csvColumn":"Member Tier","target":"custom.member_tier"}]
  • validation JSONB — the pre-import dry run summarising total, willUpdate, noMatch, errors and their reasons
  • stats JSONB — the actual post-run results, plus error_log_path for downloading the log
  • Index on (line_oa_id, status)

The migration that creates this table also registers the import-mapping module into system_module, system_role_module and organization_module.

  • prisma/schema.prisma:716 — model LineUserImport
  • prisma/schema.prisma:742 — model LineUserImportDetail
  • manual-sql/9.import_mapping.sql — creates import_mapping_job and grants the module permissions
  • schema-dumps/2026-07-24/schema.sql:2281, :2306 and :1984

Connections to Other Services​

  • cms-api-go — accepts the upload, creates the job, renders the result summary, and serves the error log download.
  • worker-go — processes the import_mapping_job queue and LINE user import jobs, writing results back into line_user. During bulk updates it sets app.skip_triggers='true' so the attribute_changed trigger does not fire on every row.
  • The destination of all this data is LINE Friends, and the mapping keys reference definitions in Attribute Definitions.