ClickUp

O conector ClickUp lê as tasks, os Spaces, as listas e os membros de um workspace ClickUp, as páginas dos Docs e os anexos das tasks, e grava com cada item quem pode vê-lo segundo as permissões do ClickUp.

​

Capacidades

• Traz ao Data Catalog as tasks, com status, prioridade, datas, responsáveis, criador, lista e Space, e a estrutura do workspace: Spaces, listas (dentro e fora de pastas) e membros.
• Publica modelos limpos de tasks, listas, Spaces e membros, com datas em UTC e e-mails em minúsculas. O de tasks traz a lista, a pasta, o Space, o criador, todos os responsáveis e observadores (id, nome e e-mail), os nomes das tags, a task pai, o link da task e o tempo estimado e o gasto, em milissegundos.
• Publica em clickup_tasks o tipo de cada status (status_type), que separa task aberta de concluída sem depender do nome que o workspace dá ao status, e os campos personalizados preenchidos em forma legível.
• Alimenta o Memory pelo fragmento de ontologia do conector: tasks, listas, Spaces e membros viram nós, ligados por “está na lista”, “está no Space”, “atribuída a” (o primeiro responsável) e “criada por”. Membros se unem a pessoas de outras fontes pelo e-mail. Os nós só entram no grafo depois que a ontologia unificada é aplicada.
• Envia ao Knowledge cada página de Doc como um documento, com o título no formato Doc › página pai › página, e o texto dos anexos de tasks em PDF, Word, Excel, PowerPoint, Markdown, texto e CSV.
• Calcula a permissão de cada task, lista, Space, página de Doc e anexo a partir da hierarquia do ClickUp (ver Permissões).

​

Recursos disponíveis

No Data Catalog, docs e attachments nascem ligados, members fica sempre ligado e os demais recursos nascem desligados. Você escolhe quais carregar depois de conectar. members não pode ser desligado porque é por ele que a Strattum conhece os membros do workspace. Sem ele, nenhum documento ficaria visível no modo “Espelhar a fonte”. Um anexo entra no Knowledge quando a extensão está na lista acima e o arquivo tem até 1 MB (texto, Markdown e CSV) ou até 10 MB (PDF e Office). Um anexo acima do limite é registrado no Knowledge sem o texto, então não aparece na busca. Um anexo com outra extensão, como imagem, vídeo ou zip, não é publicado.

​

Como ler os dados

• status é o nome que o workspace dá ao status em cada lista, como backlog ou review. status_type é a classe que o próprio ClickUp atribui: open, custom, done ou closed. Uma task está aberta quando status_type não é done nem closed.
• custom_fields é uma lista com um item por campo personalizado preenchido. Campo vazio fica de fora, e uma task sem nenhum preenchido traz lista vazia. Cada item tem id, name, type e value. Em campo de lista suspensa (drop_down), value é o nome da opção escolhida. Em campo de etiquetas (labels), é o nome das opções, separados por vírgula. Nos demais tipos, é o valor em texto, e objetos e listas vêm como texto JSON. Se a opção escolhida não existe mais na configuração do campo, value mantém o código bruto.
• description é o texto da task, ou NULL quando ela não tem texto. archived diz se a task está arquivada.
• Datas (date_created, date_updated, date_closed, due_date, start_date) saem em UTC. time_estimate e time_spent estão em milissegundos.
• assignee_id é só o primeiro responsável, e é por ele que o Memory cria a ligação “atribuída a”. Todos os responsáveis estão em assignee_ids, assignee_names e assignee_emails, na mesma ordem. Os observadores seguem o mesmo formato, em watcher_*. Task sem responsável traz listas vazias.
• folder_id e folder_name ficam NULL quando a lista está direto no Space. A task traz só o id do Space (space_id); o nome está em clickup_spaces.
• parent_id só é preenchido em subtasks. tag_names traz o nome das tags.
• clickup_lists e clickup_spaces trazem a hierarquia, e clickup_members traz external_id, username, email (em minúsculas) e role.

​

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 ClickUp. O conector grava esse e-mail como uma identidade do ClickUp, ligada a esta conexão, e assume que a pessoa usa o mesmo e-mail na Strattum. O ClickUp 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 ClickUp, Space, pasta, lista, task e Doc podem ser privados. Um item privado é visto só por quem foi adicionado a ele. Um item não privado é visto por quem foi adicionado a ele e por quem vê o item acima dele na hierarquia: task, lista, pasta, Space e, no topo, o workspace. No workspace, todos os membros, exceto os convidados (guests), veem o que não é privado.

​

Como a Strattum traduz o acesso

A cada execução, o conector percorre Spaces, pastas, listas e Docs e calcula quem alcança cada um seguindo a regra acima. A leitura das permissões usa um recurso da API do ClickUp que não tem documentação pública. Por isso o conector confere o resultado de duas formas:

• No começo de cada execução, testa a leitura em um Space. Se a resposta mudou de formato, a execução para antes de gravar qualquer coisa e as permissões anteriores continuam valendo.
• Para cada lista, compara o resultado com a lista de membros que o próprio ClickUp informa. Se houver diferença, a lista e tudo abaixo dela ficam sem leitores naquela execução.

Cada pessoa vira uma identidade do ClickUp pelo e-mail, ligada a esta conexão.

​

Quando a identidade não é encontrada

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

• Um membro sem e-mail no ClickUp não recebe acesso. A execução registra quantos ficaram de fora.
• Um acesso dado a um grupo de usuários (user group) do ClickUp não é lido. Quem só tem acesso pelo grupo não vê o item na Strattum, e a execução registra quantas entradas de grupo foram ignoradas.
• Convidados não entram no acesso do workspace. Um convidado só vê o item a que foi adicionado diretamente.
• Se a permissão de um item não puder ser lida, por erro ou falta de acesso, esse item e tudo abaixo dele ficam sem leitores naquela execução.
• Uma task que mudou de task pai durante a execução fica sem leitores até a execução seguinte.
• Um item sem nenhum leitor fica invisível no modo “Espelhar a fonte”. Uma página de Doc ou um anexo nessa situação não é entregue ao Knowledge. Se já estava indexado, o conteúdo continua lá, mas sem leitores.
• Quem usa na Strattum um e-mail diferente do que usa no ClickUp não vê nada no modo “Espelhar a fonte”.

​

Quando a permissão é atualizada

Em toda execução, o conector relê as permissões de Spaces, pastas, listas e Docs, e recalcula a permissão de todas as tasks, inclusive as que não mudaram. Uma task fora da janela do incremental cuja permissão mudou é regravada no lugar, e os anexos dela são republicados no Knowledge com a permissão nova. A permissão própria de cada task (se ela é privada e quem foi adicionado) fica guardada entre execuções. O conector a relê por inteiro em todo full refresh e quando a última releitura completa tem mais de 6 horas. Nas outras execuções, relê só as tasks que mudaram. Por isso, tornar uma task privada no ClickUp pode levar até 6 horas para valer na Strattum. Uma mudança em Space, pasta, lista ou Doc vale já na execução seguinte.

​

Pré-requisitos

• Um workspace ClickUp em qualquer plano. O plano define o limite de requisições (ver API da fonte).
• O token de API pessoal de um usuário que vê tudo o que deve ser sincronizado. O conector só alcança o que esse usuário alcança. Prefira um usuário de serviço, membro de todos os Spaces, pastas, listas e Docs de interesse.
• Se o teste de conexão disser que as permissões não podem ser lidas, use o token de um Owner ou Admin do workspace.
• O ID do workspace (Team ID).
• Uma só conexão ClickUp por instalação da Strattum.

​

Autenticação e escopos

A autenticação usa o token de API pessoal do ClickUp, que começa com pk_, enviado no cabeçalho Authorization. O token pessoal não tem escopos e não expira: ele herda o acesso do usuário que o gerou.

​

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 por hora. Além dela, roda um full refresh de manutenção por dia, às 03:00 por padrão. Ordem. Em cada execução, o conector lê primeiro as permissões (Spaces, pastas, listas e Docs), depois spaces, lists e members, depois o índice de todas as tasks e as tasks, e por último as páginas dos Docs e os anexos. Recurso desligado no Data Catalog não é gravado. Paginação. As tasks são lidas página por página até o ClickUp indicar a última. Docs, páginas de permissão e anexos avançam por cursor, com até 100 itens por página. Full refresh. spaces, lists e members são reescritos a cada execução. tasks em full refresh também, e uma task apagada no ClickUp some da tabela. Incremental. Só tasks aceita. A execução pede ao ClickUp as tasks atualizadas desde a posição guardada do cursor, menos 5 minutos de margem, e mescla o resultado pelo id. O full refresh de manutenção lê todas as tasks, mesmo com o incremental ligado. A posição guardada depende do campo Avança por, na aba Carga de tasks no Data Catalog: Com “Tempo de execução”, uma task com date_updated no futuro não leva o cursor junto, e as tasks atualizadas depois dela continuam entrando. Docs. Todas as páginas de todos os Docs são lidas em toda execução, porque só baixando a página dá para saber se ela mudou. O Knowledge só reindexa o que mudou. Páginas vazias não viram documento, e imagens coladas na página são removidas do texto. Anexos. Os anexos seguem a janela de tasks. Num incremental, entram só os anexos das tasks da janela. Num full refresh, os de todas as tasks. O arquivo é baixado do endereço que o ClickUp informa, sem enviar o token. Remoção. Uma task, um Doc, uma página ou um anexo apagado no ClickUp, ou um acesso perdido, só sai da Strattum num full refresh, no máximo no de manutenção do dia seguinte. No Knowledge, a remoção só vale quando docs e attachments estão ligados juntos. Se um Doc responder sem permissão de leitura para o token, o que já estava indexado dele sai no próximo full refresh. Duração. O custo de cada execução cresce com o número de tasks, porque a permissão de cada uma é recalculada. Num workspace com 719 tasks, o primeiro full refresh levou cerca de 27 minutos, e um incremental, cerca de 2 minutos.

​

API da fonte

Rate limits. O ClickUp limita requisições por minuto e por token: 100 nos planos Free Forever, Unlimited e Business, 1.000 no Business Plus e 10.000 no Enterprise. Acima do limite, responde 429. O conector conta cada requisição numa janela móvel de 60 segundos e envia no máximo o limite menos 5, ou seja, 95 por minuto até o ClickUp informar outro limite. Quando a API avisa que o saldo acabou, ele espera a renovação. Diante de um 429, espera o maior entre o tempo pedido pelo ClickUp e o fim da janela (60 segundos se a resposta não disser nada, no máximo 120) e tenta de novo, até 5 vezes. Erros 5xx e conexões interrompidas têm até 3 tentativas, com espera de 1 e 2 segundos. Se a leitura da permissão de um item esgotar as tentativas, esse item e o que está abaixo dele ficam sem leitores. Se a listagem de Docs ou de anexos falhar, o que foi lido é publicado e nada é removido naquela execução. Se a listagem de tasks falhar, a execução falha. O download de anexos não conta no limite da API. Cada leitura de permissão custa duas requisições, e a permissão de cada task entra no cálculo. Num plano de 100 por minuto, um workspace com milhares de tasks pode levar mais de uma hora por execução. Nesse caso, a execução seguinte espera a anterior terminar. Referência oficial: ClickUp, rate limits

​

Limitações conhecidas

• A leitura de permissões usa um recurso da API do ClickUp sem documentação pública. Se o ClickUp mudar esse recurso, as execuções param antes de gravar e as permissões anteriores continuam valendo até uma correção.
• O conector só alcança o que o dono do token vê. Conteúdo que esse usuário não vê não chega à Strattum.
• Acesso dado por grupo de usuários (user group) do ClickUp não é lido.
• Se o ClickUp der a Owners e Admins acesso implícito a itens privados, a Strattum não o reproduz: só valem as pessoas adicionadas e a herança.
• Um convidado que só tem acesso a um Doc ou a uma task específica pode não ver o item na Strattum.
• O ClickUp não permite vincular a conta de cada usuário: a identidade é o e-mail do usuário no ClickUp.
• Tornar uma task privada pode levar até 6 horas para valer na Strattum.
• Itens apagados no ClickUp só saem num full refresh. No Knowledge, a remoção só acontece com docs e attachments ligados juntos.
• Anexos de comentários não são lidos. Imagens, vídeos, áudios e arquivos compactados anexados a tasks não são indexados.
• Não dá para limitar a extração a alguns Spaces ou pastas. O recorte por Space, pasta e lista vale só para o que entra num contexto do Knowledge.
• Os dados pessoais dentro do texto de páginas e anexos não são mascarados.
• status_type, description, archived e custom_fields ficam no Data Catalog e não viram propriedade do nó de task no Memory.
• Campos personalizados não viram colunas, porque cada workspace tem os seus. Eles chegam em custom_fields, como lista, com o valor em texto.
• O texto de description e o de custom_fields são sugeridos para mascaramento no painel de dados pessoais do Data Catalog. Nada é mascarado até você aplicar a sugestão e salvar.
• O SQL de cada tabela clean é instalado quando você cria o conector, e editar o conector não o reinstala. Uma conexão criada antes da versão que trouxe status_type, description, archived e custom_fields mantém o SQL anterior de clickup_tasks, sem essas colunas. A Strattum precisa reinstalar o modelo e rodar uma sincronização antes de as colunas aparecerem.
• No Memory, só o primeiro responsável vira a ligação “atribuída a” (o campo assignee_id de clickup_tasks). Todos os responsáveis ficam em assignee_ids, assignee_names e assignee_emails, no modelo limpo.
• A tela de execução pode mostrar “Sincronizando, sem avanço” durante execuções longas, como o primeiro full refresh de um workspace grande, mesmo com o conector trabalhando.
• Uma conexão ClickUp por instalação.

​

Troubleshooting

​

Próximos passos

Desenvolvimento local

O conector não lê credenciais de variáveis de ambiente. O token e o Team ID são gravados por conexão, quando você cria a conexão no Console, com as chaves CLICKUP_API_KEY e CLICKUP_TEAM_ID. Para testar localmente, suba o ambiente pelo guia de desenvolvimento local e crie a conexão pelo Console desse ambiente.