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:
Introduction (overview of the Command Line Export functionality)
Requirements (prerequisite system requirements)
Syntax and Options (which exports 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)
Using SSL (working around the No trusted certificate found exception)
You may also be interested in:
Integration Management Utility (IMU) (overview of a stand-alone utility that helps manage inbound and outbound imports and exports)
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, or 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.
You must have Java 11 or higher installed on the server invoking the command-line export program.
Usage: |
java -jar Export.jar --help |
--url url |
REQUIRED. The base URL for the Unanet application. For example: http://www.yourdomain.com/unanet. |
--username username |
REQUIRED. A Unanet administrator login username. |
--password password |
REQUIRED. The password for the login username used. |
--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 |
REQUIRED. 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.). Enclose in quotes if multiple words (e.g., --template "Employee Type"). It is also case-sensitive. Available template names (in bold font) include: Accounts Alternate Approval Group Assignment Contract Contract Modifications 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 Journal Entry Item - Master Item - Project Labor Category - Master Labor Category - Project Location - Master Location - Project Organization Organization Access Organization Address Organization Contact Organization Contact Address Organization Contact Email Organization Contact Phone Pay in Lieu of Benefits Person Person Accruals Person Benefits Person Skills Planned Work PO Assignment Project Project Administrators Project Fee Project Invoice Setup Purchase Order - Open/Close Purchase Order - Originals Purchase Order - Mods Skill Level Skill Type Skills Task Time Vendor Invoice Vendor Payment Vendor Profile
NOTE: The following templates are not delivered with the system but can be created as a custom template: 1099 Vendor Payment Templates: Document Level 1099 Detail Track 1099
Accounts Receivable Templates: Form 1034/1035/ Excel Template Export Invoice
General Ledger Templates: GL Extract GL Transactions
Journal Entry Templates: Fixed Asset Net Book Value Journal Entry
|
--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 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 (includes "Document Level 1099 Detail" and "Track 1099" templates) Fixed Price Item Organization Contact |
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
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 where 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 the filename to which the output will be written.
"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 was 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 a 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. 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.
********************************************************************************
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 website.
Also, you must have Java 11 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.
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 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"
If using SSL and attempting to run the command line export, you should ensure you are using Java 11 on the machine running the export.
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:
Data encryption, and
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 have 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 accepted it 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.
When configuring authentication / single sign-on options, you need to ensure to include the native Unanet Authentication option in your configuration file. The command line export requires a "Unanet" username and password to operate (i.e. it will not function with an external authentication option).
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):
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 the pull of data from your system (formatting the data in a format that is appropriate for your downstream need).
You may need to have a step that copies these files to specified directories for the purpose of processing or archiving.
You may want a step to read the resulting return codes (searching for issues), 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 outbound exports. Check out the Integration Management Utility (IMU) for additional information.