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 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/NetxIOWindows
C:\Users\me\NetxIOStep 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.2.0.jarWindows
C:\Users\me\NetxIO\netxio-4.2.0.jarStep 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. Example:
Mac OS
/Users/me/Desktop/SourceFilesWindows
C:\Users\me\Desktop\SourceFilesStep 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 Manager-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/2022Step 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.1.0.jar |
|
-url |
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 |
This is the username of your NetX user. |
|
-password |
This is the password of your NetX user. |
|
-netxSourceFolder |
This is the folder (or "category") in NetX which files and folders will sync. Example: /Projects/Campaigns/2022 |
|
-localSourceDir |
This is the local directory where folders and files are synced with the NetX server. Example: /Users/me/Desktop/SourceFiles |
|
-mode |
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 |
|
-localStorageDir |
Local storage for NetX I/O program files, including logs, clientId data file, and lostandfound folder. Please see the storage capacity note below. Example: /Users/me/NetxIO |
|
-loop |
This sets NetX I/O to run the sync process every 15 minutes. 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 |
|
-replacementCharacter |
Optional. If illegal characters are encountered in either files or folders, then use this replacement character (single). Values: |
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.2.0.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 15Windows
java -Xms512M -Xmx2048M -cp "C:\Users\me\NetxIO\netxio-4.2.0.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 15Notes:
- 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 in accordance with 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.2.0.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). Command-line parameters that require no arguments — like blind in the example above — can be set with a value of true.
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.2.0.jar com.netxposure.external.client.io.NetxIO -helpMerge 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!