Updating JTL-Shop

    In this video we explain how to update JTL-Shop.

    Updating JTL-Shop

    This tutorial describes how to update a self-hosted JTL-Shop to a more recent available minor version of JTL-Shop. Customers using JTL-Hosting should read the following instructions: Having a hosted JTL-Shop updated.

    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 an upgrade 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.

    Instructions on how to upgrade to specific versions of JTL-Shop can be found on the following pages:

    Go to the help pages for upgrading JTL-Shop3 to JTL-Shop4

    Go to the help pages for upgrading JTL-Shop4 to JTL-Shop 5

    For the update of a minor version, 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 the JTL-Customer Centre

    Changes for each version can be found with the corresponding target version in our issue 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.

    Updating a minor and/or build/patch version is possible with these instructions, but we also provide patch packages for updating a build/patch version. The difference is that the patch package really only contains the changed files and thus the file upload is much faster. If you would like to update the build/patch version using a patch package, please follow the instructions below: Go to help pages for JTL-Shop build packages.

    Please note: While you need an active subscription (or CFE licence) to upgrade to a newer major or update a minor version, build/patch packages are exempt from this rule. For example, if your subscription expired before the release of version 5.1.0, you cannot update to 5.1.0, but you can still use all future 5.0.x builds/patches.

    Instructions for a JTL-Shop update

    System requirements

    You need at least JTL-Shop 5.0.0 to follow these instructions. For upgrading from previous versions, please read the section “Updating JTL-Shop” above. For an update to a newer version of JTL-Shop 4, please read the JTL-Shop 4 version of this page.

    With new minor versions and patch/build updates, we can usually avoid changes to the system requirements. This may still happen, however. You should therefore review our official standard system requirements, the release notes concerning the respective version in our release forum as well as all release posts of versions you may have skipped!

    Please note: If you use a customised template, please contact your service partner or developer in advance to have it prepared for the new version!

    If you would like to adjust your template yourself or update it, our developer documentation will support you: Go to the JTL-Shop developer documentation

    Please note: If you use plug-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

    Please note: You need at least JTL-Shop 5.0.0 to follow these instructions. For upgrading from previous versions, please read the section “Updating JTL-Shop” above. For an update to a newer version of JTL-Shop 4, please read the JTL-Shop 4 version of this page.
    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 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.
    • Block the affected JTL-Shop for the synchronisation in the respective online shop connection settings.
    1. If you use the object cache, deactivate it completely under Administration > System > Cache!
    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 update 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 and/or /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 copy of the JTL-Shop database or have it 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 home page, go to Produkte > Onlineshop > Shop Editionen (Products > Online shop > > Shop editions). The licence overview opens.
    2. Under Licences – ungrouped , you can now download the JTL-Shop installation package via the button 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 these files are not required during an update:
    • install (complete folder)
    • shopinfo.xml
    1. Make the same changes to the following files in the downloaded package, which you have also made to the files of the same name of your existing shop:
    • .htaccess
    • admin/.htaccess
    • robots.txt

    If you have not made any adjustments to these files in your existing JTL-Shop, you can use the files in the downloaded package without any changes.

    Important note about the .htaccess files: New shop versions may include changes to .htaccess files of JTL-Shop. Those changes must be taken into account! Don’t just overwrite these files with your old files. 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 /templates/Evo and /templates/NOVA folders will be overwritten.
    2. Overwrite your existing JTL-Shop files (saved in step 1.2) 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).
    Please note: 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

    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 forwarding, 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 /export/backup directory.
    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: Removing orphaned files

    By updating JTL-Shop, some files may no longer be required. 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 if you have the necessary write permissions or generate a script that you can forward to your hosting provider or service partner.

    Step 5: 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, 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.
    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. Therefore, you must trigger the template update manually. To do this, first back up all of your customized email templates. Then open the back end of JTL-Shop and open Administration > Email > Templates. Click the Reset button for the templates. After that, you incorporate your previously saved adjustments into the now updated templates.
    Note: When resetting, the contents of the templates for all languages except German and English are completely emptied, because there are no default templates for other languages.
    1. If no errors occur, deactivate the Maintenance mode under View > Settings > Global > Maintenance mode. From now on, you may synchronise again and reactivate JTL-Worker.
    2. If necessary, activate the object cache under Administration > System > Cache .
    3. 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.

    Requesting help for the update

    In case of problems with or after the JTL-Shop update, please first check in the administration area under Administration > Troubleshooting > Diagnostics whether there are any problems with the server, files, directory rights, or the database. For example, if there are modified files, make sure that they use the binary transfer mode and that there are no transfer errors.
    Also make sure that you have checked all the points under “Step 5: Further steps”.

    If you cannot solve the problem, please create a ticket in the JTL-Customer Centre for the product selection JTL-Shop and enter a meaningful error description and title. Alternatively, please contact your service partner.
    Describe all important steps that lead to the problem and enter your JTL-Shop access data into the access data field, NOT in the description text.
    In case of update issues, we may need access to the admin back end, web space (FTP) and the database (PHPMyAdmin or hosting administration). Your hosting provider can explain exactly how to grant us access to the database.

    If you have neither a JTL support contract nor a service partner, you can open a thread in our JTL-Shop forum. Be sure to use a descriptive title and not publish access data.