> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msportal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Autotask PSA Integration

> Connect your Autotask PSA instance to MSPortal.ai using the step-by-step setup wizard

This guide walks you through connecting your Autotask PSA instance to MSPortal.ai using our streamlined setup wizard.

## Prerequisites

* Admin access to Autotask, or API credentials (username and secret)
* Admin access to MSPortal.ai with integration management permissions

## Part 1: Configure Autotask PSA

Before connecting to MSPortal.ai, you need to create an API user and security role in Autotask.

### Create Security Role

<Steps>
  <Step title="Access Security Settings">
    1. Navigate to [Autotask](https://ww2.autotask.net)
    2. Go to the Admin area
    3. Click **Account Settings & Users**
    4. Click **Security Levels**
  </Step>

  <Step title="Create MSPortal Security Role">
    1. Copy the default **API User (system)** role
    2. Rename it to **MSPortal**
    3. Scroll down to **Other** and enable:
       * **Can create webhooks**: Yes
       * Set webhook limit to **25**

    <Note>
      We recommend setting unused areas to "No permissions" or "Read only" to follow the principle of least privilege. However, this may cause synchronization issues if you later enable those features.
    </Note>
  </Step>

  <Step title="Save the Role">
    Click **Save & Close** to finalize the security role settings.
  </Step>
</Steps>

### Create API User

<Steps>
  <Step title="Navigate to Users">
    1. Go back to **Account Settings & Users**
    2. Select **Resources/Users**
    3. Click to add a new **API user**
  </Step>

  <Step title="Configure API User">
    Fill in the following details:

    | Field                         | Value                                                |
    | ----------------------------- | ---------------------------------------------------- |
    | **First Name**                | MSPortal                                             |
    | **Last Name**                 | Integration                                          |
    | **Security Level**            | MSPortal (the role you created)                      |
    | **Email Address**             | Use an internal alias for receiving integration logs |
    | **Primary Internal Location** | Select your headquarters                             |
    | **Integration Vendor**        | MSPortal.ai                                          |
  </Step>

  <Step title="Generate API Credentials">
    1. Under **Credentials**, click **Generate Key**
    2. Click **Generate Secret**
    3. **Important:** Save the API username and secret immediately - the secret cannot be retrieved later

    <Warning>
      Make sure to copy and save your API credentials before closing this dialog. The secret cannot be viewed again after creation.
    </Warning>
  </Step>

  <Step title="Associate Lines of Business">
    Associate the appropriate lines of business with the API user, then click **Save & Close**.
  </Step>
</Steps>

***

## Part 2: MSPortal Setup Wizard

MSPortal.ai provides a guided setup wizard that walks you through connecting and configuring your Autotask integration in 4 easy steps.

### Starting the Wizard

<Steps>
  <Step title="Navigate to Integrations">
    In MSPortal.ai, go to **Settings** > **Integrations**.
  </Step>

  <Step title="Start Setup">
    Find the **Autotask PSA** integration card and click **Configure** to launch the setup wizard.
  </Step>
</Steps>

***

### Step 1: Connect

Enter your Autotask API credentials to establish the connection.

<Steps>
  <Step title="Enter API Credentials">
    Fill in the following fields:

    | Field            | Description                                                    |
    | ---------------- | -------------------------------------------------------------- |
    | **API Username** | Your Autotask API user email (e.g., `api.user@yourdomain.com`) |
    | **API Secret**   | The API secret generated for your API user                     |
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify your credentials. You'll see a green "Connected" status when successful.

    <Note>
      If the connection fails, verify your API username and secret are correct and that the API user has the MSPortal security role assigned.
    </Note>
  </Step>

  <Step title="Proceed">
    Once connected, click **Next** to continue to sync configuration.
  </Step>
</Steps>

***

### Step 2: Sync

Configure what data to sync from Autotask and set up automatic contact import.

<Steps>
  <Step title="Configure Data Sync Options">
    Enable or disable the following sync options:

    | Option                      | Description                             |
    | --------------------------- | --------------------------------------- |
    | **Sync Users**              | Sync user/contact data from Autotask    |
    | **Sync Companies**          | Sync company/account data from Autotask |
    | **Enable Ticket Sync**      | Sync tickets from Autotask              |
    | **Enable Opportunity Sync** | Sync opportunities from Autotask        |
  </Step>

  <Step title="Configure Contact Auto-Import">
    If you want contacts to be automatically imported when companies are added:

    1. Enable **Auto-Import** to automatically create user accounts for active contacts
    2. Select a **Default Role for Imported Contacts** (e.g., Viewer)

    <Tip>
      We recommend choosing a role with minimal permissions (basic ticket creation only) if you plan to import all contacts.
    </Tip>
  </Step>

  <Step title="Configure Ticket Sync Scope">
    Define which tickets to sync:

    | Setting              | Description                                   |
    | -------------------- | --------------------------------------------- |
    | **Queues to Sync**   | Select which Autotask queues' tickets to sync |
    | **Categories**       | Select ticket categories to include in sync   |
    | **Exclude Statuses** | Select ticket statuses to exclude from sync   |

    <Info>
      When you proceed to the next step, data sync will begin in the background. This may take a few minutes depending on the amount of data in your Autotask account.

      Syncs are automatically deduplicated - if you navigate back and forth between steps, the same sync will not run multiple times within a 2-minute window.
    </Info>
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to ticket and opportunity configuration.
  </Step>
</Steps>

***

### Step 3: Configure

Set up ticket status mapping and opportunity defaults.

#### Ticket Settings

<Steps>
  <Step title="Configure Status Settings">
    | Setting                   | Description                                      |
    | ------------------------- | ------------------------------------------------ |
    | **Closed Statuses**       | Select statuses that indicate a ticket is closed |
    | **Client Comment Status** | Status to set when a client comments on a ticket |
  </Step>

  <Step title="Configure Resolution Status Stepper">
    The Resolution Status Stepper provides a visual indicator of ticket progress. Map your Autotask statuses to each stage:

    | Stage        | Description                                             |
    | ------------ | ------------------------------------------------------- |
    | **New**      | Tickets that are newly created or not yet triaged       |
    | **Triaged**  | Tickets that have been reviewed and categorized         |
    | **Working**  | Tickets actively being worked on                        |
    | **Waiting**  | Tickets waiting for customer response or external input |
    | **Resolved** | Tickets that have been completed                        |

    <Tip>
      You can map multiple Autotask statuses to each stage. The stepper will show the appropriate stage based on the ticket's current status.
    </Tip>
  </Step>

  <Step title="Sync Actions">
    Use these buttons to manage ticket sync:

    | Action             | Description                                                                                   |
    | ------------------ | --------------------------------------------------------------------------------------------- |
    | **Quick Sync**     | Trigger an immediate sync of ticket data                                                      |
    | **Clear & Resync** | Delete all synced tickets and perform a fresh sync (useful after major configuration changes) |
  </Step>
</Steps>

#### Opportunity Settings

<Steps>
  <Step title="Configure Opportunity Defaults">
    Set default values for opportunities created from MSPortal:

    | Setting                  | Description                                                                        |
    | ------------------------ | ---------------------------------------------------------------------------------- |
    | **Fallback Owner**       | The owner assigned to opportunities when the user doesn't have an Autotask account |
    | **Default Stage**        | The starting stage for new opportunities                                           |
    | **Default Category**     | Default category for new opportunities                                             |
    | **Projected Close Days** | Number of days from start date for projected close                                 |

    <Note>
      Opportunity sync can be enabled or disabled in the Sync step. These settings only apply when opportunity sync is enabled.
    </Note>
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to the import step.
  </Step>
</Steps>

***

### Step 4: Import (Optional)

Import users and companies from Autotask. This step is optional - you can skip it and import later from the respective settings pages.

<Tabs>
  <Tab title="Import Users">
    Import resources (your MSP staff) from Autotask to create user accounts.

    1. Enable **Import Users Now**
    2. Select users from the list to create accounts for
    3. Choose a default role for imported users

    <Note>
      Client contacts are not imported here. They can be managed via Company settings after companies are imported.
    </Note>
  </Tab>

  <Tab title="Import Companies">
    Import accounts from Autotask to sync their data.

    1. Enable **Import Companies Now**
    2. Select companies to import or link to existing MSPortal companies

    <Tip>
      Companies will sync automatically based on your sync settings. Use this option if you want to import specific companies immediately.
    </Tip>
  </Tab>
</Tabs>

***

### Complete Setup

Click **Complete Setup** to finish the wizard. Your Autotask integration is now configured!

<Note>
  You can return to the setup wizard at any time by clicking **Configure** on the Autotask integration card. The wizard will resume with your current settings.
</Note>

***

## Managing Your Integration

After setup, you can manage your integration from **Settings** > **Integrations**:

* **Configure**: Re-open the setup wizard to modify settings
* **Resync**: Trigger a manual sync of data
* **Sync PSA Data**: Refresh configuration data (boards, statuses, types) from Autotask

### Webhook Management

MSPortal automatically provisions webhooks in Autotask to sync ticket and company changes instantly. If webhooks stop working:

1. Navigate to **Settings** > **Integrations**
2. Click the **Provision Autotask Webhooks** button to re-provision them

***

## Additional Configuration

After completing the wizard, you may want to configure additional settings:

### Configure Ticket Settings

Navigate to **Settings** > **Tickets** to:

1. Set the **Delivery Method** to **PSA**
2. Ensure **Autotask** is selected as your PSA provider
3. Configure ticket categories and map them to Autotask ticket types
4. Set **Ticket Defaults** for tickets created from compliance tasks or automation

<Tip>
  Ticket defaults are also used as the starting point for new ticket templates, making template creation faster.
</Tip>

### Configure Display Groups

Display groups control which ticket fields users can see based on their role.

1. Navigate to **Settings** > **Tickets**
2. Scroll to **Display Groups** and click **Create Group**
3. Configure:
   * Name for the display group
   * Select **Autotask** as the PSA provider
   * Assign roles that should use this display group
   * Select which fields are visible

<Warning>
  Only grant access to information users need for their role. Follow the principle of least privilege.
</Warning>

### Configure Allowed Statuses

Set which ticket statuses users can select when updating tickets:

1. Navigate to **Settings** > **Tickets**
2. Configure status permissions for each display group

<Tip>
  We recommend preventing users from closing tickets directly. Instead, use a "Ready for Review" status to ensure tickets are reviewed before closure.
</Tip>

***

## Troubleshooting

| Issue                  | Solution                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| Connection test fails  | Verify your API username and secret are correct. Ensure the API user has the MSPortal security role. |
| Tickets not syncing    | Check that the correct queues and categories are selected in Ticket Sync Scope.                      |
| Webhooks not working   | Click "Provision Autotask Webhooks" to re-provision them. Ensure your API user can create webhooks.  |
| Missing data           | Verify the API user has appropriate permissions in the MSPortal security role.                       |
| Contacts not importing | Verify Auto-Import is enabled and a default role is selected in the Sync step.                       |