Quick search:eBay DataTransfer JTL-Worker PayPal

JTL-Links

Thank you for using the English version of the JTL-Guide!
We are currently still building up the English documentation; not all sections have been translated yet. Please note that there may still be German screenshots or links to German pages even on pages that have already been translated. This guide mostly addresses English speaking users in Germany.

Note: On 1 September 2024, JTL introduced new editions that bundle most of the previous individual services into different packages. In order for you to continue working as smoothly as possible, existing customers were automatically switched to the package configuration that best matched their existing contract. The individual packages differ in terms of limitations and/or range of functions. Therefore, some of the features described in the JTL-Guide may not be available to you as part of your booked JTL edition. You can change your package configuration in your JTL customer account. Find out more about the new editions and packages here. Check our FAQ for frequently asked questions about the product editions.

Contents

JTL-Shop build packages

While we are already working on the next version of JTL-Shop, critical bug fixes are published via build packages for the current shop version. These build packages are patches that are released for a current version of JTL-Shop, e.g. 4.05, and fix known problems. With the help of build packages, we ensure high software quality in terms of maintainability and support.

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. Updating from JTL-Shop 4 to JTL-Shop 5 comes with new features but can also introduce incompatible changes regarding 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.

This tutorial describes how to update a self-hosted JTL-Shop to a more recent available build/patch version of JTL-Shop. If you use JTL-Shop Hosting, your updates will be carried out directly by us. Please read the instructions: Update of JTL-Shop for JTL-Shop Hosting.

In the case of a pure build update (e.g. from 5.0.3 to 5.0.4), normally no database updates are carried out. The update usually only affects JTL-Shop files. However, in important cases, some database migrations may be necessary for crucial bug fixes. Therefore, after uploading the new shop files, check Administration > System > Update for pending updates and, if necessary, carry them out after a database backup.

There are three different options for updating to the latest build or patch version. We recommend option 1.

If the minor shop version changes when you update (e.g. from 5.0.x to 5.1.x, regardless of which build), please follow the instructions below: Updating JTL-Shop

Note: You can find out if a new build is available for the current JTL-Shop version via the JTL-Shop back end dashboard widget called Information about online shop and the associated version thread in our Release forum. We recommend subscribing to this subforum and the JTL-Shop version threads so that you also receive notifications via email.

Update of the current shop version to a more recent build

Version 1: Patch package of all build updates for a shop version

If possible, we offer a package with all build updates. These are characterised by the fact that they already contain the affected version numbers in the name of the archive, e.g. 5.0.0 to 5.0.4. This means that you can use this patch package with the JTL-Shop versions 5.0.0, 5.0.1, 5.0.2 and 5.0.3 to update directly to version 5.0.4.

And this is how you proceed:

Download the patch package in the release thread of the respective version in the release forum: Go to release forum
Check the patch package in the folder /templates/ to see if there are files in there that would overwrite any customised files or the template you are using. Rename these files if necessary. We try to avoid changes to the templates in build packages. However, if there are any changes, you can find the .diff files in the release post of the release forum.

Important note about the .htaccess files: With a new version of JTL-Shop, there may also be changes in the .htaccess files. If you have adjusted your .htaccess (e.g. the recommended domain forwarding), you will either have to make the changes in the more recent .htaccess again or copy our changes in your .htaccess files.

Place JTL-Shop in maintenance mode in the back end under View > Settings > Global.
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.

If you use the object cache, deactivate it completely under Administration > System > Cache!
Overwrite your existing JTL-Shop files with the new files and folders via FTP (overwrite all). Set the transfer type in the FTP programme to binary transfer! Also check whether all files have been transferred or whether your FTP program reports failed transfers. For example, you can learn how to switch Filezilla to binary transfer here: Go to the video tutorial “Binary Data Transfer”
Log in to the admin back end of JTL-Shop. If there are any necessary database changes, you will be automatically redirected to the update menu. If there is no automatic forwarding, to be on the safe side, call up the menu via Administration > System > Update. If there are pending updates, first create a database backup via Backup copy (stored in /export/backup) and then carry out the migrations via the Start database update button.
Continue with Further steps below.

Variant 2: Download individual patches and upload in ascending order.

If no patch package with all included patches (see option 1) is available but only a single patch (e.g. from 5.0.3 to 5.0.4 or 5.0.0 to 5.0.1), it must be ensured that the initial shop version is actually correct. With a single patch for 5.0.4, you cannot, for example, update from 5.0 Build 1 to 5.0 Build 4! Build 2 and then Build 3 must be installed beforehand. Pay attention to the correct ascending order, otherwise you can overwrite newer files with older files.

After applying all patches, go to Administration > Troubleshooting > Diagnostics in the JTL-Shop back end. For the file structure, the number of modified files must be 0. If more than 0 modified files are listed there, then an error probably occurred when uploading the files. Make sure that you transfer files via FTP in binary mode, that there are no transfer errors and that you keep the correct order of the patch builds (first Build 1, then Build 2, then Build 3 and so on).

And this is how you proceed:

Download the next higher build patch package for your current shop version in the release thread of the respective version in the release forum: Go to release forum. You can check which shop version you are currently using in the admin back end in the dashboard widget Information about online shop.
Check the patch package in the folder /templates/ to see if there are files in there that would overwrite any customised files or the template you are using. Rename these files if necessary. We try to avoid changes to the templates in build packages. However, if there are any changes, you can find the .diff files in the release post of the release forum.

Place JTL-Shop in maintenance mode in the back end under View > Settings > Global.
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.

If you use the object cache, deactivate it completely under Administration > System > Cache!
Overwrite your existing JTL-Shop files with the new files and folders via FTP (overwrite all). Set the transfer type in the FTP programme to binary transfer! Also check whether all files have been transferred or whether your FTP program reports failed transfers. For example, you can learn how to switch Filezilla to binary transfer here: Go to the video tutorial “Binary Data Transfer”
Log in to the admin back end of JTL-Shop. If there are any necessary database changes, you will be automatically redirected to the update menu. If there is no automatic forwarding, to be on the safe side, call up the menu via Administration > System > Update. If there are pending updates, first create a database backup via “Backup copy” (stored in /export/backup) and then carry out the migrations via the Start database update button.
Repeat steps 1 to 7 of option 2 until JTL-Shop has reached the latest build for your shop version.
Continue with Further steps below.

Variant 3: Downloading and transferring the complete package

Option 3 corresponds to the standard JTL-Shop update instructions, with which you can also update minor versions (e.g. from 5.0.x to 5.1.x). Go to JTL-Shop update instructions

Further steps

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.
Remove orphaned shop files! Go to Administration > Troubleshooting > Diagnostics > File structure > Details. Alternatively, you can use the notification bell and click on the message Database structure: Error in the database structure. Expand the corresponding entry of the orphaned files and scroll to the bottom of the page. There you can either delete the files directly if you have appropriate write permissions or generate a script. This script can then be forwarded to your hosting provider or service partner.

Caution: The deletion of orphaned files is safety-relevant! Any existing security vulnerabilities in files from older versions of the shop can be removed by deleting the files.

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

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.
If no errors occur, deactivate the maintenance mode under View > Settings > Global. From now on, you may synchronise again and reactivate JTL-Worker.
If necessary, activate the object cache under Administration > System > Cache .
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.