This document explains important Streamlined Sales Tax concepts, describes the different software components and how they work together, and guides you through running the software.
We encourage questions and feedback. Both help us improve documentation and give us hints about areas that need improvement. The main support mechanism is the gateway-discuss mailing list . E-mail sent to the list is forwarded to all developers and any users that have decided to join. It is publicly accessible and will be archived forever, so think before you hit the 'Send' button. If you'd like to discuss something privately, please contact one of the developers .
The Streamlined Sales Tax Project (SSTP) is really hard to fully explain in a couple of paragraphs, especially to people not familiar with the American tax system. So instead of trying to explain it all, we'll just focus on the parts that relate to this software project. If you really want to, you can read the full Streamlined Agreement .
The Streamlined Sales Tax Project enables participating states to collect sales and use tax from businesses residing outside the state that sell to the states' citizens through mail order, catalogs and the Internet. Sales and use tax returns are filed through a CSP (certified service provider). There are several CSPs for a business to pick from. The businesses send all of their returns to a CSP. The CSP in turn forwards the returns to the appropriate states. This is where the gateway project comes it.
A very brief description of the MeF as it pertains to the Gateway would be as follows:
Various organizations enable taxpayers to file electronically via eFile. This data is collected by an organization and shipped off to the IRS. Federal data is utilized by the IRS and eventually, by 2009, state specific taxpayer filings will be organized by state and available for each to download for its own processing. The Gateway project will allow tax staff to pull this state data for Vermont processing and review.
There is a wealth of information on this project separate from the Gateway at the IRS eFile site .
The gateway project was tasked with the creation of software for accepting Streamlined Sales Tax returns and plugging the information into Vermont's existing tax systems. The Tax Information Group for ECommerce Requirements Standardization (TIGERS) defined and maintains the XML schema used in transmissions for the Streamlined Sales Tax Project. The XML is transmitted by CSPs via a Simple Object Access Protocol (SOAP) web service. The gateway performs authentication, authorization, and input validation on each transmission. If the transmission is acceptable, it is processed into a SQL file. The SQL is exported to Vermont's existing tax databases and processed by Vermont's existing software. Additional functionality, like a web interface, has been added. Client software was also created.
The gateway is a JavaEE application that runs on an application server . The gateway currently runs on an open source JavaEE App Server called JBoss . The source code is split up into several modules that can be mixed and matched. For example, you could provide the Streamlined Sales Tax web service but omit the web interface. The modules are packaged up into a single Enterprise Archive (EAR) file that is run on a JBoss server. JBoss runs on pretty much any operating system with Java 5.
The SSTP Server module is one of the key components. It provides the web service framework for transferring tax data. The WSDL defines several web service operations which can be performed. Each operation is described briefly below. These are important terms to know as they are used often in the documentation and throughout the web interface and client software.
The ping operation allows transmitters and automated monitoring software with a mechanism for testing whether the web service and the system providing the web service are operational or not. The ping operation simply echos back a string and displays some version information. No authentication is needed for the ping operation. All other operations require authentication.
The send operation allows transmitters (CSPs and others) to transmit tax payments and tax returns. Business registrations are also handled by the send operation. Each return, payment or registration is contained within an SSTP Document. A set of documents is contained within an SSTP Transmission. When the transmission arrives, some basic checks are done (is it XML, does it validate against the schema, was the user authorized to send it, etc). If the basic checks pass, the transmission is saved to the database and an SSTP Receipt is given to the transmitter. The receipt lets the transmitter know that we got the file and will attempt process it.
When a transmission is saved to the database an enterprise java bean, the processor or endorser as we sometimes refer to it, wakes up. The processor begins doing more intensive validation on the documents and their content. If a major problem is detected, the whole transmission is rejected. If the problem is isolated to specific documents, then those documents are rejected. The documents' status is kept track of. The documents that pass the intensive validation get transformed into SQL that can be loaded into a database at the Vermont Department of Taxes.
The acknowledgment operation allows states to acknowledge that a transmission has been processed or not processed, accepted or rejected. After the processor validates and processes a transmission, an SSTP Acknowledgment is generated. The acknowledgment lets the transmitter know which of the transmission, the transmission's documents, and the payments were accepted or rejected. Any rejection sections in the acknowledgment will list detailed error messages. The acknowledgment operation acts like a queue. Every time the transmitter calls acknowledgment, it returns the next available acknowledgment document. The transmitter will usually perform the acknowledgment operation repeatedly until the gateway returns null. The acknowledgment operation doesn't provide a way to access acknowledgments for specific transmissions, just the next available acknowledgment in the queue.
The last acknowledgment operation allows transmitters to get a copy of the last acknowledgment returned by the acknowledgment operation.
During development, we created a simple client that we used to test the web service. Over time we've extended and expanded it. Currently, the Vermont Department of Taxes maintains a command line client, a graphical client, and a web based client. Besides supporting all of the web service operations, the graphical client also includes a transmission validator.
This is the web interface to the Streamlined Sales Tax web service. It allows administrators to configure users and groups, configure access restrictions and view log messages. The portal allows tax staff members to inspect transmissions, download summary spreadsheets, check the status of the processor and register businesses that wish to participate in Streamlined Sales Tax. Transmitters may use the portal as a Streamlined Sales Tax web services client. Web service operations are explained in more detail above.
It is impossible for the Vermont Department of Taxes to implement the gateway in such a way that it could be used out of the box by any other state. This is because each state has its own way of storing tax information and processing returns. If another state were to use the gateway, some programming changes would be needed to integrate the gateway into that state's existing infrastructure.
The gateway developers knew that there could be other states wanting to use the gateway, so extra steps were taken during the planning and implementation phases to ensure that the process of customizing the gateway to work for another state would be pretty painless. Vermont specific code is isolated and a mock state (Xyzzy) was created to demonstrate the changes another state would have to make to use the gateway. In short, it was designed from the ground up for extension.
The Vermont Integrated Revenue Collection System (VIRCS) is a state specific piece Vermont uses to handle payment and return processing. As mentioned above, valid SSTP documents are transformed into SQL that Vermont's existing software knows how to handle. Since the gateway and Vermont's existing systems aren't directly connected, the gateway provides a web service that can be used to access the SQL. There is a client program that runs periodically and loads the SQL into the VIRCS database.
By now you should have a high level understanding of how the software is supposed to work. The next few sections will point you to documentation explaining how to install, setup and use various pieces of the software. The instructions are ordered from easiest and least time consuming to hardest and most time consuming.
Our friends at OSU OSL host a demo server running the gateway's web service and web interface (the portal). Before installing the gateway on your own, we suggest taking a look at the demo. Information about the demo server can be accessed at the following URL: http://gateway-demo.osuosl.org/ . A list of compatible browsers can be found here .
The client installation guide can be found here . Installation is fairly painless. There is a Windows installer and a standalone JAR for non-Windows users. A usage guide (with screenshots) can be found here . The usage guide will walk you through various common tasks. The client's default configuration is setup to communicate with the gateway demo site, so you can try out the client without having to setup your own SSTP web service.
The graphical client, with its point and click interface, is a lot easier for a new user to use than the command line client, but if you like the command line or want an automated way of performing SST web service operations, then the command line client is for you. Installation instructions can be found here . As with the graphical client, a Windows installer and standalone JAR are provided. Usage instructions are available here .
The SST web service, the web portal, and other modules are packaged up into an EAR file that can be run without much effort. The package provides the same level of functionality as the demo site. We envision it being used for internal testing or for demonstrating and evaluating the gateway. Setup instructions are available here .
If you want to use the gateway in a production environment, you'll want to use a real database like MySQL. Perhaps you'd like to set up several gateway instances with a load balancer too. If you answered yes to any of the above questions, then we have documentation for you. Be warned, while the setup process is well documented and repeatable, it requires setting up several software applications and may be more complex than a novice administrator would like. To setup several load balanced instances of the gateway running on JBoss and using a MySQL database for data storage, you'll need to follow the following guides: MySQL Setup , JBoss Setup , Pen Setup , DB Setup , and Deployment . Along the way, you'll also have to re-package the EAR file. Some notes on backing up the system are available here .
We are constantly working to improve our documentation. If you have questions or comments about this document, contact one of the developers . Your feedback will help us improve this document and others.