# Integration Id migration

A one-time admin tool that fills the Integration Id from a key field you already maintain, so you can bind Business Central records to your external system without re-keying every record.

Most integrations bind a Business Central record to the external system by writing its key into [the Integration Id](https://eonesolutions.github.io/eone-bc-integration/integration-id.md). If you are already storing that key somewhere (a field from a retired integration, another add-on, or a spare base-app field), you do not have to re-enter it. This tool copies that existing field into `Integration Id` in bulk, across one company or every company in the tenant.

It is a **setup-time convenience**, not part of the running integration: use it once during onboarding to seed history, then drive new records through the API as normal.

## Open the tool

Search **Tell Me** for **eOne Integration Id Migration**. The page opens with **one row per covered table** already listed. You do not add rows, you only choose which tables to migrate.

## Map a source field

For each table you want to seed:

1. On its row, choose the lookup on **Source Field No.** and pick the field that already holds your key.
2. Leave every table you are not migrating **blank**; blank rows are ignored.

The lookup only offers fields that can safely hold a key: **Text or Code**, normal (not calculated), enabled, and **100 characters or shorter** (the Integration Id is `Text[100]`, so a longer field is rejected to avoid truncating keys). It also shows the **owning extension** for each field, so you can tell your legacy key field apart from a similarly named base-app field, and it hides the extension's own `EONE`-affixed fields, including the destination.

> **Tip:** If you are moving off a retired SmartConnect extension, use **Pre-seed from Legacy Extension** first (below) instead of mapping fields by hand.

## Choose overwrite behavior

**Overwrite Existing Values** controls what happens to records that already have an Integration Id:

- **Off** (default). Only records with a blank Integration Id are filled. Re-running fills the gaps and leaves existing values untouched, so it is safe to run repeatedly.
- **On.** The source value wins even over an existing Integration Id.

## Run

Choose **Run Migration** and pick a scope:

- **Current company only.** Migrates the company you are signed into.
- **All companies.** Migrates every company in the tenant in one pass, without signing into each. Each company is committed independently, so a long run is not one giant transaction, and if one company fails (for example a permission gap) it is reported and skipped rather than aborting the whole run.

Only rows that have a Source Field set are processed. Grid selection does not matter. After the run, each row shows **Records Migrated**, **Records Skipped**, and **Last Run**, and a summary message reports the totals (and lists any companies that could not be processed).

> **Note:** The copy is a raw key backfill. It writes the Integration Id directly and does **not** fire the table's `OnValidate`/`OnModify` logic or trip change-tracking webhooks. It is a data-seeding step, not a document import.

## Pre-seed from a legacy extension

If a retired SmartConnect extension is installed (**[eCommerce](https://github.com/ethan-sorenson/SmartConnect-eCommerce-Extension)** or **[ConnectWise](https://github.com/ethan-sorenson/SmartConnectConnectWise/tree/main)**), choose **Pre-seed from Legacy Extension** to fill in the source fields for the tables that extension covered (for example the eCommerce Id on Customer and Item, or the ConnectWise Id across the master and line tables). This **only sets up the mapping for you to review**. It does not change any data or run the migration. Rows you have already mapped are left as-is, so it is safe to choose more than once.

The same pre-seed runs automatically on install and upgrade when a legacy extension is present, so you may find the mappings already filled in when you open the tool. Review them, adjust if needed, then **Run Migration** when you are ready.

> **Caution:** Pre-seed covers what maps cleanly into the `Text[100]` Integration Id. A few legacy fields have no direct target. For example, the eCommerce **Inventory Id** on Item maps to `EONE Inventory Id`, not `Integration Id`, so it is left for a manual step.

## Where to go next

- Learn the external-key contract this tool populates in [The Integration Id](https://eonesolutions.github.io/eone-bc-integration/integration-id.md).
- See the whole setup sequence in the [Overview](https://eonesolutions.github.io/eone-bc-integration/home.md).

**Next:** [How document workflow works](https://eonesolutions.github.io/eone-bc-integration/document-workflow.md). The pipeline your endpoint settings drive.