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

# Asana Integration

> Connect Gradial to Asana to automatically ingest tasks and sync results back to your projects.

**What you can do:**

* Ingest Asana tasks into Gradial with full metadata
* Filter by project, section, assignee, or tag
* Trigger Gradial execution when tasks match your criteria
* Write results — previews, links, comments — back to the Asana task

***

## Prerequisites

### Create a dedicated Gradial service account in Asana

Gradial requires a dedicated Asana user account — do not use a personal or shared account. This service account is what Gradial authenticates as when syncing tasks and posting results back to Asana.

1. Create a new Asana user with an email address dedicated to the integration (e.g., `gradial-integration@yourcompany.com`)
2. Add the service account as a **member of every Asana project** you plan to sync into Gradial
3. Ensure the account has sufficient permissions to read tasks and post comments in those projects

<Warning>
  The PAT you generate must come from this dedicated service account, not a personal user. Actions Gradial takes in Asana — such as posting comments — will appear as this account.
</Warning>

**Required permissions for the service account:**

| Scope           | Permissions required                 |
| --------------- | ------------------------------------ |
| **Projects**    | Member access to all target projects |
| **Tasks**       | Read / Write across all task types   |
| **Comments**    | Read / Write                         |
| **Attachments** | Read / Write                         |

***

## Connect Asana to Gradial

Once the service account is set up, generate a PAT for it and connect to Gradial.

### Step 1 — Generate a Personal Access Token

1. Log in to Asana **as the service account**
2. Go to the Asana Developer Console at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
3. Click **Create new token**, give it a descriptive name (e.g., "Gradial Integration"), and confirm
4. Copy the token immediately — it will not be shown again

<Info>
  Treat your PAT like a password. If it is ever compromised, revoke it from [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps) and generate a new one.
</Info>

### Step 2 — Add the integration in Gradial

Go to **Integrations** in the Gradial sidebar, find Asana under **Ticket System Integrations**, and click **Connect**.

1. Enter an **Integration Name** to identify this connection (e.g., "Marketing Asana")
2. Paste the token you generated into **Personal Access Token**
3. Click **Validate Connection**

<Info>
  Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.
</Info>

***

## Configure routes

Once connected, click **Add Route** to define which Asana tasks Gradial ingests and where they go in Gradial.

Each route has two parts: an **Asana Filter** that controls which tasks are fetched, and a **Gradial Destination** that controls where they land.

### Asana Filter

Routes use GIDs — Asana's internal numeric identifiers — not names. You can find GIDs in the URL when viewing a project, section, or workspace in Asana (e.g., `app.asana.com/0/{workspace_gid}/{project_gid}`).

| Field             | Required                          | Description                                                                               |
| ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
| **Project GIDs**  | Optional                          | Comma-separated list of Asana project GIDs to fetch tasks from                            |
| **Section GIDs**  | Optional                          | Comma-separated list of section GIDs to narrow to a specific board column or list section |
| **Workspace GID** | Required when using Assignee GID  | The GID of your Asana workspace                                                           |
| **Assignee GID**  | Required when using Workspace GID | Fetch only tasks assigned to a specific user (e.g., the Gradial service account)          |

<Info>
  Use **Project GIDs** to pull from one or more specific projects. Use **Workspace GID + Assignee GID** together to pull all tasks assigned to the Gradial service account across your workspace — regardless of project.
</Info>

Use **Test Query** to preview which tasks the current filter will return before saving.

### Gradial Destination

| Field           | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| **Project**     | The Gradial project where ingested tasks will appear as threads |
| **Environment** | The Gradial environment to execute tasks in                     |

***

## How task execution works

Once a route is configured, Gradial polls Asana for matching tasks and processes them automatically:

1. A task matching a route's filter criteria is discovered in Asana
2. Gradial ingests the task as a thread, including title, description, and attachments
3. The AI agent executes the requested work
4. Results — previews, links, and comments — are written back to the original Asana task
5. Gradial continues to monitor the task for updates or `@gradial` mentions that trigger follow-up actions

***

## Troubleshooting

| Issue                         | Likely cause                           | Fix                                                                              |
| ----------------------------- | -------------------------------------- | -------------------------------------------------------------------------------- |
| No tasks syncing              | Service account missing project access | Confirm the account is a member of all target projects                           |
| Authentication fails          | Invalid or expired token               | Regenerate the PAT at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps) |
| Test Query returns no results | GID incorrect or filter too narrow     | Double-check GIDs from the Asana URL; try a Project GID-only filter first        |
| Tasks stuck pending           | Insufficient task permissions          | Ensure the service account has write access to all target tasks                  |
| Wrong tasks ingested          | Filters too broad                      | Add Section GIDs or an Assignee GID to narrow the route                          |

Contact your Gradial Product Specialist or email [support@gradial.com](mailto:support@gradial.com) if issues persist.