About Category Mapping
When importing automotive catalog data from an external catalog provider (such as ASAP Network, AutoSync, SEMA Data, Turn14, etc.), aligning the category structure between your X-Cart store and the provider's catalog structure may be necessary. X-Cart offers a Category Mapping feature for this purpose. Category Mapping enables you to specify, prior to importing product data from a provider's catalog, which categories from the provider's catalog should be imported into which categories in your store.
Note: Configuring Category Mapping is not mandatory for product imports. You may choose to simply import products with the categories specified for them in the provider's catalog.
Prerequisites for Category Mapping
In your X-Cart store, category mapping is executed through the Category Mapping page within the specific automotive integration. To enable category mapping, ensure the following prerequisites have been met:
The automotive integration connection process has been completed properly
Please ensure you have configured the connection of the automotive integration to the provider API before attempting category mapping. It won't be possible if you try to initiate category mapping without completing the connection first. For example, in the SEMA Data integration, until you have stored a security token in the integration settings, any category mapping controls on the Category Mapping page will remain inaccessible. Note that the page provides a Settings link for quick access to the integration settings page where you can input and store your API access credentials, including the security token.
Connection instructions for X-Cart's automotive integrations can be found in the guides for the respective automotive integrations:
ASAP Network (Enter and save your Web API Key);
AutoSync (Enter and save your AutoSync API Key);
SEMA Data (Enter CDC Login and Password, generate and save a Security Token);
Turn14 (Enter and save your Client ID and Client Secret).
Your store has successfully imported categories from the automotive integration provider catalog
For automotive integrations where category import is done as a separate step (like it is for SEMA Data or ASAP Network), it means that, before initiating the mapping process, you will need to import the complete category tree from the provider's catalog into your X-Cart store. Without this, the integration will not have information about which provider categories can be mapped.
The import of provider categories can be initiated manually from the Category Mapping page using the "Import Categories" button. This button allows you to import categories either before or after importing brands.
How to Map Categories
After a successful import of categories from a data provider, the contents of the Category Mapping page in your X-Cart store will look similar to the following (using SEMA Data as an example):
In the provided screenshot, the left-hand side showcases the category tree structure as per the taxonomy of your chosen data source, whereas the right-hand side features X-Cart category selectors enabling the assignment of corresponding X-Cart categories.
If needed, the category tree can be expanded; you can expand any level in the tree structure to access the categories nested therein by clicking on the arrow icon located to the left of the level name.
Depending on the automotive integration being utilized, the depth of category nesting can vary.
The middle column provides slider controls allowing you to adjust the status of the "Copy nested categories" setting.
The "Copy nested categories" setting determines whether the final X-Cart category branch should be formed by copying the branch of nested categories from the provider's catalog starting from the current level. Further details and examples explaining this will be provided further in this article.
Speaking of product placement within the categories in a tree structure, in all data provider catalogs, irrespective of the data provider, products reside only within so-called "leaf" categories. Leaf categories are the final-level categories that do not have any subcategories beneath them. You can think of a leaf category as the tip of a branch on the category tree. For example, the highlighted section of the category tree structure in the screenshot below includes a top-level category - "Accessories" - and a branch of subcategories under this category, which ends with a final-level category titled "License Plate Frame Bracket."
In this case, "License Plate Frame Bracket" would be considered the leaf category of this branch. Within this category branch, products exist only within the "License Plate Frame Bracket" category; there are no products within the "Accessories" and "Brackets, Flanges, and Hangers" categories.
When you visit the Category Mapping page for your automotive integration for the first time, you will see that the category mapping configuration for the integration is at its default:
Nothing is selected in any of the "To X-Cart category" selectors;
The "Copy nested categories" setting is enabled for all category tree levels that have nested categories.
If you choose to keep the default settings for some or all of the branches of the category tree, the category mapping will follow the route of copying the original structure of the respective category tree branches in the data provider catalog to your X-Cart store. For example, if we are importing a product that is located in the SEMA Data catalog within the category "License Plate Frame Bracket" (remember, it is the leaf category from the screenshot we discussed above), then, with mapping settings set at default, this product will be placed in the X-Cart store's catalog under the category path Accessories / Brackets, Flanges, and Hangers / License Plate Frame Bracket. As you can see, exactly the same category path is shown on the Category Mapping page as the destination for products from the "License Plate Frame Bracket" category of SEMA Data.
If you want not just to copy the category tree structure from the provider's catalog to the store catalog but also to use your own categories in the store, you will need to configure rules that describe from which categories of the provider's catalog the products should be imported into which categories of the store catalog. Category Mapping settings are flexible enough for you to describe any configuration you require. Let's take a closer look at the options available to you when you want to configure category mapping rules for your automotive integration.
In the simplest case, you have a category in the data provider's catalog where the products you want to import are located (for example, this category is Accessories / Brackets, Flanges, and Hangers / License Plate Frame Bracket):
You also have a category in your X-Cart store to which you want these products to be imported (let's say, Exterior Accessories). You want to configure category mapping in such a way that during import products will simply be added to the said X-Cart store category, Exterior Accessories; you do not want the structure of the respective branch of the category in the provider's catalog to be inherited by your store.
To configure category mapping for this case, follow the steps below:
Locate the branch in the data provider's category tree which contains the leaf category with the products that you are going to import. Expand this branch to access the level of the leaf category (in our example, this is the category License Plate Frame Bracket).
Note that when you edit the category mapping settings for your automotive integration, you can expand only one top-level category in the category tree at a time, and after making changes, you need to save the modified settings before you can move on to expand another top-level category. There are no restrictions on the number of child categories that can be expanded within a top-level category.
In the category selector opposite the leaf category that you intend to map with a category from your store, choose the X-Cart store category you require. You can start typing the category name in the selector, then select the category from the drop-down list. Choose the Exterior Accessories category.
The category selectors and "Copy nested subcategories" sliders on levels above the leaf category in the same branch of the tree do not affect the path to the final category, so you can just leave them be.
Once the name of the final-level category you have chosen appears in the selector, the full category path will be displayed to the right of the selector. Ensure that the path is correct and save the changes you have made by clicking the Save changes button. The changes will be saved, and the selected category (Exterior Accessories) will be assigned as the primary category for all new products that will be imported from the source leaf category in the provider's catalog (License Plate Frame Bracket) to your store.
Now, let's consider a slightly more complex scenario. Suppose you want to import products into the store from several leaf categories located within one parent category in the provider's catalog; for example:
Accessories / Decals and Emblems / Door Decal,
Accessories / Decals and Emblems / Emblem,
Accessories / Decals and Emblems / Exterior Decal, etc.
You want products from all these categories to be placed within a specific category in your X-Cart store (for example, let it be the category Test that already exists in your store). However, you want the products to be placed not in the Test category itself, but within subcategories inside this category. While you can specify the final-level X-Cart store category for each of these provider leaf categories manually, in cases where the number of leaf categories requiring category mapping configuration is sufficiently large, this task may turn out rather bothersome and time-consuming. For such cases, the category mapping feature provides the "Copy nested categories" setting. This setting can help you perform category mapping more efficiently by automatically copying parts of the category tree branch structure from the provider's catalog to your store. Let's see how it can be done.
In our example, the products we are going to import are located in leaf categories in the provider's catalog, such as Door Decal, Emblem, Exterior Decal, etc. Here, we don't want to change anything, and it suits us perfectly if, upon product import, subcategories like Door Decal, Emblem, and Exterior Decal are created within the Test category in our X-Cart store. Imported products will be placed inside these subcategories, similar to the structure in the provider's catalog (essentially, we want products to be imported to the categories Test / Door Decal, Test / Emblem, and Test / Exterior Decal). To ensure the import happens this way, we will want to specify Test as the parent category at one of the upper levels in the branch. Let's say we've chosen the topmost level (the level of the category Accessories).
Now this category appears as the top-level category in the paths of all the final-level categories below it.
Note that we have left the "Copy nested categories" slider at the Accessories category level in the "On" (enabled) state. This means that if we save our category mapping settings as they are adjusted now, the provider categories Brackets, Flanges, and Hangers, and Decals and Emblems, which are nested within the Accessories category, will be copied to the store catalog during product import. Consequently, the corresponding subcategories will also appear within the Test category. We can observe this in the category paths displayed to the right of the category selectors.
This does not align with our initial plan because we wanted the paths to our final categories to look like this:
Test / Door Decal,
Test / Emblem,
Test / Exterior Decal.
Therefore, before saving the settings, we will need to do one more thing - that is disable the copying of nested categories at the level of the category Accessories:
This way, the category Decals and Emblems, as well as the category Brackets, Flanges, and Hangers will be removed from our X-Cart store's final category paths.
The settings are very flexible and allow you to produce any category mapping configuration you require, including configurations where some of the final-level category paths are configured manually and others are produced automatically by partial inheritance of the category tree branch structure from the provider catalog.
Here is an example of a more complex configuration
In this configuration, the category Accessories / Brackets, Flanges, and Hangers / License Plate Frame Bracket is mapped to the category Test / License Plate Frame Bracket;
the categories
Accessories / Decals and Emblems / Door Decal,
Accessories / Decals and Emblems / Emblem,
Accessories / Decals and Emblems / Exterior Decal,
Accessories / Decals and Emblems / Hood Decal,
Accessories / Decals and Emblems / Windshield Decal
are mapped to the category Accessories / Decals and Emblems;
and the category Accessories / Decals and Emblems / Multi-Purpose Decal is mapped to the category Accessories / Multi-Purpose Accessories.
Dealing with Category Structure Changes
Please be aware:
Product category info is not updated for existing products in accordance with category mapping rules
When import is used to update the information of products that already exist in the store, the category information of those products is not updated. This means that if you have a product in a specific category in your X-Cart store (originally imported to that category or moved there at a later time), and the category in which the product is placed differs from the final-level X-Cart store category specified by the category mapping rules at the time of a new product import for updating product information, the import will update the product's information, but not the product's primary category (the product will remain in the same category as before the import).
Example:
A product is in the category Accessories / Decals and Emblems / Door Decal of the provider catalog. We map this category to Accessories / Decals and Emblems in our X-Cart store and perform an import. As a result of the import process, the product gets added to the category Accessories / Decals and Emblems in our store. Then we decide we don't like this category structure anymore and want to have a category Accessories / Decals and Emblems / Door Decal in our store instead of Accessories / Decals and Emblems, and we want the product we have imported to be in that category. We readjust the category mapping rules so the category Accessories / Decals and Emblems / Door Decal in the provider catalog is mapped to the category Accessories / Decals and Emblems / Door Decal in our X-Cart store. We run a new import updating our previously imported products. After the completion of the import process, we check the details of our product and find that it is still in the category Accessories / Decals and Emblems; it has not been moved to the Accessories / Decals and Emblems / Door Decal. To move the product to the new category, we will need to reassign the category in the product's details.
If a category involved in category mapping is deleted, you need to readjust your category mapping rules
If, after your category mapping rules have been configured, a category involved in the category mapping configuration is deleted on the X-Cart store's end, a warning mentioning the necessity to readjust the category mapping rules is provided. Further imports are disallowed until the category mapping issue is resolved. To resolve this issue, you need to reconfigure your category mapping settings.
Example:
We have a category Tire and Wheel in the provider catalog that is mapped to the category Wheels & Tires in our X-Cart store.
We go to Catalog > Categories and delete the category Wheels & Tires. The category is deleted, and we are notified that we now need to readjust our category mapping rules:
On the Category Mapping page, we no longer see the X-Cart store's category Wheels & Tires where it used to be; the provider category Tire and Wheel is no longer mapped, and a warning icon appears next to the store category selector:
We need to choose a new category and save the changes.