Command Line Import

As an alternative to using the import screens, you can also invoke imports programmatically using the command line import utility.  This functionality allows you to invoke each import without accessing the Unanet system application via the user interface.  This may be useful if you would like to create your own process external to Unanet that could extract data from an upstream system and programmatically load it into Unanet (without manual intervention) -- e.g. a nightly load.

Topics covered on this help page include:

• Introduction    (overview of the Command Line Import functionality)

• Requirements    (prerequisite system requirements)

• Syntax and Options    (which imports can this utility be used with -- and what options are available)

• Syntax Example    (sample of what the execution line may look like)

• Reading the Output    (capturing warnings and error messages)

• Running from Another Machine  

• Using SSL    (working around the  No trusted certificate found  exception)

• Using with Single Sign-On

• Automated Import Example

You may also be interested in:

• Integration Management Utility (IMU)    (overview of a stand-alone utility that helps manage inbound imports to Unanet)

Introduction

The command-line import program is designed to allow you to execute any of the imports using a command-line interface. This program may be run either from the server running Unanet, of from a different computer that has standard TCP/IP access to the port (usually 80) on the Unanet server that is used to access Unanet.  Basically, if you can access Unanet using a browser from a particular machine, then you can use the command-line import program from that machine.

The command-line import program is located in the unanet/utilities directory, and is named Import.jar. To run the program, simply make the directory containing the Import.jar file your current directory and type:

  java -jar Import.jar

This will simply give you a help message, since it doesn't include all the required elements.

Requirements

You must have Java 1.8 or higher installed on the server invoking the command-line import program.

Syntax and Options

Available "Options"

Currently, several Unanet import types support options:

Note: allowClosedFP refers to the option to allow changes to documents  in closed Fiscal Periods.

Syntax Example

A sample session (using a one line person import file) might look like this:

C:\unanet\utilities> java -jar Import.jar --url http://yourco.com:8080/unanet --username admin --password admin --import person --option update_passwords=true --option outputOption=warnings --file person.csv

Person Import starting...

'JSMITH' was updated successfully.  Line1

Total People processed: 1

Total People added: 0

Total People updated: 1

Total People rejected: 0

**Assumes all files are in the same directory.

Reading The Output

The command-line import utility produces exactly the same output as the standard, interactive Unanet import screens. It simply dumps the output to standard error and  standard output.  If you are using the command-line import utility in an unattended situation, you will probably want to capture this output and interrogate the results checking for any issues.  

How you capture these results will depend on your operating system syntax, but one possible example is:

C:\unanet\utilities> java -jar Import.jar --url http://yourco.com:8080/unanet --username admin --password admin --import person --option update_passwords=true --option outputOption=warnings --file person.csv > c:\yourdirectory\import_output.txt 2>&1

You will likely have some sort of shell script or batch file that runs your unattended import.  Within this script you may want to email the resulting output to someone for manual review, or possibly create a process that will parse the output searching for an error condition --- and upon receiving such a condition, you may wish to notify someone via email or some other means.  The creation and maintenance of these types of processes are external to Unanet and are the responsibility of your IT staff.

The command-line import utility will return 0 if it runs successfully, and non-zero if it failed for a detectable reason. Failures will also output a reason for the failure on standard error output. Following are some possible error codes:

RETURN CODE

0 - if all processing finished normal.

1 - The reasons for this return code could be one of the following:

• the command line syntax is incorrect

• the URL of the environment is not provided in command line args

• the username, password, or type of import is not provided in the args

• the import process is not able to read the import definition based on the type

• the file size is too large for the import to process - try splitting the file into smaller files

2 - processing of the file failed - if you need assistance, please contact Unanet support (support@unanet.com) with the details of the file/import template being processed and any log messages in order to troubleshoot the issue

See Automated Import Example below for additional information.

Running The Command Line Import from Another Machine

You must have a copy of the Import.jar file on the machine from which you will run the command-line import program (or have access to that file from your machine).  This file is delivered with the Unanet software and resides in the "unanet/utilities" directory and is also available for download from the Support area on our website.

Also, you must have Java 1.8 or higher installed on the machine. You can obtain Java from Oracle following the links for "Java SE Downloads" (note: download the JDK latest update -- not the JRE).

Note: You must use the copy of the Import.jar file packaged with each release.  When migrating from one major release to the next major release, you'll need to make sure you copy the new Import.jar file to your remote machine.

Memory Issues  

If you encounter a java "OutofMemoryError", you should check your memory setting on the server running Unanet (see Performance Tuning for more information), but you may also need to increase the memory on the machine running the command line import.  To do this, you can include a memory setting directly within the command line you are running by including the following syntax "java –Xms128m –Xmx512m" in front of the rest of the command line parameters.  Thus your complete command line syntax may resemble:

C:\unanet\utilities> java –Xms128m –Xmx512m -jar Import.jar --url http://yourco.com:8080/unanet --username admin --password admin --import person --option update_passwords=true --option outputOption=warnings --file person.csv > c:\yourdirectory\import_output.txt 2>&1

Using SSL

If using SSL and attempting to run the command line import, you should ensure you are using Java 1.8 on the machine running the export.  

Using a Self-Signed SSL Certificate

If you are using a self-signed SSL certificate on your web server instead of one from a recognized certificate issuing authority, and you are trying to use SSL for the command-line import, then you will probably get the No trusted certificate found exception. In this case you will need to do a little additional configuration.

SSL provides two services:

1. Data encryption, and

2. Server identity verification.

The second service is the problem here. When you make an SSL connection, the server sends its certificate to the client. The certificate contains such information as:

• The server name,

• The organization name,

• The dates for which the certificate is valid,

• Etc.

To ensure that the certificate isn't lying about this information, it is signed by some "recognized" certificate authority, such as Verisign, Thawt, etc. The theory is that you trust Verisign, and Verisign claims that they've validated the information on the certificate, so you can trust the information.

In the case of a self-signed certificate, the certificate is not signed by a recognized certificate authority. This means that the information cannot be trusted. To get around that problem you have to import the server's certificate into your client JVM's keystore. Here's basically what you need to do:

Use Internet Explorer to go to your Unanet installation. You should get a security alert pop-up window warning you that there is a problem with the certificate on this site. (If you don't get this alert, then it's because you already told your browser to accept this certificate permanently. Go to a machine that hasn't and try it.) Click on the "View Certificate" button. Then select the "Details" tab and click on the "Copy to File..." button. This should start the certificate export wizard. Click next, then select the "DER encoded binary X.509 (.CER)" format. Click next again, and now enter any name for the certificate, like "c:\unanet.cer". Click next again and finish.

Now you should have a certificate file, unanet.cer, that you can import into your JVM's keystore file. Copy that file to the machine where you're trying to run the Unanet import. (If you're using FTP, remember to use binary mode.) Now the main thing is to find the keystore file for your JVM. If you are using Sun's JVM, then it is located in the Java home directory at %JAVA_HOME%/lib/security/cacerts. If you're not using Sun's JVM, then you'll have to look for it either in the file system or in the documentation. Once you find it then run this command:

If the JAVA_HOME environment variable is not set correctly, then replace %JAVA_HOME% with the correct home directory of your Java installation. You should be prompted for a password to alter the cacerts file. If it has not been changed, then you should be able to use the default password of changeit. That should do it.

Using Command Line Import with Single Sign-On

When configuring authentication / single sign-on options, you need to include the native Unanet Authentication option in your configuration file.  The command line import requires a "Unanet" username and password to operate (i.e., it will not function with an external authentication option).

Automated Import Example

If you are attempting to automate the process of importing data into Unanet, you may need to create a process external to Unanet that accomplishes the following (this is just an example):

• Create a script that can be scheduled to run at your desired interval.  Some customers do this once per time period, once per week, nightly or even hourly.  This may be a shell script, bat file or another type of script depending on your operating environment.  

• You may have several steps that initiate a pull of data from your external system (formatting the data in the Unanet import layout formats).  

• You may need to have a step that copies these files to specified directories for the purpose of processing or archiving.  

• You may need a step to call our ImportDiff utility program (to help you filter out only changes -- depending on your pull program).

• You will need to have a step to invoke the command line import(s).

• You may want a step to read the resulting output file (searching for ERROR), and perhaps send an email to someone to indicate any problems found.

Unanet has a stand-alone utility that can assist with the management of the inbound imports.  Check out the Integration Management Utility (IMU) for additional information.