{"id":22569,"date":"2026-08-04T07:02:32","date_gmt":"2026-08-04T07:02:32","guid":{"rendered":"https:\/\/tenthplanet.in\/idempiere\/?p=22569"},"modified":"2026-08-20T07:01:36","modified_gmt":"2026-08-20T07:01:36","slug":"how-to-configure-copy-tenant-in-idempiere","status":"publish","type":"post","link":"https:\/\/tenthplanet.in\/idempiere\/how-to-configure-copy-tenant-in-idempiere\/","title":{"rendered":"How to Configure Copy Tenant in iDempiere"},"content":{"rendered":"\n

Learn how to configure the Copy Tenant window in iDempiere to migrate or duplicate retail store tenants, including field setup and validation steps.<\/p>\n\n\n\n

Introduction<\/strong><\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

Process Flow<\/strong><\/h2>\n\n\n\n
\"Tenthplanet-Idempiere-CopyTenant\"<\/figure>\n\n\n\n

Business Rules<\/strong><\/h2>\n\n\n\n
    \n
  • Only Validate Data must be unchecked to actually copy records; checked mode is validation-only.<\/li>\n\n\n\n
  • Copy Template Tenant duplicates an existing tenant instead of connecting to an external database.<\/li>\n\n\n\n
  • JDBC URL is mandatory when copying from an external database.<\/li>\n\n\n\n
  • Tenants to Include and Tenants to Exclude should not both be used in the same run.<\/li>\n\n\n\n
  • Tables listed in Tables to Exclude are skipped entirely during migration.<\/li>\n\n\n\n
  • Preserve IDs keeps original record IDs instead of generating new ones for listed tables.<\/li>\n\n\n\n
  • Fallback Records apply when a foreign key reference cannot be resolved during migration.<\/li>\n\n\n\n
  • Run as Job executes the migration in the background without blocking the user session.<\/li>\n<\/ul>\n\n\n\n

    Prerequisites<\/strong><\/h2>\n\n\n\n
      \n
    • Target iDempiere database instance is installed and accessible.<\/li>\n\n\n\n
    • Source database connection details (JDBC URL, User Name, Password) are available for external migration.<\/li>\n\n\n\n
    • Template tenant already exists when using Copy Template Tenant mode.<\/li>\n\n\n\n
    • System Administrator role access is granted to run the process.<\/li>\n\n\n\n
    • Full backup of the target database is completed before running migration.<\/li>\n<\/ul>\n\n\n\n

      Configuration Steps<\/strong><\/h2>\n\n\n\n

      Step 1: Choose the Migration Mode<\/strong><\/h3>\n\n\n\n

      This determines whether the process copies a template tenant locally or connects to an external database.<\/p>\n\n\n\n

      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.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      Copy Template Tenant<\/td>Checked \/ Unchecked<\/td>Selects internal template copy vs. external database migration<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Step 2: Configure Source Database Connection<\/strong><\/h3>\n\n\n\n

      Required so iDempiere can read tenant data from the external system when not copying a template.<\/p>\n\n\n\n

      Enter JDBC URL, User Name, and Password for the source database. Leave these blank when Copy Template Tenant is checked.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      JDBC URL<\/td>jdbc:postgresql:\/\/192.168.1.20:5432\/idempiere<\/td>Connection string to the external source database<\/td><\/tr>
      User Name<\/td>idempiereuser<\/td>Database login used to read source data<\/td><\/tr>
      Password<\/td>********<\/td>Database password for the source login<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Step 3: Define Migration Scope<\/strong><\/h3>\n\n\n\n

      Limits the migration to specific tenants and tables to avoid moving unnecessary data.<\/p>\n\n\n\n

      Enter tenant IDs in Tenants to Include or Tenants to Exclude. List tables to skip in Tables to Exclude using comma-separated values.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      Tenants to Include<\/td>1000001<\/td>Restricts migration to the listed tenant(s) only<\/td><\/tr>
      Tenants to Exclude<\/td>11,12<\/td>Migrates all tenants except those listed<\/td><\/tr>
      Tables to Exclude<\/td>AD_ChangeLog,AD_Session<\/td>Skips listed tables during migration<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Step 4: Run Validation Before Migration<\/strong><\/h3>\n\n\n\n

      Confirms the source data is compatible with the target database schema before any records are copied.<\/p>\n\n\n\n

      Keep Only Validate Data checked and run the process first. Review the log for errors before unchecking it to perform the actual migration.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      Only Validate Data<\/td>Checked<\/td>Runs schema and data checks without copying any records<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Step 5: Configure ID Handling<\/strong><\/h3>\n\n\n\n

      Controls whether original record IDs are kept or replaced, and how unresolved references are handled.<\/p>\n\n\n\n

      Enter table names in Preserve IDs to keep original IDs. Use Fallback Records when FK not found to define default records for broken references.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      Preserve IDs<\/td>C_UOM<\/td>Retains original record IDs for the listed tables<\/td><\/tr>
      Fallback Records when FK not found<\/td>Standard<\/td>Assigns a fallback record when a foreign key cannot be matched<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Step 6: Execute the Migration<\/strong><\/h3>\n\n\n\n

      Starts the actual data copy once validation passes and all parameters are confirmed.<\/p>\n\n\n\n

      Uncheck Only Validate Data, optionally check Run as Job for background execution, then click OK to start the migration.<\/p>\n\n\n\n

      Field<\/strong><\/td>Sample Value<\/strong><\/td>Description<\/strong><\/td><\/tr><\/thead>
      Run as Job<\/td>Checked<\/td>Executes the process asynchronously as a background job<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
      Note: <\/strong>Always run with Only Validate Data checked first. A clean validation pass significantly reduces migration failures in production.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Common Issues and Resolutions<\/strong><\/h2>\n\n\n\n
      Issue<\/strong><\/td>Cause<\/strong><\/td>Resolution<\/strong><\/td><\/tr><\/thead>
      Migration stops at validation<\/td>Column length mismatch between source and target<\/td>Adjust the target column length or exclude the table<\/td><\/tr>
      Duplicate client error<\/td>A tenant with the same Name, Value, or UUID already exists<\/td>Rename or remove the existing tenant before retrying<\/td><\/tr>
      Orphan record error<\/td>A child record references a missing parent, e.g. Order_ID not found<\/td>Fix the source data or exclude the affected table<\/td><\/tr>
      Cross-tenant reference error<\/td>A record from one tenant references another tenant’s data<\/td>Correct source data so references stay within one tenant<\/td><\/tr>
      External storage not supported<\/td>Attachments or archives are stored outside the database<\/td>Move attachments into the database before migration<\/td><\/tr>
      Migration runs slowly<\/td>Large log or history tables copied without exclusions<\/td>Exclude tables like AD_ChangeLog and AD_Session<\/td><\/tr>
      Sequences out of sync after copy<\/td>Document sequences are not refreshed after migration<\/td>Manually verify and reset sequence next numbers<\/td><\/tr>
      JDBC connection failure<\/td>Incorrect URL, credentials, or restricted network access<\/td>Verify the JDBC URL format and database accessibility<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Next Steps<\/strong><\/h2>\n\n\n\n
        \n
      • Configure Document Sequence for the newly migrated or copied tenant.<\/li>\n\n\n\n
      • Review Organization and Warehouse setup for the tenant.<\/li>\n\n\n\n
      • Set up Role and User Access for the new tenant.<\/li>\n\n\n\n
      • Run database compression or vacuum after large migrations.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"

        Learn how to configure the Copy Tenant window in iDempiere to migrate or duplicate retail store tenants, including field setup […]<\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[10,91],"tags":[],"class_list":["post-22569","post","type-post","status-publish","format-standard","hentry","category-idempiere-product","category-idempiere-general-rules"],"_links":{"self":[{"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/posts\/22569","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/comments?post=22569"}],"version-history":[{"count":2,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/posts\/22569\/revisions"}],"predecessor-version":[{"id":27765,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/posts\/22569\/revisions\/27765"}],"wp:attachment":[{"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/media?parent=22569"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/categories?post=22569"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tenthplanet.in\/idempiere\/wp-json\/wp\/v2\/tags?post=22569"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}