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.

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

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:

1. Download the patch package in the release thread of the respective version in the release forum: Go to release forum
2. 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.

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

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

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

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

5. If you use the object cache, deactivate it completely under Administration > System > Cache!
6. 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”
7. 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.
8. Repeat steps 1 to 7 of option 2 until JTL-Shop has reached the latest build for your shop version.
9. 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

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

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

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