Metadata Mapping¶

Metadata is the supporting data your transactions point at: the chart of accounts, tax codes, classes, locations, departments, payment terms, payment methods, and customer categories. Your source system has its own list of these, and so does NetSuite. Metadata Mapping is where you tell SuiteMigration which NetSuite record each source value corresponds to.

This has to be done before you push. If a record uses an account that has no mapping, that record fails to push with a message such as "expense line account 123 not mapped". Other values, such as classes or payment terms, are not translated when they are unmapped, so that field is left off the record pushed to NetSuite. Mapping is also what the NetSuite pre-checks and several validation rules read from, so an incomplete mapping set will show up as failures in the Migration Readiness Audit.

Open it from a migration under Metadata Mapping in the left sidebar, just below Rules and Actions.

Before you start¶

Both connections need to be in place for the tabs you will actually map. The migration must be connected to a source (QuickBooks Online, QuickBooks Desktop, Xero, or a source NetSuite account) and to a destination NetSuite account. Until both exist, those tabs tell you which connection is missing instead of showing the table.

The exception is Item Categories, which is display-only. It needs only the source connection and renders fine without a destination. Everywhere this article says mappable tab, it means every tab except Item Categories.

You also want the source data synced and the destination metadata pulled, since the two dropdown lists are built from whatever each side last returned.

The workflow¶

The same steps work on every mappable tab.

1. Open a tab and look at how many rows are unmapped.
2. Run Auto-Map by Name. It fills the exact matches and leaves you the ambiguous rows.
3. Click Save Mappings.
4. Run Auto-Map by AI if you want suggestions for the rows still empty. The button stays disabled until you save, because the run always starts from the last saved state.
5. Work through what is left by hand, using the search box in each dropdown.
6. Map the Blank Value row if your source has records with the field left empty. Accounts has no such row; see below.
7. Click Save Mappings again, then move to the next tab.

Once every mappable tab is saved, run the Migration Readiness Audit and the NetSuite pre-checks. They will tell you if anything is still unmapped or mapped incompatibly.

How the screen works¶

Each metadata type gets its own tab across the top:

Payment Terms, Customer Categories, Tax Codes, Classes, Accounts, Locations, Departments, Payment Methods, Item Categories, and Custom Segment (covered in its own section below).

Inside a tab you get a two-column table. The left column lists your source values. The right column is a searchable dropdown of the matching NetSuite records. Pick the NetSuite record for each source row.

Both columns are sortable. Click the source or destination header to sort by name, which is a quick way to group the unmapped rows together.

At the bottom of the screen a sticky bar shows how many items are mapped and how many unsaved changes you have. Nothing is stored until you click Save Mappings. Refresh discards unsaved edits and reloads what is saved on the server.

Tabs each save independently, so map a tab, save it, and move on.

The Blank Value row¶

Every mappable tab except Accounts has a Blank Value row pinned to the top. It stands in for source records that left the field empty. If your source has invoices with no class on them, mapping Blank Value on the Classes tab decides what class those invoices get in NetSuite. Leave it unmapped and those records simply carry no class across.

Accounts is the exception. It has no Blank Value row, and a blank-value mapping is not saved there even if one somehow existed, so there is nothing to set on that tab.

The tabs¶

Accounts¶

Usually the longest tab. Source accounts are shown as number name when the source has an account number, with the source account type printed underneath.

Above the table there are four filter chips that describe how each account is actually used in your data:

• Items (I): the account is the income, expense or asset account on at least one item.
• Trial Balance (TB): the account appears on the latest Trial Balance pulled from your source.
• Transactions (Tr): the account is used on a transaction, either on the header or on a line.
• Unused (U): nothing references the account.

Unused is off by default, which is deliberate. Most charts of accounts carry dead accounts that were never posted to, and there is no reason to map them. Turn the chip on if you want to see them anyway. The count next to the chips tells you how many rows are currently showing.

An account may carry a subtype badge, on the source side and on the NetSuite side once you pick an account. Today the only one is Undeposited Funds. It needs care: NetSuite has exactly one Undeposited Funds account and it cannot be recreated, so the badge is telling you which specific NetSuite account to point at.

Only subtypes that exist once per company and cannot be created by hand are badged, which is why Undeposited Funds is the only one. Other accounts, including A/P and A/R, carry no badge. Those rows still need your attention, they just do not announce themselves.

The NetSuite dropdown on this tab shows each account as number name, and you can search by number or name. The Undeposited Funds badge is searchable too, so typing "undeposited" finds that account. Once you pick an account, its type and subtype are shown next to it on wider screens, so you can check them at a glance.

Tax Codes¶

Rows are your source tax rates, with the rate percentage shown next to the name, mapped to NetSuite tax codes.

This tab has an extra All / Used only toggle. Used only narrows the list to tax rates that actually appear on transactions, which usually cuts a long list down to something manageable. Start there, and switch to All only if you need to map something that has not been used yet.

Every tax rate that appears on a record needs a mapping. On a QuickBooks Online migration, an invoice, sales receipt or credit memo that carries tax is checked rate by rate, including each part of a combined tax. If any rate on it is unmapped, the record fails to push rather than going across with partial tax.

If tax is not coming across on a QuickBooks Online migration at all, the problem is usually upstream of mapping. See Set Up SuiteTax in NetSuite.

Locations and Departments¶

These two tabs share one source list, on every source system.

The reason is a QuickBooks Online one: QuickBooks Online tracks locations and departments as a single list, and some accounts relabel that list "Location". NetSuite has two separate dimensions. SuiteMigration keeps the merged behaviour on every source, so you will see it on Xero and QuickBooks Desktop migrations too. So SuiteMigration shows the same merged source entries on both tabs and lets you decide independently: map an entry to a NetSuite Location on the Locations tab, and to a NetSuite Department on the Departments tab. A blue banner at the top of each tab reminds you of this.

You do not have to use both. Map only the tab that matches how you want the dimension to land in NetSuite. Mapping an entry on both tabs is fine too, and means the entry lands as both a Location and a Department in NetSuite.

Classes, Payment Terms, Payment Methods, Customer Categories¶

Straightforward name-to-name tabs. Source value on the left, NetSuite record on the right. These are usually the fastest tabs to finish with Auto-Map by Name.

Item Categories¶

Display only. Category-type items are listed so you can see what is in your source, but they are not mapped and there is nothing to save here.

Custom Segment¶

Use this tab if you want your QuickBooks locations and departments to land on a NetSuite custom segment.

QuickBooks keeps locations and departments in one list, so the same source entries appear on the Locations, Departments and Custom Segment tabs. You decide independently where each entry goes in NetSuite.

1. Pick the NetSuite custom segment from the NetSuite Custom Segment dropdown. The list comes from your last destination metadata pull. If it is empty, run a destination metadata pull and reload the page.
2. Map each source entry to one of the segment's values.
3. Click Save Mappings.

Mapped entries are written to that segment on the transactions pushed to NetSuite, and unmapped entries leave the segment empty. Only record types that the segment is set up for in NetSuite receive the value. The Blank Value row works as on the other tabs, and covers records that have no location or department.

Things to know:

• A migration maps one custom segment at a time. If you save after switching to a different segment, the earlier segment's mappings are replaced. You are asked to confirm first, and it cannot be undone.
• Switching segments with unsaved edits discards them, because the values belong to one segment. You are asked to confirm first. Mappings you have already saved are not affected.
• Values that disappear. If a saved mapping points at a value that no longer exists on the segment, the row is marked for re-mapping. It is kept until you re-map it, and it is skipped when pushing.
• A segment with no values cannot be saved. Re-run the destination metadata pull, or choose another segment.
• To turn segment mapping off, clear the segment selection and save. The saved mappings are replaced by nothing, so you are asked to confirm first.
• Auto-Map by AI, Copy from Migration and the download buttons are not available on this tab. Auto-Map by Name is.

Mapping faster¶

You do not have to fill in every row by hand.

Auto-Map by Name¶

Matches source values to NetSuite records with the same name, ignoring case and surrounding whitespace. On the Accounts tab it matches on number name combined, so a source account 4000 Sales Income matches a NetSuite account named 4000 Sales Income.

It only fills rows that are currently empty, so it will never overwrite a mapping you already made. It skips Blank Value. When it finishes it tells you how many rows it matched, or that it found no new matches.

Run this first on every mappable tab. It usually clears most of the list, leaving the ambiguous rows. Then save, before you reach for the AI.

Auto-Map by AI¶

Available on every mappable tab except Custom Segment. It earns its keep most on Accounts and Tax Codes, where names rarely match exactly and the account type matters, but nothing stops you using it elsewhere.

The button is disabled until the tab is saved, because the run always starts from the last saved state. Save first; then it only fills rows that are still empty, so it never replaces a mapping you have already saved.

On Accounts it compares the account name, the account number and the account type together. On the other tabs it compares names only. A source value and a NetSuite value that are identical once case, punctuation and "&" versus "and" are ignored score 100%.

Choosing a model and a threshold¶

Clicking Auto-Map by AI does not start a run. It opens a Select AI Model dialog with two decisions:

• The model. Each option carries a one-line description and a badge:
  • Cohere Rerank v3.5 (Recommended, the default): best for name matching.
  • Titan Embeddings (Experimental): vector-based matching, suited to large lists.
  • Cohere Embeddings (Smart): English-optimized, better at picking up meaning.
• The Confidence Threshold, which defaults to 50%. A suggestion is only filled in if its score is at or above this number. Raise it for fewer but safer suggestions; lower it to have more rows filled and more to review.

Click Auto-Map by AI in the dialog to start the run.

Because the threshold is the floor for what comes back, it decides what you see in the Confidence column next. Raise it to 80% and the amber and red rows below simply will not be suggested at all.

Reading the Confidence column¶

Every AI suggestion comes with a Confidence column, shown as a percentage and colour coded: green above 80%, amber between 50% and 80%, red below 50%. Sort by that column and review the low-confidence rows first. These are suggestions, not decisions. Nothing is committed until you save.

In the run above, the exact name matches come back at 100%. The A/P and A/R accounts, where the source and NetSuite names look nothing alike, come back in the 50 to 70% band. Check those carefully: each has to point at the right NetSuite account, and a plausible-looking suggestion is not the same as a correct one. Accounts Payable 2 gets no suggestion at all. Rows like that stay unmapped for you to fill in.

The AI does not check whether a NetSuite record is already used by another row, so two source rows can end up pointing at the same NetSuite record. That is fine when you are deliberately merging accounts, but look closely at any rows you did not expect to merge.

The run takes a minute or so and the tab is locked while it works. If a run goes over ten minutes it stops with a timeout error, and you can run it again.

Import Mappings¶

Available on Accounts and Tax Codes. Best when someone wants to work the mapping in a spreadsheet, or when the list is long enough that the browser is the wrong tool.

1. Click Import Mappings, then Download Template. The template comes prefilled with your source entries. On the Tax Codes tab, if Used only is active, the template is limited to the same set.

2. Fill in the destination columns. For Accounts, give the destination account code, the name, or both. For Tax Codes, give the destination tax code name.

   Leave the source column exactly as the template wrote it. Sub-accounts are exported fully qualified, so the template holds Automobile:Fuel rather than Fuel, and shortening it means the row will not match. Tax rates carry their rate in brackets, such as GST (5%), because two rates can share a name. Names are not case sensitive, but spelling and punctuation need to match NetSuite.

   For accounts, a code always wins. If you give a code, SuiteMigration finds the account by that code and ignores the name. If the name you typed differs from the account's real name, the row still imports and a notice lists the rows with name mismatches. If you give only a name and it matches more than one account, the row fails and asks you for a code. 3. Upload the completed CSV and click Preview Import. 4. Review the results, then click Import N Valid Rows to apply them.

Preview Import is a dry run. It checks the file and reports what would happen, without writing a single mapping. Nothing is imported until you click Import N Valid Rows on the results screen.

The results screen gives you a Total, Valid and Failed count, and lists each failed row with the row number and the reason. QuickBooks Online account not found points at the source column, NetSuite account not found at the destination one:

Download errors as CSV saves just the failed rows as import_errors.csv, so you can correct those and re-upload without touching the rest. Back returns you to the upload step.

The results screen can also show two notices that do not stop an import:

• Duplicate source. If the same source appears on more than one row, the last row wins, and the notice tells you which rows were involved.
• Account type warning. Rows that map across account categories, such as Expense to Income, still import. They are listed so you can check them.

Only when you click Import N Valid Rows are the valid rows written, and they are saved straight away, so you do not click Save Mappings afterwards. The failed rows are skipped, so a partial import is fine: fix them and run the flow again.

An import only changes the rows in your file. Other mappings already saved on the tab are left alone, and a row in your file replaces the saved mapping for the same source.

Copy from Migration¶

If you have already mapped a sibling migration that is in the same project and uses the same source connection, you can reuse that work rather than redoing it.

Both conditions matter. A project can hold migrations from different source connections, and those are not offered as candidates. The dialog shows which source connection it is filtering by, and tells you directly when no sibling migration shares it.

• Copy from Migration (inside a tab) copies just that metadata type.
• Copy All Mappings from Migration (top right) copies every type that can be copied: Accounts, Tax Codes, Classes, Locations, Departments, Payment Terms, Payment Methods and Customer Categories. Item Categories (display only) and Custom Segment are not copied.

Either way the flow is the same:

1. Pick the migration you want to copy from. The list shows each sibling migration alongside how many mappings it holds.
2. Click Preview Copy and review what is about to happen. The preview breaks the copy down per type into Add, Overwrite, Cleared, Unchanged, Needs review, and Not found, so you can see exactly what will change before anything does.
3. Tick the confirmation checkbox, then click Confirm & Copy.

What each count in the preview means:

• Add: the mapping is new in this migration.
• Overwrite: this migration already had a different mapping for that source.
• Cleared: this migration has a mapping that the other migration does not have, or leaves empty, so it is removed. Copy makes this migration match the other one, it does not merge the two.
• Unchanged: already identical.
• Needs review: the NetSuite record the other migration used was not found in this migration's NetSuite account. SuiteMigration looks for it by name. For accounts it tries the account number together with the name first. These rows show Re-map until you pick one.
• Not found: the source record does not exist in this migration's source data.

If this migration has no NetSuite destination connected yet, the preview warns you that copied entries stay unresolved until one is connected.

The checkbox is there because copying replaces existing mappings in this migration, and anything overwritten or cleared cannot be recovered automatically. Confirm & Copy stays disabled until you tick it. Read the preview if you have already mapped anything here by hand, and check the Overwrite and Cleared columns.

Both buttons are disabled while you have unsaved changes. Save or refresh first.

Download¶

Download Source <tab name> gives you the raw source list for the current tab, so on Accounts the button reads Download Source Accounts and on Tax Codes Download Source Tax Codes. Download Mappings gives you the current mapping set. That file leaves out the Blank Value row and any row with no NetSuite record.

Useful for reviewing with an accountant, or for keeping a record of what was mapped.

Warnings and how to resolve them¶

Account type mismatch¶

When you map a source account to a NetSuite account in a different category, the row is tinted red and gets a warning triangle. Hovering it tells you the mapped NetSuite account is a different type than the source account.

The categories compared are Asset, Liability, Accounts Payable, Accounts Receivable, Credit Card, Equity, Income and Expense. That means mapping an A/P account to a general Liability account is flagged too, not only an expense account mapped to an income account. If either side has an account type SuiteMigration does not recognise, no warning is shown.

On save, SuiteMigration stops and shows an Account Type Mismatch summary listing every affected row with both types side by side. From there you can go Back and correct the mappings, or Save Anyway if the mismatch is intentional.

This one catches people out after an Auto-Map by Name run in particular. Names that match exactly across the two systems can still sit under different account types, as in the Installation and Plants and Soil rows above.

Sometimes the mismatch is what you want. Charts of accounts get restructured during a migration, and reclassifying an account is a fair reason to save through the warning. Check that you meant it, though. A mismatched account posts transactions to the wrong section of your financial statements, and you will meet it again later as a reconciliation difference that is much harder to trace.

Could not match after relinking¶

A red triangle with "Could not match destination by name after relinking of destination" means the mapping existed before, but the destination NetSuite connection was relinked and the previously mapped record could not be found again by name. The dropdown for those rows reads Re-map instead of Select. Pick the correct NetSuite record again and save.

Arriving from a filtered link¶

Rules and Actions has View Unmapped, View Mismapped and View Accounts buttons that open this page with a filter already applied, so you only see the rows a particular rule flagged. The Migration Readiness Audit reports the same rules but does not link here itself; its rule rows link to a support article where one exists, and the view and action controls live on Rules and Actions.

You can also arrive from a record. On a page such as an invoice, bill or item, the mapped values link to the matching row here, and that row is highlighted in yellow for a few seconds.

When you arrive from one of those links, a yellow banner at the top explains what you are looking at:

• Showing only unmapped accounts means these accounts are used by items but have no NetSuite mapping. The banner also names an account type when the link narrowed it further.
• Showing accounts flagged by a rule name means these accounts need re-mapping to a compatible NetSuite account type or subtype.

Work through the filtered list and save. When the last one is handled, the page reruns the underlying check and shows a green confirmation that nothing is left, so you know you are genuinely done rather than just looking at an empty filter. Clear Filter returns you to the full list.

Which NetSuite account types work where¶

NetSuite is strict about which kind of account a given transaction can post to. SuiteMigration checks your mappings against these rules, and the results show up in the Migration Readiness Audit and in Rules and Actions. It is quicker to get them right while mapping.

Two more cases to know about:

• Undeposited Funds has to be mapped to NetSuite's own Undeposited Funds account. There is only one and it cannot be recreated. One check fires when it is unmapped, and another when it is mapped to a different account.
• Checks and cash expenses with a line on an A/P account cannot be pushed as a check, because NetSuite does not allow A/P accounts on a check's expense lines. You can convert them to journal entries and push those instead, or change the line's account in the source.

Merging accounts and checking your work¶

Merging accounts¶

Nothing stops you pointing several source accounts at one NetSuite account, for example folding three "Sales" accounts into one. Make sure it is intentional, because neither Auto-Map by Name nor Auto-Map by AI checks whether a NetSuite account is already used by another row.

Seeing the whole project at once¶

Open Account Mappings under Project Reports in the project's left sidebar. This page sits at project level, so it covers every migration in the project at once.

The Account Mappings by Migration page opens with a Migration Summary, one row per migration, showing:

• the number of source accounts,
• how many are unmapped, and
• how many are duplicated, meaning they share a NetSuite account with another source account.

The same usage chips as on the Accounts tab filter the Migration Summary, with Unused off by default.

Below the summary, each migration has its own section showing every group of source accounts that point at the same NetSuite account, and how many merges it has. You can collapse a section with its arrow.

To work on a migration's mappings, click its name in the Migration Summary. This opens that migration's Accounts tab.

Who changed what¶

Saving, importing and copying mappings are all recorded in the workspace Audit Log. Each entry shows what was added, removed or updated, with the old and new NetSuite record side by side.

When you are done¶

Mapping is not a one-time step. New accounts, tax codes, or classes created in the source after your last sync will appear here as unmapped rows the next time you resync, so it is worth a quick pass before each push.

Once the mappable tabs are mapped and saved, run the Migration Readiness Audit and the NetSuite pre-checks. Between them they will tell you whether anything is still unmapped or mapped incompatibly before you push. Use Rules and Actions to work through whatever they flag.

Mappings survive disconnecting and reconnecting your source or NetSuite. After the next sync they are re-attached: source entries by their source ID, and NetSuite entries by name. Rows where the NetSuite record could not be found again show the red triangle and Re-map, as described above.

Related articles¶

• Migration Readiness Audit
• Connect to NetSuite
• Set Up SuiteTax in NetSuite
• Mixed A/P Account Rule
• Mixed A/R Account Rule