It's important to understand that the Akeneo Salesforce app is primarily designed for one-way data synchronization: from Akeneo PIM to the Salesforce core platform. This app does not support the transfer of existing data from Salesforce back into Akeneo PIM. Any such transfer must be handled independently, customized to your specific catalog structure and requirements.

Before installing the Salesforce app on an existing Salesforce platform, please consider the following key points:

• Migration Context: If you are connecting a new Akeneo PIM instance to an existing Salesforce environment, the app's installation and configuration are just one component of your broader data migration process.
• Structural Differences: When integrating with an existing Salesforce instance that already contains products, attributes, or other entities, you must account for potential differences in catalog and entity structures between Akeneo PIM and Salesforce.
• Critical Pre-synchronization Steps: Prior to initiating synchronization in any existing Salesforce environment, it is essential to back up your data and conduct thorough testing in a non-production setting.

These considerations are vital for a smooth integration and successful data management.

How the App Handles Pre-existing Products

By default, when syncing to an empty Salesforce organization, the connector generates a unique UUID field within the Product2 object to manage all future product creation and updates.

However, if you already have a pre-existing product catalog in Salesforce, the app provides flexibility by offering two distinct matching mechanisms to reconcile your PIM products with your existing Salesforce records before triggering duplicates:

The Salesforce ID Approach (System-Based Match)

This is the most robust and highly recommended method. It relies on mapping the immutable, system-generated Salesforce 15 or 18-character Technical ID directly within Akeneo PIM. Because this ID is entirely unique to your Salesforce environment, it completely eliminates any risk of name conflicts, homonyms, or accidental product merges during initial synchronization.

The Custom Pivot Field Approach (Value-Based Match)

If your PIM does not store Salesforce Technical IDs, the connector allows you to choose a specific text or identifier field in Salesforce (such as the standard Product Code or a custom External_ID__c) to serve as the unique pivot for matching. The connector will look up this user-defined field to see if a product already exists before deciding to link it or create a new one.

Selecting your Pivot Field

To avoid a rigid reliance on the standard Salesforce Product Code, the app allows administrators to select their own master unique identifier field (e.g., a Custom ID or an External ID).

1. In the Salesforce App, open the product field mapping grid
2. Locate the configuration option for the Pre-existing Identification Field
3. Default Value & Backward Compatibility: The Product Code field is selected by default
4. Custom Pivot Selection: You can select another field (e.g., External_ID__c). Only one field can be selected as the pivot identifier at a time.
5. If you select No Identifier, the app will entirely skip the pivot search step

Mapping Identification Fields in Catalogs for Apps

To maintain clear visibility, the target field selected as your pivot identifier will dynamically update its label within the Catalog for Apps interface to include a visual mention: Field_Name [Pre-existing identifier]

Option A: Mapping the Salesforce ID (Recommended & Safest Method)

If you already store native Salesforce Technical IDs inside your PIM, use the following steps to enable the most reliable matching method:

• Create two technical identifier attributes in Akeneo PIM to register the Salesforce technical ID at each structural level (you can choose your own attribute codes):
  • Create one identifier attribute for the Product Model level (e.g., salesforce_id_model).
  • Create a second identifier attribute for the child Product level (e.g., salesforce_id_variant).
• Navigate to the Catalogs for Apps extension and open your fields mapping interface.
• Map the Product Model Level: Under the Product tab, locate the default target field named Salesforce ID and map it to your Product Model identifier attribute (salesforce_id_model).
• Map the Product/Variant Level: Under the Variant tab, locate the default target field named Salesforce ID and map it to your child Product identifier attribute (salesforce_id_variant).
• Result: During synchronization, the app will directly query these system keys at both hierarchy levels. This completely bypasses fallback text checks and eliminates any risk of creating duplicate records for models or variants.

Option B: Mapping the Custom Pivot Field (Fallback Method)

If you do not store Salesforce IDs in your PIM and are relying on a custom pivot field (such as the default Product Code or a custom External ID) configured in your Salesforce App:

• In your Salesforce App configuration interface, verify which field you have selected as your pivot identifier (e.g., Midas_Code__c).
• Log into Akeneo PIM and open the Catalogs for Apps interface
• Thanks to the app's dynamic UI updates, the app automatically appends a visual hint to the target field's name in the mapping grid to guide you. Search for the following mention: Midas_Code__c [Pre-existing identifier]
• Map this dynamically labeled target field to the corresponding unique attribute in your PIM (e.g., sku or inner_code).

Synchronization Behavior Flow

During a data transfer, the app executes a strict 4-Step Search Logic to identify if an Akeneo product already exists in Salesforce.

The search verification is performed in the following precise order:

1. Check UUID. The connector checks if the product possesses a valid, previously synchronized Akeneo UUID
2. Check Salesforce ID (Priority Match). If the client already possesses the native Salesforce Technical ID inside Akeneo PIM, the connector uses it to perform a direct match. If a result is found here, the search is successful, and the process completely skips the pivot field check.
3. Check User-Selected Pivot Field (Fallback Match). If Steps 1 and 2 yield no results, the connector queries Salesforce records using the dynamic field chosen by the administrator (e.g., Product Code or a custom External_ID__c). Note: If "No Identifier" is configured, this step is skipped.
4. Create New Product. If no match is found after all three checks, a new product record is created in Salesforce

Error and Duplicate Handling Behaviors

To ensure data integrity, the app enforces strict rules and logs explicit warnings when data conflicts occur: