PSA integration best practices

A Professional Services Automation (PSA) connection is the source of your companies, contacts, opportunities, and first product list. You can have one PSA connected at a time — Autotask, ConnectWise, or HaloPSA.

Do the work in the PSA first, then map into one Salesbuildr category tree. The first sync imports what is already active and mapped. It does not tidy a messy catalog for you.

This article is for admins connecting Autotask, ConnectWise, or HaloPSA. The full workspace sequence — PSA, categories, distributors, catalog, pricing, templates, users — is in Set up Salesbuildr in this order.

Key rules

• Clean up the PSA product list and categories before you save credentials. The first sync imports what is already active and mapped; it does not tidy a messy catalog.
• You can have one PSA connected at a time. Map Autotask, ConnectWise, or Halo groups into one Salesbuildr category tree — unmapped groups skip items.
• Edits you make in Salesbuildr push as they happen. What comes back, and when, is different for Autotask, ConnectWise, and HaloPSA — do not assume they behave the same.
• Quote in Salesbuildr and push the quote to the PSA. Do not treat the PSA quote screen as the system of record unless that PSA writes the field back.
• When sync looks wrong, open the record’s sync card first. Do not run a full Synchronize as the first step.
• Confirm the connection at Settings → Integrations → Manage → Configure (Save and Verify, do not turn the integration off) and that webhooks or callbacks are installed.

Before you connect: clean up the PSA product list and categories first

The first product import takes active catalog rows only. Unused, duplicate, or badly named items that are still active in the PSA will land in Salesbuildr as soon as you map their category.

Do this in the PSA before you save credentials in Salesbuildr.

In any PSA

1. Deactivate discontinued products, services, and labour. If they are still active, they are eligible for the first import.
2. Retire unused product groups or categories. Every group you keep will need a Salesbuildr mapping. Unmapped groups skip items (see each PSA below).
3. Fill in manufacturer part numbers (MPNs) on hardware you will later match to a distributor feed.
4. Standardize names you want on quotes. The name in the PSA is the name that arrives in Salesbuildr.

Do not build a second product list in Salesbuildr first. Until a PSA is connected you also cannot create a new root category under Products → Categories.

Autotask

• Products and labour import only when Active. Inactive services are not created as new catalog rows.
• An Autotask product, service, or labour item with no mapped Salesbuildr category is skipped — it never appears in the catalog. Services also need their billing code mapped.
• If a service name starts with its MPN, Salesbuildr strips that prefix on import (to avoid putting an MPN on customer-facing quotes). When the name is the MPN, the Salesbuildr name comes through blank. Rename those services in Autotask to a customer-friendly name, or turn on Import service name including MPN on Settings → Integrations → Autotask → Data import → Product Import.
• Saving Autotask credentials for the first time replaces manually created Salesbuildr products and resets opportunity field lists (payment terms, pipeline stages, categories, sources, loss reasons). Finish Autotask catalog cleanup before that save.

Credential fields and first connection: Autotask Setup.

ConnectWise

• Catalog import includes only items that are not inactive.
• An item whose subcategory or product type is unmapped is skipped. No partial product is created.
• Sites on a ConnectWise company become delivery addresses on one Salesbuildr company — they do not become separate companies.
• Decide which ConnectWise company statuses should import, and map company types, before you rely on opportunity import. An opportunity is skipped when its company is missing in Salesbuildr. Companies whose Salesbuildr type is the configured Manufacturer type are not used as the company on an imported opportunity.
• Do not leave disabled ConnectWise product categories in place if you will map them. A mapping that later points at a disabled category fails quote sync. See PSA Sync Issues.

Credential fields and first connection: ConnectWise Manage Setup.

HaloPSA

• Item import uses Halo’s active-only filter. Obsolete items are not imported.
• After you are connected, marking an item Obsolete in Halo unlists it in Salesbuildr. Deleting the Halo item removes the Salesbuildr product.
• Halo product groups become the units you map to Salesbuildr root categories. Collapse unused groups before you import them.
• Parent-company links import as a single parent (child → top-level Halo client). A parent you set later in Salesbuildr is not written back to Halo. Clean the Halo client hierarchy if you care about that parent showing correctly on first import.

Credential fields and first connection: HaloPSA Setup.

Map categories into one clean Salesbuildr tree

Product import works through category mapping. You map each PSA group to a Salesbuildr category, then run the product sync. Only items in mapped groups are imported.

A product that is imported still cannot go on a quote if it has no category. Category is what Salesbuildr uses for markup, tax, discount-group rules, and which product table the line lands in.

Map both sides of an acquisition into one Salesbuildr tree. Do not import two parallel “Hardware / Hardware” structures and leave quoters to guess.

Create the Salesbuildr tree under Products → Categories after the PSA is connected. Use Listed off on a category while you tidy it — quote managers will not see that category in pickers until you list it. Category behaviour: Categories.

Then run the first product pull:

• Autotask: Import All Mapped Categories Products and Services on the Product Import tab.
• ConnectWise: Synchronize products and services at the bottom of Categories.
• HaloPSA: Synchronize products and services at the bottom of Products.

Import and mapping detail: Importing Products. If an Autotask item fails with no category, see Cannot import Autotask product — no category mapped.

After mapping, Synchronize to Autotask / ConnectWise / HaloPSA controls whether edits in Salesbuildr are pushed back. New catalog products created in Salesbuildr are still sent to the PSA even when that toggle is off. Autotask labour is the exception — roles are imported, not pushed as products.

What syncs in each direction, and when

Do not assume Autotask, ConnectWise, and HaloPSA behave the same. Each PSA has its own real-time path, schedule, and gaps.

Edits you make in Salesbuildr are pushed to the connected PSA as they happen (companies, contacts, opportunities, and quotes that the PSA accepts). What comes back from the PSA is different for each product.

Autotask

Confirm Account and Contact webhooks show Valid under Settings → Integrations → Autotask → Webhooks. Install or update them there if they are missing.

A full pull of companies, contacts, products, and field lists is Settings → Integrations → Autotask → Synchronize. Synchronize only fields refreshes dropdown values (pipeline stages, payment terms, billing codes) without re-importing every record. On Settings → Opportunities, Refresh from source re-pulls one field list (pipeline stages, categories, sources, or loss reasons).

More Autotask screens: Autotask Configuration.

ConnectWise

Confirm company, contact, opportunity, and productcatalog show Installed under Settings → Integrations → ConnectWise → Callbacks. Reinstall with Install if a row says Not installed.

Map opportunity statuses both ways under Settings → Integrations → ConnectWise → Opportunities before you expect a ConnectWise stage to land on the right Salesbuildr status.

HaloPSA

Confirm client, user, product, ticket, and site show Installed under Settings → Integrations → HaloPSA → Webhooks.

Map quote statuses under Settings → Integrations → HaloPSA → Quotes (Draft, Sent, Approved, Declined, Expired). An unmapped Salesbuildr status blocks that quote’s Halo sync.

Map opportunity statuses both ways under Settings → Integrations → HaloPSA → Opportunities.

Keep opportunities and quotes in sync

Work in Salesbuildr for quoting. Push the quote to the PSA; do not treat the PSA quote screen as the system of record unless the table below says the PSA writes that field back.

Autotask

• Opportunity name, company, status, probability, and expected close sync both ways. Autotask has no opportunity webhook, so Autotask-side edits appear after the 10-minute pull (or after Import from Autotask / Fetch updates from Autotask).
• One-time revenue and monthly revenue sync both ways. Salesbuildr pushes those two fields on save; Autotask values come back on the same 10-minute pull (or after Import from Autotask / Fetch updates from Autotask).
• Autotask Amount and Cost on the opportunity are not the same as one-time / monthly revenue. Salesbuildr does not copy Salesbuildr revenue into Autotask Amount or Cost, and it does not import Amount or Cost back. When Salesbuildr first creates the Autotask opportunity it sends zeros for Amount and Cost (Autotask requires them), then never updates those two fields.
• Turn on Use Revenue of Quoted Items on the Autotask opportunity if Autotask should take revenue from the linked quote lines. Salesbuildr sends that flag as on only when the opportunity already has at least one quote. With the flag off, or with no quotes yet, Autotask keeps the revenue typed on the opportunity.
• Quotes created in Salesbuildr are sent to Autotask with line items and the approved PDF. Approve and send in Salesbuildr.
• If someone moves a contact to another company in Autotask, the contact webhook updates immediately but the opportunity can still sit on the old company until the next pull. Opening the quote then asks you to repair the opportunity (contact and company must match).
• Closed, lost, implemented, or deleted Autotask opportunities can stay Active in Salesbuildr when they fall outside the 10-minute window, the Autotask row was deleted, or a single-row import failed. Use Import from Autotask or Fetch updates from Autotask, or compare statuses side by side. Detail: PSA Sync Issues.

ConnectWise

• Opportunity name, company, contact, owner, status, probability, expected close, stage, type, source, and notes sync both ways when statuses are mapped.
• Revenue is not synced as an opportunity value. Imported ConnectWise opportunities are set so Salesbuildr totals come from quote lines. ConnectWise keeps its own opportunity-product totals; Salesbuildr does not write an opportunity-value field back.
• Quotes created in Salesbuildr are sent as ConnectWise opportunity products, plus the approved PDF (ConnectWise fetches it from a URL) and a one-time portal link.
• Shipping goes to ConnectWise as an opportunity product whose description is the Salesbuildr shipping-type name. The quote must be the primary quote. Shipping updates travel with the next quote sync, not on a separate shipping event.
• A new ConnectWise opportunity still needs its company (already imported, not the Manufacturer type), contact when one is set, primary sales rep linked to a Salesbuildr user, and mapped stage and status. Otherwise the callback and the 10-minute pull skip it. Open Opportunities → Import from ConnectWise after those records exist.
• If a line item never received a ConnectWise id, Send waits or fails. Use Retry on the quote sync card, or edit and save the quote, then send again.

HaloPSA

• Opportunity name, description, company, contact, status, type, probability, and value sync both ways when statuses are mapped. Opportunity stage changes in Halo update the Salesbuildr opportunity — they do not approve the quote.
• Always approve, decline, or send the quote in Salesbuildr (or on the Salesbuildr customer link). Approving only in Halo leaves the Salesbuildr quote on Waiting approval and skips Salesbuildr post-approval steps (emails, approved PDF, later sales-order actions).
• After you approve in Salesbuildr, the mapped Halo quotation status is pushed automatically.
• A Halo shipping charge line is added only when the quote has shipping and Shipping Product Mapping is set on Settings → Integrations → HaloPSA → Products → Defaults. The line uses the mapped Halo item’s name, not the Salesbuildr shipping-type label. That label is not written to Halo.
• Halo sales-order lines do not include shipping. Creating a Halo sales order is a separate Create sales order action on the quote — quote approval does not create it.
• Import from Halo on the opportunities list can also pull missing companies and contacts that the opportunity references.

Manual import buttons and skip reasons: Pipeline & Importing.

When sync looks wrong: what to check first

Start with the record in front of you, then the connection, then the mapping for that PSA. Do not run a full Synchronize as the first step.

1. Open the sync card on the quote, opportunity, company, contact, or product. Use Retry when the card shows an error. Admins can also work the queue at Settings → Tools → Issues (Retry or Dismiss).
2. Wait for that PSA’s inbound path. Autotask opportunity edits are not instant — wait up to about 10 minutes, or use Import from Autotask / Fetch updates from Autotask. ConnectWise opportunity callbacks are real time when Installed; the scheduled pull is every 10 minutes. Halo opportunity and item webhooks are real time when Installed; quotes never come back from Halo.
3. Verify the connection at Settings → Integrations → Manage → Configure, then Save and Verify. Do not turn the integration off. See Update your PSA connection.
4. Confirm the category (and Autotask billing code) mapping for the product on the quote. Unmapped Autotask items never enter the catalog. Disabled ConnectWise categories break quote sync. Halo items in an unmapped product group never import.
5. Confirm webhooks or callbacks are installed (Autotask Webhooks, ConnectWise Callbacks, HaloPSA Webhooks).
6. Check the prerequisite records the PSA requires for that opportunity or quote (company, contact, owner / sales rep, mapped status). ConnectWise opportunities are skipped when those are missing. Autotask opportunities are skipped without a linked company, owner, and (when Autotask sent a contact) a matching contact.

Autotask-specific checks

• “BillingCode does not exist or is invalid” — map the Salesbuildr category under Settings → Integrations → Autotask → Billing Codes.
• “Opportunity was not found in Autotask” — the Autotask opportunity was deleted or is gone. Confirm it in Autotask, then retry or unlink.
• “companyID is not associated with contactID” — fix the company–contact link in Autotask, or use Manage opportunity on the quote.
• Autotask shows fewer active opportunities than Salesbuildr — expected when historical closures sit outside the 10-minute pull window. Pull those rows on demand.
• Service prices in Autotask should stay Autotask’s. Current sync does not push Salesbuildr prices onto a linked Autotask service.

ConnectWise-specific checks

• “catalogItem object is invalid” / inactive category — remapping steps are in PSA Sync Issues. Set a Default category on the Defaults tab so a later disabled category does not hard-fail the product.
• “opportunity object is invalid. contact … not found” — the stored ConnectWise contact id is gone. Re-sync the contact, point the opportunity at a live contact, then Retry the opportunity.
• “The item … has not been synchronized with connectwise yet” — wait for the in-flight push (Send retries automatically), or Retry the quote. Option-group candidates, unticked add-ons, and zero-quantity lines are not pushed as ConnectWise products.
• “Already synchronizing” — wait; do not stack another full sync.
• “ConnectWise API rate limit exceeded” — Salesbuildr backs off and retries. Wait a few minutes, then retry the failed card.

HaloPSA-specific checks

• Quote still Waiting approval after someone approved it in Halo — approve it in Salesbuildr. Halo cannot complete that workflow.
• “Quote status mapping is missing” — map that status under Settings → Integrations → HaloPSA → Quotes.
• “HaloPSA opportunity status not found” — add the Halo stage to HaloPSA → Salesbuildr on the Opportunities tab.
• Duplicate Halo item name — Halo may require unique item names. See Duplicate name in HaloPSA.
• Sync pauses or fails during a large import — Halo allows 700 requests per 5 minutes for the whole instance. Wait and retry; do not start another full product import on top.
• Geolocation or persistent 401 after Verify — Halo is blocking the Salesbuildr region, or the application credentials were rotated. Update Base URL, Client ID, and Client Secret together.

Error catalog and retry steps: PSA Sync Issues.

See also

• Update your PSA connection — replace Autotask, ConnectWise, or HaloPSA credentials without turning the integration off
• PSA Sync Issues — Autotask, ConnectWise, and HaloPSA synchronization errors
• Set up Salesbuildr in this order — PSA, categories, distributors, catalog, pricing, templates, then users
• Importing Products — category mapping and the first product sync
• Categories — listed / unlisted categories and defaults
• Pipeline & Importing — Import from Autotask / ConnectWise / Halo
• Quoting best practices for new quoters — catalog cleanup after the first import
• Autotask Setup
• ConnectWise Manage Setup
• HaloPSA Setup