Command Line Export

As an alternative to using the export screens, you can also invoke exports programmatically using the command line export utility.  This functionality allows you to invoke each export 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 export data from Unanet and programmatically trigger another downstream process (without manual intervention) -- e.g. a nightly feed.

Topics covered on this help page include:

 

You may also be interested in:

 


Introduction

The command-line export program is designed to allow you to execute any of the exports 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 export program from that machine.

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

  java -jar Export.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 export program.


Syntax and Options

Usage:

java -jar Export.jar --help
java -jar Export.jar [options] --url --username name --password pass --template temp

 

 

--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.

--file file

If specified, the name of the file that will contain the output of the template.  It can be a fully qualified file name or a relative file (to the current directory).  The file will only contain output from the export.  All errors and other output will be written to standard err/out as appropriate.  If a file is not specified, the output will be written to standard out.

--checkVersion

Causes the export.jar to initiate a communication with the specified unanet servlet and verify that the two are compatible. If any incompatibilities are found, the appropriate message will be displayed and an error code (2) will be returned.

--criteria saved_criteria

Specifies the name of the saved export criteria to use when running the export.

--quiet

Causes ONLY results from the export to be displayed to standard out. Criteria, Sql and other output will be suppressed. Any errors encountered will still be reported.

--template template_name

Specifies the name of an export template you wish to use. This will dictate the type of export that will run (Time, Expense, Project, etc.).   This option is required.

--version

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

--option var=value

Allows additional options to be provided to the export process. You may specify multiple options.  If you are interested in supplying several values for the same option you will need to include separate option entries for each.  For example, if passing in 2 users to export on the person export (having person keys of 100 and 101), you would include:

   --option person=100
   --option person=101

Note that rather than passing in these individual items, you may instead want to manually configure a selection criteria page, save the criteria and use the saved criteria instead.

Note that the default values used when specific options are not provided will match the default values that the user interface supplies (for each export type).

The options that are available vary by template type.  See which options are available for each type of export below:  

Generally Available for all Types

1099 Vendor Payment

Accounts

Accounts Receivable

Alternate

Approval Group

Assignment

Customer Payment

Customer Profile

Employee Type

Employee Type Expense Type

Employee Type Pay Code

Expense

Expense Budget

Expense Plan

Expense Type - Master

Expense Type - Project

Fixed Price Item
General Ledger

General Ledger Journal Entry

Journal Entry

Labor Category - Master

Labor Category - Project

Location - Master

Location - Project

Organization

Organization Access

Organization Address

Organization Contact

Person

Person Accrual

Person Skills

Planned Work

Project

Project Administrators

Project Fee

Project Invoice Setup

Skill Level

Skill Type

Skills

Task

Time

Vendor Invoice

Vendor Payment

Vendor Profile

 


Syntax Example

A few sample command line export calls might resemble the following:

c:\unanet\utilities> java -jar Export.jar --url http://yourco.com:8080/unanet --username admin --password test --template "Approval Group"

C:\unanet\utilities> java -jar Export.jar --url http://yourco.com:8080/unanet --username admin --password admin --template "Approval Group" --file myoutput.txt > c:\yourdirectory\export_output.txt 2>&1

 


Reading The Output

There are several sections of output which may come from the command line export depending on the options that the user specifies.

"Starting" Section

This section will have the export.jar version as well as the Unanet server version that the client is connecting to, along with the results of the compatibility check.  This section will be written to stdout and will be omitted if the --quiet option is specified.

"Sql" Section

This section will display the SQL query that was used by the export including the criteria values were applicable. This section will be written to stdout and will be omitted if the --quiet option is specified.

"Criteria" Section

This section will display the run date and time along with ALL criteria used during the run.  This not only includes the visible criteria that the user would see on the selection criteria page, but ALL criteria including the hidden elements, keys, etc.  It will be very handy for use in trouble-shooting. This section will be written to stdout and will be omitted if the  --quiet option is specified.

"Output" Section

This section will display the output of the export.  In the event that the user specified the --file option, this section will only contain an not displaying the filename that the output will be written to.

"Error" Section

This section will only be displayed in the event of an error.  Errors not only include critical things like "no Export.jar found", but also any unexpected conditions from the actual export OR any "!HALT!" messages (see export expressions for more information on the !HALT! expression).  This section will be written to stderr and cannot be suppressed.

 

RETURN CODE

0 - if all processing finished normal.

2 - if the checkVersion option was called and the version check showed an incompatibility.

4 - if there was an error trying to connect to the server.

6 - if the username or password not accepted by the server OR the authentication cookie

    was not returned for any reason.

7 - if the provided password is correct, but expired.

8 - if the provided user is not an administrator.

10 - if an error occurred during the export process.

 

StdErr and StdOut can be captured to file for further interrogation.  Depending on your operating system syntax, one possible example may be:

C:\unanet\utilities> java -jar Export.jar --url http://yourco.com:8080/unanet --username admin --password admin --template "Approval Group" --file myoutput.txt > c:\yourdirectory\export_output.txt 2>&1

You will likely have some sort of shell script or batch file that runs your unattended export.  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.

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

 

Example Output

 

********************************************************************************

Unanet Command Line Export Starting...

********************************************************************************

     Current Export.jar Version: 1.1.0-alpha

     Current Unanet.war Version: 9.4.0-alpha

     

     Servlet and Jar are compatible.

********************************************************************************

Sql generated by the Export

********************************************************************************

     select chain.chain_name,

            ac.person_key,

            chain.description

     

     from chain chain

     left outer join approval_chain ac on ac.chain_key = chain.chain_key

     order by chain.chain_name

     ,ac.person_key

     ,chain.description

          

********************************************************************************

Criteria Used by the Export

********************************************************************************

     Run Date: 11/8/2010 3:12 PM

     distinct = false

     servletVersion = 9.4.0-alpha

     suppressOutput = false

     template = Approval Group

     version = 1.1.0-alpha

********************************************************************************

Output

********************************************************************************

*approval_group_name,approvers,description,delete

Admin,"RAS,EXPAPPROVER,TSAPPROVER",,

Demo Approvals,SVICHECK,,

Expense Approval Group,"PHESS,EXPAPPROVER",Expense Approval Group,

HessGrp,"RAS,PHESS",,

Time Approval Group,"MHESS,PHESS,PADMIN",Time Approval Group,

********************************************************************************

Unanet Command Line Export Finished.

********************************************************************************


Running The Command Line Export from Another Machine

You must have a copy of the Export.jar file on the machine from which you will run the command-line export 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 Export.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 Export.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 export.  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 Export.jar --url http://yourco.com:8080/unanet --username admin --password admin --template "Approval Group"


Using SSL

If using SSL and attempting to run the command line export, 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 export, 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 export. (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 Export 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 export, as this feature requires a "Unanet" username and password to operate (ie it will not function with an external authentication option).


Automated Export Example

If you are attempting to automate the process of exporting data from 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 outbound exports.  Check out the Integration Management Utility (IMU) for additional information.

 

Related Topics