Set up the Autotask PSA integration

The Autotask PSA integration connects octoja to your Autotask instance so that monitoring alarms turn into tickets your team already works in. Setting it up takes three things: the connection itself, the ticket settings, and an alert rule that routes alarms to Autotask.

What the integration does

Once connected and configured, the integration does three separate jobs:

• Creates a ticket from an alarm — when a monitoring check raises an alarm and an alert rule routes it to the Autotask channel, octoja opens a ticket on the matched Autotask company.
• Handles the recovery — when the check recovers, octoja always adds a note to that ticket, and closes the ticket when nobody has picked it up yet.
• Syncs devices as configuration items — optionally, once an hour, octoja creates or updates a configuration item in Autotask for each of your devices.

Everything runs outbound, from octoja to Autotask. octoja only ever touches the tickets it created itself, and it never deletes anything in Autotask.

Connecting on its own creates nothing. A connected integration with every setting filled in still produces zero tickets until an alert rule points at the Autotask channel. That routing step is Step 5 below, and it is the one people most often miss.

Prerequisites

• The Integration Management permission in octoja. Permissions are assigned under Administration → Groups.
• The Customer Management permission as well, if you also want to import customers from Autotask.
• An Autotask API user, with its API integration code, its username, and its secret. Autotask generates all three; octoja never creates them.
• That API user needs to create tickets and update their status, create ticket notes, and query, create and update configuration items. It also needs to read companies, company locations, products, and the ticket priority, status and queue picklists. Which Autotask security level grants exactly that is decided on the Autotask side — check with Autotask if you are not sure.
• A monitoring check that already runs, so there is an alarm to turn into a ticket.

Step 1 — Gather your Autotask API credentials

Collect the three values your Autotask API user was issued: the API integration code, the username of that API user, and its secret. You will paste all three into octoja in the next step.

There is no server, region or zone field to fill in. octoja works out which Autotask zone your instance lives in from the credentials themselves.

Step 2 — Connect octoja to Autotask

1. In octoja, go to Administration → Integrations and find the Autotask PSA card.
2. Click Set up. The Set up Autotask PSA dialog opens.
3. Fill in the three fields:

4. Click Test connection. octoja contacts Autotask with the credentials you entered and reports Connection successful. or the error Autotask returned.
5. Click Connect. octoja stores the credentials and opens the Autotask integration page on its Configuration tab.

Test connection is optional, but use it anyway. Connect does not verify your credentials — octoja saves whatever you type without asking Autotask whether it works. Wrong credentials connect perfectly happily, and the mistake only surfaces afterwards, when the configuration page shows the banner Autotask rejected the connection and all the dropdowns below it stay empty. One click on Test connection before you connect turns an hour of debugging into a clear error message.

Step 3 — Match customers to Autotask companies

Autotask requires a company on every ticket, so octoja needs to know which Autotask company each of your customers is.

1. On the Configuration tab, find the Customer mapping section.
2. Click Match customers and pair each octoja customer with its Autotask company. Save the dialog.
3. Click Match sites to map each customer's octoja sites to Autotask company locations. This button stays disabled until at least one customer is matched, so do the customer matching first.

In the site dialog, … → Auto-match by name fills unambiguous name matches within each customer. Existing mappings are preserved and ambiguous matches stay open. Review the suggestions and save the dialog.

A device whose customer has no matched company is skipped: no ticket is created for it. The attempt is recorded on the History tab as a successful delivery reading skipped: no company match, so it reads green rather than as an error. If tickets are missing for one customer only, this is the first thing to check.

The company dropdown lists only companies that are active in Autotask and have the company type Customer. Prospects, leads, vendors and inactive companies do not appear.

Step 4 — Choose the queue, priorities and statuses

The Ticket mapping section decides what a ticket looks like. Several of these settings are hard requirements: if one is missing, octoja skips the ticket silently — nothing shows up in octoja at all, not even on the History tab.

Fill in at least the queue, the status for new tickets, and the priority for the severity you expect to be alerted on. Set both priorities if you want tickets for Warning and Critical alike.

Settings are not saved automatically. Every dropdown you change stays local until you click Save settings in the page header, or press Ctrl+S.

All of these dropdowns are filled from Autotask picklists, and values that are inactive in Autotask are filtered out. If somebody deactivates a status or a queue in Autotask, it quietly disappears from the dropdown here while octoja keeps using the stored value — so re-pick it after any picklist cleanup on the Autotask side.

Step 5 — Route alerts to the Autotask channel

This is the step that makes tickets appear. Everything so far only prepared octoja; no alarm reaches Autotask until an alert rule sends it there.

1. Open the config package that contains the check you want tickets for, go to its Checks tab and open the check.
2. Switch to the check's Alert tab and pick or create an alert configuration.
3. In that configuration, add the channel Autotask ticket.
4. Set the rule for the channel — the share of recent results and the minimum severity that has to be reached — and save the check.

Autotask is a single, tenant-wide channel: once you pick Autotask ticket there is nothing else to select, no target and no queue to choose again. The channel only appears in the picker while the integration is connected.

For the full walkthrough of alert configurations, rules and schedules, see Set up alerts for a check.

A ticket octoja opens is titled octoja: check "<check>" on <device>. Its description names the check, the device, the reported status and how many of the last runs failed, followed by the check's own output and a link back to the device's check page in octoja. If the matched company already has a configuration item for that device — matched on the octoja device id first, on the hostname second — octoja links the ticket to it; if not, the ticket is created without one rather than failing. When the device belongs to a site with a matched Autotask location, that location is set on the ticket too.

What happens when a check recovers

Recovery is handled in two parts, and only the first is unconditional.

Only tickets octoja created for that alarm are touched. If the original ticket was skipped — because a setting was missing or the customer was unmatched — there is nothing to comment on, and the recovery passes without a trace in Autotask.

Step 6 — Sync devices as configuration items (optional)

Device sync keeps Autotask's configuration items in step with your octoja devices. It is off until you turn it on.

1. Under Device products, pick an Autotask product for each device kind you want to sync — Windows Server, Windows Workstation, Linux Server, macOS, Switch, Firewall and so on. Autotask derives the configuration item type from the product. Kinds you leave unset are skipped.
2. In the Device sync section, turn on Automatically sync devices hourly.
3. Click Save settings.

Sync runs on an hourly schedule rather than on demand, so the first run follows within the hour of saving. For each matched customer, octoja creates or updates one configuration item per device and writes the hostname, the octoja device id, the serial number, the primary IP address, the MAC address, the operating system, the matched company location and the mapped product.

Existing configuration items are recognised by the octoja device id in the reference number field, falling back to the hostname in the reference title. Devices without a name, and devices whose kind has no product mapped, are skipped. Configuration items are never deleted — if you remove a device in octoja, tidy up its configuration item in Autotask yourself.

If another system previously synced these configuration items, compare their reference titles with the device names in octoja before enabling sync. For agent-managed devices, this is the reported machine name, not the editable alias. Without octoja's device id in the reference number, a matching title (ignoring case and surrounding whitespace) lets octoja update the existing item. If neither field matches, octoja creates a new item, potentially a duplicate; serial numbers alone are not used for matching.

Each run is recorded on the History tab as a Device sync entry with its created, updated and skipped counts, and the Device sync section shows when the last run finished. As long as no device kind has a product mapped at all, the hourly run has nothing to do and writes no entry — so an empty History tab after switching sync on usually means Device products is still blank.

Import customers from Autotask

If your customers do not exist in octoja yet, you can seed them from your Autotask companies. This lives on the Customers page, not on the integration page.

1. Open Customers and choose Import from ticketing system.
2. Select the Autotask companies you want and confirm the import.

Each selected company becomes an octoja customer, its Autotask locations become octoja sites, and both the company match and the site matches are created for you — so an imported customer needs no manual matching in Step 3. Every company that is already matched to an octoja customer is marked Already imported and skipped — including the ones you paired by hand in Step 3.

The menu item opens the first connected ticketing system in a fixed order: DocBee, HaloPSA, Inserve, Autotask, Codemeta OS, Odoo, Jira, TOPdesk, TANSS, c-entron Service-Board, Freshservice, Zammad. If one of the first three is connected as well, its import dialog opens instead of Autotask's.

When tickets stop arriving

The History tab lists recent ticket, recovery and device-sync attempts with their outcome and response, and is the place to look whenever a ticket you expected is missing.

• The banner "Autotask rejected the connection" is showing. The stored credentials are no longer valid, so the dropdowns cannot load. Disconnect and connect again with working credentials — and click Test connection first this time.
• A delivery failed. octoja retries a failed ticket create or close after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. Errors Autotask reports as a client mistake are not retried, because repeating them would not change the answer. A failed device sync is not retried either — the next hourly run picks it up.
• The card shows the status Paused. After 20 consecutive delivery failures octoja stops sending, so a broken connection does not keep hammering Autotask. To resume, use Disconnect Autotask and connect again with the same credentials. Your matches and settings survive the round trip, so nothing has to be set up twice.
• Tickets are missing for one customer. Check the History tab for skipped: no company match and match that customer in Step 3.
• No tickets at all. Confirm that the queue, the status for new tickets and the priority for that severity are set, and that an alert configuration on the check really includes the Autotask ticket channel.

Disconnect Autotask

To remove the connection, open the Autotask integration page, scroll to the danger zone and click Disconnect Autotask, then confirm with Disconnect.

Only the three credentials are removed. Your customer and site matches, all ticket and sync settings, and the delivery history stay exactly as they were, and every ticket and configuration item already created remains in Autotask. Reconnecting later is a matter of entering the credentials again.

Tips

• If a company is missing from the dropdown, check in Autotask that it is active and has the company type Customer.
• The product dropdown lists only active Autotask products that have a name.
• Click Save settings after every change — a dropdown you changed but did not save has no effect on the next alarm.
• Set both Priority for Warning and Priority for Critical unless you deliberately want tickets for one severity only.
• Rename devices in octoja rather than in Autotask. The octoja device id is stable, so a rename in octoja is matched correctly, while renaming a configuration item in Autotask before the first sync can produce a second one.
• Leave Status when closing on recovery empty if your team prefers to close tickets by hand — recoveries are still noted on the ticket.