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:

 

You may also be interested in:

 


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.6 or higher installed on the server invoking the command-line import program.


Syntax and Options

Usage:

java -jar Import.jar --help
java -jar Import.jar --url url --username username --password password --import type [--option var=value] [--file file]

 

 

--url url

The base URL for the Unanet application. For example: http://www.yourdomain.com/unanet  This option is required.

--username username

 A Unanet administrator login username.  This option is required.

--password password

The password for the login username used.  This option is required.

--version

When using this option, the import will return a version number of the import.jar file.  This is used internally for compatibility checking only.

--import type

 

The type of import.  This option is required.

Available types include:

account
alternate
approval_group
assignment
credit_card        (for the KR-1025 import --- see generic_credit_card for the other credit card import)
customer_payment
customer_org   (for customer profile import)
employee_type
employee_type_expense_type
employee_type_pay_code
expense
expense_budget
expense_plan
expense_type
fixed_price
generic_credit_card
general_ledger_journal_entry
journal_entry    
labor_category   (for the master labor category import)
labor_category_assignment  (for the project labor category import)
location
mie_breakdown
organization
organization_access
organization_address
organization_contact
person
person_accruals
person_credit_card_number
person_skills
per_diem_rates
planned_work
project
project_administrator
project_invoice_setup
project_expense_type
project_fee
project_location
skill_level
skill_type
skills
task
time
vendor_invoice
vendor_org   (for vendor profile import)
vendor_payment

--option var=value

An additional option that should be sent to the server when performing the import. May be used multiple times (separated by white space). Each option must include an equal sign. The left of the equal sign is the name of the option, the right side is the value. This will have no effect unless the Unanet import type understands the option.  

For example:

--option update_passwords=true  

Example passing multiple options:

--option update_passwords=true --option outputOption=warnings

 

--file file

The file to import. This file must follow the appropriate format for the import type being performed. If no file option is used, then the program reads the standard input.

 

Available "Options"

Currently, several Unanet import types support options:

Import Type

Option

Syntax

Description

All import types

outputOption

--option outputOption=warnings

Valid values include: all, warnings, errors (case insensitive).  errors is the default if no value is provided.

assignment

notifyUser
notifyPM
notifyPL
notifyAssigner
notifyPlanner
additionalEmail
allowLinkDates

--option notifyUser=true
--option notifyPM=true
--option notifyPL=true
--option notifyAssigner=true
--option notifyPlanner=true
--option additionalEmail=you@abc.com,me@abc.com
--option allowLinkDates=true

Valid values for notifyUser, notifyPM, notifyPL, notifyAssigner and notifyPlanner options are true and false.  false is used by default if no value was provided for either.

The additionalEmail option will accept a series of comma separated email addresses.

Valid values for the allowLinkDates option are true and false.  false is used by default if no value was provided.

credit_card

paymentMethod

--option paymentMethod=3

The value passed in will be the Payment Method key.  

Pre-10.0 there were only 3 values (where 1 is Employee, 2 is Corp. Card and 3 is Company Paid).  Beginning with 10.0 we support more than 3 payment methods (you'll need to lookup the key to use).  

Valid values include active Payment Methods valid for P&R entry.

If no value is supplied the system will default the payment method to the first payment method found in the database.

customer_payment

purgeFirst
status
allowClosedFP

--option purgeFirst=true
--option status=SUBMITTED
--option allowClosedFPt=true

Valid values for purgeFirst and allowClosedFP options are true and false.  false is used by default if no value was provided.

Valid values for status are  INUSE and SUBMITTED

expense

method
expense_status

--option method=person
--option expense_status=locked

Valid values for method are person, project and item.  

person is used by default if no value was provided.  

Valid values for status are  INUSE, SUBMITTED, COMPLETED, LOCKED and EXTRACTED.  

INUSE is used by default if no value was provided.

expense_budget

notifyPM
notifyPL
additionalEmail
allowLinkDates

--option notifyPM=true
--option notifyPL=true
--option additionalEmail=you@abc.com,me@abc.com
--option allowLinkDates=true

Valid values for the notifyPM and notifyPL option is true and false.  false is used by default if no value was provided.

The additionalEmail option will accept a series of comma separated email addresses.

Valid values for the allowLinkDates option are true and false.  false is used by default if no value was provided.

expense_plan

allowLinkDates

--option allowLinkDates=true

Valid values for this option is true and false.  false is used by default if no value was provided..

generic_credit_card

payment_method

--option payment_method=3

 

The value passed in will be the Payment Method key.  

Pre-10.0 there were only 3 values (where 1 is Employee, 2 is Corp. Card and 3 is Company Paid).  Beginning with 10.0 we support more than 3 payment methods (you'll need to lookup the key to use). 

Valid values include active Payment Methods valid for P&R entry.

If no value is supplied the system will default the payment method to the first payment method found in the database.

general_ledger_journal_entry

purgeFirst
status
allowClosedFP

--option purgeFirst=true
--option status=SUBMITTED
--option allowClosedFPt=true

Valid values for purgeFirst and allowClosedFP options are true and false.  false is used by default if no value was provided.

Valid values for status are  INUSE and SUBMITTED

per_diem_rates

purgeFirst

--option purgeFirst=true

Valid values for the purgeFirst option are true and false.  false is used by default if no value was provided.

person

update_passwords
adjust_extracted

--option update_passwords=true
--option adjust_extracted=true

Valid values for these options are true and false.  false is used by default if no value was provided.

planned_work

allowLinkDates

--option allowLinkDates=true

Valid values for this option is true and false.  false is used by default if no value was provided.

project

update_assignment_level
update_billing_type  

--option update_assignment_level=true
--option update_billing_type=true

Valid values for these options are true and false.  false is used by default if no value was provided.

task

remove_predecessors
update_billing_type  

--option remove_predecessors=true
--option update_billing_type=true

Valid values for these options are true and false.  false is used by default if no value was provided.

time

updateMethod
status
purgeFirst
allowAdjustments

--option updateMethod=append
--option status=locked
--option purgeFirst=true
--option allowAdjustments=true

Valid values for updateMethod are replace and append.  append is used by default if no value was provided.  

Valid values for status are INUSE, SUBMITTED, COMPLETED and LOCKED.  INUSE is used by default if no value was provided.

Valid values for the purgeFirst option are true and false.  false is used by default if no value was provided.

Valid values for the allowAdjustments option are true and false.  false is used by default if no value was provided.

vendor_invoice

purgeFirst
status
allowClosedFP

--option purgeFirst=true
--option status=SUBMITTED
--option allowClosedFPt=true

Valid values for purgeFirst and allowClosedFP options are true and false.  false is used by default if no value was provided.

Valid values for status are  INUSE and SUBMITTED

vendor_payment

purgeFirst
status
allowClosedFP

--option purgeFirst=true
--option status=SUBMITTED
--option allowClosedFPt=true

Valid values for purgeFirst and allowClosedFP options are true and false.  false is used by default if no value was provided.

Valid values for status are  INUSE and SUBMITTED

 


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.

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 the machine you are running from).  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 web-site.

Also, you must have Java 1.6 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 using 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.6 on the machine running the export.  


Using a Self-Signed SSL Certificate

If you are using a self-signed SSL certificate on you 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:

 

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 poke around a little to find it, either in the file system, or in the documentation. Anyway, once you find it then run this command:

C:\>keytool -keystore %JAVA_HOME%/lib/security/cacerts -alias unanet -import -file c:\unanet.cer

 

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'll need to make sure you include the native Unanet Authentication option in your configuration if you plan on using the command line import, as this feature requires a "Unanet" username and password to operate (ie 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):

 

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.

 

Related Topics