Introduction

This page explains how identifiers are used to uniquely identify records between your data and Shopware.

In synQup there are two traits available to make a document identifiable:

  • Elio\CommonBundle\Traits\IdentifiableDocument
  • Elio\CommonBundle\Traits\UniqueIdentifiableDocument.

Both traits provide the field identifier which is used to uniquely identify records between Shopware and synQup.

Valid Identifiers

The output module expects valid identifiers for documents, otherwise they will be sorted out by validation. A valid identifier ...

  • ... is not empty or null
  • ... is not whitespace only
  • ... does not start or end with whitespace

It is highly recommended to use unique identifiers for every document. Non-unique identifiers can cause unexpected behaviour of the output-module.

Custom Fields for Identifiers

In Shopware the identifying values are stored in a custom field whose name is configurable in the identifier section of the module configuration. If the custom field is not existing in Shopware it will be created automatically.

{  
	"identifier": {  
	  "customFieldName": "synqup_identifier",  
	  "customFieldSetName": "synqup_identifier_set",  
}
  • The configuration key customFieldName determines the name of the CustomField in which the identifying values are stored.
  • The configuration key customFieldSetName determines the name of the CustomFieldSet that the custom field is part of.

Warning: Do not change the name of the custom field after its creation! Otherwise, you will most likely generate a lot of duplicate entities in Shopware.

Exceptions

There are documents that do not provide (unique) identifiers or identifiers at all. The affected Shopware entities are currently:

  • product-cross-selling are identified by their position in the Product::relations collection
  • order-line-items, order-transactions and order-deliveries are deleted and recreated on every order update

You can find more information about identifying those entities in the relevant sections of the documentation.

Usage of Identifiers

  • The subsection build-cache uses that identifier to find corresponding entities for your documents in Shopware.
  • The subsection upsert uses the identifier to generate a unique uuid for the entity if it does not exist yet.
  • Several internal data structures use the identifier as well.
On this page