Shopware

Installation and configuration guide for Shopware 6.5 <> Ergonode connector (plugin)

Last manual update: 2024-09-04

The Shopware plugin is now fully Open Source and maintained by a third party.

Please go to GitHub to download the newest version, read about changes, or create an issues ticket if any arise.

This manual may become obsolete in time.

Please read the DISCLAIMER before using this plugin.

Shopware to Ergonode connector works only with Ergonode Cloud and Shopware 6.5 It uses the GraphQL API to establish a connection between these platforms.

The license of the plugin grants users the liberty to modify the code independently, enabling them to introduce additional features or rectify issues. While submissions of these modifications to Ergonode are welcomed, their incorporation into the official plugin codebase is at Ergonode’s discretion and not guaranteed.

Do NOT use double floor sign __ anywhere in Ergonode, this may cause the plugin to behave improperly as __ is used to mark things internally in the plugin code.

Configuration (in terms of endpoint API URL, fields mapping, categories, scheduler, and custom fields) is done once and is shared across all sales channels. However, it is possible to synchronize a different product segment with each sales channel. This is achieved by choosing a specific sales channel in the plugin configuration and then editing the API key for this channel. In this case, that specific channel will be synchronized with the Ergonode product segment specified by the given API key.

A “Segment” in Ergonode is a set of products that can be chosen using a rule and can have its own API key assigned. In this context, we can use the Segments functionality to assign different sets of products to different sales channels.

This plugin is designed to work with a single consumer. The proper behavior of the plugin cannot be guaranteed when working with multiple consumers.

General assumptions

Running Ergonode installation
At least 1 Ergonode API key generated
Running Shopware consumer (either Admin Worker or CLI - messenger:consume)
All synchronization tasks are running on the queue

Shopware Language:

The default Shopware language (the one selected during Shopware installation) MUST be marked as active in Ergonode.

Additional Points:

At least the Ergonode Attribute mapped with the Shopware name MUST be filled to have the default Product name in Shopware.
It is recommended to have at least the default Shopware language translations filled in all Ergonode products/categories/attributes, etc.
When there is no translation, the plugin's fallback is to code. For example, having Shopware default language of pl-PL, fill at least one field for every Ergonode product/category/attribute in Polish translation.

Important:

Each language has to be activated in the “Language pack” plugin.

If the product SKU in Ergonode PIM is the same as the Product number of the product that already exists in Shopware, product information for the product in Shopware will be overwritten, otherwise the new product will be created

Step 1: How to get the Shopware > Ergonode connector

The connector is accessible upon request. To obtain the secure Google Drive link, please contact Ergonode Support.

Step 2: Generate API keys in the Ergonode admin panel

Remember, your API key is sensitive information. Keep it safe and don’t share it with anyone you don’t trust. If you ever need to revoke access to your API key, you can do so from the same API Keys page where you created it.

When creating the API key you can select the segment (optional), so the Shopware Connector will only fetch products that match those in the chosen segment. If you leave this field blank, all products in the Ergonode system will be fetched. The “Allow to write” checkbox value doesn’t matter as the module is not writing anything in Ergonode. It is recommended to leave it unchecked.

When syncing grouping products, or products with variants please note that ALL products MUST be in the same segment.

Information on how to create an API key can be found here.

Step 3: Installation

A comprehensive guide for extension installation is available in the official Shopware documentation under the section: Shopware 6 - My extensions.

Upon successful addition of the plugin to your Shopware shop, initiate the installation process. This can be accomplished by navigating to ‘Shopware Admin > Extensions > My Extensions’. Locate ‘Shopware Ergonode Integration’ in the list and select ‘Install’.

Activate the plugin by selecting the radio button situated to the left.

Upon completion of these steps, the configuration should resemble the following representation.

Updating from the older version

Download the New Plugin Version

Download the new plugin version from the provided Google Drive link.

Upload the Plugin to Shopware

Navigate to Administration > Extensions > My Extensions.

Click on the Upload extension button and confirm your intent.

Select the ZIP file with the new plugin and confirm the upload.

Update the Plugin

In the plugin list, you will now see the option to Update.

Click on it and wait until the update is completed.

The new plugin version is now installed, and the version number has been updated.

Step 4: Configuration

First, it is necessary to configure the connection with Ergonode. This can be accomplished by accessing the plugin configuration via the Administration sidebar. Please follow the subsequent navigation path: ‘Extensions > My Extensions > Shopware Ergonode Integration > … (3 dots to the right) > Configuration’.”

API Settings

Ergonode GraphQL API endpoint:

The field necessitates a complete GraphQL endpoint URL.
The URL should be exclusively provided for all Sales Channels. Assigning different URLs for other Sales Channels will not yield any effect. This value is propagated to other sales channels and must not be altered or removed for individual channels.
The URL should adhere to the format “https://name.ergonode.cloud/api/graphql/”, where the initial segment (underlined) corresponds to the URL of the utilized Ergonode environment.
Contrary to the base URL, API keys can be individually set for each Sales Channel. However, it is mandatory to fill it in for all sales channels. It can be modified for each channel, allowing the configuration of Segments in Ergonode to assign only Products filtered by Segment conditions to the Sales Channel. If only the primary API key is set, all Sales Channels will be assigned to Products by default."

Please note that for successful operation, all sales channel segments must encompass products that will be utilized to populate distinct sales channels.

For instance, all channel keys are configured to operate with a ‘main_segment’ that houses products with SKUs: SKU1, SKU2, and SKU3. Subsequently, the user is required to generate a new API key for the ‘Headless’ channel that exclusively contains SKU2 and SKU3.

If the segment associated with the API key, which is employed with all sales channels, does not contain products from other channels, product creation for those additional channels will not be executed.

Warning: after saving changes you will be redirected back to “All Sales Channels”. This is normal behavior of Shopware.

Credentials Verification:

Click ‘Verify’ to authenticate the credentials provided above.
It is strongly recommended to verify the credentials prior to saving the configuration.
In the event of incorrect credentials, pertinent information can be located in the Shopware log directory, typically found at ‘/var/log’."

Fields mapping

It is feasible to optionally configure Shopware custom fields and cross-selling attributes mapping.

Caution: It is necessary to establish the API Settings and preserve the configuration prior to advancing to the fields mapping configuration.

Ergonode Attributes as Shopware Custom Fields:

The dropdown menu enumerates all Ergonode Attributes.
The selected attributes will be utilized to:
- Generate Shopware Product Custom Fields with appropriate types during Attribute Sync.
- Synchronize the values during Product Sync.

Ergonode Attributes as Cross-Selling:

The dropdown menu enumerates all Ergonode Attributes of type ‘relation’ (also known as ‘Product relations’).
The selected attributes will be utilized to create Product Cross-Selling collections during Product Sync (refer to ‘Product Cross Selling’ for details)."

Force to save product sku in uppercase:

When this option is on, products will be saved in Shopware in uppercase, for example, Ergonode: Product-12a will be saved as PRODUCT-12A

Category sync

To facilitate the synchronization of Ergonode Categories with Shopware, it is incumbent upon the administrator to define the category tree code within the plugin configuration.

Please note: Your category trees can be located in Ergonode within the ‘Category tree code’ column on the Category trees’ grid.

The category trees to be synchronized can be selected from a multi-select dropdown menu, allowing for the synchronization of multiple category trees.

Each category is synchronized from Ergonode to Shopware on a one-to-one basis, implying the following:

A category created in Ergonode is replicated in Shopware.
A category translation in a specific language is transferred to Shopware.
The removal of a category from Ergonode results in its removal in Shopware.
The position of a category on a category tree in Shopware mirrors its position on the corresponding category tree in Ergonode.

Please be aware that a situation may arise where a category in Ergonode only has a ‘category code’ filled and lacks any translation. In such a case, the ‘category code’ will be transferred to Shopware as a translation in the default system language.

There exists the possibility to map categories that are present in both systems prior to synchronization. Further information can be found in the ‘Category mappings’ section of the documentation.

Scheduler

To facilitate automatic synchronization, it is essential to configure the scheduler.

Field Descriptions:

Enable Scheduler: This switch allows you to enable or disable automatic synchronization.
Start Date and Time: This field allows you to select the commencement time for the scheduler to initiate synchronization.
Scheduler Timezone: This field allows you to set the timezone for the selected date and time.
Recurrence Hour: This field, with a range of 0-24, determines the hourly frequency of synchronization.
Recurrence Minute: This field, with a range of 0-59, determines the minute frequency of synchronization.

Examples:

If Recurrence Hour = 0 and Recurrence Minute = 10, synchronization will occur every 10 minutes.
If Recurrence Hour = 1 and Recurrence Minute = 0, synchronization will occur every hour.
If Recurrence Hour = 2 and Recurrence Minute = 30, synchronization will occur every 2.5 hours.

Caution: Exercise discretion when selecting very small intervals (such as 1 minute). Depending on your server’s capability, the frequency of product changes in your Ergonode instance, and the number of attributes to synchronize, frequent synchronization may potentially cause performance issues, although this is not guaranteed."

Please remember to save changes before leaving the basic configuration page.

Step 5: Mapping

Select (boolean) fields

It is possible to map Shopware boolean fields (like active) with Ergonode select attributes. To do so Ergonode select options must meet the following:

It is recommended to set Ergonode select attributes scope to global, boolean attributes and Shopware custom fields are not translatable in Shopware. If the attribute is local, only the default language value will be used during synchronization.

The following values are allowed to be used as option codes:

Value that will be saved in SW

Option codes set in Ergonode

If the option code does not match with any of the above values, the value will be considered false during synchronization

Delivery time attribute

Delivery time in Shopware is a SELECT-type attribute. The options for that attribute are configured in shop settings. The value of that attribute for each product can be synchronized from Ergonode if certain conditions are met:

Options for delivery time are created in Shopware:

SELECT-type attribute named (code) delivery_time is created in Ergonode.
Options for the delivery_time attribute are created in Ergonode.

Attention! These options must be identical to the options created in Shopware! New options created in Shopware will NOT be created upon synchronization in Ergonode, so you need to create them manually.

Delivery time in Shopware is mapped with Ergonode’s delivery_time in plugin settings.

Tax rates

By default, Shopware allows to assign 3 typical tax rates (SW Admin Panel -> Left-hand menu -> Settings -> Shop -> Tax): Standard, Reduced, Super-reduced. These tax rates can have different numerical values assigned (see screenshot below):

If the tax rate value synchronized from Ergonode has a different numerical value than those 3 rates, then a new tax rate will be generated in Shopware and assigned to the product. It will be named “Ergonode Autogenerate ([numerical value here]%)”.

Attribute mapping

Once created, the attribute types in both systems cannot be altered. If you wish to change their types, it will be necessary to make completely new attributes.

Upon successful completion of the plugin configuration, it is feasible to finalize the configuration process by setting up the ‘Attribute Mappings’.

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Attribute Mappings’.

To enable synchronization of Ergonode product attribute values with Shopware, it is essential to map them with Shopware attributes utilizing the ‘Attribute Mappings’ page.

The selection fields at the top contain all attributes that are permissible to map between systems. Simply select the Shopware attribute and its corresponding Ergonode attribute, then click ‘Add Mapping’.

You can type to search for an attribute.

The most recent mappings are displayed at the top of the list.

Note that attribute types must be mapped accordingly. The compatibility of attribute types is a crucial factor in successful mapping. The types of attributes that can be mapped together are displayed in brackets next to the attribute name.

This means that when selecting attributes to map, you should ensure that the types of the Shopware attribute and its corresponding Ergonode attribute are compatible as indicated. This step is necessary to ensure the correct functioning of the attribute mapping and synchronization process. Incorrect mapping of attribute types may lead to errors or unexpected behavior.

Note that mapping multiple Ergonode attributes into a single Shopware attribute is not feasible. However, mapping a single Ergonode attribute into multiple Shopware attributes is permissible.

To edit a mapping, simply remove it and add the desired one."

Currently Permitted Mappings for Each Attribute Type:

Since Ergonode does not have a bool type attribute, a workaround must be used to map those. Information on how this can be done can be found later in this article.

Shopware attribute

Attribute type(s) in Ergonode

"Warning: Please be informed that in the current version of the plugin, when mapping properties to select-type Ergonode attributes, the option values of select attributes are displayed as their system code if the translations are not available. Therefore, special caution must be applied when configuring this kind of mapping.

Warning 2: Shopware properties in the mapper are displayed as their translated names to match the naming of fields in the admin panel."

Shopware custom fields mappings

Analogous to properties, it is feasible to map Shopware custom fields to Ergonode attributes.

This feature is distinct from the ‘Ergonode attributes as custom fields’ field in the plugin configuration. The plugin facilitates the selection of Ergonode attributes which will be imported to Shopware as new custom fields (within a newly established ‘Ergonode Custom Fields’ set). The feature delineated in this section enables the actual mapping of existing custom fields to specific Ergonode attributes.

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Custom Fields Mappings’.

The configuration process parallels that of attribute mapping. Initially, select a custom field from the ‘Shopware Custom Field’ dropdown menu, followed by the appropriate Ergonode attribute in the ‘Ergonode Attribute’ field. Click ‘Add Mapping’, and the mapping will be displayed in the list below.

The requirements applicable to attributes also pertain to Shopware custom fields when mapping them with the Ergonode select attribute.

For additional details, please refer to the ‘Step 5: Mapping -> Select (Boolean) Fields’ section."

Category mappings

Users have the capability to align existing categories in Shopware with those originating from Ergonode.

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Category Mappings’.

To establish a match between categories across systems, select a category from the ‘Shopware Category’ dropdown menu, followed by a category from the ‘Ergonode Category’ dropdown menu. During the synchronization process, the category in Shopware will inherit certain data from Ergonode (such as translations, tree location), while preserving its existing data.

This implies that if a category has an assigned layout or populated custom fields, these attributes will be retained and not be removed or overwritten.

If you wish to discontinue the mapping of your categories and revert them to separate entities, simply remove the mapping. This will result in any category from Ergonode, previously mapped with one in Shopware, being reintroduced as a new, independent entity. Future changes to this category will not impact the previously mapped Shopware category.

It is recommended to execute the ‘Synchronize all’ job once the configuration is complete.

Category attribute mappings

To enable the utilization of Ergonode attribute mappings to populate category attributes, it is essential to establish Category synchronization prior to this operation

Category attributes are added to existing categories in Shopware.

If you create mapping and don’t fill values in Ergonode - Category Attribute Sync will nullify all mapped values!

Before category attributes can be used in Shopware, they must be created and filled in Ergonode.

Remember that you don’t have to map all attributes. Add only that attribute that you will be using. You can add fields in Ergonode and map them later in Shopware when your data is ready to go.

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Category attribute mappings’.

The mapping here works exactly like mapping in category mappings.

Instruction on how to map categories by region:

General tab

Fields on the current view: ● Name ● Active ● Tags ● Category Type

Name

Mapped in category sync.

Active

A boolean field is a toggle switch that allows you to control whether a category is visible in the front end or not. When a category is inactive, it is not displayed in navigation menus or on product pages, and it is not accessible to customers.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Tags

The tags allow you to store keywords for your products, categories, media, customers, orders, shipping methods, newsletter recipients, landing pages, or rules. These keywords can then be used, for example, within rules from the Rule Builder. With this overview, you can directly view and manage all created tags.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Category type

Shopware allows to set 3 values: Page / List, Structuring element / Entry point, Link

Page/List category: This category type serves as a standalone landing page for a specific product group, promotion, or marketing campaign. It’s similar to the existing Landing Page Category but with more granular control over the content and layout of the page.

Structuring Element/Entry Point category: This type of category is primarily used for structuring your product catalog and providing a clear navigation path for customers. It’s similar to the existing Navigation Category but with more options for customizing the category’s appearance and behavior.

Link category: This type of category serves as a direct link to a specific product, page, or external URL. It’s similar to the existing Link entity in Shopware, but it’s now integrated into the category management system.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Displays when page type is set to “Page / List

Fields on the current view: ● Hide in navigation ● Display image ● Description

Hide in navigation

Allows to hide category and its nodes in navigation.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Display image

Image used in some templates that allow displaying images for categories.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Description

Some templates allow to display of descriptions for categories.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to that attribute value!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

General - Customisable link

Displays when page type is set to “Link”

Fields on the current view (With Link type = External): ● Link type ● Link destination (External link) ● Open in a new tab

Fields on the current view (With Link type = Internal): ● Link type (Internal) ● Entity (Internal Link types) ● Internal link (Category, Product, Landing Page) ● Open in a new tab

Link type

Allow to decide what link type will be used.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

External link

URL to resources from outside Shopware.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Internal link data

URL to resources from outside Shopware.

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Open in a new tab

Allows to open link in a new tab instead of in the current window

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

Do not add translations to these attribute options!

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Seo tab

Fields on the current view: ● Meta title ● Meta Description ● Keywords

Meta title

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Meta Description

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Keywords

If you want to use this field in the mapping, add a new attribute in Ergonode with the following parameters:

After creation do not forget to add this attribute as a Category attribute otherwise it will not show up in the mapper.

Step 6: Synchronization

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Synchronization’.

Synchronize Latest Changes: This operation initiates all synchronization tasks, processing the most recent modifications on products and comprehensive data of other entities, such as attributes and categories. Following each execution, the Ergonode cursors are preserved to commence the subsequent run from the current state, implying that only alterations made henceforth will be processed.
Synchronize All: This operation synchronizes ALL entities from Ergonode. It begins by clearing saved Ergonode cursors to fetch all entities, not merely the latest changes, and then triggers all synchronization tasks. The progress of the synchronization process can be monitored in the ‘Import history’ tab.

Scheduled Tasks

The synchronization process is divided into several scheduled tasks. The interval for these tasks can be modified in the plugin configuration. To do so, navigate to Configuration -> Plugin config -> Scheduler for more details.

The tasks, in their correct order, are as follows:

LanguageSync
AttributeSync
CategorySync
ProductSync
ProductVisibilitySync
DeletedProductSync
DeletedAttributeSync

Synchronization details

Property Groups

All Ergonode Attributes of the ‘select’ or ‘multi-select’ type are transferred to Shopware as properties (referred to as Shopware Property Groups), and their options are transferred as property options (known as Shopware Property Group Options).

Custom Fields

All Ergonode Attributes that are designated as Custom Fields in the plugin configuration are transferred to Shopware as Product Custom Fields. In addition, existing custom fields can be mapped with Ergonode attributes in the same manner as regular properties are configured. For more information, please refer to the Attribute Mappings section. Any unmapped custom fields are sent from Ergonode and created as new entries in Shopware. Please see the Matching Types table below for further details.”

Shopware limitations: Attributes of the ‘gallery’ or ‘file’ type have a certain limitation. In Ergonode, these fields can contain multiple entities, whereas the corresponding Shopware Custom Field types can only support a single entity per field. As a result, when transferring these fields to Shopware, their values are restricted to the first entity. Example For instance, if you have the following list of files in an Ergonode file Attribute, only the first one will be transferred to Shopware

Product Media

To enable the synchronization of Product Media (such as product images) from Ergonode to Shopware, the administrator must map the Shopware media field with the Ergonode Attribute of the ‘gallery’ type.

Product Cross Selling

Synchronization of product relations will only work if the product you are linking is either included in the segment you are importing for this sales channel or is already present in that sales channel in Shopware.

All Ergonode Product Relations Attributes designated as Cross Selling in the plugin configuration will be utilized to create Product Cross-Selling during Product Sync. The system will identify the values from Ergonode Attributes and generate a separate Cross-Selling collection for each identified Attribute. The Attribute names established in Ergonode will be used as the names of the Cross-Selling collection and will be displayed on the Shopware storefront.

Shopware limitations: Shopware permits the creation of Cross-Selling only for the primary product. The creation of Cross-Selling for variants will be disregarded.

Additionally, Cross-Selling is not translatable in Shopware. This implies that even if the scope of the Ergonode Product Relation Attribute is set as local, the values will be derived from the default locale of Shopware during Product Sync. Therefore, it is recommended to set all Ergonode Product Relation Attributes as global.

Step 7: Import History

Displays a table with all imports, whether triggered manually or by scheduled tasks.

Longer-running imports will appear multiple times. This is because a single sync has a limited number of entities it can process.

IMPORTANT: For comprehensive visibility of all import details, it is imperative that Shopware log files, particularly those located in var/log/ergonode_integration, are retained on the primary Shopware server. For instance, if consumers are operating on distinct machines, the logs may not be visible in the administrative panel unless they are stored on the same Shopware server.

The configuration of this mapping can be accomplished by navigating to ‘Settings -> Ergonode Integration -> Import history’.

The filters function in the Import History tab provides a user-friendly interface to streamline your search for specific import records. It features three main components:

Show only error: This option allows you to filter the import history to display only those records where errors occurred. By checking this box, the system will hide all successful import records and only display those with errors. This can be particularly useful when troubleshooting or auditing the import process.
From: This is a date selector that allows you to specify the start date for your search. By selecting a date from this field, the system will only display import records from this date onwards. This can be useful for narrowing down your search to a specific time period.
To: Similar to the ‘From’ field, this is a date selector that allows you to specify the end date for your search. By selecting a date from this field, the system will only display import records up to this date.