> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/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

<CardGroup cols={2}>
  <Card title="Conta Jira Cloud" icon="jira">
    Acesso a uma instância Jira Cloud (`suaempresa.atlassian.net`).
  </Card>

  <Card title="API token do Atlassian" icon="key">
    Um API token gerado na conta Atlassian do usuário que fará a leitura.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="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.
    </Warning>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Teste e salve">
    Clique em **Testar Conexão** para validar as credenciais e, em seguida, em **Salvar Conector**.
  </Step>
</Steps>

<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].
</Note>

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

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>