# Asana

Configure Asana project management integration with Risotto

## Overview

The Asana integration creates an Asana task for every ticket Risotto handles in a configured department, so teams that manage work in Asana instead of a traditional ticketing tool can track requests alongside their other projects.

> **Note:** Asana sync is **one-way**: Risotto creates and updates tasks in Asana, and
> posts new ticket comments there as they happen. Changes made directly in Asana
> (marking a task complete, editing its description, adding a comment in Asana)
> do not sync back to the Risotto ticket.

## Prerequisites

Before connecting, make sure you have:

1. **An Asana Personal Access Token** with access to the target project
2. **The ID of the Asana workspace** that contains the project
3. **The name of the Asana project** tickets should be created in

> **Tip:** Saving the settings doesn't check the project name. Risotto looks the project
> up by name in the workspace when it syncs the department's first ticket, and
> remembers it after that. Create a test ticket to confirm the name.

## Configuration

| Field                     | Required | Description                                                                       |
| ------------------------- | -------- | --------------------------------------------------------------------------------- |
| **Personal Access Token** | Yes      | Your Asana access token                                                           |
| **Workspace ID**          | Yes      | The ID of the Asana workspace that contains the project                           |
| **Project Name**          | Yes      | The Asana project new tasks should be created in                                  |
| **Resolved Section Name** | No       | The project section Risotto moves a task to when its ticket is resolved or closed |

## Setup Process

### Step 1: Configure a Department

You need permission to change the department's settings: an Org Admin, a Manager, or a Supervisor of the department.

1. **Open your department**

   In your Risotto dashboard, go to **Settings**. Under **Departments**, click a
   department, then click **Ticket Sync**.

2. **Add Asana ticket sync**

   Click **Add ticket sync** and select **Asana**. **Add ticket sync** shows
   only while the department has no ticket sync: a department syncs with one
   ticketing system.

   *Product example: The Add Ticket Sync for IT dialog, listing the ticketing integrations, with Asana ringed.*

3. **Enter your Asana details**

   In the **Configure Asana for \<department>** dialog, enter the **Personal
   Access Token**, **Workspace ID**, and **Project Name**. Optionally, enter the
   **Resolved Section Name**. Click **Save**.

   *Product example: The Configure Asana for IT dialog, with the token, workspace ID, the project IT Requests and the resolved section Done filled in, and Save.*

4. **Turn on sync**

   The **Ticket Sync** page now shows the department's sync settings and an
   **Asana** card with the workspace, project, and resolved section. Make sure
   **External ticket sync enabled** is on.

   *Product example: The IT department's Ticket Sync page with Asana connected to the project IT Requests, and External ticket sync enabled.*

   To create tasks only for tickets that escalate, turn on **Only sync
   escalated tickets**. To change the settings later, open the **Connected**
   menu on the **Asana** card and click **Configure...**.

### Step 2: Test the Integration

Create a test ticket through Risotto and confirm a matching task appears in the configured Asana project with the ticket's details in the task description.

## What Syncs to Asana

- **Ticket creation** — a new task is created for every ticket in the department. If **Only sync escalated tickets** is on, Risotto creates the task when the ticket escalates.
- **Title and description** — changes to the ticket's title and description update the task
- **Comments** — new replies on the Risotto ticket are added as comments on the Asana task, each starting with the author's name. Internal comments don't sync.
- **Resolution** — when the ticket is resolved or closed, Risotto marks the task complete and, if you set a **Resolved Section Name**, moves it to that section
- **Attachments** — files and screenshots shared in Slack upload to the Asana task

> **Warning:** Asana isn't currently a supported request source — you can't create Risotto
> tickets by adding a task in Asana. If you need requests to flow in from Asana
> as well as out to it, let your Risotto contact know; it's a known request.

## Troubleshooting

### Ticket doesn't sync to Asana on creation

Check for a "failed to create ticket in external system" event on the ticket.
This is most often caused by content in the ticket description that Asana's
API rejects (for example, certain URL formats) — the ticket still exists in
Risotto even if the Asana task creation fails.

### Escalating a ticket doesn't create an Asana task

Confirm the department's Asana sync is still connected on the department's
**Ticket Sync** page. If the initial sync failed and exhausted its retries,
the ticket may need to be escalated again.

### Tasks don't appear in the project

Risotto finds the project by its exact name, including capitalization, in the
workspace you entered. Double-check the **Project Name** and **Workspace ID**
on the department's **Asana** card. Risotto searches the first 5,000 projects
in the workspace.

## Best Practices

1. **Use a dedicated Asana account**: Generate the access token from an account set aside for integrations, not a personal one
2. **Pick a project scoped to the department**: Avoid pointing multiple departments at the same Asana project, since tasks from different departments will otherwise mix together
3. **Test escalation, not just creation**: Since escalations are a common trigger for task creation, verify that flow specifically before rolling out

## Related Integrations

- [Ticketing Integrations Overview](https://www.tryrisotto.com/docs/integrations/ticketing/overview)
- [GitHub Issues](https://www.tryrisotto.com/docs/integrations/ticketing/github)

Source: https://www.tryrisotto.com/docs/integrations/ticketing/asana
