The jtl-bridge helper

jtl-bridge is a small program from allverto for the migration. It runs on the computer your JTL-Wawi runs on (usually a Windows server), reads your Wawi's data there and transfers it to allverto in encrypted form. Your Wawi database and the Wawi's REST server do not have to be reachable from the internet for this. You don't need any commands – a double-click and a pasted code are enough.

#Before you start

You don't have to enter anything beforehand. In allverto open Settings → Data migration → Migration from JTL-Wawi, step Connect source, and choose the source: JTL-Wawi API (see Setting up the REST API) or JTL database (see Access via the JTL database).

Then expand the box Server not reachable from the internet? Transfer data with jtl-bridge. It shows the same steps as here. The program asks for address, SQL server, user and password later on your server. What allverto already detects is ticked off in the box.

#Step by step

1. Download jtl-bridge. In the box, click Download for Windows. The file is called e.g. allverto-jtl-bridge-1.0.0-windows-x64.exe and doesn't need to be installed. If the browser warns about the file, choose Keep or Download anyway.
2. Copy the file to the server your JTL-Wawi runs on – e.g. via Remote Desktop onto the desktop. Copy the file on your PC (Ctrl + C) and paste it onto the server's desktop in the Remote Desktop window (Ctrl + V). You can also open allverto directly in the server's browser and download the file there.
3. On the server, start the file with a double-click. A window with a black background opens. If Windows first shows “Windows protected your PC”, click More info and then Run anyway – the program is not digitally signed yet.
4. Click “Create setup code” here, copy the code, paste it into the window with a right-click and press Enter. allverto sets up the connection to the chosen source in the process. Copy the code with Copy setup code. It starts with AVJTL1. and contains everything the program needs.
5. Answer the questions in the window – usually Enter is enough. The suggestion in square brackets usually fits; then just press Enter. The program checks the connection right away. If it doesn't work, it explains why and asks again. It hands the checked details over to allverto encrypted – the next time it starts, it doesn't ask again.
   • JTL-Wawi API: The program looks for the REST server on this computer itself (ports 5883 to 5890) and suggests the address it found, e.g. “Found: http://localhost:5885/api/eazybusiness – press Enter to use it.” If it finds nothing, it asks for the address of the REST server. The port is the one you set for the REST server in the Wawi (e.g. 5883).
   • JTL database: The program asks for SQL Server [localhost], Instance [JTLWAWI] (enter a minus - if there is none), Database [eazybusiness], User [sa] and Password. You don't see the password while typing. This means the SQL Server password, not your password for JTL-Wawi.
6. Only with the source “JTL-Wawi API”: register the application in JTL-Wawi. The window tells you when it's time: The program then hands the API key to allverto itself, encrypted – you don't have to copy anything. If a key is already stored, this step is skipped.
   1. In JTL-Wawi, open Anwendungsregistrierungen (application registrations) → Anwendung registrieren (register application) and click on to Registrierung beginnen (start registration). It then says “Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet …” (waiting for a registration request from the application).
   2. Now press Enter in the jtl-bridge window. The program sends the request allverto – Umzug von JTL-Wawi. If the Wawi doesn't accept it yet, the program tries again every 5 seconds for 10 minutes.
   3. In the Wawi, click Weiter (next) on Anwendungsinformationen and Benutzer (pre-filled with the user you are logged in with), tick all three rows in the Erteilen (grant) column under Zugriffsverwaltung (all.read is already ticked; also salesinvoices.print and salesinvoicecorrections.print so allverto can take over the original PDFs of your invoices and invoice corrections) and click Einrichtung abschließen (complete setup).
7. Wait until “Done” appears – allverto then ticks off the step. The program first checks the connection, counts the data and then uploads it data type by data type. Depending on the amount of data, this takes a few minutes to hours. Keep the window open until then. Afterwards press Enter – the window closes.

In allverto, you continue with Data found and Mappings – see Migrating from JTL-Wawi: how it works.

#Where does the API key come from?

JTL-Wawi does not show an API key you could copy, and does not create one at the push of a button. It only issues a key to an application that is currently requesting it – while its wizard waits at “Registrierung beginnen”. If your REST server is reachable from the internet, allverto sends the request itself (Send registration from allverto). Otherwise jtl-bridge does it: it sends the request, receives the key after “Einrichtung abschließen” and hands it to allverto encrypted.

#The details in the wizard

Under Connection details you see what jtl-bridge has transferred: REST server address or SQL server, instance, database and user. The password is never shown. You only need to change something here in exceptional cases. There you also find the switch Add missing data from the database (optional) – see Setting up the REST API.

#Test connection

The wizard shows the last check result, e.g. “Last checked by jtl-bridge: connected ✓ (2 minutes ago)”, or the error with a hint on how to fix it. jtl-bridge reports at every start whether the connection worked.

With Test connection you check the connection from the wizard:

• If the address can only be reached on your server or in your company network (e.g. localhost, 127.0.0.1, 192.168.…, 10.… or a computer name like WAWI-SERVER), allverto cannot reach it. Then jtl-bridge does the test: start the file with a double-click and paste the setup code – the result appears in the wizard.
• If the address can be reached from the internet, allverto checks it itself: for the REST server, whether it responds; for the SQL Server, the login and the Wawi version. Only open such a port in your firewall for the addresses of the allverto servers.

#The setup code

• The code contains the address of your allverto and your personal import token. It is like a password: don't send it by email and don't copy it into tickets.
• allverto shows the code only right after it has been created. If you need it again later, create a new one with Create new setup code – the old one then stops working.
• A code is valid for 30 days, at most until the migration is completed. With Extend by 30 days you extend it from today.
• It is only valid as long as the person who created or last extended it is active and may “Carry out migration from JTL-Wawi”.

#Does your Wawi run on a server in your office?

Then you don't have to start the program on the server itself: any Windows PC in the same network works too. In the window, enter the server's name or IP address instead of localhost for the address or the SQL server (e.g. http://WAWI-SERVER:5883/api/eazybusiness). The server must allow access from this PC (Windows firewall); if in doubt, starting the program directly on the server is easier. If you enter the IP address of the computer the program is running on, it points this out: localhost is enough then.

#If something doesn't work

If an error occurs, the window tells you what happened and what you can do. The most common cases:

More cases: Troubleshooting the JTL migration.

#Other systems

The Wawi runs on Windows, which is why allverto always offers the Windows file first. Under Other systems, jtl-bridge is also available for Linux (make the file executable and start it in a terminal) and macOS (unzip the ZIP, double-click jtl-bridge.command; if macOS reports an unverified developer: click it while holding the ctrl key → Open). The process afterwards is the same.

#Security

• jtl-bridge transfers only via HTTPS. The data is additionally encrypted with a key derived from the import token.
• The program only reads – it changes nothing in your Wawi.
• Password and API key are never shown in the window. What you enter in the window, the program hands over to allverto encrypted. allverto stores the password and the API key encrypted and uses them only for this migration; the log only notes that they were stored.
• allverto only stores a fingerprint of the import token, never the token itself.
• After ten invalid codes from the same address, allverto blocks further attempts for a few minutes.
• After Complete changeover, the code is invalid and the cached JTL data is deleted. You can then remove the application “allverto – Umzug von JTL-Wawi” from the Wawi again under Anwendungsregistrierungen.

#For advanced users

jtl-bridge can also be controlled with commands in a Command Prompt or PowerShell, e.g. for tests or scheduled tasks. Instead of --code, --url <allverto-address> --token <import-token> also works.

In the Windows program, the command is named like the file, e.g. .\allverto-jtl-bridge-1.0.0-windows-x64.exe check --code ….

You can also set the password and API key only on the computer (environment variables JTL_DB_PASSWORD, JTL_API_KEY) – then they never leave it. The checksum (SHA-256) of each file is provided by the download list at /api/downloads/jtl-bridge.