Setting Up Integrations

Setting Up Integrations #

Preview Environments can connect to external services like Xero, QuickBooks Online (QBO), SharePoint, and more. This guide shows you how to configure these integrations for testing.

Overview #

Unlike production environments where integrations are pre-configured, Preview Environments require manual setup for OAuth-based integrations. This is because:

  • 🔐 Each OAuth integration requires a unique callback URL
  • 🌐 Preview URLs are dynamically generated per PR
  • 🔒 Security best practices prevent automatic OAuth configuration

General Integration Setup Process #

The basic process for all OAuth integrations:

┌─────────────────────────────────────────────────────────────┐
│  1. Get your Preview Environment URL                        │
│     Example: https://app-preview--coder-preview-123--john...│
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Contact a developer with integration admin access       │
│     Provide: Preview URL + Integration type                 │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Developer updates OAuth callback URL                    │
│     In integration provider's developer portal              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Test OAuth flow in Preview Environment                  │
│     Connect organization → Authorize → Verify connection    │
└─────────────────────────────────────────────────────────────┘

Supported Integrations #

Integration Type OAuth Required Configuration Complexity
Xero Accounting Yes Medium
QuickBooks Online (QBO) Accounting Yes Medium
SharePoint Document Storage Yes Medium
Googole Drive Document Storage Yes Medium
Intercom Customer Support Webhook Low
Stripe Payment Processing API Key Low

Xero Integration Setup #

What You’ll Need #

  • Preview Environment URL
  • Xero Developer account access (contact developer)
  • Test Xero organization

Step-by-Step Process #

1. Get Your Preview URL #

From your PR comments, copy the full preview URL:

https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/

2. Update Xero OAuth Settings #

The developer will:

  1. Go to Tofu-local configuration page
  2. Add redirect URI in Configuration: 
    https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/api/v1/integrations/oauth/authorize/callback
  3. Save changes

⏱️ Wait Time: Changes are effective immediately

3. Connect Xero in Preview Environment #

  1. Access your Preview Environment
  2. Navigate to Settings → Integrations
  3. Find Xero in the integrations list
  4. Click “Connect”
  5. You’ll be redirected to Xero’s authorization page
  6. Sign in with your Xero test account
  7. Select the test organization
  8. Click “Allow access”
  9. You’ll be redirected back to BonsAI
  10. Verify connection status shows “Connected”

4. Test the Integration # 

# Trigger a sync
Settings → Integrations → Xero → "Sync Now"

# Verify data sync
Navigate to Invoices → Check for synced data

# Check sync logs
Settings → Integrations → Xero → "View Logs"

Troubleshooting Xero #

Error: “Invalid Redirect URI”

  • Cause: OAuth redirect URL not configured
  • Solution: Verify developer has added the correct redirect URI

Error: “Organization Not Found”

  • Cause: Connected to wrong Xero organization
  • Solution: Disconnect and reconnect, selecting correct org

QuickBooks Online (QBO) Setup #

What You’ll Need #

  • Preview Environment URL
  • QuickBooks Online Developer account access
  • QBO Sandbox account

Step-by-Step Process #

1. Get Your Preview URL #

Copy from PR comments:

https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/

2. Update QBO OAuth Settings #

The developer will:

  1. Go to Tofu Local Settings page
  2. Navigate to Redirect URIs
  3. Add redirect URI: 
    https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/api/v1/integrations/oauth/authorize/callback
  4. Save changes

⏱️ Wait Time: Changes are effective immediately

3. Connect QBO in Preview Environment #

  1. Access your Preview Environment
  2. Go to Settings → Integrations
  3. Find QuickBooks Online
  4. Click “Connect”
  5. Sign in to QuickBooks
  6. Select your sandbox company
  7. Click “Authorize”
  8. Verify connection in BonsAI

4. Test the Integration # 

# Trigger a sync
Settings → Integrations → QuickBooks → "Sync Now"

# Verify customers synced
Navigate to Customers → Check for QBO data

# Verify invoices synced
Navigate to Invoices → Check for QBO invoices

# Check sync status
Settings → Integrations → QuickBooks → "View Activity"

Troubleshooting QBO #

Error: “Redirect URI Mismatch”

  • Cause: OAuth redirect not properly configured
  • Solution: Verify exact URL match including trailing slashes

SharePoint Integration Setup #

What You’ll Need #

  • Preview Environment URL
  • Microsoft Entra ID access
  • Test SharePoint site

Step-by-Step Process #

1. Get Your Preview URL #

Copy from PR comments:

https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/

2. Update Entra ID #

  1. Go to Tofu Integration Dev Authentication page
  2. Add redirect URI: 
    https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/api/v1/integrations/oauth/authorize/callback
  3. Save changes

⏱️ Wait Time: Up to 5 minutes for changes to propagate

3. Connect SharePoint #

  1. Access Preview Environment
  2. Go to Settings → Integrations
  3. Find SharePoint
  4. Click “Connect”
  5. Sign in with Microsoft account
  6. Select the SharePoint site
  7. Grant permissions
  8. Verify connection

Troubleshooting SharePoint #

Error: “AADSTS50011: Redirect URI Mismatch”

  • Cause: Azure AD redirect URI not configured
  • Solution: Verify developer has added exact URI

Google Drive Integration Setup #

What You’ll Need #

  • Preview Environment URL
  • GCP access

Step-by-Step Process #

1. Get Your Preview URL #

Copy from PR comments:

https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/

2. Update Google Drive App #

  1. Go to Integration Dev Clients page
  2. Add redirect URI: 
    https://app--preview--coder-preview-<PR number>--john.coder.internal.gotofu.com/api/v1/integrations/oauth/authorize/callback
  3. Save changes

⏱️ Wait Time: Up to 5 minutes for changes to propagate

3. Connect SharePoint #

  1. Access Preview Environment
  2. Go to Settings → Integrations
  3. Find Google Drive
  4. Click “Connect”
  5. Sign in with Google account
  6. Select the Drive
  7. Grant permissions
  8. Verify connection

Troubleshooting SharePoint #

Error: Redirect URI Mismatch"

  • Cause: Google App redirect URI not configured
  • Solution: Verify developer has added exact URI

Non-OAuth Integrations #

Some integrations don’t require OAuth configuration:

API Key Based Integrations #

Stripe:

  1. Navigate to Settings → Integrations → Stripe
  2. Enter test API key (starts with sk_test_)
  3. Click “Save”
  4. Verify connection

SendGrid:

  1. Navigate to Settings → Integrations → SendGrid
  2. Enter API key
  3. Click “Save”
  4. Send test email

Webhook Based Integrations #

Intercom:

  1. Get webhook URL from Settings → Integrations → Intercom
  2. Add webhook in Intercom admin panel
  3. Set webhook URL to: 
    https://app--preview--coder-preview-123--john.coder.internal.gotofu.com/webhook/intercom
  4. Test webhook delivery

Integration Testing Checklist #

After configuring an integration, verify:

Initial Connection #

  • OAuth flow completes without errors
  • Connection status shows “Connected”
  • Organization/Company name displays correctly
  • Last sync time is recent

Data Sync #

  • Manual sync triggers successfully
  • Data appears in BonsAI after sync
  • Sync logs show no errors
  • Background sync works (if applicable)

Error Handling #

  • Test with invalid data
  • Verify error messages are clear
  • Check that errors are logged properly
  • Ensure retry logic works

Performance #

  • Large dataset sync completes
  • No timeout errors
  • UI remains responsive during sync
  • Background jobs process correctly

Best Practices #

For Developers #

  1. Test Early: Configure integrations at start of PR testing
  2. Use Test Accounts: Never use production accounts
  3. Document Changes: Note any integration-specific changes in PR
  4. Clean Up: Remove OAuth redirects after testing (optional)

For QA Engineers #

  1. Prepare Test Data: Set up test data in integration platforms
  2. Test Edge Cases: Try various scenarios (empty data, large datasets)
  3. Verify Error Handling: Test with disconnected integrations
  4. Document Issues: Include integration name and error details

For Product Managers #

  1. Request Early: Ask developers to configure integrations before demo
  2. Test User Flows: Verify end-to-end user experience
  3. Provide Feedback: Comment on UX and error messages
  4. Plan Ahead: Schedule integration testing for realistic timelines

Common Integration Issues #

OAuth Callback Issues #

Symptom: “Invalid Redirect URI” or “Callback URL not whitelisted”

Causes:

  • Redirect URI not configured in provider portal
  • Typo in redirect URI
  • Protocol mismatch (http vs https)

Solution:

  1. Verify exact preview URL
  2. Ensure developer configured correct callback
  3. Check for trailing slashes

Token Expiration #

Symptom: “Token expired” or “Unauthorized” errors

Causes:

  • OAuth token has expired
  • Integration was disconnected
  • Token refresh failed

Solution:

  1. Disconnect integration
  2. Reconnect through OAuth flow
  3. Verify new token works

Permission Issues #

Symptom: “Access Denied” or “Insufficient Permissions”

Causes:

  • User account lacks required permissions
  • OAuth scopes insufficient
  • Organization-level restrictions

Solution:

  1. Use admin account for testing
  2. Verify required OAuth scopes
  3. Check organization settings

Data Sync Issues #

Symptom: Data not appearing after sync

Causes:

  • Sync still in progress
  • Filters excluding data
  • Background job not running
  • Integration error

Solution:

  1. Check sync logs for errors
  2. Verify background workers are running
  3. Check RabbitMQ queue status
  4. Review sync filters/settings

Getting Help #

Who to Contact #

For OAuth Configuration:

  • Contact developers with admin access to integration portals
  • Include: Preview URL, Integration type, PR number

For Integration Issues:

  • Post in #engineering channel with:
    • Preview URL
    • Integration name
    • Error message
    • Steps to reproduce

For Test Account Access:

  • Contact IT or team lead for:
    • Xero sandbox organization
    • QBO sandbox company
    • SharePoint test site
    • Other test accounts

Useful Resources #

Next Steps #