Shopware Connector
Introduction
This page describes the Perfion Connector for Shopware.
Applicable versions
The following Shopware version have currently been tested and are approved for this version of the Perfion Connector:
Shopware 6.4 (all 2.x.x versions)
Shopware 6.5 (from version 3.0.1 and forward)
The basics of what this connector does
The connector (depicted in a very simplified way in Figure 1) works as follows:
Shopware asks Perfion for data based on the configured channels in Perfion. It is possible to extend this functionality using the built in fluent PHP API. The Perfion Connector will process the received data and create the custom fields, properties, categories, products, and images.
Installation
Prerequisites
Before installing the connector make sure, you have the following prerequisites set up:
You have a running Shopware (6.4 or 6.5) installation with PHP 7.3, PHP 7.4 or PHP 8.1 running.
You have a Perfion Database v. 4.6 (or newer).
You have a Perfion API set up on IIS Perfion running at least 4.6 (or newer). The Perfion API endpoint must be accessible from the Shopware server.
Please note: If a firewall protects your Perfion instance in your infrastructure setup, please put all Shopware server IPs in the allow list of your firewall.
Your Perfion license must include licenses for the Perfion Ecommerce API with at least one Ecommerce Channel and the Shopware connector.
Setting up the needed features in Perfion
Before the connector can be used, you need to ensure that you have active the Ecommerce API in Perfion, this gives you access to the API mapping functionality.
Installing the connector in Shopware
The Shopware connector can be installed from the Shopware store and using composer. Please be aware that all Connector versions 2.x.x are compatible with Shopware 6.4 and all above 3.x.x are compatible with Shopware 6.5.
Configuring the connector
This chapter takes you through all configuration needed for setting up the connector for the first time. First section will take you through the necessary steps in the Shopware backend interface. Next section will take you through the steps needed in Perfion.
When you have completed this chapter, you have a very basic setup of Shopware with the Perfion Connector.
Configuration in Shopware
After the connector has been installed though the Shopware store, it needs to be configured to reach the Perfion API. Please note, that it is possible to have a unique configuration for each of your sales channels if you want to.
It is often a good idea not to activate the integration on “All sales channels”, but instead type in a general configuration on the “all sales channels” level (1), and override the configuration inheritance, and activate the unique sales channels one by one (2). If you activate all your sales channels, the integration will try executing once per channel, even if you don’t need data on a particular sales channel.
Please refer to the Configuration section for configuring Perfion section, for an overview of the mandatory features you need to setup in Perfion.
Plugin configuration
When you enter the plugin configuration section in Shopware, you have the following options.
Perfion channel name - The name of the channel you have setup in the Ecommerce Mapping in Perfion.
Activate channel - Only active channels are processed when running the integration.
Perfion API Url – The URL to your Perfion API
Perfion user name – If you are using a secure service, type in your Perfion username
Perfion password - If you are using a secure service, type in your Perfion password
When this is enabled. Custom fields are imported as complex fields - You can enable / disable how custom fields are imported. If complex custom fields are enabled, fields will be imported as selectables / lists etc in Shopware, at the cost of import speed. If disabled, all custom fields are imported as simple values. Multi selects are imported as string arrays. This improved import performance.
Default active status – When enabling this feature, products are only activated in Shopware, if they have the ‘active’ field mapped in Perfion, and this field is set to true for your products. If this features is disabled, products are always considered active.
Deactivate Perfion categories in Shopware that are removed from Perfion – When this feature is active, categories that are removed from the Perfion catalog, will be deactivated in Shopware.
Deactivate Perfion products in Shopware that are removed from Perfion– When this feature is active, products that are removed from the Perfion catalog, will be deactivated in Shopware.
Import prices – If enabled, also imports prices (via the price mapping in Perfion) into Shopware.
Import stock – If enabled, also imports stock (via the stock mapping in Perfion) into Shopware.
Perfion batch count – The amount of products downloaded from Perfion in a single batch.
How many seconds before an attempted connection is dropped – Timeout for the Perfion API requests connection initiation.
How many seconds before the whole request is dropped – Timeout for the duration of an entire HTTP request to the Perfion API.
Enable scheduled tasks – If enabled, the Shopware scheduled tasks will download products. 1 Full import every night, and 1 delta import every hour. It is highly suggested that you use CRON jobs, and not this feature, since it is mainly implemented for testing purposes.
Index rebuild on import – Check this to immediately rebuild your index, when you import data.
Server time offset – DEPRECATED – no longer in use.
Root category – The category that will be used as the root, when importing categories into Shopware.
Use "Filter" view in Perfion – When this feature is enabled, Shopware will use the chosen view below, to figure out which features should be created as properties. Mapped features not selected in this view, will still be created as custom fields.
The View in Perfion you use to control features – If the above setting is enabled, type in the view name, that you wish to use to select which features should be properties in Shopware. (Note: as of Perfion 5.3.2, only WebDetail, WebList or WebVariant can be used)
Test API Button – The Test API button, will call Perfion, and validate that a connection can be established. Furthermore, the Test API button will also validate common mapppings and settings in Perfion and Shopware, and report back any issues found. This should help you figure out, if you are missing anything in your configuration.
Configuration in Perfion
Please note that a complete configuration example is shown at the end of this section.
Creating a channel
Since Perfion supports multiple output channels, and multiple channel mappings, you need to predefine your Shopware channel first.
Go to your “EcommerceSystem” feature data section, and ensure that the feature “Shopware” exists. If it does not, then create it.
Next, go to your “EcommerceChannel” feature data section, and add your new Shopware channel. In this example, the channel I simply called Shopware, using the EcommerceSystem also called Shopware.
Language Deviations
Go to your EcommerceMapping feature data section.
In your EcommerceMapping you need to set up language deviations for your channel, such that the Ecommerce API can properly fit you localizable data into Shopware.
The input (left hand side) of your Ecommerce Mapping should point to the Perfion language you would like to send to Shopware. Language Deviation “Output Kind” is empty. On the right hand side, in the “Ecommerce To” column, you have to type in the Shopware language code, that matches your Perfion language. In the example shown below, English(EN) is mapped to en-GB, and Danish(DAN) is mapped to da-DK. The language code must exactly match the Shopware language code.
Category mapping
Set up your category structure and map required fields in EcommerceMapping
Create a selectable string feature in Perfion and configure it as a multiselectable localizable string with allowed hierarchyas seen in screenshot below. This catalog is no different than any other catalog you create in Perfion.
It would proable also be helpful, to define a Perfion section for your Shopware catalog, to ease your work when categorizing your website products; However this is not a requirement.
Category Ecommerce mapping
For categories, you can map the following fields. Please note, that required field, are required for the integration to work. Required fields must always have the exact value in the TO column as shown below. Certain system field like “.id” and “.childCount” must always be spelled exactly as in the “Mapping” column. Read “Note” column carefully.
Mapping | Kind | TO | Note |
ShopwareCatalog/WebDetail/ShopwareCategories | Context |
| The context mapping configures the Perfion Ecommerce API to gather categories from the “Category” feature, gather features from the “WebDetail” view, and finally executes the predefined “ShopwareCategories” EcommerceSearch that further filters the resultset sent to Shopware. REQUIRED |
.id | KeyField | perfion_id | The identifier for Perfion categories. |
Any string feature | Field | name | The name of the category. |
Any boolean feature | Field | active | Used to activate / deactivate categories |
Any single select image feature | Image(Url) | cover_image | Image used as category cover image |
Any string/text feature (RTF Encoded editor not supported; however, HTML is) | Field | description | Category description. |
.order | Field | sort_order | Used to pass the Perfion sort order of categories to Shopware. |
.childCount | Field | child_count | Used to construct categories in shopware. |
Additional custom fields:
If you map any other Perfion feature in your category mapping, they will be created as custom fields on the category.
Eg. this mapping:
Will result in a “headline” custom field being created in the category custom field set.
Full example of a standard category mapping without any additional custom fields
How to setup a category search
Create a new feature under “EcommerceSearches”. This search must be the same name as you defined in your EcommerceMapping’s Context mapping seen in the example above (Category/WebDetail/ShopwareCategories); in this example it is “ShopwareCategories”. Right click the search, and provide a query, if you need to filter the categories for Shopware futher. A common thing to do, is to filter away categories, that have been deactivated via a Boolean feature, which you can see an example of below.
Product mapping
Ecommerce Mapping
Since you have already created your language deviations which will also work for products, we can jump directly to the EcommerceMapping of products.
You can find the currently supported fields in the table below. Please bear in mind, that any mapped field that is not in the table below, will be created as a custom field on your products in Shopware. Any fields to your “filterable_properties” mapping, your fields will be created as properties on your products in Shopware. Filterable properties is also described in this document.
Product / Variant mapping
Mapping | Output Kind | To | Note |
Product/WebDetail/ShopwareProductSearch | Context |
| The context mapping configures the Perfion Ecommerce API to gather categories from the “Product” feature, gather features from the “WebDetail” view, and finally executes the predefined “ShopwareProductSearch” EcommerceSearch that further filters the resultset sent to Shopware. |
Any string feature | KeyField | sku | REQUIRED |
.id | Field | perfion_id | REQUIRED |
Any string feature. | Field | name | REQUIRED |
Any string/text feature (RTF Encoding not supported. However HTML is). | Field | description | OPTIONAL |
Single select image feature | Image(Url) | cover_image | Used to set the cover image |
Multi select image feature | Image(Url) | images | Used as additional images |
Boolean feature | Field | active | Activates and deactivates products in shopware (this feature needs to be activated in shopware) |
Number feature | Field | stock_quantity | OPTIONAL |
Selectable hierarchical feature | RelatedCategory | categories | OPTIONAL |
Number feature | Field | weight | OPTIONAL |
Number feature | Field | height | OPTIONAL |
Number feature | Field | length | OPTIONAL |
Number feature | Field | width | OPTIONAL |
Number feature | Field | list_price | OPTIONAL |
Number feature | Field | list_price_no_vat | OPTIONAL |
Number feature | Field | purchase_price | OPTIONAL |
Number feature | Field | purchase_price_no_vat | OPTIONAL |
Date feature | Field | release_date | OPTIONAL |
String or number feature | Field | ean | OPTIONAL |
String feature (Select / non selectable) | Field | manufacturer | OPTIONAL |
String feature (Select / non selectable) – Can also be multiselect for multiple sales channels. Sales channels can be mapped via a single feature, a multi feature or optionally as a hard coded value, separated with a semicolon.A combination of the above can also be used. | Field | sales_channels | The sales channel mapped needs to be the Shopware sales channel UUID(see screenshot) |
String feature (Select / non selectable) | Field | tax_id | The tax object that will be assigned when products are transferred to Shopware. Needs to be the Shopware UUID of the tax. (See screenshot) |
Explicit mapping. Format: | Field | filterable_properties | Se further explanation of filterable properties below. |
String feature (Select / non selectable) | Field | currency | By filling in a Shopware currency code, the price/currency will be updated in Shopware. See screenshot for example. |
String feature (Select / non selectable) | Field | meta_title | OPTIONAL |
String feature (Select / non selectable) | Field | meta_description | OPTIONAL |
String feature (Select / non selectable) | Field | meta_keywords | The Ecommerce API output must be in the form of a string. If you are using a Multi Select feature in Perfion, you need to use FormatMultiValue in your Ecommerce Mapping, to ensure that the output is a single string. |
Related product feature (Selectable) | RelatedProduct | some_name_you_define | You can define any kind of product relation you wish. The captions of your Perfion related product will be used to create the cross selling group in Shopware. |
Boolean value(true/false) or Integer value (1/0) | Field | Is_top_seller | Marks the product in shopware as “Highlight product” OPTIONAL |
Number value. | Field | restock_time | Amount of days to restock OPTIONAL |
Number value. | Field | max_purchase | Max amount of products you can purchase. OPTIONAL |
Number value. | Field | min_purchase | Minimum amount og products to buy OPTIONAL |
Number value. | Field | purchase_steps | Maximum amount of buyable products OPTIONAL |
Boolean (True/false) or Integer (1/0) value | Field | is_closeout | Mark the product as “Clearance sale” OPTIONAL |
String | Field | pack_unit | Set the Pack Unit text OPTIONAL |
String | Field | pack_unit_plural | Set the Pack Unit Plural text OPTIONAL |
Boolean (True/false) or Integer (1/0) value | Field | free_shipping | Mark the product with “free shipping” OPTIONAL |
Ecommerce API Specific mappings
Remember that, as with any other use of the Perfion Ecommerce API, you also need to map the special Ecommerce API mappings, to enable variant setup.
For products and variants, you need to map the following (see complete mapping screenshot for more help):
EcommerceVariantDimensions
EcommerceType
EcommerceVariantOfProduct
How does the “filterable_products” mapping work?
When you are mapping the filterable_products mapping, you have the opportunity to select which features you would like to create as Properties in Shopware.
Properties in Shopware are features that can be used as filtering, or as variant configurations.
The filterable_products mapping, is a text string enclosed by apostrophes ‘’. The values inside the apostrophes are the output mapping names (in the Ecommerce TO column) of the features you want to configure as properties. These must be semi-colon seperated.
Remember, if you do not add your mappings to the filterable_properties mapping, the fields will be created as custom fields on the products, and this cannot be used for filtering or variant dimensions.
YOU ALWAYS HAVE TO INSERT THE NAMES OF FEATURES THAT ARE USED AS VARIANT DIMENSIONS, OTHERWISE VARIANTS CANNOT BE CREATED CORRECTLY.
Example 1:
Lets say you have a product that has 2 variant dimensions, color and size. Before you can use these dimensions, you will need to map them in your Ecommerce Mapping; note that the TO / output name is an arbitrary name. I chose color_dimension and size, eg:
Before variants can be created, the two mapping names (color_dimension, size), needs to be added to the filterable_properties like so:
Example 2:
Lets say that you added another feature, that you would like to be able to filter on in Shopware, you could do the following.
Add the feature mapping:
Add the Ecommerce TO name, to the filterable_properties like so:
How to setup a product search
To setup a product search, go to the EcommerceSearches feature data section, and create a new search to filter your products. As with categories, the search should be names the same, as the search part of your Context mapping.
In this case, the search is called ShopwareProductSearch.
Right click the search and input your product search filter query. It is common to limit your search, to products that are contained in the active categories that you are using for Shopware, eg:
Ecommerce Settings - Activating variants
If you are working with variants, you need to enable variants in the EcommerceSettings feature data section, by setting VariantSupportEnabled to True.
Additional required EcommerceSettings
To enable incremental / delta imports to Shopware, you need to create a settings feature called “TimeZone”, and set it to “utc”
You also need to type in your FileServiceUrl and ImageServiceUrl (see screenshot above).
Complete category, product and variant mapping
How to setup your products and variants in the Perfion grid
When you are done mapping your Ecommerce API setup, the next step is to configure your products. In this example, we have configured a product to have two variant dimensions, Color and Material.
In the screenshot below, you will see the needed column for such a setup.
EcommerceVariantOfProduct: In this column you need to type in the Value/