Systems integration using command line - ODL Connect

Introduction

ODL Connect is a tool which lets you call ODL Studio functionality from the command line. It is designed to let you embed ODL Studio into larger systems, so you can run route optimisation or other tasks in the background either on-demand or at regular intervals (using Windows Task Scheduler or the Linux Cron command). Your external system calls ODL Connect when it needs to perform an ODL Studio task. ODL Connect is 100% compatible with existing ODL Studio functionality so you can - for example - run route optimisation in the background and then load the generated vehicle routes into ODL Studio later-on if you need to perform further analysis.

ODL Connect is a closed-source software module; the income from its sales helps fund the development of our open source software. For pricing see our current pricelist and contact us if you’re interested in purchasing.

Installing ODL Connect
Calling the command line
- Using a batch file
Automating route optimisation
- Calling the example files
- What the example files do
Commands index

Installing ODL Connect

There are several steps to install and configure ODL Connect which require the user to be familiar with basic system administration and command line usage.

ODL Connect is shipped with the following zip files:

Installer or a zip file containing the reference version of ODL Studio.
- In ODL Connect version 1.0.1, this is a pre-release version of ODL Studio, with some additions to support ODL Connect.
Zip file containing ODL Connect itself.
(ODL Connect 1.0.1 only). Postcode geocoding files, as their file format has changed in the pre-release ODL Studio.

ODL Connect sits on top of the ODL Studio installation. The reference version of ODL Studio is the recommended version to run ODL Connect against, although in most cases your version of ODL Connect should also work with versions of ODL Studio newer than the reference version. Never use ODL Connect with a version of ODL Studio older than the reference version. To install:

Install the supplied version of ODL Studio - either by extracting the zip file or using the Windows installer if available. If using the zip on Windows, extract it to a directory in Program Files. If using the zip on Linux, extract the zip to a directory of your choice ensuring the full directory path contains no spaces.
Copy all files from the ODL Connect zip directory into your ODL Studio installation directory. Crucially file com.opendoorlogistics.connect.jar must be in the same directory as com.opendoorlogistics.studio.jar.
Ensure you have a valid Java runtime installed - ODL Connect requires Java 8 or higher. If you're using Windows, ODL Studio will come with a suitable Java runtime, however for Linux you will need to download and install a Java runtime, if not already available.

Calling the command line

Always set the working directory to your installation directory before running the command line as ODL Studio loads its configuration, data and plugins from the respective subdirectories of the working directory. If you start ODL Connect or ODL Studio and the vehicle routing component is unavailable, it is highly likely you have the wrong working directory set.

If you’re using 64-bit Windows and the Java runtime supplied with ODL Studio, the following line will run ODL Connect and print out its help document:

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -help

To run the same on Linux using a pre-installed Java runtime, run

java -cp "com.opendoorlogistics.connect.jar:com.opendoorlogistics.studio.jar" com.opendoorlogistics.connect.CommandLine -help

This command line adds both ODL Connect and ODL Studio to the java classpath and then runs the main method in com.opendoorlogistics.connect.CommandLine. One or more commands, prefixed by -, can then be placed after com.opendoorlogistics.connect.CommandLine. To call other commands, simple replace -help with one or more of your own commands, as listed in the commands index. For example,

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -itab "stops.txt" -ex "Stops.xlsx"

will import a tab-separated file called “stops.txt” into the table Stops and then export it back out again to an Excel file.

ODL Connect uses a temporary in-memory datastore, which is a set of data tables which only exist whilst ODL Connect is running. You import data into the tables, run operations on the tables (e.g. create routes) and then export the data back out, typically to text files or Excels. Normally the operations would be contained within ODL scripts - for example the optimise operation if you use a vehicle routing script. You should configure and test these scripts within the ODL Studio user interface and then use ODL Connect to automate running them.

If you a performing a memory-intensive task - for example using a Graphhopper road network file which covers all North America (see here) - you will need to increase the max memory Java is allotted. This is done using the Java -Xmx command. You should place this command directly after the call to java.exe, so:

jre8_64-bit\bin\java.exe -Xmx4G -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine ...

tells Java it can use 4 GB RAM when running ODL Connect.

Using a batch file

Having a large number of commands called from a single command line can be cumbersome; ODL Connect therefore allows you to collect these commands into a single batch file. The command -rb tells ODL Connect to run a batch file.

Batch file format is straightforward and near-identical to the format of the command line, except:

Each command is on a separate line
Commands should not start with -
Single line comments are allowed, starting with #
Empty lines are allowed

The command,

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -itab "stops.txt" -ex "Stops.xlsx"

can therefore be replaced by a batch file called mybatchfile.odlbat containing the following text:

itab "stops.txt"

ex "Stops.xlsx"

where this command calls the batch file:

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -rb "mybatchfile.odlbat"

Automating route optimisation

Before setting up the command-line, you should configure route optimisation for your own data within the ODL Studio user-interface (see the tutorial video). With ODL Connect you basically call the same processing steps you would call manually from the UI, but automated from the command line; familiarity with how the UI is configured (particularly the scripts) is therefore strongly advised.

The basic steps involved in setting up automated command-line route optimisation are:

Setup the jsprit script in ODL Studio as per the tutorial video.
- By default a new jsprit script will only perform a small number of optimisation iterations; for a real-world system you should try increasing the number of iterations in the settings, to improve route quality.
Create input files (csv, tab-separated or Excel). The input files should have exactly the same columns available as when you run jsprit through the ODL Studio user interface. The following files are required:
1. Available vehicles - this file may be the same for each day if your vehicle fleet is fixed.
2. Stops to be routed - this file will change every day.
3. Empty Stop-Order table - the jsprit integration needs an empty imported Stop-Order table to save its results to.
Call ODL Connect from your external system and use it to:
1. Import these files via the command line.
2. Run route optimisation.
3. Export the stop-details (containing the routes) to a table in the in-memory spreadsheet (which exists only when ODL Connect runs).
4. Export the stop-details from the in-memory datastore to an output file on your system - e.g. tab, csv or Excel.
5. For logging purposes only, export the entire in-memory datastore to an Excel file, in case you need to inspect the vehicle routes in ODL Studio afterwards.
Within your external system:
1. Import the stop-details file containing the routes.
2. Check for any unassigned stops not included in the stop-details (stops can be unassigned for a variety of reasons).

Calling the example files

The ODL Connect distribution includes example files which (a) call vehicle route optimisation for fake data based in Malta and (b) export the routes to a text file, together with predicted arrival times and other useful statistics. For 64-bit Windows users, if you open a command prompt and change the directory to the install directory, the following command line will run the Malta data. Note you should create a directory c:\temp on your computer before running this command, ensuring ODL Connect has write privileges to it.

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -inputdir "Examples\VRP" -ix "Malta-input-vehicles-and-empty-stop-order-table.xlsx" -itab "stops.txt" -r "jsprit malta.odlx" "Optimise" -r "jsprit malta.odlx" "Export stop-details" -etab "Exported-Stop-Details" "Examples\VRP\output-stop-details.txt" -ex "c:\temp\VRPLog%TIMESTAMP%.xlsx"

For Linux users, again navigate to the install directory and run this instead:

java -cp "com.opendoorlogistics.connect.jar:com.opendoorlogistics.studio.jar" com.opendoorlogistics.connect.CommandLine -inputdir "Examples/VRP" -ix "Malta-input-vehicles-and-empty-stop-order-table.xlsx" -itab "stops.txt" -r "jsprit malta.odlx" "Optimise" -r "jsprit malta.odlx" "Export stop-details" -etab "Exported-Stop-Details" "Examples/VRP/output-stop-details.txt" -ex "VRPLog%TIMESTAMP%.xlsx"

Alternatively you can run this using a batch file containing these commands. Under Windows run:

jre8_64-bit\bin\java.exe -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -rb "Examples\VRP\batchfile-windows.odlbat"

…and under Linux:

java -cp com.opendoorlogistics.connect.jar;com.opendoorlogistics.studio.jar com.opendoorlogistics.connect.CommandLine -rb "Examples/VRP/batchfile-linux.odlbat"

An output Excel will be saved containing all processed tables and a stop-details file will be written to the Examples directory.

What the example files do

We breakdown these processing steps and examine each one in-turn:

jre8_64-bit\bin\java.exe -cp ....... com.opendoorlogistics.connect.CommandLine. This is just our standard launcher command for ODL Connect.
-inputdir "Examples\VRP". This tells ODL Connect all input files should be loaded from this directory. Alternatively we could have used full path names for all input files.
-ix "Malta-input-vehicles-and-empty-stop-order-table.xlsx". This loads an Excel containing the vehicles and an empty Stop-Order table.
-itab "stops.txt". This loads a tab-separated file containing the stops. The file must be called stops as the imported in-memory table is named after the filename (and the stops table is expected).
-r "jsprit malta.odlx" "Optimise". This runs the optimise option in the example script "jsprit malta.odlx" (within the input directory) to create the routes.
-r "jsprit malta.odlx" "Export stop-details". This runs the "Export stop-details" option in the "jsprit malta.odlx" script, which exports the stop-details (i.e. routes) to the in-memory datastore only. The in-memory datastore is operated on by ODL Connect and only exists whilst Connect is running.
-etab "Exported-Stop-Details" "Examples\VRP\output-stop-details.txt". This exports the "Exported-Stop-Details" table from the in-memory datastore to a file on the hard drive, to be read later by your own external system.
-ex "c:\\temp\VRPLog%TIMESTAMP%.xlsx". This exports the entire in-memory datastore to a file on your computer, replacing %TIMESTAMP% with a timestamp based on date and time down to milliseconds accuracy - e.g. VRPLog2015-07-27-T10-04-25-266.xlsx. You can use this to construct an archive of all route optimisation runs, should you need to manually inspect the results in ODL Studio later-on.

Commands index

The following commands are available in ODL Connect:

echo: Print the text to the standard output. Usage -echo "text to print".
ecsv: Export table to text file (comma-separated). If the filename contains %TIMESTAMP% this will be replaced by a filename-friendly timestamp in the form 2015-07-22-T10-39-08-287. Usage -ecsv "tablename" "filename"
etab: Export table to text file (tab-separated). If the filename contains %TIMESTAMP% this will be replaced by a filename-friendly timestamp in the form 2015-07-22-T10-39-08-287. Usage -etab "tablename" "filename"
ex: Export tables to Excel. To export all, do not specify table names. If the filename contains %TIMESTAMP% this will be replaced by a filename-friendly timestamp in the form 2015-07-22-T10-39-08-287. Usage -ex filename [tablename1] [tablename2] [tablename3]...
exportdir: Set the default data export directory. Usage -exportdir "directoryname"
h: List all commands
haltifempty: Halt processing if the table is empty. Usage -haltIfEmpty "tablename".
help: List all commands
icsv: Import text file in csv format. Usage -icsv filename1 [filename2] [filename3]...
importdir: Set the default data import directory. Usage -importdir "directoryname"
inputdir: Set the default input directory (scripts and import data). Usage -inputdir "directoryname"
isc: Import shapefile with geometry copied into spreadsheet. Usage -isc filename1 [filename2] [filename3]...
isl: Import shapefile with linked geometry. Usage -isl filename1 [filename2] [filename3]...
itab: Import text file in tab-separated format. Usage -itab filename1 [filename2] [filename3]...
ix: Import excel file. Usage -ix filename1 [filename2] [filename3]...
log2file: Start logging to the file. Usage -log2file filename
p: Add parameter to parameters table. Usage -p key value
print: Print one or more tables to standard output. Omit tables names to print all. Usage -print [tablename1] [tablename2] [tablename3]...
r: Run script. Usage -r scriptfilename [optionid1] [optionid3] [optionid3]...
rb: Run a batch file of commands. Usage -rb "batchfilename".
scriptdir: Set the default scripts directory. Usage -scriptdir "directoryname"
studio: Launch ODL Studio user interface. This can only be executed once. Importing or running scripts after launching the UI is considered unsafe and not officially supported. Usage -studio.