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

# 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](https://id.atlassian.com/manage-profile/security/api-tokens) e clique em **Create API token**. Dê um nome como `strattum-sync` e copie o token.

> [!WARNING]
>
> 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**.

> [!NOTE]
>
> 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](https://docs.strattum.ai/data-pipelines/local-development.md)**
>
> Configure o ambiente local completo com Prefect, worker e Docker Compose.

> **[Quickstart — Data Pipelines](https://docs.strattum.ai/data-pipelines/quickstart)**
>
> Ative conectores via Console strattum.ai sem precisar de ambiente local.


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