Skip to main content

PSA Integration (Auto-Sync)

The One Books integrates directly with The One PSA to automatically sync billable time, contracts, and project costs into the general ledger. This eliminates manual data entry and ensures your financial records match your service delivery.

How It Works​

  1. Technicians log time in PSA against tickets and projects
  2. PSA publishes events to The One Bus
  3. Books receives the events via the PSA integration endpoint
  4. Books creates GL entries based on your COA mappings
  5. Billable time becomes available for invoice generation

The integration uses HMAC-SHA256 signature verification (X-PSA-Signature header) to ensure events are authentic.

Setting Up the Integration​

  1. Navigate to Settings > Integrations > PSA
  2. Click Enable PSA Integration
  3. The integration is configured automatically through The One Bus — no API keys needed between One Stack products
  4. Configure your GL mappings (see below)
  5. Click Test Sync to verify with a small batch of data

GL Mappings​

GL mappings tell Books which GL account to use for each type of PSA activity. Navigate to Settings > Integrations > COA Mappings to configure.

Common Mappings​

PSA CategoryGL AccountEntry
Managed Services Time4000 - Managed Services RevenueCR Revenue
Project Time4100 - Project RevenueCR Revenue
Hardware (billable)4200 - Product SalesCR Revenue
Subcontractor Time5300 - Subcontractor CostsDR COGS
Internal Time (non-billable)6100 - Payroll ExpenseDR Expense

How Mapping Works​

Each mapping has:

  • Source system — psa
  • Source code — The PSA service category or type identifier
  • GL Account — The Books account to post to

When a PSA event arrives, Books looks up the source code in the mapping table to determine which GL account to debit or credit.

💡Set up a mapping for every PSA service category you use. Unmapped categories will be flagged in the integration event log for review.

What Gets Synced​

Time Entries​

  • Billable hours with rate and amount
  • Mapped to GL accounts based on service category
  • GL entry: DR Work in Progress or Labor Expense, CR appropriate account
  • Available for invoice generation

Contracts​

  • Recurring managed services contracts
  • Deferred revenue recognition based on service delivery
  • GL entry: DR Deferred Revenue, CR Service Revenue (as services are delivered)

Project Costs​

  • Direct project expenses from PSA
  • Mapped to COGS or expense accounts
  • GL entry: DR COGS/Expense, CR Accounts Payable or Cash

Sync Behavior​

Automatic Sync​

  • PSA events are processed in near real-time via The One Bus
  • A background timer (psa-sync-timer) runs periodically to catch any missed events
  • A reconciliation timer (psa-reconciliation-timer) verifies data consistency

Manual Sync​

To trigger a manual sync:

  1. Navigate to Settings > Integrations > PSA
  2. Click Sync Now
  3. Books pulls all unsynced events since the last sync

Idempotency​

Every PSA event has a unique event_id. Books tracks processed events to prevent duplicates — if the same event is received twice, the second is ignored.

Resolving Sync Issues​

Unmapped Categories​

If a PSA event references a service category without a GL mapping:

  1. The event is logged in Integrations > Event Log with status "unmapped"
  2. Create the missing mapping in COA Mappings
  3. Re-process the event

Period Conflicts​

If a PSA event tries to post to a locked accounting period:

  1. The event is logged with status "period_locked"
  2. Either unlock the period or adjust the event date
  3. Re-process the event

Viewing the Event Log​

Navigate to Integrations > Events to see all integration events:

  • Event type and source
  • Processing status (success, failed, unmapped, period_locked)
  • Timestamp and details
  • GL entry ID (if posted)
⚠️If sync appears stuck, check the event log first. Common causes: unmapped categories, locked periods, or Bus delivery issues.

Auto-Invoice from PSA Time​

Once time is synced, generate invoices:

  1. Navigate to Accounts Receivable > Invoices > New Invoice from PSA Time
  2. Select the customer and date range
  3. Books shows all uninvoiced billable time for that customer
  4. Review line items (hours, rate, description from PSA)
  5. Adjust or add additional items as needed
  6. Send the invoice

Next Steps​