This is the second public milestone release of USAS-R. The SSDT has been working steadily since November 2009 on completely re-designing and re-writing the OpenVMS/COBOL version of USAS into a modern SQL Java application. With this milestone release, the SSDT continues the process of testing and qualifying aspects of the new system.
It is important to understand, that this is a very early release of the software and it is not in any way near a production capable system. Much of the system is not complete nor functioning. Please read the goals and scope carefully to understand what the SSDT is looking for and what type of feedback is desired.
As this is a very preliminary software release (pre-beta), you should expect a certain amount of pain and discomfort if you choose to experiment with this Milestone release. Participation in milestone evaluation is entirely optional, so if your tolerance for pain is low, please feel free to wait for more stable and interesting releases in the future.
To provide feedback or ask questions regarding these instructions or general questions about USAS-R, please add comments in the Wiki. For specific issues regarding the software, please create an Issue in the USAS-R Feedback project. If reporting an issue related to the import process, please attach the
importResults file created by the import or the text of any errors in the console. If you experience similar problems as another issue, feel free to add comments to an existing issue. The block on the right shows the issues which have been reported so far against Milestone #3.
For more information on accessing the Wiki or JIRA, see the USASR Main Page.
Please do not use Forum for questions or feedback regarding USAS-R. JIRA provides a far more manageable interface for tracking and monitoring problem reports. The SSDT will not necessarily be monitoring Forum for issues related to USAS-R.
Goals and Scope
The goals of this milestone are:
- Testing Imports
- Testing that data is imported correctly and any problems reported in Milestone 2 have been corrected
- Review that initial requisition and current encumbered amounts on budget and cash accounts match classic USAS (other than limitations listed below)
- Note: Reporting modules are not yet available, so you will need to spot-check a subset of accounts
- Testing Requisitions and Purchase Orders
- All query options
- All options to Post or Update Requisitions and Purchase Orders
- Affect on requisitioned and encumbered amounts on budget and cash accounts
- Negative Balance warning in requisitions and purchase orders
- Note: These are implemented only at the budget account level and will always be warnings for this release
Out of Scope & Limitations
- Reporting modules are not yet available, therefore it will not be possible to do a full benchmark or comparison to the original data
- The Import process will only import Warrant, Memo and Refund checks. Payroll, Transfer, Distribution and Investment checks have not yet been implemented. (The importer will report "check number not found" for check items on unsupported checks)
- Appropriation accounts are not yet being imported.
- UI for creating users and roles has not been completed, therefore you must login to the provided "admin" account to access the system. Please ignore the "Users" and "Roles" menu options for now; these are experimental only and do not reflect any final product.
- YTD and FTD amounts are not stored in the new system. These amounts will be calculated by the application in the future. For this Milestone you will not see YTD/FTD amounts on Vendors or Accounts.
- An issue currently exists where the initial Current Encumbered figure may not match to Classic USAS if there were purchase orders left outstanding at the end of a fiscal year and some of the payment (invoice and check) details were purged off of the system, but the purchase order was left behind.
- Future purchase order batch files are not yet being imported, so Future and Future Year Encumbrances will not appear in the accounts after the import. You CAN however post a new future purchase order in USASWeb to update the future amounts.
- Expended amounts are not yet being calculated by the application. Therefore, unencumbered balance and remaining balance will NOT match classic USAS yet.
- Not all validations are being done yet when the transactions are posted. Also, not all configuration/preference options are functional in the new system at this time.
You may download the milestone release from http://download.ssdt-ohio.org/usas-r/milestones/ml3/usas-app.jar
This is an "executable WAR" file containing:
- Tomcat 7.0
- Embedded Derby SQL database
- USAS Web
- USAS SOAP Service
- USAS-R modules
This is not a production deployment of the USAS software. It is a simple method of distributing the application in a single bundle intended only for testing and evaluation. Future distributions will support server deployments, external database, etc.
- Java 1.6 SRE (not Java 1.7)
- Modern Workstation or Server class system (Windows, Linux or Mac OS X)
- Dual Core processor
- 2GB Memory
- 4GB available disk space
The instructions here assume you have the
java command on your PATH environment symbol. If you can not execute java from the command line, then you should define JAVA_HOME as environment variable pointing to the Java install directory and add
%JAVA_HOME%/bin to your PATH variable.
Executing the Application
Create a working directory on the local file system (e.g.
c:\usas-m3\) and download the
usas-app.jar and place it in the working directory. Then open a command line window and type:
The application will automatically unpack into the current working directory and launch Tomcat. You will see a series of "INFO" level logging message which may be ignored. The first time you execute the application in a given directory, the application will create a "db" folder under the working directory and create the database. This may take several minutes. When the application displays "
Access the application at: " you may open a web browser and enter the provided URL.
These instructions assume you will execute the application and web browser on the same machine. If you install the application on a server, then substitute the server's IP address or host name for
To terminate the application, press
Each database can only contain data for a single school district. If you import two districts into the same database, the results are unpredictable. If you wish to load multiple districts, create a separate working directory for each district.
The credentials for the administrator account are currently hardcoded in the application:
- username: admin
- password: 99admin00
Since the admin password is public, you should not leave the application running unattended once live data is loaded, or you should "anonymize" the data during the import (see below). You can change the password after logging into the webapp.
Resetting the database
To clear previously loaded or entered data from the database, simply terminate the application and delete the "db" folder from the working directory. The application will create a new database the next time it is started.
Using the Application
When first executed, the application contains no data and has been assigned as a "Template Organization". You may browse the application normally and enter data if desired. However, if you intend to import data be aware that imported data will be "merged" with any data you enter and may cause conflicts.
See USAS-R Import Process for details on how to export USAS data and import it into the USAS-R system.
Please note the following regarding Milestone #3:
- The performance of imports varies significantly depending on a number of a factors (hardware, number of transactions, number of fiscal years, etc). We recommend you start with a small or medium sized district before loading your largest district.
- The web page which monitors the import process does not report errors. Errors will be recorded in the current working directory in a file named "
- Performance metrics and error messages will be automatically submitted to the SSDT
- Any legacy data which violates new application's validation constraints will be omitted from the import process. In some cases, a "Template" record will be created to act as a place holder for the invalid record. For example, if a Vendor contains invalid data, the vendor record will be rejected. A "Template Vendor" will be created if any transactions (Purchase Orders, Checks, etc.) refer to the rejected vendor. This is the intended behavior to allow the SSDT to collect and evaluate the types of invalid data which exist in the field. ITC staff are encouraged to report validation errors during the import.
- Please note that there may be a noticeable delay after either the user import or anonymize steps during milestone #3 which did not exist during milestone #2. This is due to the loading of the ledger data used to calculate the requisition and encumbered amounts. The status in the web page will switch to "Completed" once this process is done.
After importing data, you should shutdown the application and restart it. In some cases, failing to restart will cause NPE (Null Pointer Exceptions).
Two bugs have been noted with the import process specifically affecting Milestone 3. First, the output from the import utility is not appearing as intended when using Internet Explorer. Thus, it is recommended that Firefox or other browser be used for the import. You can also see the messages from the console. The second problem reported is that the importResults-datetime.txt file is not being created. For now, if you have a problem with the import, please just include as much information along with any error message displayed in your JIRA issue. We will be fixing both of these problems before the next Milestone release.
USAS SOAP Service
The USAS SOAP Service is bundled with the application. If you wish to attempt testing the SOAP service using a third-party application, the SOAP end-point is