How to Configure Copy Tenant in iDempiere
Learn how to configure the Copy Tenant window in iDempiere to migrate or duplicate retail store tenants, including field setup and validation steps.
Introduction
The Copy Tenant window runs iDempiere’s Move Client process, used to duplicate a template tenant or migrate a tenant from an external database into the current instance. Retail chains use it when onboarding a new store from a standard template or consolidating an acquired franchise’s database into a central iDempiere instance. Because tenant data includes business partners, products, price lists, and transactions, this configuration directly affects data integrity, reporting accuracy, and store go-live timelines.
Process Flow
Business Rules
- Only Validate Data must be unchecked to actually copy records; checked mode is validation-only.
- Copy Template Tenant duplicates an existing tenant instead of connecting to an external database.
- JDBC URL is mandatory when copying from an external database.
- Tenants to Include and Tenants to Exclude should not both be used in the same run.
- Tables listed in Tables to Exclude are skipped entirely during migration.
- Preserve IDs keeps original record IDs instead of generating new ones for listed tables.
- Fallback Records apply when a foreign key reference cannot be resolved during migration.
- Run as Job executes the migration in the background without blocking the user session.
Prerequisites
- Target iDempiere database instance is installed and accessible.
- Source database connection details (JDBC URL, User Name, Password) are available for external migration.
- Template tenant already exists when using Copy Template Tenant mode.
- System Administrator role access is granted to run the process.
- Full backup of the target database is completed before running migration.
Configuration Steps
Step 1: Choose the Migration Mode
This determines whether the process copies a template tenant locally or connects to an external database.
Check Copy Template Tenant to duplicate an existing tenant in the same database. Leave it unchecked to migrate from an external source using JDBC connection details.
| Field | Sample Value | Description |
| Copy Template Tenant | Checked / Unchecked | Selects internal template copy vs. external database migration |
Step 2: Configure Source Database Connection
Required so iDempiere can read tenant data from the external system when not copying a template.
Enter JDBC URL, User Name, and Password for the source database. Leave these blank when Copy Template Tenant is checked.
| Field | Sample Value | Description |
| JDBC URL | jdbc:postgresql://192.168.1.20:5432/idempiere | Connection string to the external source database |
| User Name | idempiereuser | Database login used to read source data |
| Password | ******** | Database password for the source login |
Step 3: Define Migration Scope
Limits the migration to specific tenants and tables to avoid moving unnecessary data.
Enter tenant IDs in Tenants to Include or Tenants to Exclude. List tables to skip in Tables to Exclude using comma-separated values.
| Field | Sample Value | Description |
| Tenants to Include | 1000001 | Restricts migration to the listed tenant(s) only |
| Tenants to Exclude | 11,12 | Migrates all tenants except those listed |
| Tables to Exclude | AD_ChangeLog,AD_Session | Skips listed tables during migration |
Step 4: Run Validation Before Migration
Confirms the source data is compatible with the target database schema before any records are copied.
Keep Only Validate Data checked and run the process first. Review the log for errors before unchecking it to perform the actual migration.
| Field | Sample Value | Description |
| Only Validate Data | Checked | Runs schema and data checks without copying any records |
Step 5: Configure ID Handling
Controls whether original record IDs are kept or replaced, and how unresolved references are handled.
Enter table names in Preserve IDs to keep original IDs. Use Fallback Records when FK not found to define default records for broken references.
| Field | Sample Value | Description |
| Preserve IDs | C_UOM | Retains original record IDs for the listed tables |
| Fallback Records when FK not found | Standard | Assigns a fallback record when a foreign key cannot be matched |
Step 6: Execute the Migration
Starts the actual data copy once validation passes and all parameters are confirmed.
Uncheck Only Validate Data, optionally check Run as Job for background execution, then click OK to start the migration.
| Field | Sample Value | Description |
| Run as Job | Checked | Executes the process asynchronously as a background job |
| Note: Always run with Only Validate Data checked first. A clean validation pass significantly reduces migration failures in production. |
Common Issues and Resolutions
| Issue | Cause | Resolution |
| Migration stops at validation | Column length mismatch between source and target | Adjust the target column length or exclude the table |
| Duplicate client error | A tenant with the same Name, Value, or UUID already exists | Rename or remove the existing tenant before retrying |
| Orphan record error | A child record references a missing parent, e.g. Order_ID not found | Fix the source data or exclude the affected table |
| Cross-tenant reference error | A record from one tenant references another tenant’s data | Correct source data so references stay within one tenant |
| External storage not supported | Attachments or archives are stored outside the database | Move attachments into the database before migration |
| Migration runs slowly | Large log or history tables copied without exclusions | Exclude tables like AD_ChangeLog and AD_Session |
| Sequences out of sync after copy | Document sequences are not refreshed after migration | Manually verify and reset sequence next numbers |
| JDBC connection failure | Incorrect URL, credentials, or restricted network access | Verify the JDBC URL format and database accessibility |
Next Steps
- Configure Document Sequence for the newly migrated or copied tenant.
- Review Organization and Warehouse setup for the tenant.
- Set up Role and User Access for the new tenant.
- Run database compression or vacuum after large migrations.