> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Asana

> Workspaces, times, projetos, tarefas, comentários, metas e portfólios do Asana no Data Catalog e no Memory, com a permissão de cada projeto aplicada às tarefas.

O conector Asana lê os workspaces, times, projetos, seções, tarefas, subtarefas, comentários, tags, campos personalizados, status updates, briefs, metas e portfólios que um usuário de integração enxerga no Asana, e grava com cada registro quem pode vê-lo segundo os projetos e times do Asana.

| | |
| - | - |
| **Status** | Disponível |
| **Conteúdo** | Registros |
| **Autenticação** | Token de acesso pessoal |
| **Permissões** | Por item |
| **Sincronização** | Incremental e full refresh, por recurso |
| **Última revisão** | 24/10/2026 |

## Capacidades

* Traz ao Data Catalog o estado do trabalho no Asana: projetos (ativos e arquivados), seções, tarefas e subtarefas com responsável, datas e status de conclusão, comentários e eventos de cada tarefa, tags, campos personalizados, status updates, briefs de projeto, metas e portfólios.
* Traz também a estrutura da conta: workspaces, usuários, times e os membros de times e de projetos.
* Publica 18 modelos limpos, um por recurso e mais quatro de ligação: `asana_task_projects` (tarefa, projeto e seção, inclusive tarefa em vários projetos), `asana_task_tags`, `asana_task_custom_field_values`, e os membros de time e de projeto em `asana_team_members` e `asana_project_members`. Datas saem em UTC e e-mails em minúsculas.
* Alimenta o Memory pelo fragmento de ontologia do conector: usuários, times, projetos, tarefas e metas viram nós, ligados por "atribuída a", "criada por", "subtarefa de", "pertence a", "dono" e "membro de". Cada tarefa ganha uma linha do tempo de atividade e de comentários, e projetos e metas ganham a dos status updates. Usuários se unem a pessoas do Slack, Jira, ClickUp, Fireflies, HubSpot, Pipedrive, Salesforce e Zendesk pelo e-mail. Os nós só entram no grafo depois que a ontologia unificada é aplicada.
* Calcula a permissão de cada registro a partir dos projetos, times, metas e portfólios do Asana (ver Permissões).

## Recursos disponíveis

| Recurso | O que contém | Carga | Cursor | Destino | Permissão por item |
| - | - | - | - | - | - |
| `workspaces` | Workspaces e organizações que o token enxerga, com `is_organization` e `email_domains` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `users` | Usuários de cada workspace, um por usuário, com `name`, `email` e os workspaces de que participa | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `teams` | Times de cada organização, com `description` e `visibility` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `team_memberships` | Membros de cada time, com `is_admin`, `is_guest` e `is_limited_access` | Segue `teams` | Nenhum | Catálogo e Memory | Sim |
| `projects` | Projetos ativos e arquivados, com `privacy_setting`, dono, time, membros, datas, status atual e `notes` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `project_memberships` | Membros de cada projeto (usuário ou time), com `access_level` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `sections` | Seções de cada projeto | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `tasks` | Tarefas e subtarefas, com `notes`, responsável, criador, seguidores, datas, `completed`, tags, `custom_fields`, projetos e seções, e `parent_gid` nas subtarefas | Full refresh, incremental opcional | `modified_at` | Catálogo e Memory | Sim |
| `stories` | Comentários e eventos de sistema de cada tarefa (atribuição, conclusão, mudança de projeto) | Segue `tasks` | Nenhum | Catálogo e Memory | Sim |
| `tags` | Tags de cada workspace | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `custom_fields` | Definições dos campos personalizados, com tipo e opções. Os valores ficam em `tasks` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `status_updates` | Status updates de projetos, metas e portfólios, com título, texto e `status_type` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `project_briefs` | O brief de cada projeto que tem um | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `goals` | Metas de cada workspace, com dono, time, período, status e `privacy_setting` | Full refresh | Nenhum | Catálogo e Memory | Sim |
| `portfolios` | Portfólios de que o usuário do token é dono, com membros e status atual | Full refresh | Nenhum | Catálogo e Memory | Sim |

Ao criar a conexão, os modelos limpos do Asana já nascem ligados no Data Catalog, e com eles os recursos que eles leem. Como o conector tem um modelo limpo por recurso, todos os recursos começam ligados. Desligue no Data Catalog o que você não quiser carregar.

`projects` não pode ser desligado porque as tarefas só são listadas por projeto e a permissão de quase todo registro nasce do projeto. `team_memberships` não tem switch próprio: ele segue `teams`.

A permissão não depende do que você ligou. A cada execução, o conector lê usuários, times, projetos e membros direto da API para calcular as permissões, mesmo com `users` ou `project_memberships` desligados.

`goals`, `portfolios`, `custom_fields`, `status_updates` e `project_briefs` só existem nos planos pagos do Asana. Num workspace sem acesso a eles, o recurso é pulado e a execução termina com sucesso (ver Como a sincronização funciona).

O teste de conexão confere esses recursos e a visibilidade dos e-mails por amostra, só no primeiro workspace que o token enxerga. Numa conta com vários workspaces, um recurso pode estar disponível no primeiro e indisponível em outro; a execução trata cada caso e pula o recurso indisponível.

### Como ler os dados

* Responsável, criador, seguidores, donos e membros aparecem como `gid` e nome em todas as tabelas. O e-mail está só em `users` (no modelo limpo, `asana_users`), e você o encontra juntando pelo `gid`.
* Uma tarefa pode estar em vários projetos ao mesmo tempo. `project_gids` lista todos, e `asana_task_projects` traz uma linha por tarefa e projeto, com a seção em cada um. Uma subtarefa sem projeto próprio não tem linha ali: ela fica ligada à tarefa pai por `parent_gid`.
* `custom_fields` chega em `tasks` como texto JSON. Os valores aparecem por tipo em `asana_task_custom_field_values`.
* Em `asana_stories`, `story_type` separa o que uma pessoa escreveu (`comment`) do que o Asana registrou (`system`).
* `due_on` e `start_on` são datas sem fuso, como o Asana envia. Os demais horários estão em UTC.

## Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em **Comportamento dos dados**, você escolhe entre dois modos:

| Modo | Quem vê |
| - | - |
| Aberto | Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas. |
| Espelhar a fonte | Cada pessoa vê apenas os registros que a própria fonte libera para ela. |

No modo "Espelhar a fonte", a Strattum reconhece cada pessoa pelo e-mail que ela tem no Asana. O conector grava esse e-mail como uma identidade do Asana, ligada a esta conexão, e assume que a pessoa usa o mesmo e-mail na Strattum. Times e o conjunto de membros de um workspace viram grupos, e a Strattum lê quem pertence a cada grupo direto no Asana. O Asana não tem a opção **Exigir login na fonte como prova de identidade**.

No passo de acesso do assistente de criação, o **Comportamento dos dados** começa em "Aberto".

### Como a fonte define acesso

No Asana, quem vê uma tarefa é quem vê algum projeto em que ela está. Um projeto público para o workspace é visto por todos os membros do workspace. Um projeto privado é visto só pelos seus membros, que podem ser pessoas ou times inteiros. Metas e portfólios têm membros próprios.

### Como a Strattum traduz o acesso

A cada execução, o conector lê a configuração de privacidade e os membros de cada projeto, meta e portfólio, e calcula quem vê cada um. Os registros que dependem deles recebem essa permissão.

| Item | Quem recebe acesso |
| - | - |
| `projects` público para o workspace | Os membros do workspace, os membros diretos do projeto e os times membros |
| `projects` privado para o time | Os membros do time do projeto, os membros diretos e os times membros |
| `projects` privado, ou com privacidade desconhecida | Só os membros diretos e os times membros |
| `sections`, `project_memberships`, `project_briefs` e `status_updates` de projeto | A mesma permissão do projeto |
| `tasks` | A soma das permissões de todos os projetos em que a tarefa está. Uma subtarefa sem projeto próprio herda a permissão da tarefa pai |
| `stories` | A mesma permissão da tarefa |
| `goals` | Os membros da meta e, se ela for pública para o workspace, os membros do workspace |
| `portfolios` e `status_updates` de metas e portfólios | Só os membros da meta ou do portfólio, mesmo quando o portfólio é público |
| `workspaces`, `users`, `teams`, `team_memberships`, `tags`, `custom_fields` | Todos que podem usar o conector |

Cada pessoa vira uma identidade do Asana pelo e-mail, ligada a esta conexão. Cada time e cada workspace vira um grupo, e a Strattum o resolve consultando os membros no Asana.

### Quando a identidade não é encontrada

Todo erro de leitura reduz o acesso, nunca o amplia.

* Um usuário cujo e-mail o usuário de integração não enxerga não recebe acesso. O teste de conexão avisa quando os e-mails estão ocultos.
* Um time cujos membros o usuário de integração não consegue ler não dá acesso aos seus membros. Quem só tem acesso pelo time não vê o item na Strattum.
* Convidados (guests) nunca entram no grupo do workspace. Um convidado só vê o projeto em que foi adicionado diretamente. Se o Asana não informar quem é convidado, nenhum projeto público dá acesso ao workspace inteiro, só aos membros diretos e times.
* Uma tarefa cujos projetos estão todos fora do alcance do token fica sem leitores, mesmo que a tarefa pai esteja num projeto visível.
* Se a leitura de um projeto falhar por erro temporário, os registros dele mantêm a permissão da última execução boa. Um registro novo desse projeto recebe só a permissão que foi possível confirmar.
* Um item sem nenhum leitor fica invisível no modo "Espelhar a fonte".
* Quem usa na Strattum um e-mail diferente do que usa no Asana não vê nada no modo "Espelhar a fonte".

### Quando a permissão é atualizada

Em toda execução, o conector relê a privacidade e os membros de todos os projetos, metas e portfólios. Quando a permissão de um projeto muda, a mesma execução regrava a permissão das seções, membros, briefs, status updates, tarefas e comentários desse projeto, inclusive das tarefas que não mudaram. Tornar um projeto privado vale na próxima execução.

Entrar ou sair de um time, ou do workspace, não exige nova sincronização. A Strattum relê os membros dos grupos a cada 10 minutos.

Se a Strattum não consegue identificar algum membro de um time ou do workspace (por exemplo, um membro cujo e-mail o usuário de integração não enxerga), ela não atualiza os grupos desta conexão naquela leitura e mantém os membros da última leitura completa. Nesse caso, entradas e saídas de times só passam a valer quando todos os membros voltam a ser identificáveis.

## Pré-requisitos

* Um workspace ou organização no Asana. No plano gratuito, metas, portfólios, campos personalizados, status updates e briefs não ficam disponíveis.
* O token de acesso pessoal de um usuário de integração, membro dos times e projetos que serão sincronizados. O conector só alcança o que esse usuário alcança.
* Para o modo "Espelhar a fonte", esse usuário precisa enxergar o e-mail dos demais membros.
* Uma só conexão Asana por instalação da Strattum.

## Autenticação e escopos

A autenticação usa um token de acesso pessoal (Personal Access Token) do Asana, enviado no cabeçalho `Authorization` como `Bearer`. O token não tem escopos: ele dá acesso a tudo o que a conta que o gerou enxerga, e não expira por padrão.

| Permissão do usuário | Para quê |
| - | - |
| Membro do workspace ou da organização | Listar workspaces, usuários, times, projetos, tags e campos personalizados |
| Membro dos times e projetos que serão sincronizados | Ler projetos privados, suas tarefas, comentários, seções, briefs e status updates. O que o usuário não vê não chega à Strattum |
| Visibilidade do e-mail dos membros | Reconhecer cada pessoa no modo "Espelhar a fonte" |
| Dono dos portfólios | Ler `portfolios`: o Asana só devolve os portfólios de que o dono do token é dono |

**1. Entre com o usuário de integração**

Acesse o Asana com o usuário cujo token o conector vai usar.

**2. Abra o developer console**

Acesse `app.asana.com/0/my-apps`.

**3. Crie o token**

Clique em **+ Create new token**, preencha **Token name** com uma descrição (por exemplo, `Strattum`) e clique em **Create token**.

**4. Copie o token**

Copie o token e guarde-o. O Asana mostra o valor uma única vez.

> [!WARNING]
>
> O token dá acesso a tudo o que o usuário vê no Asana e não expira por padrão. Guarde-o em local seguro e nunca o publique em repositórios.

## Configuração no Console

**1. Abra o assistente**

Em **Conectores**, crie uma nova conexão e selecione **Asana**.

**2. Preencha a conexão**

**Nome do Conector** (Opcional): como a conexão aparece na lista. O padrão é `Asana`.

**Token de acesso pessoal** (Obrigatório): o token gerado no developer console do Asana.

**3. Teste a conexão**

Clique em **Testar Conexão**. Você só avança depois de um teste com sucesso ou com avisos. O teste confere o token e se ele enxerga algum workspace. Ele também avisa quando os e-mails dos usuários estão ocultos e quando o plano do workspace não inclui metas, portfólios, campos personalizados, status updates ou briefs.

**4. Escolha a frequência**

Em **Frequência de Sincronização** (Obrigatório), escolha a frequência. A opção recomendada é a cada 4 horas.

**5. Defina o acesso**

Em **Permissionamento**, defina **Quem pode usar este conector** e o **Comportamento dos dados**. O padrão é "Todos os usuários" e "Aberto".

**6. Revise e salve**

Em **Revisão**, confira os dados e salve. Depois, no Data Catalog, ligue os recursos que você quer carregar, escolha na aba **Carga** se `tasks` roda em incremental e como o cursor avança (**Avança por**), e marque os dados pessoais, se houver. Ver [Dados pessoais (PII)](https://docs.strattum.ai/data-pipelines/personal-data.md).

## Como a sincronização funciona

A frequência vem do passo **Frequência de Sincronização**. A referência do conector é uma execução a cada 4 horas.

**Ordem.** Cada execução começa lendo workspaces, usuários, membros dos workspaces, times e seus membros, projetos e membros dos projetos, para calcular as permissões. Depois extrai os recursos ligados no Data Catalog, na ordem da tabela de recursos, e só então grava. Por último, atualiza a permissão dos projetos que mudaram e publica os modelos limpos.

**Paginação.** Toda listagem pede 100 itens por página e segue até o Asana indicar a última. Uma página expirada no meio da listagem é tratada como erro, para que uma lista incompleta nunca substitua a anterior.

**Full refresh.** Todos os recursos, exceto `tasks` e `stories` no modo incremental, são reescritos a cada execução. Um item apagado no Asana some da tabela.

**Incremental.** Só `tasks` aceita, e você escolhe na aba **Carga** do Data Catalog. O conector guarda um cursor de `modified_at` por projeto. A cada execução, pede ao Asana as tarefas de cada projeto alteradas desde o cursor menos 10 minutos de margem, e mescla o resultado pelo `gid`. Um projeto que aparece pela primeira vez é lido inteiro. `stories` e subtarefas seguem a mesma janela: entram só os das tarefas devolvidas.

A posição guardada depende do campo **Avança por**, na aba **Carga** de `tasks`:

| Opção | Posição guardada ao fim da execução |
| - | - |
| Maior valor lido (padrão) | O maior `modified_at` lido em cada projeto |
| Tempo de execução | O maior `modified_at` lido em cada projeto, limitado ao início da execução menos 10 minutos |

**Full de manutenção.** Com o incremental ligado, a primeira execução de cada dia (UTC) lê todas as tarefas, subtarefas e comentários. É ela que alcança o que o incremental não vê: uma mudança só numa subtarefa, um comentário editado e uma tarefa apagada.

**Planos pagos.** Um recurso que o plano do workspace não inclui é pulado. A tabela dele fica como estava, e a execução termina com sucesso.

**Falhas.** Um token recusado interrompe a execução. Outro erro num recurso faz só esse recurso falhar: os demais são gravados, os modelos limpos são publicados e a execução termina com erro nomeando o recurso. Se um projeto falhar por erro temporário, os recursos que dependem de projeto são mesclados naquela execução, sem remover nada, e o cursor desse projeto não avança.

**Remoção.** Um projeto apagado no Asana sai da Strattum na execução seguinte. Uma tarefa ou um comentário apagado sai no próximo full refresh de `tasks` em que nenhum projeto falhou. Com o incremental ligado, isso acontece no máximo no full de manutenção do dia seguinte.

## API da fonte

Todas as chamadas são `GET` em `https://app.asana.com/api/1.0`.

| Método e caminho | Usado para | Recurso |
| - | - | - |
| `GET /workspaces` | Teste de conexão; listar workspaces | `workspaces`, Permissão |
| `GET /users?workspace={workspace_gid}` | Listar usuários e o e-mail de cada um | `users`, Permissão |
| `GET /workspaces/{workspace_gid}/workspace_memberships` | Saber quem é convidado e montar o grupo do workspace | Permissão |
| `GET /workspaces/{workspace_gid}/teams` | Listar times | `teams`, Permissão |
| `GET /teams/{team_gid}/team_memberships` | Listar membros de cada time | `team_memberships`, Permissão |
| `GET /projects?workspace={workspace_gid}&archived=` | Listar projetos ativos e arquivados | `projects`, Permissão |
| `GET /memberships?parent={gid}` | Listar membros de projetos, metas e portfólios | `project_memberships`, Permissão |
| `GET /projects/{project_gid}/sections` | Listar seções | `sections` |
| `GET /tasks?project={project_gid}&modified_since=` | Listar tarefas de um projeto, inteiras ou desde o cursor | `tasks` |
| `GET /tasks/{task_gid}/subtasks` | Listar subtarefas | `tasks` |
| `GET /tasks/{task_gid}/stories` | Listar comentários e eventos | `stories` |
| `GET /workspaces/{workspace_gid}/tags` | Listar tags | `tags` |
| `GET /workspaces/{workspace_gid}/custom_fields` | Listar definições de campos personalizados | `custom_fields` |
| `GET /status_updates?parent={gid}` | Listar status updates de projetos, metas e portfólios | `status_updates` |
| `GET /project_briefs/{brief_gid}` | Ler o brief de um projeto | `project_briefs` |
| `GET /goals?workspace={workspace_gid}` | Listar metas | `goals` |
| `GET /portfolios?workspace={workspace_gid}&owner=me` | Listar os portfólios do dono do token | `portfolios` |

**Rate limits.** O Asana limita requisições por minuto e por token: 150 em domínios do plano gratuito e 1.500 em domínios pagos, com até 50 leituras simultâneas. Acima do limite, responde 429 com o cabeçalho `Retry-After`, e a requisição recusada também conta na cota. O conector faz uma requisição por vez. Diante de um 429, espera o tempo pedido pelo Asana (entre 1 segundo e 15 minutos; sem o cabeçalho, 2, 4, 8 segundos e assim por diante) e tenta de novo, até 6 esperas. Erros 5xx e conexões interrompidas têm até 5 tentativas, com espera de 1, 2, 4 e 8 segundos. Cada requisição tem 60 segundos de limite. Se a leitura de um projeto esgotar as tentativas, o projeto é tratado como parcial naquela execução. Em outro recurso, o recurso falha.

Os comentários custam ao menos uma requisição por tarefa, e as subtarefas, uma por tarefa que as tem. No plano gratuito, um workspace com muitas tarefas pode levar bastante tempo por execução.

Referência oficial: [Asana, rate limits](https://developers.asana.com/docs/rate-limits)

## Limitações conhecidas

* O conector só alcança o que o usuário de integração vê. Projetos privados de que ele não é membro ficam de fora, sem aviso.
* `portfolios` traz só os portfólios de que o usuário do token é dono. Na maioria das contas, a tabela fica parcial.
* Tarefas sem projeto (as de "My Tasks") não são sincronizadas. Uma subtarefa sem projeto próprio entra pela tarefa pai.
* Anexos não são lidos. Descrições, comentários, status updates e briefs ficam como texto no Data Catalog e não são indexados no Knowledge.
* No incremental, uma mudança só numa subtarefa, um comentário editado e uma tarefa apagada esperam o full de manutenção do dia seguinte.
* Se o usuário de integração não enxerga os e-mails da organização, ninguém recebe acesso no modo "Espelhar a fonte", e os usuários do Asana não se unem a pessoas de outras fontes no Memory.
* Quem só tem acesso a um projeto por meio de um time que o usuário de integração não consegue ler não vê o projeto na Strattum.
* O Asana não permite vincular a conta de cada usuário: a identidade é o e-mail do usuário no Asana.
* O texto dos campos personalizados chega em `custom_fields` como texto JSON e não pode ser marcado para mascaramento no painel de dados pessoais. Texto pessoal digitado num campo personalizado chega sem máscara.
* As colunas de `gid` que ligam registros (responsável, projeto, tarefa pai) não aceitam mascaramento, porque a permissão e os modelos limpos dependem delas.
* Metas, portfólios, campos personalizados, status updates e briefs ficam vazios em workspaces do plano gratuito.
* Uma conexão Asana por instalação.

## Troubleshooting

| Mensagem ou sintoma | Causa | O que fazer |
| - | - | - |
| Informe o token de acesso pessoal do Asana. | O campo do token está vazio. | Gere um token em `app.asana.com/0/my-apps` e cole no campo. |
| Token do Asana inválido ou revogado. | O token está errado, foi apagado ou a conta foi desativada. | Gere um novo token de acesso pessoal e atualize a credencial. |
| O Asana limitou as requisições desta conta. | O token atingiu o limite por minuto. | Aguarde alguns instantes e teste novamente. |
| O token não enxerga nenhum workspace do Asana. | O dono do token não participa de nenhum workspace ou organização. | Use o token de um usuário que seja membro de ao menos um workspace. |
| Não foi possível contatar a API do Asana. | Falha de rede até `app.asana.com`. | Verifique a conectividade de rede e tente novamente. |
| E-mail dos usuários não visível: o controle de acesso espelhado não vai casar ninguém. | O usuário do token não enxerga o e-mail dos membros. | Use o token de um usuário que enxergue os e-mails da organização. |
| Metas, Portfólios: só disponíveis em planos pagos do Asana; não terão dados no catálogo. | O plano do workspace não inclui esses recursos. | Siga sem eles ou mude o plano do workspace no Asana. |
| A execução termina com erro nomeando um recurso. | O Asana recusou a leitura desse recurso, ou ela falhou depois das tentativas. | Os demais recursos foram gravados. Confira o acesso do usuário de integração e aguarde a próxima execução. |
| Uma pessoa não vê nada no modo "Espelhar a fonte". | O e-mail dela na Strattum é diferente do e-mail no Asana, ou ela só tem acesso por um time que o usuário de integração não lê. | Use o mesmo e-mail nos dois, adicione o usuário de integração ao time, ou adicione a pessoa diretamente ao projeto. |
| Uma tarefa apagada continua no Data Catalog. | `tasks` está em incremental, e a remoção só vale no full refresh. | Aguarde o full de manutenção do dia seguinte. |

## Próximos passos

> **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)**
>
> Ligue os recursos do Asana, escolha o modo de carga de `tasks` e marque dados pessoais.

> **[Memory](https://docs.strattum.ai/memory/overview.md)**
>
> Veja como tarefas, projetos, times e metas entram no grafo e se unem às pessoas de outras fontes.

> **Desenvolvimento local**
>
> O conector não lê credenciais de variáveis de ambiente. O token é gravado por conexão, quando você cria a conexão no Console, com a chave `ASANA_ACCESS_TOKEN`. Para testar localmente, suba o ambiente pelo [guia de desenvolvimento local](https://docs.strattum.ai/data-pipelines/local-development.md) e crie a conexão pelo Console desse ambiente.


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