Configure Advanced Database Mapping

Configure Advanced Database Mapping

Advanced Database Mapping extends supported mapping to fields and underlying database columns when the complete migration path is eligible. Use it only when both the Source Platform and Target Platform are Open-Source, then confirm that the specific source field or column, target destination, and value compatibility remain within supported scope.

Both platforms must be Open-Source

An Open-Source Source Platform alone is not sufficient, and an Open-Source Target Platform alone is not sufficient. If either platform is Non-Open-Source, Advanced Database Mapping is not available for that migration path.

Before you start

Prepare:

• the confirmed Source Platform and Target Platform for the purchased migration;
• confirmation that both platforms are Open-Source;
• the selected data type;
• the supported source field or database column;
• the intended compatible target field or database column;
• the source and target field or column types;
• the business function or target-side component that is expected to use the stored value;
• representative normal, boundary, empty, and exception values.

Tax data is excluded from Standard Advanced Database Mapping scope. If the requirement involves Tax fields or columns, stop and confirm the supported handling before configuring the mapping.

Separate path eligibility from mapping support

When both platforms are Open-Source, the migration meets the Add-on’s platform prerequisite. You must still confirm that the specific field or database column, target destination, and value representation are supported.

Check	Question
Platform path	Are both the Source Platform and Target Platform Open-Source?
Source support	Is the required source field or database column supported for this migration?
Target support	Is the intended target field or database column available and supported?
Value compatibility	Can the target field or column represent the complete source value correctly?
Target consumption	Does the required admin, storefront, theme, app, extension, integration, or business logic actually use the stored value?

All applicable checks must pass for the requirement to be complete.

Configure a database mapping

1. Open Advanced Database Mapping

   In Add-ons, locate Advanced Database Mapping.

2. Confirm the migration-path prerequisite

   Verify that the purchased Source Platform and Target Platform are both Open-Source before creating rules.

3. Select the data type

   Work within the supported data type that owns the source field or database column.

4. Select the supported source field or column

   Choose the exact source value whose destination must change.

5. Select the compatible target field or column

   Choose a supported target destination that can represent the source value correctly.

6. Review field or column types

   Check the complete expected value range, including empty, long, numeric, text, date, Boolean, or structured values where applicable.

7. Add other required mappings

   Keep each rule tied to one defined source value, destination, and expected result. Remove conflicting destinations before execution.

8. Test representative records

   Verify both the stored value and any target-side behavior that depends on it.

Practical use cases

These examples apply only when both the Source Platform and Target Platform are Open-Source and the specific source and target locations are confirmed supported.

Requirement	Advanced Database Mapping role	What to verify
Use a supported source regional_base_price field or database column as the compatible target Regular Price	Map the approved source location to the compatible target field or column without changing the value as part of mapping.	Path eligibility, source and target support, value compatibility, stored result, and the target behavior that consumes the price.
Preserve an illustrative custom legacy_product_code value in a compatible target custom field or column used by an integration	If that specific source column and target destination are supported and compatible, map the code at the database level while preserving its value.	The code is stored on the correct Product and the downstream integration or process actually reads and uses the target value as required.

A custom field or database column is not automatically supported merely because both platforms are Open-Source. If the specific mapping is unavailable, keep other supported Standard Add-on rules and prepare only the unsupported portion for review.

Understand what the mapping guarantees

Advanced Database Mapping changes the supported destination of a value. It does not transform the value by itself.

A successful database write proves that the value reached the intended supported field or column. It does not by itself prove that the Target Platform will expose or use that value through every interface or component.

Stored value and target behavior are separate checks

A mapped value can exist in the target database while remaining unused by the admin interface, storefront, theme, app, extension, integration, or business logic. Validate the consumer that matters to the requirement instead of treating database presence as complete acceptance.

Interaction with other Add-ons

Advanced Database Mapping is the third Add-on stage:

Data Filter → Advanced Data Mapping → Advanced Database Mapping → Data Transformation

• Data Filter determines which records continue.
• Advanced Data Mapping establishes supported field-level destinations first when applicable.
• Advanced Database Mapping then applies eligible supported field or database-column destinations.
• Data Transformation changes selected resulting target-field values after the mapping stages.

Do not use Data Transformation to disguise an unsupported source or target column, and do not use database mapping to imply a target-side feature that must be implemented separately.

Expected result

After configuring Advanced Database Mapping:

• both platforms satisfy the Open-Source path prerequisite;
• each rule uses a supported source field or database column;
• each target field or database column is supported and compatible;
• the mapped value is unchanged by the mapping operation;
• Tax data is excluded from Standard database-mapping rules;
• representative records store the complete expected value in the approved destination;
• every required target-side consumer is separately verified when the business outcome depends on it.

Verify the database mapping

Check	Pass condition
Platform path	Source Platform and Target Platform are both Open-Source.
Source field or column	The intended supported source value is selected.
Target field or column	The selected destination is supported and compatible.
Value compatibility	Normal, boundary, empty, and exception values can be represented correctly.
Value preservation	The value is unchanged by mapping unless a separate Data Transformation rule intentionally changes it later.
Tax exclusion	No Standard Advanced Database Mapping rule is used for Tax data.
Stored result	Representative records contain the expected value at the approved destination.
Consumer behavior	Required admin, storefront, theme, app, extension, integration, or business behavior uses the value as expected, when applicable.

If this does not work

Issue	What to do
One platform is not Open-Source	Advanced Database Mapping is not available for the path. Use another supported Standard capability or prepare the non-standard requirement for review.
A required source or target column is unavailable	Do not substitute a different column unless it represents the same approved business meaning. Prepare the unsupported portion for technical or Custom Service review.
Field or column types are incompatible	Choose a compatible destination. If the actual requirement is a supported value change, evaluate Data Transformation separately.
The value is stored but not shown or used	Identify which target-side component owns the missing behavior. Database placement alone does not configure that component.
Several rules target the same destination	Remove the conflict or define one approved destination before execution.
The requirement needs bespoke schema engineering, scripts, APIs, relationships, or unsupported platform behavior	Prepare a Tailored Add-on, Custom Add-on, or broader Custom Service requirement as appropriate.

Next step

Return to Configure Add-ons and review this mapping with any field mapping and transformation rules before migration execution.