Autotask PSA Troubleshooting Guide
If your Autotask sync isn't behaving the way you expect, this guide walks through the most common issues and how to resolve them.
If your Autotask sync isn't behaving the way you expect, this guide walks through the most common issues and how to resolve them. Work through the sections in order. Most issues are caught in the first two checks.
- What a healthy Autotask sync looks like
- Sync didn't start or is stuck
- An account isn't appearing in Gradient
- A service or contract line isn't appearing
- PSA counts don't match
- Stale or old contract lines
- Microsoft NCE renewals creating duplicates or wrong dates
- Reversing a pushed change
- Still need help?
What a healthy Autotask sync looks like
Before troubleshooting, it helps to know what Gradient expects from your Autotask environment. For an account, contract, or service to appear in Reconcile, all four of the following must be true:
- The account exists in Autotask as an active Customer (not a Prospect).
- The account has at least one current, active recurring service contract.
- That contract has the vendor's services listed with a quantity greater than zero.
- A PSA sync has completed since those records were created or updated.
Gradient pulls from Autotask. It does not push setup data back. If something is missing in Autotask, it will be missing in Gradient until you add it in Autotask first and then sync.
Quick reference: which section do I need?
| If you're seeing… | Go to section |
|---|---|
| The sync is stuck, hung, or didn't start | 1. Sync didn't start or is stuck |
| An account isn't appearing in Gradient | 2. An account isn't appearing |
| A service or contract line isn't appearing | 3. A service or contract line isn't appearing |
| Gradient's PSA count doesn't match Autotask | 4. PSA counts don't match |
| Old services or zero-quantity lines won't go away | 5. Stale or old contract lines |
| Microsoft NCE renewals are creating duplicates or wrong dates | 6. Microsoft NCE renewals |
| I pushed something to Autotask and need to undo it | 7. Reversing a pushed change |
1. Sync didn't start or is stuck
If a sync has been running for an unusually long time or never appeared to start, work through the following:
Step 1: Confirm the last successful sync
In Gradient, check the sync status indicator. A sync that has been running for more than 30 minutes is usually stuck rather than working.
Step 2: Initiate a full PSA sync
If the sync is hung or you suspect cached data, manually trigger a full sync. See the article How to initiate a full PSA Sync.
Step 3: Check your Autotask API user
If the sync repeatedly fails to start, the API user credentials may have expired or been disabled in Autotask. Verify in Autotask under Admin > Resources/Users > API User that the Gradient API user is active and has the correct security level.
Do not delete and recreate the API user. Reset the secret or re-enable the user instead. Deleting and recreating breaks the connection to Gradient and requires re-integration.
2. An account isn't appearing in Gradient
If a customer is in your Autotask but you can't see them in Gradient, use the following decision table to identify which requirement isn't being met.
| Check this in Autotask | What it should be | Where to look |
|---|---|---|
| Account Type | Customer (not Prospect, Lead, Vendor, or Partner) | CRM > Accounts > [Account] > General |
| Account Status | Active | CRM > Accounts > [Account] > General |
| Has at least one current contract | Yes, with today's date falling between Start and End | Contracts > Contracts (filter by account) |
| Contract has Services with qty > 0 | Yes | Inside the contract record > Services tab |
| A sync has run since changes were made | Yes | Gradient sync status |
If all five of the above are true and the account still isn't appearing, perform a full PSA sync and wait for it to complete before checking again. For additional context, see PSA Account Visibility Troubleshooting.
Future-dated contracts will not appear in Gradient until their start date arrives. If you've set up a contract with a start date of, for example, the first of next month, the account and services will only become visible on that date.
3. A service or contract line isn't appearing
If the account is visible but a specific service or contract line is missing, the issue is usually at the contract level.
Common causes
- The service was added to the contract but no sync has run since.
- The contract start date is in the future.
- The service quantity is zero. Gradient does not bring across lines with a quantity of zero.
- The service is on a non-recurring contract type. Reconcile works against recurring service contracts.
- The service is part of a Service Bundle that hasn't been correctly flagged in Autotask. See Service Bundle Best Practices for Autotask PSA.
How to verify in Autotask
- Open the contract in Autotask: Contracts > Contracts > [Contract Name].
- Confirm the Contract Period Type is set to a recurring type, with a Start Date on or before today.
- Open the Services tab on the contract.
- Confirm the service is listed with a quantity greater than zero.
- Run a full PSA sync in Gradient.
If the service still does not appear, see Not Ready - No Services Detected.
Set new recurring service contracts to start on the first of the previous month rather than today. This ensures the contract is fully active when Gradient first syncs it and avoids edge cases at month boundaries.
4. PSA counts don't match
When Gradient shows a different PSA count than what you see in Autotask, work the following five-step diagnostic in order. Most mismatches are resolved by step 3.
Step 1: Confirm the sync completed
If the sync is mid-run or recently failed, what Gradient displays may be from the previous successful sync. Check the sync status timestamp and run a full PSA sync if needed.
Step 2: Compare like with like
Open the contract in Autotask and verify the quantity directly on the affected service line. Take note of the exact contract name and the exact service line you're comparing. Mismatches often turn out to be different contracts or different service lines than expected.
Step 3: Check for stale or zero'd contract lines
If a service was previously on a contract and has since been changed to a quantity of zero, the line can persist in Gradient's view for one or more billing cycles. See section 5 below, and Incorrect PSA Data? Old Services?
Step 4: Verify service mapping
A count that looks wrong is sometimes a mapping problem rather than a count problem. The vendor may be reporting a total (for example, total mailboxes protected) while you're billing on a subset (for example, billable mailboxes). Open the affected service in Reconcile and confirm:
- The vendor service is mapped to the correct Autotask service line.
- The vendor metric being pulled is the one you intend to bill against.
For details, see Service Mapping and Integration Account and Service Mapping.
Step 5: Check for back-dated changes
If a quantity was changed in Autotask with an effective date in a past period, the change may not be reflected the way you expect in the current sync. Confirm with whoever made the change in Autotask what effective date was used.
If you've worked through all five steps and the count still doesn't match, open a support ticket and include: the account name, contract name, service name, expected count, count Gradient is showing, count Autotask is showing, and the timestamp of your most recent sync.
5. Stale or old contract lines
If you've reduced a service to zero on a contract in Autotask or removed it entirely, Gradient may continue to display the line for a period of time. This is most often visible in two scenarios:
- A line showing a PSA quantity of zero that won't drop off.
- A service that's been replaced by a new line, with both old and new visible.
How to clear stale lines
- Confirm the line is zero'd or removed in Autotask. Open the contract directly to verify.
- Run a full PSA sync from Gradient.
- If the line is still showing after a full sync, document the example (account, contract, service, screenshots from both systems) and open a support ticket. This pattern is occasionally caused by cached data that requires manual intervention.
Do not dismiss a stale line just to clear it from your view if you haven't yet confirmed the change in Autotask. Dismissing without verifying can hide a real reconciliation issue in the next billing cycle.
For more context, see Incorrect PSA Data? Old Services?
6. Microsoft NCE renewals creating duplicates or wrong dates
If you're seeing duplicate lines after a Microsoft NCE renewal, or the effective date of changes doesn't match how you bill, the issue is usually the effective date setting in your Microsoft Module configuration rather than an Autotask sync problem.
How Gradient handles effective dates for Microsoft NCE
Gradient gives you two options for how the default effective date is calculated when Microsoft NCE quantities change:
| Setting | Behaviour | Best for |
|---|---|---|
| First day of next billing period | Changes detected mid-cycle are applied with an effective date of the first of the next billing period. | MSPs who invoice on a fixed cycle and don't prorate mid-cycle changes. |
| Day the change was detected (Proration) | Changes are applied with an effective date equal to the day Gradient detected them in Microsoft. | MSPs who prorate licenses as they're added or removed. |
Where to change this setting
This setting lives in two places (they are kept in sync):
- Microsoft Integration Setup wizard, on the Settings and Customization step.
- Microsoft Integration Configuration page, under Billing Config.
Changing this setting affects newly detected Microsoft reconciliation items going forward. Existing reconciliation items already in your queue keep their original effective dates unless you edit them manually.
For complete details on Microsoft NCE configuration, see Managing and Updating Your Microsoft Integration Configuration.
7. Reversing a pushed change
Once Gradient has pushed a change to Autotask (a quantity update, a service addition, or a new line), Gradient does not pull those changes back.
To undo a change that has already been pushed to Autotask, you must make the correction directly in Autotask yourself. Gradient cannot remove or reverse pushed changes.
After you've made the correction in Autotask, run a full PSA sync from Gradient so its records align with the corrected state.
Review reconciliation items carefully before approving. Use the Review and Approve step to catch quantity or service mapping issues before they reach Autotask. See Reviewing and Approving Services for Reconciliation.
Still need help?
If you've worked through the relevant section and the issue isn't resolved, open a support ticket. Including the following in your ticket gets us to an answer faster:
- The account name in Autotask.
- The contract name and service name involved.
- What you expected to see, and what you're actually seeing.
- Screenshots from both Gradient and Autotask showing the same record.
- The timestamp of your most recent successful sync.
Submit a ticket at support.meetgradient.com/kb-tickets/new or email support@meetgradient.com.