Quick search:eBay DataTransfer JTL-Worker PayPal
Contents

    Upgrade from JTL-Shop 4 to JTL-Shop 5

    These instructions describe how to update a self-hosted JTL-Shop 4 to JTL-Shop 5. Hosting customers at JTL should follow these instructions.

    Please note: Shop versioning & upgrade vs update:  JTL-Shop uses the Semantic Versioning Specification (SemVer). We distinguish accordingly between major, minor and patch version numbers and specify versions in the format MAJOR.MINOR.PATCH. An upgrade is an update from one major version to the next major version. For example, updating from JTL-Shop 4 to JTL-Shop 5. An upgrade comes with new features but can also introduce incompatible changes to the system. Come with templates or plug-in interfaces. Therefore, please check whether the plug-ins you use and the desired template are also available for the new shop version. An update, on the other hand, takes place within the same major version. It usually contains bug fixes and often new features.

    For the update, you need a valid JTL-Shop licence with an active subscription (or CFE licence).

    You can download the current version of JTL-Shop here: Go to JTL-Customer Centre.

    Changes for each version can be found with the corresponding target version in ourissue tracker for JTL-Shop. You can find an example here: Go to the issue tracker for JTL-Shop target version 5.0.0
    In addition, you can find important information about each release in the release section of the JTL-Forum: Go to the release forum
    You can see an example here: Go to the release forum for JTL-Shop 4.06.

    If you do not want to upgrade but only want to install the latest version of a specific JTL-Shop major version, please follow the instructions below:

    Attention: An upgrade directly from JTL-Shop 3, 4.00 or 4.01 to JTL-Shop 5 is not possible! You need at least version 4.02! Please follow one of the previously mentioned update methods relating to your initial version before continuing with these instructions!

    Instructions for an upgrade from JTL-Shop 4 to JTL-Shop 5

    System requirements

    • You need at least JTL-Shop 4.02 for the upgrade!
    • You need at least JTL-Wawi 1.0! (For the correct processing of UTF-8 character sets, at least JTL-Wawi 1.6 is required!)
    • 64-bit Apache web server(PHP mode: FCGI or Apache Module) 2.2 or 2.4 with mod_rewrite module, .htaccess support (the web server must allow for default rules to be overwritten and added)
    • Otherwise, please observe all standard system requirements.
    Please note: If you use a customised template, please contact your JTL Service partner or developer in advance to have it prepared for the new version!

    If you would like a new customised template and still need a partner to help you with it: Find a service partner here.

    If you would like toadjust your template yourself or update it, our developer documentation might prove useful: Go to JTL-Shop developer documentation.

    Please note: If you useplug-ins, please find out in advance whether they are compatible with the new JTL-Shop version or whether compatible versions exist. That way, you can update to newer versions seamlessly or adapt to alternative solutions.

    Step 1: Preparations

    1. Your JTL-Shop licence key works with both JTL-Shop 4 and JTL-Shop 5. If you only have a JTL-Shop 2 or JTL-Shop 3 licence, please purchase a JTL-Shop licence in our store.
    Please note: Please note that you must have at least JTL-Shop 4.02 before you can upgrade to JTL-Shop 5. The upgrade is not possible with a lower version. An direct update from JTL-Shop 3 to JTL-Shop 5 is also not possible.
    1. Activate the maintenance mode in the back end of JTL-Shop under  View > Settings > Global.
    2. Create a backup copy of all files of JTL-Shop. Pay particular attention to saving your template files (folder /templates/) as well as the shop’s configuration file (/includes/config.JTL-Shop.ini.php).
    3. From now on, do not carry out any more synchronisations with JTL-Wawi. If you use JTL-Worker, you have the following options:
    • Exit JTL-Worker and only restart it after the upgrade has been successfully completed.
    • Exit JTL-Worker. In its background service settings, specify that no online shop synchronisations are to be carried out. Start JTL-Worker again to continue synchronisations with other platforms.
    • For the affected JTL-Shop, lock the synchronisation in the Online shop connection dialogue.
    1. If you use the object cache, deactivate itcompletely under System > Cache > Settings !
    2. Check your plug-ins:
    • Uninstall all plug-ins (active and inactive) of which you know that you will no longer use them after the upgrade or are not using anymore now. For these plug-ins, the files should also be removed on the web space from the directory /includes/plugins, as in rare cases even uninstalled plug-ins can cause problems after updates.
    • Deactivate all plug-ins that you would like to continue using after the upgrade.
    Hint: If you use a lot of plug-ins and some of them have been deactivated for a long time, take screen shots of your currently active plug-ins. This way you can later distinguish the plug-ins that have been inactive before from the newly deactivated ones.
    1. Create a backup of the JTL-Shop database or have one created by your hosting provider. Go to the guide page about creating JTL-Shop backups

    Step 2: Updating JTL-Shop files

    1. Log in to the JTL-Customer Centre. On the start page, go toLösungen von JTL (Solutions by JTL) >Onlineshop: xLizenzen(Online shop: x licences). The licence overview opens.
    2. Under Lizenzen – ungruppiert (Licences – ungrouped), you can now download the JTL-Shop installation package via the button Aktionen > Downloads > Download (Actions > Downloads > Download).
    3. Unzip the downloaded zip file locally on your computer into a directory, e.g. C:\jtl-shop.
    4. Delete the following files in the downloaded package, as the files of the same name of your existing JTL-Shop contain individual data and should not be overwritten by the new files:
    • install (complete folder)
    • admin/.htaccess (only if you have customised it)
    • robots.txt (only if you have customised it)
    • shopinfo.xml
    Important note about the .htaccess files: New shop versions may include changes to the top-level .htaccess file of JTL-Shop. Those changes must be taken into account! For this reason, the file is not listed here and should be overwritten! If you have adjusted your .htaccess file (e.g. the recommended domain forwarding), you must either make the changes again in the more current .htaccess file or must not overwrite the file and add our changes to your .htaccess files!
    1. If you use a standard JTL folder for your customised template, rename the new standard templates in the directory /templates/ so that your customised templates are not overwritten in the next step. The folder /templates/NOVA will be overwritten.
    2. Overwrite your existing JTL-Shop files (saved in step 1.3) with the files and folders unzipped in step 2.3 (except for the files removed in step 2.4) via FTP (merge folders, overwrite only existing files).
    Set the transfer type in the FTP programme to binary transfer! Also check if all files have been transferred or if your FTP programme reports failed transfers. For example, you can learn how to switch Filezilla to binary transfer here: Go to the video tutorial “Binary Data Transfer”.

    Step 3: Updating the database

    Please note: At this point at the latest, a PHP version compatible with the version must be activated (see System requirements).
    1. Log in to the admin back end of JTL-Shop. You will be automatically redirected to the update menu. If there is no automatic redirection, call up the menu via Administration > System > Update.
    Please note: We recommend selecting Safe mode to log in. To do this, click on Advanced in the login window and then select Safe mode.
    1. You can create a backup of the JTL-Shop database again at this point via Backup copy. The backup is stored in the directory/export/backup.
    2. Start the update to the newer version of JTL-Shop by clicking on the button Start database update.
    Note: If an error occurs at this point, please save a screenshot of it and contact the JTL-Shop Support team or your respective service partner via a Customer Centre ticket or a forum thread. If you want to cancel the update attempt at this point, it is not sufficient to only update the shop files to the old status (new files must not remain). Please also note our Notes on importing a database backup.

    Step 4: Migration to InnoDB/UTF-8

    After the database update to the new JTL-Shop version has been completed, the database tables must now be converted to InnoDB and UTF8 when upgrading from JTL-Shop 4.

    1. To do this, go to Administration > Troubleshooting > Diagnostics > Database structure > Details. Alternatively, you can use the notification bell and click on the message Database structure: Error in the database structure.
    2. Read the information on this page carefully and click Start migration to start the migration.
    Note: If an error occurs at this point, please save a screenshot of it and contact the JTL-Shop Support team or your respective service partner via a Customer Centre ticket or a forum thread. If you want to cancel the update attempt at this point, it is not sufficient to only update the shop files to the old status (new files must not remain). Please also note our Notes on importing a database backup.
    1. When the migration is finished, you should see Number of modified tables: 0. If there are modified tables, please save a screenshot/copy&paste the issue and contact the JTL-Shop Support team or your respective service partner via a Customer Centre ticket or a forum thread.

    Step 5: Removing orphaned files

    When updating JTL-Shop, some files become redundant. These should be deleted.

    Attention: Deleting orphaned files is safety-relevant! Any existing security vulnerabilities in files from older versions of the shop can be removed by deleting the files.
    1. Go to Administration > Troubleshooting > Diagnostics > File structure > Details. Alternatively, you can use the notification bell and click on the message File structure: Error in the database structure.
    2. There you should see how many files are orphaned. Expand the corresponding entry and scroll to the bottom of the page.
    3. There you can either delete the files directly (requires appropriate write permissions) or generate a script that you can forward to your hosting provider or JTL Service partner.

    Step 6: Further steps

    1. Check if your online shop is working properly! The various integrated test methods under Administration > Troubleshooting > Diagnostics will help you do this. In addition, we recommend that you take a close look at the online shop itself after the update. You can carefully inspect the front end even if the maintenance mode is activated as long as you are logged into the same browser session into the back end. At the very least, check that the registration and purchase process can be completed successfully.
    2. Check your individually adapted template if necessary! If your template is not up to date, have your template designer/JTL Service partner update it to the latest version. Otherwise, it may cause errors. By checking it against our new standard template, you can test whether an error is caused by your adapted template.
    3. Check your plug-ins! After each update of JTL-Shop, especially after large ones, updates may be required for some or all of the plug-ins. You can see whether an update is available under Plug-ins > My purchases after you have connected JTL-Shop to your Customer Centre account. You can update all existing plug-ins via the Update all button. Then switch to the Plug-in administration via Plug-ins > Plug-in manager and check for pending updates. Carry them out. You can reactivate and reconfigure plug-ins for which no warning is displayed and whose versions fit. In case of errors, deactivate all plug-ins and then check whether the problem still occurs. Then reactivate your plug-ins one after the other to identify the responsible plug-in.
    Please note: Plug-ins that are not maintained in the JTL-Extension Store may also need an update reflecting the new shop version or may be incompatible. Please contact the respective provider for more information.
    1. With each update, we may also update email templates. These updates are not automatically imported since individual adjustments could be overwritten. Individual adjustments that you have made to the templates must then be carried out again. Therefore, you should save all email templates once beforehand in order to be able to set them up/rebuild them afterwards. To do this, go to the back end of JTL-Shop and open Administration > Email > Templates. Click the Reset button for the templates.
    Attention: Check for missing translations. If you used languages other than German or English in your old shop, important translations may be missing after the upgrade. In those other languages, custom pages or legally important pages regarding data privacy or the checkout might not be translated.
    1. To add translations in the JTL-Shop back end, open the menu under View > Custom contents > Pages and pay attention to the corresponding markings. Maintain all languages on all pages.
    2. If no errors occur, deactivate the maintenance mode under View > Settings > Global. From now on, you may synchronise again and reactivate JTL-Worker.
    3. If necessary, activate the object cache under Administration > System > Cache .
    4. Check again that no errors occur and keep an eye on your shop via the back-end notifications (notification bell) and the pages Administration > Troubleshooting > Log, Marketing > Orders, and Administration > Email > Log to detect any overlooked errors or abnormalities.

    FAQ

    The storage space of JTL-Shop has increased significantly after the upgrade

    JTL-Shop uses a new image interface from version 5 for all images sent by JTL-Wawi. This is the same image interface that was newly introduced for item images with JTL-Shop 4. This ensures that images are generated live when called up and that changes in the back end of JTL-Shop take effect immediately. With JTL-Shop 3 and 4, the images had to be synchronised again via JTL-Wawi for each change. As a result of this interface change, images are no longer stored in the /bilder/ folder, but in the /media/image/storage/ folder and are then generated for display in the front end in the /media/image/ folder, sometimes in up to four different sizes. The prerequisite for this is that the images have been resent at least once via JTL-Wawi (>=1.0) after the upgrade.

    Since the old images (/bilder/produkte/) will not be deleted, this initially requires more than twice as much storage space for images (also four image sizes as with JTL-Shop 3 and the storage folder for the original image files). To be on the safe side, the old image data (/bilder/produkte/) should only be deleted manually once they are no longer addressed by search engines. However, the old item image URLs will redirect to the new image URLs after the upgrade.

    Switch to Community Free

    If you are using the Community Free Edition (not the BETA version) and want to switch to a paid version, you do not need to reinstall the shop. Simply enter the new licence key in the Wawi.

    JTL-Shop Hosting upgrade

    The upgrade from JTL-Shop 4 to JTL-Shop 5 when you use our hosting works in exactly the same way as an update from, for example, JTL-Shop 4.05 to 4.06. Go to instructions for a hosting update.

    Please note: To upgrade a JTL-Shop 3 hosting directly to JTL-Shop 5, please contact our Hosting department via ticket.

    Test shop

    If you would like to have a look at the system and test it first, we recommend requesting a test shop.

    JTL-Shop modules

    The Survey Module is no longer supported with JTL-Shop 5. All other purchased modules are still compatible with JTL-Shop 5.0.0. An upgrade of the modules is not necessary. If you have rented the modules within the frame of a hosting, nothing changes.

    JTL-Shop plug-ins

    If your plug-ins developed by partners no longer work, contact the plug-in developer directly. JTL no longer delivers plug-ins directly. Plug-ins by JTL are available via the ExtenstionStore and can be installed after being linked to your shop under My Purchases.

    Payment methods

    The following JTL-Shop 4 payment methods are generally no longer supported in JTL-Shop 5 and may have to be re-integrated via plug-ins: Old PayPal payment method (JTL now only supports the JTL PayPal plug-in), Wirecard, EOS, Moneybookers, Billpay, Sofort, Safetypay, Worldpay, Postfinance, PaymentPartner, ipayment, UT, UOS.

    Export formats

    The following JTL-Shop 4 export formats are generally no longer supported in JTL-Shop 5 and may have to be re-integrated via plug-ins: Yatego, hardwareschotte, Kelkoo, Become Europe (become.eu), Billiger, Geizhals, Preisauskunft, Preistrend, Shopboy, Idealo, Preisroboter, Milando, Channelpilot, Preissuchmaschine, Elm@r Produktdatei, Yatego Neu, LeGuide.com, Twenga

    Other removed options

    For other removed options, please see the release post for JTL-Shop 5.0.0 in our release forum.

    Incorrect login data after upgrade during a synchronisation with JTL-Wawi

    This can happen due to a password that uses a character that was not supported before JTL-Shop 5. This character was then stored as a question mark in the database and was also recognised as a question mark during the synchronisation check. After upgrading to JTL-Shop 5, the character is now supported. Therefore, the correctly processed character cannot be assigned appropriately by JTL-Shop 5 because a question mark is stored in the database. The passwords no longer match.

    Therefore, store a new password in the shop connection and in the shop back end under Administration > Users & Rights > Sync with JTL-Wawi.