QuickBooks Payroll Compensation Types in Time Activities Sample App

This is a sample Java application that demonstrates how to integrate with QuickBooks APIs using OAuth 2.0 authentication and use payroll compensation types in time activities.

Features

• OAuth 2.0 authentication with QuickBooks
• Payroll API integration via GraphQL

Prerequisites

• Java 17 or higher
• Gradle 7.0 or higher
• QuickBooks Developer Account
• QuickBooks Online Account
• ngrok (for local development)

Required OAuth Scopes

The API requires the following OAuth scopes for full functionality:

• com.intuit.quickbooks.accounting - Access to QuickBooks accounting data
• project-management.project - Required for Projects API access
• payroll.compensation.read - Required for Payroll API access

Setup

1. Clone the repository:

   git clone <repository-url>
   cd SampleApp-Payroll-Java

2. Configure your QuickBooks app:

   • Go to Intuit Developer Portal
   • Create a new app or use an existing one
   • Enable Payroll, Project and Accounting API scopes
   • Add your redirect URI (e.g., https://your-ngrok-url/callback)

3. Update configuration:

   • Open src/main/resources/application.yml
   • Update the OAuth2 provider details with your app credentials:

   quickbooks:
     client-id: YOUR_CLIENT_ID
     client-secret: YOUR_CLIENT_SECRET
     redirect-uri: YOUR_REDIRECT_URI

   • Set the minor version and the environment as appropriate:

   quickbooks:
     minor-version: 75
     environment: production

4. Start ngrok:

   ngrok http 8080

5. Run the application:

   ./gradlew bootRun

Usage

1. Visit http://localhost:8080 in your browser
2. Step 1: Connect to QuickBooks - Click "Connect to QuickBooks" to authenticate
3. Step 2: Fetch Data - Click "Fetch Data" to load employee and project data automatically
4. Step 3: Fetch Compensations - Click "Fetch Compensations" to load compensation data for the selected employee
5. Step 4: Enter Info - Select a compensation type and optionally a project for which you want to create a time activity. Then enter the hours and minutes worked.
6. Step 5: Create Time Activity - Click "Create Time Activity" to create the specified time activity for your company.

Project Structure

SampleApp-Payroll-Java/
├── src/main/java/com/quickbooks/demo/
│   ├── Application.java              # Main application file
│   ├── config/                       # Configuration classes
│   ├── controller/                   # Web controllers
│   ├── service/                      # Business logic services
├── src/main/resources/
│   ├── application.yml               # Configuration settings
│   ├── graphql/                      # GraphQL queries and mutations
│   ├── static/                       # Static files (CSS, images)
│   └── templates/                    # HTML templates
└── README.md

API Endpoints

• / - Home page with multi-step workflow
• /qbo-login - Initiates OAuth flow
• /callback - OAuth callback handler
• /datafetch - Retrieves employee and project data automatically
• /fetch-compensations - Retrieves compensation data for the selected employee
• /create-time-activity - Creates a time activity in QuickBooks
• /logout - Logs out of QuickBooks

Error Handling

The application includes error handling for:

• OAuth authentication failures
• API request failures
• Missing parameters
• Invalid scopes

Common Issues

1. "Forbidden" Error

   • Ensure project-management.project and payroll.compensation.read scopes are included in OAuth authorization
   • Check that all required scopes are configured in application.yml

2. "Invalid URI or environment" Error

   • Verify Environment is set to "production"
   • Check that RedirectUri matches your QuickBooks app configuration

3. GraphQL Query Errors

   • Filtered queries use projectManagementProjects or getEmployeeCompensations (with 's')
   • Ensure proper variable types: ProjectManagement_ProjectFilter! for filtered projects or Payroll_EmployeeCompensationsFilter! for compensations

API Requests and Responses

All API requests that the app makes are logged at DEBUG level. Reponses are logged in the same way, unless the request fails. In that case, the response is logged at ERROR level.

Please set the required logging level in application.yml.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support, please visit the Intuit Developer Community or create an issue in this repository.