Please refer to the custom field documentation of the output-module for a general overview on how to deal with custom fields.

The media module is able to handle custom fields since version 2.1.1.

Media Module Custom Fields

The media-module creates a custom field set to store some information about the uploaded media files. You can configure the name of the custom field set by setting the configuration customFields.mediaDataSetName:

    "customFields": {
        "mediaDataSetName": "synqup_media_data"

There are to custom fields that store information about the uploaded images assigned to that custom field set:

  • The field originalFilenameFieldName contains the original file name that the uploaded file has on its source file system.
  • The field imageHashFieldName contains a hash of the media file. This is used to compare the files in synQup and Shopware to determine whether the files have changed.

You can configure their names by setting the customFields.imageHashFieldName and customFields.originalFilenameFieldName configurations:

    "customFields": {
        "mediaDataSetName": "synqup_media_data",
        "imageHashFieldName": "synqup_image_hash",
        "originalFilenameFieldName": "synqup_original_filename"

Custom Fields from Assets

This section explains how to map custom fields for Asset documents.

In general all rules of the custom field handling of the main module apply to the media-module as well. There are some minor differences though that will be covered in the following section.


  • Each AttributeGroup of an Asset will be converted to a custom field set. This set has a relation to the media-entity.
  • Each Attribute of an AttributeGroup will be converted to a custom field that is assigned to this custom field set.
  • Since the MediaEntity is translated the rules for translated custom fields apply.


In this example we will prepare an Asset with Attributes in order to map a custom field set and custom field to Shopware. The following code creates a custom field set named "_media_custom_fields_example". Two custom fields are will be assigned to that set (media_custom_field_1 and media_custom_field_2):

foreach ($this->documentManager->getRepository(Category::class)->findAll() as $category) {

    /** @var AssetGroup $assetGroup */
    foreach ($category->getAssetGroups() as $assetGroup) {

        /** @var Asset $asset */
        foreach ($assetGroup->getAssets() as $asset) {
            $attributeGroup = new AttributeGroup(
                new AttributeCollection(
                        new Attribute('media_custom_field_1', ...),
                        new Attribute('media_custom_field_2', ...)
            $asset->setAttributeGroups(new AttributeGroupCollection([$attributeGroup]));


Since media-entities are translated (so the custom fields are written into the translation-tables) you have to provide a valid locale-configuration.

You also have to add a valid configuration for custom fields to your media-module-config:

    "customFields": {
        "enabled": true,
        "autoCreate": true,
        "create|fill|ignore": "...",
        "mediaDataSetName": "...",
        "imageHashFieldName": "...",
        "originalFilenameFieldName": "..."

To map custom fields with the media-module you have to set customFields.enabled and customFields.autoCreate to true. As in the main module you are able to configure filters to filter out individual custom fields.

Custom Field Updates

The module analyzes every Attribute that is assigned to an Asset. Since an Attribute does not provide timestamps the module uses the timestamp-values of the owning Asset to determine whether the custom field values must be updated or not.

In other words: An Attribute is ignored, if the timestamp-values createdAt or updatedAt of its owning Asset are before the value of lastSync in the module configuration. So the module generates jobs to update the custom field values of an Asset if one of the timestamp-values createdAt or updatedAt is after the last sync date.