--- title: "Upgrade" manual: "Matomo Widgets" version: "4.0" permalink: "https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:upgrade@4.0" source: "Upgrade/Index.rst" rendered: "2026-09-22T16:08:26+00:00" --- # Upgrade {#upgrade} > [!IMPORTANT] > Before updating from a version before 0.3 to 1.x, 2.x or 3.x you should > update to version 0.3.2 first and execute the upgrade wizards. Then update to > the newest 1.x version and run the next upgrade wizards. Then you can upgrade > to version 2.x, 3.x or 4.x. - [From version 3.x to 4.0](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:from-version-3-x-to-4-0@4.0) - [From version 2.x to 3.0](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:from-version-2-x-to-3-0@4.0) - [From version 1.x to 2.0](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:from-version-1-x-to-2-0@4.0) - [From version 0.3 to 1.0](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:from-version-0-3-to-1-0@4.0) - [From version 0.2 to 0.3](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:from-version-0-2-to-0-3@4.0) ## From version 3.x to 4.0 {#from-version-3-x-to-4-0} No migration necessary. ## From version 2.x to 3.0 {#from-version-2-x-to-3-0} No migration necessary. The date ranges for the following widgets have been changed: - [Bounce rate](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-bounce-rate@4.0) - [Browser plugins](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-browser-plugins@4.0) - [Browsers](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-browsers@4.0) - [Campaigns](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-campaigns@4.0) - [Content names](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-content-names@4.0) - [Content pieces](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-content-pieces@4.0) - [Countries](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-countries@4.0) - [Custom dimensions](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-custom-dimensions@4.0) - [Most viewed pages](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-most-views-pages@4.0) - [Operating system families](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-operating-system-families@4.0) - [Site search keywords](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-operating-site-search-keywords@4.0) - [Site search keywords with no result](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widgets-operating-site-search-keywords-no-result@4.0) **Old configuration**: current month\ period: month date: today **New configuration**: last 28 days\ period: range date: last28 You can define your custom date ranges as described in the [widget configuration](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:widget-configuration@4.0). ## From version 1.x to 2.0 {#from-version-1-x-to-2-0} No migration necessary. ## From version 0.3 to 1.0 {#from-version-0-3-to-1-0} In version 1.0 the format changed how the active widgets for a site are stored in the site configuration. For the migration of this configuration an upgrade wizard is available. > [!WARNING] > **Attention** > > As with all upgrades: Please backup your data before executing the upgrade > wizard! The migration can be started in the TYPO3 backend via **Admin Tools** \> **Upgrade** \> **Upgrade Wizard**. ![Migrate configuration in backend](../Images/EnableWidgetsMigrationBackend.png) Alternatively, you can also execute the migration wizard on a TYPO3 console: ![Migrate configuration on console](../Images/EnableWidgetsMigrationConsole.png) > [!NOTE] > After executing the upgrade wizard you have to flush the cache via the > module **Admin Tools** \> **Maintenance**. The migration wizard updates: - File `config//config.yaml` ## From version 0.2 to 0.3 {#from-version-0-2-to-0-3} To allow the configuration of more than one Matomo instance the configuration moved from the extension configuration to the [site management](https://docs.typo3.org/permalink/brotkrueml/typo3-matomo-widgets:site-configuration@4.0). > [!WARNING] > **Attention** > > As with all upgrades: Please backup your data before executing the upgrade > wizard! > [!NOTE] > If only one site is available the migration of the configuration can be done > with a upgrade wizard. If there is more than one site configured you have to > migrate the configuration by yourself. For this purpose the extension > configuration is still available but has no effect at all. ### Migrating from extension configuration to site configuration {#migrating-from-extension-configuration-to-site-configuration} The migration can be started in the TYPO3 backend via **Admin Tools** \> **Upgrade** \> **Upgrade Wizard**. ![Migrate configuration in backend](../Images/SiteConfigurationMigrationBackend.png) Alternatively, you can also execute the migration wizard on a TYPO3 console: ![Migrate configuration on console](../Images/SiteConfigurationMigrationConsole.png) > [!NOTE] > After executing the upgrade wizard you have to flush the cache via the > module **Admin Tools** \> **Maintenance**. The migration wizard updates: - File `typo3conf/LocalConfiguration.php` - File `config//config.yaml` > [!TIP] > **Hint** > > If you use Git for versioning your site configuration you should consider > to store the authentication token in an > [environment variable](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ApiOverview/SiteHandling/UsingEnvVars.html#sitehandling-using-env-vars) for > better security. ### Migrating the dashboard widgets {#migrating-the-dashboard-widgets} As the identifiers of the dashboard widgets have changed they can also be migrated to the new identifiers. If multiple site configuration exist the widgets have to be assigned manually to the dashboards again. The migration can be started in the TYPO3 backend via **Admin Tools** \> **Upgrade** \> **Upgrade Wizard**. ![Migrate dashboard widgets in backend](../Images/WidgetMigrationBackend.png) Alternatively, you can also execute the migration wizard on a TYPO3 console: ![Migrate dashboard widgets on console](../Images/WidgetMigrationConsole.png) > [!NOTE] > After executing the upgrade wizard you have to flush the cache via the > module **Admin Tools** \> **Maintenance**. The migration wizard updates: - Table "be_dashboards" ### Migrating the backend user group configuration {#migrating-the-backend-user-group-configuration} Use this upgrade wizard to migrate the widget identifiers to the new format. If multiple site configuration exist the widgets have to be assigned manually to the backend user groups again. ![Migrate widgets identifiers of backend user groups in backend](../Images/WidgetBackendUserGroupMigrationBackend.png) Alternatively, you can also execute the migration wizard on a TYPO3 console: ![Migrate widgets identifiers of backend user groups on console](../Images/WidgetBackendUserGroupMigrationConsole.png) The migration wizard updates: - Table "be_groups"