AvaTax4J Readme

This is a Java client adapter for Avalara AvaTax web services. This version has support for the tax and address services.

The adapter was built using Apache Axis WSDL2Java to build the stubs which were then enhanced to support a custom Profile SOAP header element and a WS-Security UsernameToken SOAP header element.

A set of JUnit tests are provided as examples. You may wish to refer to .NET/COM documentation for more details.

YOU MUST CONFIGURE avatax4j.properties before running tests or samples!
Use avatax4j.properties.sample as an example and insert your account and license.

Contents
/doc/api Javadocs - API Documentation
/lib All required jars
/samples

Sample applications

  • AddressValidateSample
  • TaxTransactionSample
  • TestConnectionSample
/src Full source code
/test TaxSvcTest JUnit test class to be used as an initial example.
avatax4j.properties.sample Sample properties file for JUnit tests to configure url, account, license
This must be renamed to avatax4.properties and configured prior to running the unit tests.
build.xml Ant build script. Run "ant" for usage instructions

Dependencies

All dependent jar files are included for build and running.

Getting Started

  1. Look at the examples in the samples directory.
  2. Look at the unit tests for more examples.
  3. Read the Javadocs
  4. Configure avatax4j.properties.Use avatax4j.properties.sample as an example and insert your account and license.
  5. Run the samples and unit tests. See build instructions below.

Build Instructions

A complete Ant build.xml script is provided in the root directory. Here is a list of the main target Ant tasks.

Deployment

Many applications will only need to deploy the avatax4j.jar and avatax4j.properties file. The avatax4j.properties file can be eliminated by setting the server url, username and password credentials in your code. Examples of this can be found in any of the samples (e.g. TestConnectionSample).

Some applications may require deployment of additional jar files from the lib folder. These are all standard Sun, Apache, or other open-source components. The version is indicated in most of the jar file names, but avatax4j should be generally compatible with later versions. The axis-ant.jar, junit.jar, wsdl4j.jar are only used for building and testing avatax4j.

Important Notice

This year we will be releasing a High-Availability version of our adapters designed to work with geographically distributed AvaTax servers.  This new version will eliminate the DocId property for most operations, including GetTax, PostTax, CommitTax, and CancelTax.  To simplify the transition, we highly recommend using DocCode instead of DocId for these operations.  DocId is server specific and will change depending on which AvaTax server processes the request.  We will maintain support for clients using earlier adapters, but they will not be able to take advantage of the new high-availability architecture.

Change History

5.3.1 - March 2009

Several properties were added and some behavioral changes were made for the existing ones.

GetTaxRequest class

GetTaxResult class

TaxDetail class

TaxLine class

TaxSvc class

5.2.0.0 - August 2008

  1. AddressSvc.Validate: Added a Taxability flag to the ValidateRequest to retrieve whether the address is a taxable address. This is indicated by the ValidateResult.Taxable flag.
  2. TaxSvc.ApplyPayment: This is a new method for applying payments to invoices. This only applies to companies that have CashBasisEnabled and in US states or countries where the AccountingMethod is set to CashBasis in the Nexus for that state or country. CashBasis invoices are not considered reportable until payment has been applied. ApplyPayment will set the Line.ReportingDates to the PaymentDate. Otherwise, it will be left at 9999-12-31 and won't show on reports.
  3. TaxSvc.GetTax:
    1. A new TaxOveride element was added to the GetTaxRequest and the Line. This allows specifying an overriding tax date and tax amount, or overriding the exempt status.
    2. CurrencyCode was added. The default is USD, if not specified.
    3. PaymentDate was added to GetTaxRequest which allows applying a payment to a cash basis transaction when calculating tax.
    4. ExchangeRate and ExchangeRateEffDate were added to GetTaxRequest to indicate the rate of currency exchange relative to the company's base currency. This defaults to 1. It should only be set if the transaction currency is different than the company's base currency. The rate should be TransactionCurrency * ExchangeRate = BaseCurrency.
    5. TotalTaxCalculated has been added to the GetTaxResult and TaxCalculated has been added to TaxLine and TaxDetail. This indicates the tax that AvaTax calculated in cases where a TaxOverride was used.
    6. TaxSummary was added to the GetTaxResult which contains a summary of taxes by jurisdiction. This is only returned when the GetTaxRequest.DetailLevel is Summary or Line.
    7. A new global JurisType of Country is now returned for foreign countries, including Canada. Previously State and County were used for Canada and Province jurisdictions. To prevent breaking existing clients, this same behavior is retained unless the Profile.Name is set to "5.1.0" or later. In general, the version of the avatax4j release should be used in the Profile.Name. For this release, it should be Profile.Name = "5.2.0.0".

5.0.0.271 - June 2007

1 GetTaxRequest class

2 GetTaxResult class

3 Line class

4 Address class

5 AdjustTax call

6 AdjustTaxRequest class

7 AdjustTaxRequest class

8 PostTaxRequest class

9 TaxLine class

10 CancelCode enum

11 DocStatus enum

4.15.0 - June 2007

  1. Eliminated backward compatibility issue with AvaTax server API changes. Previously if new elements were added to the server api, it was necessary to either get a new adapter or make sure that the avatax4j.jar preceeded axis.jar on the classpath. This was problematic or not possible in some environments. We are handling this issue now and no longer depend on the classpath order. Updating the adapter for server API changes is not necessary except when you wish to use the new features. Backward compatibility will be maintained. We highly recommend updgrading to this new adapter. No code changes should be necessary. The interface has not been changed.

4.14.0 - May 2007

  1. Eliminated need for wss4j-1.1.0.jar, opensaml-1.0.1.jar, and xmlsec-1.2.1.jar files. The SOAP security token is now directly built in BaseSvcSoapStub.setSecurity(). The only required code change is in the wsdd configuration. See the next change for details.
  2. Eliminated the need for the avatax4j.wsdd file. You should simply call the default AddressSvcLocator() or TaxSvcLocator() constructor instead of passing a config file (new FileProvider("avatax4j.wsdd")). If you wish to still use a wsdd config file, then you need to remove the <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > handler. This is because we no longer use wss4j. See any of the samples or junit tests for code examples. The handler has been removed from the included avataxj4.wsdd, but it isn't necessary if you just use the default locator constructors.
  3. Included the activation.jar and mailapi.jar files to eliminate the annoying, but inocuous "Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled" warning message.

Known Issues

  1. If you get a warning message regarding Xalan as follows:

    Unable to patch xalan function table.
    java.lang.NoSuchFieldException: m_functions
    at java.lang.Class.getField(Unknown Source)
    at org.apache.xml.security.Init.registerHereFunction(Init.java:429)
    at org.apache.xml.security.Init.init(Init.java:124)… (and so on)

    You need to copy the xalan-2.6.0.jar to your JAVA_HOME/lib/endorsed/ directory. You may need to create the endorsed directory.
  2. Ant test target cannot find the junit task:

    The easiest way to fix this is to copy the junit jar from the avatax4j/lib directory to your ant/lib directory.
  3. Warning message: "Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled" occurs.

    You need to include the activation.jar and mailapi.jar (included in releases 4.14.0 and later). Or you can download these at: http://java.sun.com/products/javabeans/jaf/downloads/index.html and http://java.sun.com/products/javamail/downloads/index.html