> For the complete documentation index, see [llms.txt](https://gitbook.tryprotege.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.tryprotege.com/integrations/asana.md).

# Asana

## What this is

Asana is a Hookshot™ integration that connects your Asana workspace to Hookshot. Asana commonly serves as a source of tasks or project status, a scheduled review target, and a data source for workflow checks. Asana also provides a chat surface where Proteges can respond to task comments.

## When to use it

* When Asana activity should start a Protege
* When a Protege should inspect Asana state before acting
* When you want to talk to a Protege inside an Asana task comment by mentioning `@hookshot`
* When you need to sync Asana projects into the Work Hub

## What you need first

* Access to the Asana workspace, project, or task area you want to use
* Permission to complete the connection flow
* A clear reminder or review workflow

## Steps

### 1. Connect Asana

1. Open **Integrations**.
2. Select **Asana**.
3. Complete the connection flow.
4. Confirm the integration is connected.

### 2. Review Trigger Access

Use Trigger Access when Asana activity should start the Protege.

Examples:

* A task created or updated in a selected project
* A live event path scoped to a project or portfolio

Configure the trigger to the narrowest project or portfolio boundary.

If an Asana project is already managed by a Work Hub project, the Builder presents the Work Hub project as the scope instead of raw Asana triggers. The Work Hub provider sync automatically sets up and maintains the trigger subscription for the linked project.

### 3. Review Tool Access

Use Tool Access when the Protege should inspect Asana state before acting.

Examples:

* Check whether a task is complete
* Review project state before sending a reminder
* Update or respond to Asana work when the workflow allows it

If an Asana project is managed by a Work Hub project, Work Hub policy mediates writes. The Protege cannot directly write to Asana for managed sources.

Use the smallest practical project or workspace scope for the job.

### 4. Set up Work Hub provider sync

You can link an Asana source to a Work Hub project so that Hookshot imports and tracks Asana tasks.

1. In Work Hub, choose **Create a project**.
2. Select the **Asana** option.
3. Select an Asana connection (or connect one first if none exists).
4. Browse and select an Asana source: a **project**, **portfolio**, or **workstream**.
5. Configure the project details.
6. Confirm — Hookshot imports all tasks, comments, attachments, and project links from the selected source and automatically creates a provider-managed trigger subscription.

{% hint style="info" %}
Asana provider sync supports both import and outbound projection. Changes you make in Work Hub can push back to Asana. Hookshot periodically reconciles data to catch changes that event listeners missed.
{% endhint %}

#### What gets imported

| Asana concept              | Work Hub concept                                         |
| -------------------------- | -------------------------------------------------------- |
| Asana project or portfolio | Project with imported workstream                         |
| Asana task                 | Work item with status, priority, assignee, custom fields |
| Asana comments             | Comments                                                 |
| Asana attachments          | Artifacts                                                |

### 5. Set up chat

Asana chat is team-scoped. When you enable chat on Asana, Hookshot can respond to mentions in task comments:

* Include `@hookshot`, `@hookshotdev`, or `@composio` in a task comment to invoke a response
* Hookshot posts its reply as a comment on the same task
* While processing, a temporary "Hookshot is working on this..." comment appears and is automatically deleted after the response is posted
* Follow-up comments in the same task continue the conversation

Chat connections are always team-scoped — they cannot be personal connections.

See [Chat](/create-a-protege/chat.md) for the full chat feature documentation.

For Asana chat-style workflows, choose the exact projects or portfolios Hookshot should monitor. A Protege should not watch a broader Asana area than the workflow owner can review.

### 6. Review permissions

Review the Asana connection carefully. In practice, Hookshot™ needs permission to:

* Access the tasks or project objects that matter for your workflow
* Read enough context to decide whether a reminder or follow-up is necessary

Use the smallest practical project or workspace scope for the job.

## How to verify

* Confirm Asana is connected
* Confirm the relevant trigger source or scheduled workflow is ready
* Confirm any managed project or portfolio selection is correct
* If using Work Hub, confirm the imported work items match the Asana source
* Use a known incomplete or known test item
* Check Event Feed for the scheduled or live activity
* Check Audit for the resulting reminder or follow-up run

## Common failures

* Running a reminder workflow against the wrong project
* Forgetting to verify the exact task or project boundary
* Treating a scheduled review as verified before a real scheduled test occurs
* The Protege runs but reminds on the wrong work — narrow the project or task boundary
* Using a personal connection instead of a team connection for chat
* Approving an outbound write in Work Hub without checking it will push back to Asana
* Selecting a trigger without finishing trigger setup: Asana triggers require a project or portfolio to be selected before the Protege can be enabled

## Next step

* [Jira](/integrations/jira.md)
* [Integrations Overview](/integrations.md)
* [Chat](/create-a-protege/chat.md)
* [Work Hub](/event-feed/work-hub.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.tryprotege.com/integrations/asana.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.