diff --git a/plugins/AutoTask/v1/docs/README.md b/plugins/AutoTask/v1/docs/README.md index 47c08b70..b499941a 100644 --- a/plugins/AutoTask/v1/docs/README.md +++ b/plugins/AutoTask/v1/docs/README.md @@ -1,24 +1,34 @@ # Before you start -You will need an Autotask account with admin access to create an API User. API Users are a dedicated account type in Autotask used for system integrations — they are separate from regular user accounts and do not consume a standard user licence. +You will need an Autotask account with admin access to create an API User. API Users are a dedicated account type in Autotask used for system integrations. They are separate from regular user accounts and cannot log in to the Autotask UI. ## Creating an API User -1. Log in to Autotask and go to **Admin > Resources/Users (HR) > Resources** -2. Click **New** and select **API User** as the resource type -3. Complete the required fields, including an email address — this becomes the **API Username** -4. Under the **Credentials** section, click **Generate** next to **Integration Code** to create your **API Integration Code** -5. Set a **Password / Secret** — this becomes the **API Secret** -6. Save the record +1. Log in to Autotask and go to **Admin > Account Settings & Users > Resources/Users (HR) > Resources/Users** +2. Hover over **New** and select **New API User** +3. Complete the required fields in the **General** section, including **Email Address**. This address is only used to notify you if the integration has a problem, and it is **not** the API Username +4. Set **Security Level** to an API User (API-only) level with read access to the entities you want to monitor +5. In the **Credentials** section, click **Generate Key** to create the **Username (Key)**, and **Generate Secret** to create the **Password (Secret)**. Let Autotask generate both rather than typing your own, so they are formatted correctly +6. In the **API Tracking Identifier** section, select your **Integration Vendor**, or choose **Custom (Internal Integration)** to generate an identifier. This value is the **API Integration Code** +7. Save the record, then copy the Username (Key), Password (Secret) and tracking identifier somewhere safe. The secret cannot be retrieved again after you leave the page The API User must have sufficient security permissions to read the entities you want to monitor (Companies, Tickets, Contracts, Projects, Resources, and Survey Results). +## Which value is the API Username + +This is the most common setup mistake, because the generated Username is formatted like an email address and looks interchangeable with the email address on the General section. + +- **Correct:** the **Username (Key)** value from the **Credentials** section, for example `A1B2C3D4E5F6@yourdomain.com` +- **Incorrect:** the **Email Address** field from the **General** section, for example `apiuser@yourdomain.com` + +Entering the General section email address results in a 401 error when the configuration is validated. + ## Finding your Zone URL Your Zone URL is based on the Autotask data centre your account is hosted on. To find it: -1. Log in to Autotask and look at the URL in your browser address bar — for example `https://ww14.autotask.net` -2. Replace `ww` with `webservices` to get the API base URL — for example `https://webservices14.autotask.net` +1. Log in to Autotask and look at the URL in your browser address bar, for example `https://ww14.autotask.net` +2. Replace `ww` with `webservices` to get the API base URL, for example `https://webservices14.autotask.net` Enter the full base including `https://`. @@ -26,7 +36,7 @@ Enter the full base including `https://`. | Field | Where to find it | |---|---| -| **Zone URL** | Derived from your Autotask login URL — see above | -| **API Integration Code** | Generated on the API User record under Credentials > Integration Code | -| **API Username** | The email address entered when creating the API User | -| **API Secret** | The password set on the API User record under Credentials | +| **Zone URL** | Derived from your Autotask login URL. See above | +| **API Username** | API User record > Credentials > **Username (Key)** | +| **API Integration Code** | API User record > **API Tracking Identifier** | +| **API Secret** | API User record > Credentials > **Password (Secret)** | diff --git a/plugins/AutoTask/v1/metadata.json b/plugins/AutoTask/v1/metadata.json index 59f440a0..6c46df7f 100644 --- a/plugins/AutoTask/v1/metadata.json +++ b/plugins/AutoTask/v1/metadata.json @@ -1,7 +1,7 @@ { "name": "autotask", "displayName": "Autotask", - "version": "1.0.4", + "version": "1.0.5", "author": { "name": "@TimWheeler-SQUP", "type": "community" diff --git a/plugins/AutoTask/v1/ui.json b/plugins/AutoTask/v1/ui.json index c9d8eb41..04eefe5d 100644 --- a/plugins/AutoTask/v1/ui.json +++ b/plugins/AutoTask/v1/ui.json @@ -14,8 +14,8 @@ "type": "text", "name": "userName", "label": "API Username", - "placeholder": "apiuser@yourdomain.com", - "help": "Email address of the Autotask API User", + "placeholder": "A1B2C3D4E5F6@yourdomain.com", + "help": "On the Autotask API User record, this is **Credentials > Username (Key)**, created with the **Generate Key** button. It is not the **Email Address** field on the General section, even though the Username is formatted like an email address.", "validation": { "required": true } @@ -24,7 +24,7 @@ "type": "password", "name": "integrationCode", "label": "API Integration Code", - "help": "Generated when creating an API User in Autotask — Admin > Resources > API User", + "help": "On the Autotask API User record, this is the identifier under **API Tracking Identifier**. Select an Integration Vendor, or choose **Custom (Internal Integration)** to generate one.", "validation": { "required": true } @@ -33,7 +33,7 @@ "type": "password", "name": "secret", "label": "API Secret", - "help": "Generated when creating an API User in Autotask", + "help": "On the Autotask API User record, this is **Credentials > Password (Secret)**, created with the **Generate Secret** button.", "validation": { "required": true }