Jira

Configure o conector Jira para sincronizar issues, comentários, projetos e usuários com a plataforma strattum.ai.

O conector Jira sincroniza issues e seus metadados do Jira Cloud com a infraestrutura strattum.ai. Os dados aparecem no Data Catalog e alimentam o contexto de projetos e trabalho no Memory e no Knowledge.

Capacidades

• Sincroniza issues, comentários de issue, projetos e usuários.
• Carga incremental de issues e comentários pela data de atualização.
• Suporte a campos customizados de story points e sprint, com IDs configuráveis por instância.
• Autenticação via API token do Atlassian.

Objetos suportados

Objeto	O que vem
issues	Issues com key, summary, description, status, assignee, reporter, priority, issue_type e datas de criação/atualização (incremental)
issue_comments	Comentários das issues, coletados via a data de atualização da issue pai (incremental)
projects	Projetos da instância Jira
users	Usuários da instância

Pré-requisitos

Conta Jira Cloud

Acesso a uma instância Jira Cloud (suaempresa.atlassian.net).

API token do Atlassian

Um API token gerado na conta Atlassian do usuário que fará a leitura.

Configuração

1. Gere um API token do Atlassian

   Acesse id.atlassian.com/manage-profile/security/api-tokens e clique em Create API token. Dê um nome como strattum-sync e copie o token.

   O token é exibido apenas uma vez. Copie-o e guarde em local seguro antes de fechar a janela.

2. Confirme as permissões do usuário

   O usuário dono do token precisa enxergar os projetos que você quer sincronizar. Use uma conta com permissão Browse Projects nos projetos-alvo.

3. Adicione o conector no Console

   No menu lateral do Console, clique em Conectores → + Nova Conexão e selecione Jira. Preencha os campos:

   • Nome do Conector — identificador na lista de conectores (Obrigatório)
   • Domínio — subdomínio Atlassian, apenas a parte antes de .atlassian.net (Obrigatório)
   • E-mail — e-mail da conta Atlassian dona do token (Obrigatório)
   • API Token — token gerado na etapa anterior (Obrigatório)
4. Teste e salve

   Clique em Testar Conexão para validar as credenciais e, em seguida, em Salvar Conector.

Os IDs de campos customizados de story points (customfield_10016) e sprint (customfield_10020) variam por instância. Os defaults cobrem as configurações mais comuns do Jira Cloud. Para descobrir os IDs corretos da sua instância, chame GET /rest/api/3/field. O ajuste desses IDs é feito na configuração avançada do conector [verificar].

Autenticação e escopos

A autenticação é por Basic Auth com e-mail e API token contra a REST API v3 do Jira Cloud. O Jira não usa escopos OAuth para API tokens — o acesso é o mesmo do usuário dono do token.

Permissão do usuário	Para que serve
Browse Projects	Listar e ler issues, comentários e projetos
Acesso ao diretório de usuários	Ler a lista de usuários da instância

Frequência de sync

O conector sincroniza a cada 2 horas. A primeira execução após a ativação roda como sample sync (amostra) e, ao concluir, o ciclo completo passa a rodar no schedule padrão.

Limitações conhecidas

• projects e users são carregados em full refresh a cada ciclo; apenas issues e issue_comments são incrementais.
• Comentários são capturados pela data de atualização da issue pai — editar ou criar um comentário atualiza a issue, o que dispara a recoleta dos comentários daquela issue.
• Os IDs de campos customizados são específicos da instância; os defaults podem não corresponder à sua configuração.
• Issues deletadas na origem não são removidas automaticamente em modo incremental.

Troubleshooting

Sintoma	Causa provável	O que fazer
401 Unauthorized	E-mail ou API token incorretos	Confirme o e-mail da conta dona do token e gere um novo token se preciso
Missing required Jira credentials	Domínio, e-mail ou token vazios	Preencha os três campos obrigatórios
Issues de um projeto não aparecem	Usuário sem Browse Projects	Conceda a permissão ao usuário dono do token
Story points ou sprint vazios	ID de campo customizado diferente do default	Descubra o ID via GET /rest/api/3/field e ajuste na configuração do conector

Próximos passos

Guia de desenvolvimento local

Configure o ambiente local completo com Prefect, worker e Docker Compose.

Quickstart — Data Pipelines

Ative conectores via Console strattum.ai sem precisar de ambiente local.