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.

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.

Instructions for a JTL-Shop update

System requirements

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!

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

Step 1: Preparations

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.

4. If you use the object cache, deactivate it completely under Administration > System > Cache!
5. 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.

6. 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

5. 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.

6. 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.
7. 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).

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.

2. 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.
3. Start the update to the newer version of JTL-Shop by clicking on the button Start database update.

Step 4: Removing orphaned files

By updating JTL-Shop, some files may no longer be required. These should be deleted.

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.

4. 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.

5. 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.
6. If necessary, activate the object cache under Administration > System > Cache .
7. 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.