What you can do: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.
- 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.- Create a new Asana user with an email address dedicated to the integration (e.g.,
[email protected]) - Add the service account as a member of every Asana project you plan to sync into Gradial
- Ensure the account has sufficient permissions to read tasks and post comments in those projects
| 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
- Log in to Asana as the service account
- Go to the Asana Developer Console at app.asana.com/0/my-apps
- Click Create new token, give it a descriptive name (e.g., “Gradial Integration”), and confirm
- Copy the token immediately — it will not be shown again
Treat your PAT like a password. If it is ever compromised, revoke it from app.asana.com/0/my-apps and generate a new one.
Step 2 — Add the integration in Gradial
Go to Integrations in the Gradial sidebar, find Asana under Ticket System Integrations, and click Connect.- Enter an Integration Name to identify this connection (e.g., “Marketing Asana”)
- Paste the token you generated into Personal Access Token
- Click Validate Connection
Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.
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) |
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.
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:- A task matching a route’s filter criteria is discovered in Asana
- Gradial ingests the task as a thread, including title, description, and attachments
- The AI agent executes the requested work
- Results — previews, links, and comments — are written back to the original Asana task
- Gradial continues to monitor the task for updates or
@gradialmentions 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 |
| 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 |