eCommerce Java Sample App

Welcome to the Intuit Developer's eCommerce Java Sample App.

This sample app is meant to provide working examples of how to integrate your app with the Intuit Small Business ecosystem. Specifically, this sample application demonstrates the following:

1. Implementing OAuth to connect an application to a customer's QuickBooks Online company.
2. Syncing customer and service item data from the app's local database to the QuickBooks Online company.
3. Processing a credit card payment to QuickBooks Online Payments.
4. Create a SalesReceipt in the QuickBooks Online company.

Please note that while these examples work, features not called out above are not intended to be taken and used in production business applications. In other words, this is not a seed project to be taken cart blanche and deployed to your production environment.

For example, certain concerns are not addressed at all in our samples (e.g. security, privacy, scalability). In our sample apps, we strive to strike a balance between clarity, maintainability, and performance where we can. However, clarity is ultimately the most important quality in a sample app.

Therefore there are certain instances where we might forgo a more complicated implementation (e.g. caching a frequently used value, robust error handling, more generic domain model structure) in favor of code that is easier to read. In that light, we welcome any feedback that makes our samples apps easier to learn from.

Table of Contents

• Requirements
• First Use Instructions
• Running the code
• High Level Workflow
• Importing into IntelliJ IDEA & Eclipse
  • IntelliJ IDEA
  • Eclipse
• Project Structure
• How To Guides
• Testing the code
  • Java Junit Tests
  • Javascript Karma tests
• Reset the App
• Watch & Learn
• More Information

Requirements

In order to successfully run this sample app you need a few things:

1. Java 1.7
2. A developer.intuit.com account
3. An app on developer.intuit.com and the associated app token, consumer key, and consumer secret.
4. QuickBooks Java SDK (already included in the libs/qbo-sdk folder of the GitHub repo)
5. Helper Files for the payments API (already included in the libs/payments-reference-implementation folder of the GitHub repo)

First Use Instructions

1. Clone the GitHub repo to your computer
2. Fill in your oauth.json file values (app token, consumer key, consumer secret) by copying over from the keys section for your app.

Running the code

Once the sample app code is on your computer, you can do the following steps to run the app:

1. cd to the project directory
2. Run the command:./gradlew bootRun (Mac OS) or gradlew.bat bootRun (Windows)
3. Wait until the terminal output displays the READY message.

   

4. Open your browser and go to http://localhost:9001/app/index.html

If you happen to be behind an http proxy you will need to create a file called gradle.properties in the root of the project and follow instructions on this page for configuring gradle to use a proxy.

High Level Workflow

Setup

1. Connect to a QuickBooks Online company.

   

2. Setup—sync the following from the local database to the QuickBooks Online company.
   • customers—so purchases can be billed to them,
   • items—a list of items available for purchase i.e inventory.

   

Storefront

1. Add Items to Shopping Cart.

   

2. Checkout the cart.

   

3. Submit Order - The following workflow happens when you submit an order
   • Tokenize Credit Card
   • Authorize & Capture a charge
   • Create sales receipt in Quickbooks

   

   

Importing into IntelliJ IDEA & Eclipse

To edit the code you will need to open it in an IDE. Currently we support both IntelliJ IDEA and Eclipse.

IntelliJ IDEA

• The project is maintained with IntelliJ IDEA and as such an .ipr file is checked into the GitHub repo.

Eclipse

• Importing Project into Eclipse IDE

Project Structure

• The Java code for integrating with the QuickBooks Online Accounting and Payments APIs is located in the src directory.
  • For OAuth implementation see:
    • OAuthController.java
    • OAuthInfoProvider.java
    • OAuthInfoProviderImpl.java
  • For QBO V3 Java SDK & Payments reference implementation usage see:
    • QBOGateway.java
    • PaymentGateway.java
    • QBOServiceFactory.java
• The Java code for the rest of the application is located in the src-general directory
• The HTML, CSS and JavaScript code for the web-based client are is located in the public directory

How To Guides

The following How-To guides related to implementation tasks necessary to produce a production-ready Intuit Partner Platform app (e.g. OAuth, OpenId, etc) are available:

• OAuth How To Guide (Java)

Testing the code

The two types of tests in the project (and how to run them) are listed below.

Java JUnit tests

1. ./gradlew test

Javascript Karma tests

To run the Javascript Karma tests you must have NodeJs v0.10.28 or later (http://nodejs.org/) installed and have npm on the path.

1. cd public
2. npm test

Reset the App

This app uses a file-based HSQL database that is stored in the database folder in the root of the project. Deleting this folder will delete all data persisted in the database. The next time you start your app a clean database will be created with no data.

Watch & Learn

<img src="http://img.youtube.com/vi/WK9G-bwssaY/0.jpg" alt="Watch & Learn" width="240" height="180" border="10" />

More Information

More detailed information for this sample app can be found here.