Asana

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.

​

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

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: 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. 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.

​

Configuração no Console

​

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: 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. 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

​

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

​

Próximos passos

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 e crie a conexão pelo Console desse ambiente.