> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/asana.md).

# Asana

{% hint style="info" %}
The following documentation is for **Asana v1.1.1** *(BDK)*.
{% endhint %}

## Overview

Asana is a leading project management and team collaboration platform that helps organize work and track progress. This integration allows you to automate task creation, project updates, and team notifications across your workflows. Streamline project coordination and improve team productivity with automated Asana interactions.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Asana**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Personal Access Token

Connect using a Personal Access Token (PAT).

| Label                 | Description                                                                                              | Type        |
| --------------------- | -------------------------------------------------------------------------------------------------------- | ----------- |
| Personal Access Token | The Asana Personal Access Token (PAT). Found under My Settings > Apps > Personal Access Tokens in Asana. | `sensitive` |

## Procedures

### to add a (comment) to a task

Add a comment to a task in Asana.

**Input Concepts**

| Concept                     | Description                                            | Type            | Required | Default Value |
| --------------------------- | ------------------------------------------------------ | --------------- | -------- | ------------- |
| [`task`](#asana-task)       | The task to add the comment to. Must have a valid GID. | `asana task`    | Yes      | (no default)  |
| [`comment`](#asana-comment) | The comment to add. Must have text set.                | `asana comment` | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                | Type            |
| --------------------------- | -------------------------- | --------------- |
| [`comment`](#asana-comment) | The newly created comment. | `asana comment` |

**Examples**

Add a comment to a task

```generic
get some projects from asana
get the first project's tasks
use the first task as my task
create a json
use the above as the comment
set the comment's "text" to "This looks good!"
add the comment to my task in asana
```

### to assign a (task) to a user

Assign a task to a user in Asana.

**Input Concepts**

| Concept               | Description                                            | Type         | Required | Default Value |
| --------------------- | ------------------------------------------------------ | ------------ | -------- | ------------- |
| [`task`](#asana-task) | The task to assign. Must have a valid GID.             | `asana task` | Yes      | (no default)  |
| [`user`](#asana-user) | The user to assign the task to. Must have a valid GID. | `asana user` | Yes      | (no default)  |

**Output Concepts**

| Concept               | Description                             | Type         |
| --------------------- | --------------------------------------- | ------------ |
| [`task`](#asana-task) | The updated task with the new assignee. | `asana task` |

**Examples**

Assign a task to a user

```generic
get some projects from asana
get the first project's tasks
use the first task as my task
create a json
use the above as the user
set the user's "gid" to "1234567890"
assign my task to the user in asana
```

### to complete a (task) in *asana*

Mark a task as complete in Asana.

**Input Concepts**

| Concept               | Description                                  | Type         | Required | Default Value |
| --------------------- | -------------------------------------------- | ------------ | -------- | ------------- |
| [`task`](#asana-task) | The task to complete. Must have a valid GID. | `asana task` | Yes      | (no default)  |

**Output Concepts**

| Concept               | Description         | Type         |
| --------------------- | ------------------- | ------------ |
| [`task`](#asana-task) | The completed task. | `asana task` |

**Examples**

Complete a task

```generic
get some projects from asana
get the first project's tasks
complete the first task in asana
```

### to create a (task) in a project

Create a task in a project in Asana.

**Input Concepts**

| Concept                     | Description                                                                                       | Type            | Required | Default Value |
| --------------------------- | ------------------------------------------------------------------------------------------------- | --------------- | -------- | ------------- |
| [`project`](#asana-project) | The project to create the task in. Use "get some projects from asana" to find available projects. | `asana project` | Yes      | (no default)  |
| [`task`](#asana-task)       | The task to create. Must have a name set.                                                         | `asana task`    | Yes      | (no default)  |

**Output Concepts**

| Concept               | Description             | Type         |
| --------------------- | ----------------------- | ------------ |
| [`task`](#asana-task) | The newly created task. | `asana task` |

**Examples**

Create a simple task in a project

```generic
create a json
use the above as the task
set the task's "name" to "Write documentation"
>>>
get some projects from asana
create the task in the first project
```

Create a task with notes

```generic
create a json
use the above as the task
set the task's "name" to "Review pull request"
set the task's "html_notes" to "<body>Please review PR #42</body>"
>>>
get some projects from asana
create the task in the first project
```

### to delete a task

Delete a task in Asana.

**Input Concepts**

| Concept               | Description                                | Type         | Required | Default Value |
| --------------------- | ------------------------------------------ | ------------ | -------- | ------------- |
| [`task`](#asana-task) | The task to delete. Must have a valid GID. | `asana task` | Yes      | (no default)  |

**Examples**

Delete a task

```generic
get some projects from asana
use the first project as my project
get my project's tasks
delete the first task
```

### to get some (project's sections) from *asana*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get sections from a project in Asana.

**Input Concepts**

| Concept                     | Description                                                                                           | Type            | Required | Default Value |
| --------------------------- | ----------------------------------------------------------------------------------------------------- | --------------- | -------- | ------------- |
| [`project`](#asana-project) | The project to retrieve sections from. Use "get some projects from asana" to find available projects. | `asana project` | Yes      | (no default)  |

**Output Concepts**

| Concept                                | Description                  | Type            |
| -------------------------------------- | ---------------------------- | --------------- |
| [`project's sections`](#asana-section) | The sections in the project. | `asana section` |

**Examples**

Retrieve all sections from a project

```generic
get some projects from asana
use the first project as my project
get my project's sections from asana
```

Retrieve a section by name

```generic
get some projects from asana
use the first project as my project
get my project's sections from asana whose name is "To do"
```

### to get some (project's tasks)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get tasks from a project in Asana.

**Input Concepts**

| Concept                     | Description                                                                                        | Type            | Required | Default Value |
| --------------------------- | -------------------------------------------------------------------------------------------------- | --------------- | -------- | ------------- |
| [`project`](#asana-project) | The project to retrieve tasks from. Use "get some projects from asana" to find available projects. | `asana project` | Yes      | (no default)  |

**Output Concepts**

| Concept                          | Description               | Type         |
| -------------------------------- | ------------------------- | ------------ |
| [`project's tasks`](#asana-task) | The tasks in the project. | `asana task` |

**Examples**

Retrieve all tasks from a project

```generic
get some projects from asana
use the first project as my project
get my project's tasks
```

Retrieve tasks whose name matches a value

```generic
get some projects from asana
use the first project as my project
get my project's tasks whose name is "Write documentation"
```

Retrieve incomplete tasks only

```generic
get some projects from asana
use the first project as my project
get my project's tasks whose completed is "false"
```

### to get some (projects) from *asana*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get projects from Asana.

**Output Concepts**

| Concept                      | Description              | Type            |
| ---------------------------- | ------------------------ | --------------- |
| [`projects`](#asana-project) | The projects from Asana. | `asana project` |

**Examples**

Retrieve all projects

```generic
get some projects from asana
```

Retrieve projects whose name matches a value

```generic
get some projects from asana whose name is "Marketing"
```

### to get some (task's comments) from *asana*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get comments on a task in Asana.

**Input Concepts**

| Concept               | Description                                                | Type         | Required | Default Value |
| --------------------- | ---------------------------------------------------------- | ------------ | -------- | ------------- |
| [`task`](#asana-task) | The task to retrieve comments from. Must have a valid GID. | `asana task` | Yes      | (no default)  |

**Output Concepts**

| Concept                             | Description               | Type            |
| ----------------------------------- | ------------------------- | --------------- |
| [`task's comments`](#asana-comment) | The comments on the task. | `asana comment` |

**Examples**

Retrieve all comments on a task

```generic
get some projects from asana
get the first project's tasks
use the first task as my task
get my task's comments from asana
```

### to get some (users) from *asana*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get users from the Asana workspace.

**Output Concepts**

| Concept                | Description                 | Type         |
| ---------------------- | --------------------------- | ------------ |
| [`users`](#asana-user) | The users in the workspace. | `asana user` |

**Examples**

Retrieve all users

```generic
get some users from asana
```

Find a user by name

```generic
get some users from asana whose name is "John Smith"
```

### to update a (task) in *asana*

Update a task in Asana.

**Input Concepts**

| Concept               | Description                                                                                                           | Type         | Required | Default Value |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ | -------- | ------------- |
| [`task`](#asana-task) | The task to update. Must have a valid GID. Updatable fields include name, html\_notes, notes, due\_on, and completed. | `asana task` | Yes      | (no default)  |

**Output Concepts**

| Concept               | Description       | Type         |
| --------------------- | ----------------- | ------------ |
| [`task`](#asana-task) | The updated task. | `asana task` |

**Examples**

Update a task's name

```generic
get some projects from asana
get the first project's tasks
use the first task as my task
set my task's "name" to "Updated task name"
update my task in asana
```

Set a due date on a task

```generic
get some projects from asana
get the first project's tasks
use the first task as my task
set my task's "due_on" to "2025-12-31"
update my task in asana
```

## Concepts

### Asana task

A task in Asana.

| Field Name         | Description                                             | Type                |
| ------------------ | ------------------------------------------------------- | ------------------- |
| `name`             | The name of the task.                                   | `text`              |
| `resource_type`    | The resource type (e.g., "task").                       | `optional[text]`    |
| `resource_subtype` | The resource subtype (e.g., "default\_task").           | `optional[text]`    |
| `gid`              | The global ID of the task.                              | `optional[text]`    |
| `html_notes`       | The HTML content of the task description.               | `optional[text]`    |
| `notes`            | The plain-text content of the task description.         | `optional[text]`    |
| `created_at`       | The time at which this task was created.                | `optional[text]`    |
| `due_on`           | The date on which this task is due (YYYY-MM-DD format). | `optional[text]`    |
| `completed`        | Whether the task is marked complete.                    | `optional[boolean]` |
| `assignee_gid`     | The global ID of the user assigned to this task.        | `optional[text]`    |
| `assignee_name`    | The name of the user assigned to this task.             | `optional[text]`    |

### Asana comment

A comment on an Asana task.

| Field Name        | Description                                   | Type             |
| ----------------- | --------------------------------------------- | ---------------- |
| `text`            | The plain-text content of the comment.        | `text`           |
| `gid`             | The global ID of the comment.                 | `optional[text]` |
| `created_at`      | The time at which this comment was created.   | `optional[text]` |
| `created_by_name` | The name of the user who created the comment. | `optional[text]` |
| `resource_type`   | The resource type (e.g., "story").            | `optional[text]` |

### Asana user

A user in Asana.

| Field Name      | Description                       | Type             |
| --------------- | --------------------------------- | ---------------- |
| `gid`           | The global ID of the user.        | `text`           |
| `name`          | The display name of the user.     | `optional[text]` |
| `email`         | The email address of the user.    | `optional[text]` |
| `resource_type` | The resource type (e.g., "user"). | `optional[text]` |

### Asana project

A project in Asana.

| Field Name      | Description                          | Type             |
| --------------- | ------------------------------------ | ---------------- |
| `gid`           | The global ID of the project.        | `text`           |
| `name`          | The name of the project.             | `text`           |
| `resource_type` | The resource type (e.g., "project"). | `optional[text]` |

### Asana section

A section within an Asana project.

| Field Name      | Description                          | Type             |
| --------------- | ------------------------------------ | ---------------- |
| `gid`           | The global ID of the section.        | `text`           |
| `name`          | The name of the section.             | `text`           |
| `resource_type` | The resource type (e.g., "section"). | `optional[text]` |


---

# 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://docs.kognitos.com/legacy/legacy-experience/books/reference/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.