TimeZest PSA Integration

TimeZest PSA Integration

TimeZest exists to couple customer scheduling to the MSP's PSA. The booking page is incidental — the value is that a confirmed slot lands on the ConnectWise / Autotask / Halo ticket, on the technician's PSA calendar, and in the billing record. Two parts of the scheduling request payload carry that coupling: associatedEntities and triggerMode.

Anti-triggers

This skill shapes the TimeZest side of the link. It has no PSA credentials and cannot read or write a ticket:

• Reading, updating, or closing the ticket — status, notes, time entries, assignment; use connectwise, halopsa, or the autotask plugin.
• Finding the ticket to book against — ticket search and triage happen in the PSA; arrive here with the ID already resolved.
• Configuring the PSA-side integration — the pod workflow, its notification templates, and the TimeZest app install are configured in the PSA and in the TimeZest web UI, not through these tools.
• A booking that never sent, as opposed to one that never synced — a request stuck before delivery is a scheduling-request state question; use timezest-scheduling.

associatedEntities — the PSA link

Every timezest_scheduling_create_request call should carry an associatedEntities array. Each entry links the booking to one PSA record:

{
  "associatedEntities": [
    {
      "type": "connectwise",
      "id": "88421",
      "number": "88421"
    }
  ]
}

A scheduling request created with no associatedEntities is an orphan — nobody can find the booking from the PSA side later. Always attach the association.

triggerMode — pod vs generate_url

pod is the right default for any booking tied to a ticket. generate_url against a ticket is usually a mistake worth confirming.

Common Workflows

Build a PSA-linked booking

1. Identify the PSA system the ticket lives in (connectwise, autotask, or halo) — critical when the MSP runs more than one PSA in parallel.
2. Build the associatedEntities entry with type, id, and number when known.
3. Set triggerMode: "pod" unless the dispatcher specifically wants a manual link.
4. Pass both into timezest_scheduling_create_request.

Audit requests for PSA association

1. Call timezest_scheduling_list.
2. Inspect each request's associatedEntities and bucket:
   • clean — one association, plausible type, has a number
   • orphan — no association at all
   • suspect — association present but the type looks wrong for the MSP's PSA mix
3. Pull timezest_scheduling_get for any orphan or suspect request.

Diagnose a booking that did not sync

1. timezest_scheduling_get the request — confirm it is booked.
2. Check triggerMode: a generate_url request never fires the PSA workflow, so the ticket was never meant to update automatically.
3. Check associatedEntities: a missing or wrong-type association means the workflow had nothing to update.
4. Remediation: re-create with a corrected payload, or add a manual PSA note so the booking is not lost.

Edge Cases

• Multiple PSAs — One MSP may run ConnectWise and Autotask side by side. The type enum must match the ticket's actual system.
• Cross-system ID mismatch — A ConnectWise ticket ID linked as autotask resolves to nothing. Verify the pairing.
• generate_url on a ticket — Produces a working link but no PSA update. Flag and confirm intent.

Best Practices

• Never create a scheduling request without a PSA associatedEntities entry.
• Default triggerMode to pod for ticket-driven bookings.
• Always include number when known — it makes the request findable by humans.
• Treat the scheduling request as the source of truth until the pod workflow confirms the PSA was updated.

Related Skills

• scheduling — Booking technicians against PSA tickets
• api-patterns — Auth, navigation, polling cadence