What is the Autotask Integration?

The Autotask PSA Integration automatically imports customer data, service contracts, and time entries from your Autotask account into Pracbill. This eliminates manual data entry and ensures your billing information stays synchronized with your PSA system.

What gets synced:

• Customers - Automatically created when needed

• Service Contracts - Active contracts matching your SKU filter

• Time Entries - Billable and approved time entries

How often: Daily at 2 AM (automatic), or on-demand via the admin dashboard

Prerequisites

Before setting up the Autotask integration, you'll need:

1. Autotask Administrator Access - To create API credentials

2. API Username and Secret - Created in Autotask

3. Pracbill Admin Access - To configure the integration

Getting Started

Autotask Integration - Quick Start Onboarding Guide

Using the Sync Dashboard

The Sync Dashboard provides real-time monitoring and manual control of the Autotask integration.

Access: Navigate to Admin → Autotask.

Dashboard Overview

The dashboard displays four key sections:

1. Sync Status Overview

At-a-glance metrics in colored cards:

• Last Sync (Blue) - Time since the last sync operation (e.g., "2 hours ago", "Never")

• Total Syncs (Gray) - Total number of sync operations performed

• Successful (Green) - Number of successful sync operations

• Failed (Red) - Number of failed sync operations

2. Manual Sync Operations

Two primary sync triggers:

Sync Contracts:

• Imports/updates all active contracts from Autotask

• Automatically creates customers on-demand

• Optional: Check "End expired contracts" to mark expired contracts as ended

Sync Time Entries:

• Imports billable time entries from Autotask

• Configure date range with Start Date and End Date pickers

• Default: Last 7 days to today

• Applies your configured fixed hourly rate

How to Trigger a Manual Sync:

1. Choose the sync type (Contracts or Time Entries)

2. Configure options (e.g., date range for time entries)

3. Click the sync button

4. You'll see a confirmation: "Contract sync has been queued. Check the logs for progress."

5. The sync runs in the background using Laravel Horizon

6. Page will refresh automatically after 2 seconds

Important: Manual syncs are queued asynchronously. They don't run instantly but are processed by background workers (usually within seconds).

3. Sync Type Breakdown

A table showing sync statistics by type:

Use this to identify which sync types have the most errors.

4. Recent Activity

The last 10 sync operations across all types, showing:

• Time - When the operation occurred (relative time, e.g., "5 minutes ago")

• Type - Sync type (Contract, Time Entry, Company)

• Operation - Action performed (create, update, skip, error)

• Status - Result (Success, Warning, Error)

• Message - Brief description of what happened

Status Badges:

• Green badge = Success

• Yellow badge = Warning

• Red badge = Error

• Gray badge = Other

Click View All Logs to see the complete log history with filtering.

Quick Links

Navigate to related pages:

• Configuration - Return to API credentials and settings

• View Logs - Access the full log viewer with filtering

Using the Log Viewer

The Log Viewer provides comprehensive visibility into all Autotask sync operations with advanced filtering and export capabilities.

Access: Access from the link in the dashboard

Example Filters:

• View only errors: Status = "Error"

• View contract syncs from last week: Sync Type = "Contract", Start Date = (7 days ago)

• View all activity from yesterday: Start Date = yesterday, End Date = today

Click Apply Filters to refresh the log table.

Log Table

The log table displays detailed information:

Status Badges:

• Green = Success

• Red = Error

• Yellow = Warning

• Gray = Other

Duration: Helps identify slow operations. Most operations should complete in under 500ms.

Viewing Log Details

For logs with additional details:

1. Click the View button in the Details column

2. A modal window opens showing JSON-formatted details

3. Details may include:

   • Field values that were synced

   • Error stack traces

   • API response data

   • Validation errors

4. Click Close or press Escape to close the modal

Exporting Logs

Export filtered logs to CSV for external analysis:

1. Apply your desired filters

2. Click the Export CSV button (top right)

3. A CSV file downloads with the name: autotask_logs_{department_id}_{timestamp}.csv

CSV Columns:

• ID

• Sync Type

• Operation

• Status

• Message

• Duration (ms)

• Created At

Use Cases:

• Share logs with support team

• Import into Excel for analysis

• Create reports for management

• Archive historical data

Quick Actions

• Back to Dashboard - Return to the Sync Dashboard

• View Statistics - View aggregated statistics (redirects to statistics endpoint)

Pagination

Navigate through logs using the pagination controls at the bottom of the table:

• First - Jump to first page

• Previous - Go back one page

• Page Numbers - Jump to specific page

• Next - Go forward one page

• Last - Jump to last page

The pagination preserves your filters, so you can browse through filtered results.

Understanding the Sync Process

Automatic Daily Sync

Once configured, the integration runs automatically every day at 2 AM. Here's what happens:

1. Contract Sync - Fetches active contracts from Autotask

   • Only contracts matching your SKU prefix are imported

   • Customers are created automatically if they don't exist

   • Existing contracts are updated with latest information

2. Time Entry Sync - Fetches billable time entries

   • Only billable and approved entries are imported

   • Time entries are linked to the corresponding service contracts

   • Your configured fixed hourly rate is applied

   • Entries from the last 90 days (or your configured window) are synced

Contract Service Field Mapping

When contracts are synced from Autotask, the following fields are mapped to Pracbill Engineering services:

Using Internal Description for Service Identifiers:

The internalDescription field on Autotask ContractServices is mapped to the service_num field in Pracbill. This allows you to store service-specific identifiers like:

• Phone numbers (e.g., 0412345678)

• Usernames (e.g., john.smith)

• Serial numbers (e.g., SN-12345)

• Account IDs (e.g., ACC-001)

How to set it up in Autotask:

1. Navigate to the Contract in Autotask

2. Go to the Services tab

3. Edit the ContractService line item

4. Enter the service identifier in the Internal Description field (max 100 characters)

5. Save the changes

6. Run a contract sync in Pracbill

The internal description is not visible on invoices - use the Invoice Description for customer-facing text.

Manual Sync via UI

You can trigger syncs manually from the Sync Dashboard:

1. Navigate to the Sync Dashboard

2. Choose Sync Contracts or Sync Time Entries

3. Configure options (e.g., "End expired contracts" or date range)

4. Click the sync button

5. Sync is queued and runs in the background

6. Monitor progress in the Recent Activity section or Log Viewer

How Customer Import Works

Important: The Autotask integration uses an on-demand customer import strategy.

• Customers are NOT bulk imported from Autotask

• Instead, customers are created automatically when a contract is synced

• Only customers with contracts matching your SKU prefix will be imported

• This keeps your customer list clean and relevant

Example Flow:

1. Contract sync finds "PRACBILL-Managed-Services" contract

2. Contract belongs to "Acme Corporation"

3. System checks if "Acme Corporation" exists in Pracbill

4. If not, system fetches company details from Autotask and creates customer

5. Contract is then linked to the customer

Monitoring Sync Activity

Using the Sync Dashboard

The dashboard provides real-time visibility:

1. Status Overview - See last sync time and success/failure counts

2. Sync Type Breakdown - Identify which types have errors

3. Recent Activity - Last 10 operations across all types

Recommended: Check the dashboard weekly to ensure syncs are running smoothly.

Using the Log Viewer

For detailed troubleshooting:

1. Filter by Status = "Error" to see all failures

2. Check the Message column for error descriptions

3. Click View in the Details column for full error information

4. Export logs to CSV for support tickets

Understanding Log Statuses

Common Sync Scenarios

Scenario 1: New Customer Contract

In Autotask:

• You create a new contract "PRACBILL-Website-Hosting" for "New Company Inc"

In Pracbill (after next sync or manual sync):

1. Contract sync detects new contract with "PRACBILL" prefix

2. "New Company Inc" is automatically created as a customer

3. Service "PRACBILL-Website-Hosting" is created and linked to customer

4. Log entry shows: Operation = "create", Status = "success"

How to verify:

1. Check Recent Activity on the Sync Dashboard

2. Look for "contract" type with "create" operation

3. Navigate to Customers to see the new customer

4. Navigate to Engineering Services to see the new service

Scenario 2: Logging Billable Time

In Autotask:

• Your team logs 5 hours of billable work on a contract

• The time entry is marked as billable and approved

In Pracbill (after next sync):

1. Time entry sync detects new billable entry

2. System finds the matching service contract

3. Time entry is imported and calculated: 5 hours x $150/hour = $750

4. Entry is ready to be included on the next invoice

5. Log entry shows: Type = "time_entry", Operation = "create", Status = "success"

How to verify:

1. Go to Sync Dashboard -> Recent Activity

2. Look for "time_entry" type entries

3. Check Engineering Items (i_eng_srv) table for the new entry

Scenario 3: Contract Ends

In Autotask:

• You set an end date on a contract

In Pracbill (after next sync):

• Contract sync detects the end date

• Service is marked as ended in Pracbill

• No new time entries will be synced for this contract

• Contract remains in history for reporting