Skip to main content
Version: 2024.1

Upgrade Information

Following steps are necessary during updating to newer versions.

Upgrade to 4.0.0​

  • [Indexing] Removed Elasticsearch support and indexing mechanisms, Portal Engine is using OpenSearch now via pimcore/general-data-index-bundle bundle
  • Removed usage of ongr-io/ElasticsearchDSL library and replaced it with custom solution
    • This is especially important for custom implementations of Pimcore\Bundle\PortalEngineBundle\Service\SearchIndex\Search\PreConditionServiceHandler\PreConditionServiceHandlerInterface and events manipulating the search queries.
  • [Core] Removed Pimcore 10 support
  • [Frontend] Updated frontend dependencies
  • [Events] Moved events to pimcore/general-data-index-bundle bundle
    • Pimcore\Bundle\PortalEngineBundle\Event\Asset\ExtractMappingEvent -> Pimcore\Bundle\GenericDataIndexBundle\Event\Asset\ExtractMappingEvent
    • Pimcore\Bundle\PortalEngineBundle\Event\Asset\UpdateIndexDataEvent -> Pimcore\Bundle\GenericDataIndexBundle\Event\Asset\UpdateIndexDataEvent
    • Pimcore\Bundle\PortalEngineBundle\Event\DataObject\UpdateIndexDataEvent -> Pimcore\Bundle\GenericDataIndexBundle\DataObject\Asset\UpdateIndexDataEvent
    • Pimcore\Bundle\PortalEngineBundle\Event\DataObject\UpdateIndexDataEvent -> Pimcore\Bundle\GenericDataIndexBundle\Event\DataObject\UpdateIndexDataEvent
  • [Configuration] Moved configuration options pimcore_portal_engine.index_service.es_client_params and pimcore_portal_engine.index_service.es_client_params.es_client_name to pimcore_portal_engine.index_service.opensearch_client_params and pimcore_portal_engine.index_service.opensearch_client_params.client_name
  • [Configuration] Removed configuration option pimcore_portal_engine.pimcore_portal_engine.core_fields_configuration (is now handled by pimcore_generic_data_index.core_fields_configuration of pimcore/general-data-index-bundle bundle)
  • [Configuration] Removed configuration options pimcore_portal_engine.messenger_queue_processing.*. The queue processing is now handled by pimcore/general-data-index-bundle bundle and handling it by message workers is now the only/default option.
  • [Configuration] Removed pimcore_portal_engine.index_service.index_settings configuration option. The index settings are now handled by pimcore/general-data-index-bundle bundle.
  • [Configuration] Container parameter portal-engine.elasticsearch.index-prefix was removed and replaced with generic-data-index.index-prefix of pimcore/general-data-index-bundle bundle.
  • [Configuration] Container parameter portal-engine.elasticsearch.es-client-name was removed. Use the generic-data-index.opensearch-client service to get the right client if needed.
  • [Code BC breaks] Migrated asset and data object field definition adapters to new requirements
    • Renamed getESMapping() method to getIndexMapping()
    • Renamed method getLocalizedESMapping() to getLocalizedIndexMapping()
    • Add return types to most of the methods
  • [Code BC breaks] Removed Pimcore\Bundle\PortalEngineBundle\Enum\ElasticSearchFields enum and replaced it with Pimcore\Bundle\GenericDataIndexBundle\Enum\SearchIndex\FieldCategory and Pimcore\Bundle\GenericDataIndexBundle\Enum\SearchIndex\FieldCategory\SystemField enums of pimcore/general-data-index-bundle bundle.
  • [Code BC breaks] Moved statistic trackers from Pimcore\Bundle\PortalEngineBundle\Service\StatisticsTracker\Elasticsearch to Pimcore\Bundle\PortalEngineBundle\Service\StatisticsTracker\OpenSearch and migrated them to OpenSearch instead of Elasticsearch.
  • [Code BC breaks] Make use of PHP 8 constructor property promotion feature for most of the classes.
    • Private and protected properties used in the constructor are now typed.
  • [Code BC breaks] Renamed property userLoginFields of class Pimcore\Bundle\PortalEngineBundle\Service\Security\Authentication\UserProvider to fields
  • [Search index structure] Moved field paths of standard_fields within the search index to new convention/location:
    • Asset metadata are now stored in custom_fields
    • Data object relation fields are now stored in custom_fields
    • Localized fields are now stored with {LOCALE} placeholder instead of hardcoded language locale.
    • .raw subfields are renamed to '.keyword'
    • Pimcore\Bundle\PortalEngineBundle\Migrations\Pimcore11\Version20240208161554 migration should take care of updating the index fields automatically, but the data pool configuration pool documents should be double checked to ensure that filter fields, list view fields, sortable fields and the list view name attributes are still correct.
    • Custom conditions via Pimcore\Bundle\PortalEngineBundle\Service\SearchIndex\Search\PreConditionServiceHandler\PreConditionServiceHandlerInterface should be checked and updated if necessary.
  • Take a look at this PR for a example migration to 4.0: https://github.com/pimcore/demo-enterprise/pull/247

Upgrade to 3.1.0​

  • (only relevant if not already upgraded to version 2.6.0) [Indexing] - Filters based on the asset metadata with relations to objects which have localized fields are now indexed with all the localized values. The index structure is therefore changed (from single string to array) and it is necessary to run the migration that recreates all the indexes after updating to 3.1.0.

Upgrade to 3.0.0​

  • BEFORE UPGRADE: First upgrade to last 2.5 version and make sure all migrations are executed properly.
  • BEFORE UPGRADE: Upgrade directly to 3.1.0 if you already upgraded to 2.6 versions.
  • BEFORE UPGRADE: Activate Generate Type Declarations for PortalUser and PortalUserGroup classes and save them to regenerate the php class files. This will break portals until portal engine is upgraded to v3.0.0 via composer.
  • Removed Pimcore 6.9 support.
  • If you are upgrading to pimcore 11, then please install the pimcore/admin-ui-classic-bundle bundle.
  • [Security] Removed support of old authentication system (not setting security.enable_authenticator_manager: true in security.yaml) and related Guard authenticators.
  • [OpenId Connect] Bumped required version of openid-connect bundle to ^1.1.
  • [Elasticsearch] Removed ES 6 and ES 7 support, added ES 8 support.
  • [Elasticsearch] Changed elasticsearch client configuration.
  • Adapted installation process, see docs for details.
  • Added additional parameter for the DataPoolConfigInterface in methods of WorkspaceServiceInterface, SearchServiceInterface, FolderService and PreConditionService.
  • [Indexing] Added option to re-create index or update index via settings page
  • [DataObject][Layout] - fixed layout of Field Container (vbox is now vertical and hbox horizontal layout)
  • [Security] Changed the return type of Pimcore\Bundle\PortalEngineBundle\Service\Security\DirectEditPermissionService::getUserId to null|int.
  • [Translations] Introduced separate translation domain for frontend translations - portal-engine-frontend.
  • [Translations] Implemented PO Editor workflow for shared and admin translations (they are now under src\Resources\translations in .yaml format).
  • [Migrate Statistics Explorer Data] If the statistics data (for logins, downloads and asset updates) stored in Elasticsearch are still relevant and should be kept, the data needs be migrated to OpenSearch. This can be done for example via native reindexing directly in OpenSearch:
POST _reindex
{
   "source":{
      "index": "enterprise_portal_statistics_download__2024_04",
      "remote":{
         "host":"http://elastic:9200",
         "username":"elastic",
         "password":"somethingsecret"
      }
   },
   "dest":{
      "index":"pimcore_statistics_download__2024_04"
   }
}

To make this possible it is needed to set the reindex.remote.whitelist setting in the opensearch.yml configuration file of the OpenSearch instance to allow the remote reindexing from the old Elasticsearch instance. Additionally, the correct index names/prefixes need to be checked to find the right source and target index names.

Upgrade to 2.6.0​

  • [Indexing] - Filters based on the asset metadata with relations to objects which have localized fields are now indexed with all the localized values. The index structure is therefore changed (from single string to array) and it is necessary to run the migration that recreates all the indexes after updating to 2.6.0.

Upgrade to 2.3​

  • From now on, out of the box Statistics Explorer data sources and trackers use same ES configuration as portal engine itself. If you want to change that, you need to overwrite service definition of pimcore.portal_engine.statistics_explorer.client_factory

Upgrade to 2.1.0​

  • Execute all migrations of the bundle.

Upgrade to 2.0.0​

  • First upgrade to last 1.x version and make sure all migrations are executed properly.
  • Migrate Pimcore to Pimcore 6.9
  • Migrate controller references to new naming scheme (e.g. ), for example by using migration command bin/console migration:controller-reference
  • Add following line to your firewalls configuration in the security.yml of your app after the pimcore_admin firewall.
security:
    firewalls:
        pimcore_admin: 
            # ...
        portal_engine: '%pimcore_portal_engine.firewall_settings%'
  • Clear Pimcore Caches (bin/console pimcore:cache:clear)
  • Elasticsearch mapping has changed to fix deprecations. Rebuild your index by running following commands:
bin/console portal-engine:update:index-recreate
bin/console portal-engine:update:process-index-queue