> ## 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

> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.