alla-allaos-fullstack/docs/setup/import-mapping.md

CSV Import Mapping

This document maps supported setup CSV columns to target fields and reference resolvers.

Common resolver rules:

• organization_code resolves to the setup organization by wizard code, organization slug, or import context alias.
• *_email resolves to users.email.
• branch_code resolves to ms_options where category = crm_branch.
• product_type_code resolves to ms_options where category = crm_product_type.
• Master option values resolve by category and code unless a target field explicitly stores plain text.
• All imported rows are organization-scoped unless noted otherwise.

organizations.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	setup alias / metadata	trim uppercase	unique in import batch	yes	none	none	Not currently a DB column; used by setup import context.
organization_name	organizations.name	trim	non-empty	yes	none	none
slug	organizations.slug	trim lowercase	unique	yes	organizations.slug duplicate check	generated from name only in wizard mode
created_by_email	organizations.created_by	lowercase email	user exists	yes	users.email -> id	current setup actor
plan	organizations.plan	trim lowercase	known plan string	no	none	enterprise for setup-created org
logo_url	organizations.image_url	trim	URL or relative path	no	none	null

users.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
email	users.email	trim lowercase	email format, unique	yes	duplicate by email	none	Upsert key.
name	users.name	trim	non-empty	yes	none	email local part
system_role	users.system_role	trim lowercase	super_admin,user	yes	none	user
password	users.password_hash	bcrypt hash	required for new credentials user	no	none	generated invite flow later	Do not store raw password.
active_organization_code	users.active_organization_id	resolve	org exists	no	organization resolver	null
image_url	users.image	trim	URL optional	no	none	null
reset_password	import behavior	boolean	true/false	no	none	false	Allows password update for existing users.

memberships.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	memberships.organization_id	resolve	org exists	yes	organization resolver	setup org
user_email	memberships.user_id	lowercase	user exists	yes	users.email	none
membership_role	memberships.role	lowercase	admin,user	yes	none	user
business_role	memberships.business_role	lowercase	known CRM fallback role	yes	role definition code	sales_support	Compatibility fallback only.
permissions	memberships.permissions	pipe split	known permission codes	no	src/lib/auth/rbac.ts	default permissions
branch_scope_codes	memberships.branch_scope_ids	pipe split resolve	branch options exist	no	crm_branch options	empty array	Compatibility scope only.
product_type_scope_codes	memberships.product_type_scope_ids	pipe split resolve	product type options exist	no	crm_product_type options	empty array	Compatibility scope only.

crm-role-assignments.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
user_email	user_id	lowercase	user + membership exist	yes	user resolver	none
crm_role_code	role_profile_id	lowercase	role profile exists	yes	crm_role_profiles.code	none
is_primary	is_primary	boolean	true/false	yes	none	false	One primary per user warning/enforcement.
branch_scope_mode	branch_scope_mode	lowercase	all,selected,none,inherit	yes	none	inherit
branch_codes	branch_scope_ids	pipe split resolve	required when mode selected	no	crm_branch options	empty array
product_type_scope_mode	product_type_scope_mode	lowercase	all,selected,none,inherit	yes	none	inherit
product_type_codes	product_type_scope_ids	pipe split resolve	required when mode selected	no	crm_product_type options	empty array
is_active	is_active	boolean	true/false	no	none	true

master-options.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
category	category	trim lowercase	non-empty	yes	none	none
code	code	trim	non-empty unique per category	yes	duplicate check	none
label	label	trim	non-empty	yes	none	none
value	value	trim	optional	no	none	same as code
parent_category	parent lookup	trim	parent requires parent_code	no	ms_options.category	null
parent_code	parent_id	resolve	parent exists	no	ms_options.category+code	null
sort_order	sort_order	integer	>= 0	no	none	0
is_active	is_active	boolean	true/false	no	none	true
metadata_json	metadata	JSON parse	valid object	no	none	null

branches.csv

Maps to ms_options with fixed category = crm_branch.

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
branch_code	code, value	trim lowercase snake_case	unique per org	yes	duplicate check	none
branch_name	label	trim	non-empty	yes	none	none
prefix	metadata.prefix	trim uppercase	optional	no	none	first letters of code	Used by sequence suggestions only.
address	metadata.address	trim	optional	no	none	null
tax_id	metadata.taxId	trim	optional	no	none	null
phone	metadata.phone	trim	optional	no	none	null
email	metadata.email	lowercase	email optional	no	none	null
sort_order	sort_order	integer	>= 0	no	none	0
is_active	is_active	boolean	true/false	no	none	true

product-types.csv

Maps to ms_options with fixed category = crm_product_type.

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
product_type_code	code, value	lowercase snake_case	unique per org	yes	duplicate check	none
product_type_name	label	trim	non-empty	yes	none	none
document_prefix	metadata.documentPrefix	uppercase	optional	no	none	derived from code	Used for sequence suggestion.
sort_order	sort_order	integer	>= 0	no	none	0
is_active	is_active	boolean	true/false	no	none	true
metadata_json	metadata merge	JSON parse	object	no	none	null	Merged after documentPrefix.

document-sequences.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
branch_code	branch_id	resolve	option exists when provided	no	crm_branch option	empty string	Empty string means generic branch scope.
product_type_code	product_type	normalize	option exists or all	no	crm_product_type option/code	all	Store normalized code, not option id.
document_type	document_type	lowercase	supported by sequence foundation	yes	none	none
prefix	prefix	trim	non-empty	yes	none	none
period	period	trim	matches active period format	yes	none	generated current YYMM later
current_number	current_number	integer	>= 0	no	none	0
padding_length	padding_length	integer	1-12	no	none	3
format	format	trim	contains {running}	no	none	{prefix}{period}-{running}
reset_policy	reset_policy	lowercase	known reset policy	no	none	period
is_active	is_active	boolean	true/false	no	none	true

approval-workflows.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
workflow_code	code	lowercase snake_case	unique per org	yes	duplicate check	none
workflow_name	name	trim	non-empty	yes	none	none
entity_type	entity_type	lowercase	quotation initially	yes	none	quotation
description	description	trim	optional	no	none	null
is_system	is_system	boolean	true/false	no	none	false
is_active	is_active	boolean	true/false	no	none	true

approval-steps.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
workflow_code	workflow_id	resolve	workflow exists	yes	approval workflow	none
step_number	step_number	integer	> 0	yes	none	none
role_code	role_code	lowercase	role code known	yes	role profile optional check	none
role_name	role_name	trim	non-empty	yes	none	label from role profile
approval_mode	approval_mode	lowercase	known mode	no	none	sequential
is_required	is_required	boolean	true/false	no	none	true
sla_hours	sla_hours	integer	>= 0	no	none	24
calendar_mode	calendar_mode	lowercase	known mode	no	none	calendar_days
timeout_action	timeout_action	lowercase	known action	no	none	none

approval-matrix.csv

CSV Column	Target Field	Transform	Validation	Required	Reference Resolver	Fallback	Notes
organization_code	organization_id	resolve	org exists	yes	organization resolver	setup org
entity_type	entity_type	lowercase	quotation initially	yes	none	quotation
workflow_code	workflow_id	resolve	workflow exists	yes	approval workflow	none
branch_code	branch_id	resolve	optional branch exists	no	branch option	null	Null means any branch.
product_type_code	product_type	normalize	optional product type exists	no	product type option/code	null
min_amount	min_amount	decimal	<= max when both exist	no	none	null
max_amount	max_amount	decimal	>= min when both exist	no	none	null
currency	currency	uppercase	currency option exists	no	crm_currency	null
priority	priority	integer	>= 0	yes	none	100
is_default	is_default	boolean	true/false	yes	none	false
is_active	is_active	boolean	true/false	no	none	true
description	description	trim	optional	no	none	null

CRM Business CSVs

The following mappings use the same resolver pattern:

CSV File	Business Key	Required Reference Resolvers	Important Option Resolvers	Generated Fields	Notes
customers.csv	organization_code + customer_code	organization, branch, owner user, created_by user	crm_customer_type, crm_customer_status, crm_customer_group, crm_customer_sub_group, crm_lead_channel	id, timestamps, owner assignment timestamps	Owner history should be generated by service behavior.
contacts.csv	organization_code + customer_code + email/contact_name	organization, customer, created_by user	none	id, timestamps	Contact must belong to resolved customer.
contact-shares.csv	organization + contact + shared_to_user	organization, customer, contact, shared users	none	id, shared_at, timestamps	Target user must have organization membership.
leads.csv	organization_code + lead_code	organization, branch, customer, contact, creator, marketing owner, sales assignee	crm_lead_status, crm_lead_followup_status, crm_lead_lost_reason, crm_product_type, crm_priority, crm_lead_awareness, crm_lead_channel	id, timestamps, assignment timestamps	Lead outcome defaults to open.
opportunities.csv	organization_code + opportunity_code	organization, lead, customer, contact, creator, updater, assignee	crm_product_type, crm_opportunity_status, crm_priority, crm_lead_channel, outcome/cancel/no-quotation reasons	id, timestamps, assignment/lifecycle timestamps	Validate contact/customer and optional lead lineage.
opportunity-parties.csv	opportunity + customer + role_code	organization, opportunity, customer	crm_project_party_role	id, timestamps	Used by revenue attribution.
quotations.csv	organization_code + quotation_code	organization, opportunity, customer, contact, branch, users, parent quotation	crm_quotation_type, crm_quotation_status, crm_currency, crm_discount_type, crm_sent_via	id, timestamps	Runtime approval/PDF fields must not be accepted from CSV.
quotation-items.csv	quotation + item_number	organization, quotation	crm_product_type, crm_unit, crm_discount_type	id, timestamps	Validate numeric price fields.
quotation-parties.csv	quotation + customer + role_code	organization, quotation, customer	crm_project_party_role	id, timestamps	Used by quotation reporting/PDF context.
quotation-topics.csv	quotation + topic_key	organization, quotation	crm_quotation_topic_type	id, timestamps	topic_key is import-only alias.
quotation-topic-items.csv	quotation + topic_key + sort_order	organization, quotation topic by import alias or existing lookup	none	id, timestamps	Topic must be preview-resolved before commit.

Business CSV field transforms:

• Dates: accept YYYY-MM-DD; API responses remain ISO UTC.
• Booleans: accept true,false,1,0,yes,no; normalize to boolean.
• Amounts: parse decimal with .; reject thousands separators in strict mode.
• Pipe lists: split on |, trim, reject empty tokens in strict mode.
• Empty string: normalize to null for nullable DB fields.

Business CSV fallback rules:

• created_by_email may fall back to setup actor only when the CSV file explicitly omits it and the import run is wizard-owned.
• updated_by_email may fall back to created_by_email.
• branch_code may fall back to the wizard default branch.
• currency may fall back to organization default currency once that is persisted in setup state or organization metadata.
• Option fields should not silently create new options unless import mode is allowOptionCreate.

Unsupported Mapping Decisions

CSV	Mapping Decision
departments.csv	Block. No first-class schema.
teams.csv	Block. No first-class team graph; security docs note team-scope limitations.
warehouses.csv	Block. No first-class schema.
sites.csv	Block. Current project location is text on lead/opportunity/quotation.
services.csv	Block. No first-class service catalog.
price-books.csv	Block. No price book foundation.
tax-rates.csv	Block. No tax rate table; quotation/item rows carry tax numbers.
attachments.csv	Defer. Needs binary upload/storage import design, not pure CSV.
email-settings.csv	Block. No secure first-class email settings table.