ServiceTitan Connection Plan

Readiness model

What this page prepares.

This guide keeps the public promise, internal admin records, client portal reporting, and MySQL table plan aligned before more services are connected.

Source

Name the source of truth

Use ServiceTitan as the first source label before showing the data in admin reports or the client portal.

Owner

Assign operational ownership

Integration owner owns connection status, imports, field mapping, verification, and the next client-safe explanation.

Portal

Translate data into client value

Support larger service companies with strict source labels and import batch audit trails.

Baseline

Capture the first comparable period

Save the baseline before changing forms, pages, automations, campaigns, provider mappings, or report wording.

Sync

Log every import or webhook

Every automated or manual update should have provider, date range, row count, status, and an error note when needed.

Privacy

Show summaries, not secrets

Client-facing screens should show source, movement, status, and next action without exposing sensitive payloads.

Mapped tables

Database tables involved.

These tables are the first places to check when wiring this surface into the MySQL-backed admin and portal.

integration_provider_accounts
integration_sync_jobs
integration_import_batches
crm_leads
report_metrics

Build checklist

Ship it without losing trust.

Confirm whether this data belongs in the primary app database or the traffic database.
Create or select the provider account record before importing raw activity.
Map every incoming field to a ZartsAlgo table, label, owner, and client-safe explanation.
Record the baseline date range before claiming improvement.
Separate test submissions, spam, internal checks, and duplicate marketplace leads.
Store raw payloads only where the retention policy allows it.
Show rollups in the portal; keep detailed logs in admin-only views.
Write a rollback note before changing a live integration.

Metrics

Signals this can feed.

Each metric should become a report note, portal card, admin task, or connector health signal.

Metric

booked calls

Track this only when the source, date range, and units are clear enough to explain in one sentence.

Metric

revenue context

Track this only when the source, date range, and units are clear enough to explain in one sentence.

Metric

campaign source

Track this only when the source, date range, and units are clear enough to explain in one sentence.

Metric

job outcome

Track this only when the source, date range, and units are clear enough to explain in one sentence.

Implementation timeline

Move from plan to monitored workflow.

Step 1

Step 1 checkpoint

Confirm access, source label, owner, and whether the data should enter the app DB or traffic DB.

Step 2

Step 2 checkpoint

Create the field map and choose the first metric or status that will be visible to the client.

Step 3

Step 3 checkpoint

Import a small test batch or receive a test webhook and log the result in admin.

Step 4

Step 4 checkpoint

Compare baseline and current values with a clear date range and plain explanation.

Step 5

Step 5 checkpoint

Promote the connector to a monitored workflow with retention, QA, and rollback notes.

Avoid

Common failure modes.

Do not mix Search Console clicks, ad clicks, phone calls, marketplace leads, and CRM jobs under one unlabeled lead count.
Do not give the website application user DROP, ALTER, or CREATE privileges for normal runtime.
Do not store provider passwords, tokens, or webhook secrets in public PHP files.
Do not let a partial import overwrite a clean baseline.
Do not expose raw accounting, CRM, phone transcript, or private customer payloads in the client portal.
Do not call a connector live until there is a recent test, owner, and failure path.