The NetX I/O application comes in two different forms:
- Desktop app (Mac OS and Windows)
- CLI tool (Linux, Mac OS, Windows)
The CLI (command-line interface) tool runs "headless" (no user interface) and allows you to programmatically drive NetX I/O. It can be wrapped in shell scripts and scheduled via cron (or other task managers) and allows you to set up various sync points on a workgroup file server. The CLI tool is packaged as a JAR file and executed with Java.
This article outlines the steps needed to start running the NetX I/O command-line tool, with Watched Folder mode as an example.
System requirements
- NetX I/O 4.2 or later requires a NetX version of 11.8.x or later.
- If you are using I/O with multiple NetX server instances, you must have sticky sessions configured on the network load balancer serving those instances so that each user is routed directly to a single node.
Installation
Windows users: NetX I/O requires the Microsoft Visual C++ Redistributable to be installed before it can run. For instructions on how to obtain this package, see https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads.
Step 1: Make sure JDK is installed locally
Check your Java version by typing java-version in the command line:
$ java -version openjdk version "17.0.12" 2024-07-16 OpenJDK Runtime Environment Homebrew (build 22.0.2) OpenJDK 64-Bit Server VM Homebrew (build 22.0.2, mixed mode, sharing)
If the version printed is anything other than 17.x, you will need to download a supported version of the JDK.
Step 2: Download the NetX I/O jar file
You can download the netxio.jar file from our Service Portal, found in the I/O section of the Product Downloads page.
Step 3: Create a local app storage folder on your computer
Create a folder on your workstation for NetX I/O to write application files, including logs, clientId data file, and lostandfound folder. Example:
Mac OS
/Users/me/NetxIO
Windows
C:\Users\me\NetxIO
Step 4: Move the .jar file to your app folder
Copy the netxio.jar file into your app folder created in step 3. Example:
Mac OS
/Users/me/NetxIO/netxio-4.4.6.jar
Windows
C:\Users\me\NetxIO\netxio-4.4.6.jar
Step 5: Choose the source folder on your computer
The storage location you created in Step 3 is for managing NetX I/O's application files. Now you need to choose (or create) a folder that will be the root of all the sub-folders and files you want to upload to NetX. This folder can live anywhere on your local filesystem, but do NOT nest the source folder inside of your application folder. Also, do NOT use the same folder as your application folder, and do NOT place your application folder inside the source folder. Example:
Mac OS
/Users/me/Desktop/SourceFiles
Windows
C:\Users\me\Desktop\SourceFiles
Step 6: Create an I/O user in NetX
NetX I/O logs into NetX using supplied credentials for a pre-existing user, and actions will be performed on behalf of that user. It's best to create a separate account for your NetX I/O user. If you were to log in to NetX and then log out as the same user logged in via NetX I/O, it disrupts the processes in I/O. For Watched Folder mode, a Producer-level user (or higher) is required. If you're running NetX I/O in Sync mode, you must configure it to run with an Administrator-level user. You will need to know the username and password for the NetX I/O user.
Step 7: Choose your target folder in NetX
This is the folder in NetX to which sub-folders and files from your local source folder will be written. Make sure that the user account you are running NetX I/O with has appropriate permissions to write to this target folder.
Example:
/Projects/Campaigns/2022
Step 8: Parameters for the command line
| Parameter | Details |
|---|---|
| -Xms |
This parameter sets the minimum memory for NetX IO. 512MB of RAM is usually sufficient. This parameter MUST come before com.netxposure.external.client.io.NetxIO. Example: 512M |
| -Xmx |
This parameter sets the maximum memory for NetX IO. 2048MB of RAM is usually sufficient. This parameter MUST come before com.netxposure.external.client.io.NetxIO. Example: 2048M |
| -cp |
This parameter sets the Java classpath and must point to the NetX library directory. This parameter MUST come before com.netxposure.external.client.io.NetxIO. Example: /Users/me/NetxIO/netxio-4.4.6.jar |
| -url |
Required. This is the URL of your NetX server instance. Example: https://acme.netx.net Note: if you are using an https address, see -useInsecureSSL below. |
| -username | Required. This is the username of your NetX user. For Watched Folder mode, this must be a Producer-level user (or higher). For Sync mode, this must be an Administrator-level user. |
| -password | Required. This is the password of your NetX user. |
| -netxSourceFolder |
Required. This is the folder (or "category") in NetX which files and folders will sync. If you enter a number, NetX I/O treats it as the category ID. Example: /Projects/Campaigns/2022 |
| -localSourceDir |
Required. This is the local directory where folders and files are synced with the NetX server. Example: /Users/me/Desktop/SourceFiles |
| -mode |
Required. This sets NetX I/O into the operational mode of your choice. *Merge and Sync modes are experimental and are not supported for use in mission-critical environments. Use at your own risk. Value options: import export merge sync watchedFolder analyze In analyze mode, NetX I/O emails an import report to the NetX I/O user. It makes no changes to files or folders. |
| -localStorageDir |
Local storage for NetX I/O program files, including logs, clientId data file, and lostandfound folder. Required for sync and merge modes. Please see the storage capacity note below. Example: /Users/me/NetxIO |
| -loop |
This sets NetX I/O to run the sync process repeatedly, waiting the number of minutes you enter between runs. The default is 0, which runs the process once. Example: 15 |
| -useInsecureSSL | Optional. No value is required. If you are connecting with HTTPS and can't register your SSL certificate with NetX IO, this will disable any certificate verification. |
| -blind |
Optional. For watchedFolder, import, and export modes, specifying 'blind' means the analysis step will be skipped. When enabled, imports are much faster if you're not concerned with avoiding duplicates. This option also allows for versioning of files on the NetX server (watchedFolder and import modes only). |
| -replacementCharacter |
Optional. If illegal characters are encountered in either files or folders, then use this replacement character (single). Values: |
| -deleteLimit |
Optional. In sync mode, NetX will halt if an attempt to delete more files than the limit allows, per a single sync cycle. Default: 100 Setting this to zero ('0') disables |
| -debug | No value is required. Logs debug messages. |
| -nonvolatile | No value is required. By default, NetX I/O scans the source folder, waits 20 seconds, and scans again to make sure files are no longer being copied. This option turns off that check, so the sync starts immediately. |
| -noHeartbeat | No value is required. When NetX I/O runs in a loop, it sets up a heartbeat with the NetX server and sends an email if the heartbeat stops. This option turns the heartbeat off. |
| -report |
Sets how often NetX I/O emails a report. Values: Default: weekly |
| -useChecksums | No value is required. During file uploads, NetX I/O calculates file checksums at both locations to confirm the files transferred intact. |
| -timeout |
The number of minutes NetX I/O waits for a response from the NetX server before a web service call times out. Only change this if you know what you are doing. The value must be a whole number greater than 0; any other value is ignored and the default is used. Default: 3 minutes. The NetX I/O desktop app defaults to 30 minutes. Example: 15 |
| -clientId | NetX I/O creates a Client ID automatically. Use this to set the Client ID yourself. |
| -databaseMap | No value is required. By default, NetX I/O keeps its working map in memory, which is faster but can use more memory. This option stores the map in a database instead. |
| -mapChunkSize |
The number of files (and, separately, folders) NetX I/O sends to the NetX server at a time when it sends its list of local files and folders for analysis. This analysis step is skipped when -blind is used. Default: 1000 |
Start NetX I/O CLI
Step 1: Using the command line
Type the following using the parameters defined above. Example:
Mac OS
java -Xms512M -Xmx2048M -cp "/Users/me/NetxIO/netxio-4.4.6.jar" com.netxposure.external.client.io.NetxIO -url https://acme.netx.net -username netxio_user -password 123456789 -netxSourceFolder "/Projects/Campaigns/2022" -localSourceDir "/Users/me/Desktop/SourceFiles" -mode watchedFolder -replacementCharacter _ -localStorageDir "/Users/me/NetxIO_workfiles" -useInsecureSSL -loop 15
Windows
java -Xms512M -Xmx2048M -cp "C:\Users\me\NetxIO\netxio-4.4.6.jar" com.netxposure.external.client.io.NetxIO -url https://acme.netx.net -username netxio_user -password 123456789 -netxSourceFolder "/Projects/Campaigns/2022" -localSourceDir "C:\Users\me\Desktop\SourceFiles" -mode watchedFolder -replacementCharacter _ -localStorageDir "C:\Users\me\NetxIO" -useInsecureSSL -loop 15
Notes:
- Ensure the -cp directive is placed before the class com.netxposure.external.client.io.NetxIO or it will be interpreted as a parameter to the class, instead of interpreted by Java.
- NetX I/O could potentially use a large amount of RAM, especially in sync mode. In the above example, the Java heap is set to start with 512MB (-Xms512M) and can utilize up to 2048MB (-Xmx2048M), but you should adjust this per your setup.
- Be aware of the capacity of the underlying storage when configuring the localStorageDir setting. If imports encounter significant errors, failed import files will be copied to the "lost and found" directory under this path. If that storage facility runs out of space, critical errors will occur.
- If you start NetX I/O using the command line, you may want to background the process, because closing the command window will quit NetX I/O. Additionally, you can add the NetX I/O commands to your workstation startup items.
-
If the user account running NetX I/O does not have appropriate access permissions to the NetX folders it is trying to sync, this error will be present in the logs:
[NetX I/O] ERROR (com.netxposure.external.client.rpc.ApiException: JSON-RPC Error 4003: Object not found (invalid category_id (18)) (null))
Step 2: Start moving folders and files
Drop folders or files into your local watched folder. Wait for the loop time, and then see the folders and files replicated on the other side. Rinse and repeat!
Step 3: Use a config file instead of command-line arguments
You can also set all your NetX I/O options within a configuration file. In this scenario, you only set the configuration file (the "-config" option) in the command line:
java -Xms512M -Xmx2048M -cp "/Users/me/NetxIO/netxio-4.4.6.jar" com.netxposure.external.client.io.NetxIO -config "/Users/me/NetxIO/netxio.properties"
Here's what an example configuration file might look like:
url=https://acme.netx.net username=netxio_user password=123456789 netxSourceFolder=/Projects/Campaigns/2022 localSourceDir=/Users/me/Desktop/SourceFiles localStorageDir=/Users/me/NetxIO mode=watchedFolder blind=true replacementCharacter=_
Option names are separated from their corresponding values with an equals sign (=). Do not wrap config values with quotes (like you might do on the command line). To turn on a command-line parameter that requires no argument, like blind in the example above, add its name to the file with a value of true. To leave it off, leave it out of the file. NetX I/O ignores any option name it does not recognize and writes a warning to the log.
Built-in help
You can obtain details on all the NetX I/O configurations and advanced troubleshooting tools by running the CLI tool with the -help flag.
java -cp /Users/me/NetxIO/netxio-4.4.6.jar com.netxposure.external.client.io.NetxIO -help
Merge and Sync modes are experimental and are not supported for use in mission-critical environments. Use at your own risk.
Running multiple NetX I/O processes on a single workstation
If you want to run multiple instances of NetX I/O on a single workstation, you need to ensure that each instance uses its own local app storage and sync folders. Do not attempt to run multiple instances of NetX I/O CLI with a shared local app storage directory!