Redmine/README.md

# Redmine Integration para GLPI

Integração nativa entre o **GLPI** e o **Redmine** para gestão de projetos: transforme o trabalho registrado nos chamados do GLPI em tarefas (issues) e lançamentos de tempo no Redmine, automaticamente e com os autores corretos.

> Desenvolvido pela **Mindtek** · Licença GPLv3+ · Requer GLPI ≥ 11.0.0

---

## O problema que resolve

Equipes que **executam o atendimento no GLPI** mas **gerenciam projetos e horas no Redmine** acabam lançando tempo em dois lugares — ou perdem a rastreabilidade. Este plugin elimina o retrabalho: o técnico continua trabalhando normalmente no chamado do GLPI, e o Redmine recebe a tarefa e as horas **sem nenhuma digitação dupla**.

## Como funciona

```
Projeto GLPI  ──(vínculo na aba "Redmine")──▶ Projeto Redmine   ┐
Entidade GLPI ──(vínculo na aba "Redmine")──▶ Projeto Redmine   ┘ (1:1)

Chamado GLPI ──────────────────────────────────────▶ 1 ISSUE no Redmine
  • título   = título do chamado
  • tipo / prioridade / atividade = padrões configuráveis
  • categoria = padrão por projeto
  • status   = espelha o status do chamado (mapa configurável)

TicketTask "Feito" ────────────────────────────────▶ 1 lançamento de TEMPO na issue
  • horas    = tempo gasto da tarefa (convertido p/ decimal)
  • autor    = o técnico que lançou (via impersonation)
  • comentário = descrição da tarefa
```

- **Dois pontos de vínculo**: o chamado é direcionado ao projeto Redmine pelo **Projeto** GLPI ao qual está ligado **ou**, na ausência de projeto, pela **Entidade** do chamado (clientes de suporte recorrente). Sem vínculo (projeto nem entidade), nada é enviado.
- **Uma issue por chamado**: o chamado nasce e "morre" no GLPI; para o Redmine importam as **horas** e o **andamento**.
- **Tempo só sobe quando a tarefa é concluída** (`Feito`): enquanto não concluída, fica apenas no GLPI.
- **Autores corretos**: a issue é criada como o **técnico atribuído** e cada lançamento de tempo como o **técnico que o registrou**, usando *impersonation* do Redmine — não tudo como "admin".

## Funcionalidades

- ✅ Vínculo de Projeto GLPI ↔ Projeto Redmine (criar novo ou vincular existente), com módulos, subprojeto e visibilidade.
- ✅ Vínculo de **Entidade GLPI ↔ Projeto Redmine** (1:1) — para clientes de suporte recorrente que abrem chamados sem projeto.
- ✅ Criação automática de **issues** a partir dos chamados, com valores padrão (tracker, prioridade, atividade) e **categoria por projeto**.
- ✅ Lançamento automático de **tempo** das tarefas concluídas (idempotente — sem duplicar).
- ✅ **Mapa de status** Chamado GLPI → Status Redmine, totalmente configurável.
- ✅ **Autoria real** via *impersonation* (`X-Redmine-Switch-User`), com **inclusão automática do técnico como membro** do projeto Redmine.
- ✅ **Mapeamento de usuários** GLPI → Redmine: associação automática por e-mail + overrides manuais.
- ✅ **Observadores padrão** configuráveis nas issues.
- ✅ Chave de API **criptografada** em repouso (GLPIKey).
- ✅ Interface 100% nativa do GLPI 11 (componentes Twig).
- ✅ **Templates de Payload (2.0)** — personalize o JSON enviado ao Redmine em cada operação, com **variáveis do GLPI** e **descoberta automática dos campos do seu Redmine** (inclusive campos personalizados obrigatórios). Editor visual + testador embutido. Veja [`docs/TEMPLATES.md`](docs/TEMPLATES.md).

## Requisitos

| Requisito | Detalhe |
|---|---|
| GLPI | ≥ 11.0.0 |
| Redmine | API REST **habilitada** (Administração → Configurações → API) |
| Chave de API | de um usuário **administrador** do Redmine (necessária para impersonation e gestão de membros) |
| Conectividade | o GLPI precisa alcançar a URL do Redmine |

## Instalação

1. Copie a pasta `redmine` para o diretório de plugins do GLPI (`plugins/`).
2. Em **Configurar → Plugins**, instale e ative o **Redmine Integration**.

## Configuração (passo a passo)

Acesse **Configurar → Plugins → Redmine Integration**:

1. **Conexão** — informe a **URL do Redmine** e a **Chave de API** (admin). Clique em **Sincronizar Metadados**.
2. **Valores padrão** — escolha o **Tipo (tracker)**, **Prioridade** e **Atividade** padrão das issues/tempos.
3. **Autores e observadores** — defina o **Papel padrão** (usado para adicionar o técnico como membro do projeto) e os **Observadores padrão**.
4. **Mapa de status** — para cada status de chamado do GLPI, escolha o status correspondente no Redmine.
5. **Mapeamento de usuários** — usuários com o **mesmo e-mail** nos dois sistemas são associados automaticamente; cadastre *overrides* apenas para as exceções.

Depois, defina os vínculos nas abas **Redmine**:
- Em cada **Projeto** do GLPI (`Ferramentas → Projetos`): aba **Redmine** → vincular/criar o projeto Redmine + **categoria padrão**.
- Em cada **Entidade** de cliente recorrente (`Administração → Entidades`): aba **Redmine** → vincular/criar o projeto Redmine (1:1) + **categoria padrão**.

## Fluxo de uso

**Cenário A — Projetos**
1. Vincule o Projeto GLPI ao Projeto Redmine (aba Redmine do projeto).
2. A partir de uma **tarefa de projeto**, crie um **chamado** ("Criar chamado a partir desta tarefa de projeto").
3. No chamado, o técnico registra **tarefas (TicketTask)** e o tempo gasto.
4. Ao marcar a tarefa como **Feito**, o plugin cria/atualiza a issue no Redmine e lança o tempo — com o autor correto.

**Cenário B — Clientes de suporte recorrente (Entidade)**
1. Vincule a **Entidade** do cliente ao Projeto Redmine (aba Redmine da entidade).
2. O cliente abre um **chamado** diretamente na sua entidade (sem projeto).
3. O técnico registra **tarefas (TicketTask)** e o tempo gasto.
4. Ao marcar a tarefa como **Feito**, o plugin resolve o projeto Redmine **pela entidade** e cria a issue + lança o tempo.

## Documentação para desenvolvedores

Contrato de API completo (o que sai do GLPI, como entra no Redmine — endpoints, payloads, cabeçalhos, mapeamento de campos, impersonation e exemplos): veja [`docs/API.md`](docs/API.md).

## Notas e limitações

- O tempo de uma tarefa é lançado **uma única vez** (ao concluir). Edições posteriores de horas não re-sincronizam.
- A *impersonation* exige que o usuário Redmine exista e seja **membro do projeto** — o plugin adiciona o técnico automaticamente; se não houver usuário correspondente, o lançamento usa o admin (com aviso em log).
- Categorias do Redmine são **por projeto**: a categoria padrão é definida no vínculo de cada projeto/entidade.
- O vínculo por **Entidade** é **1:1 e por correspondência exata** — não há herança pela árvore de entidades. O chamado precisa nascer na própria entidade vinculada.

## Licenciamento

Este é um plugin proprietário distribuído pelo **Mind Place** (marketplace da Mindtek).
Ele exige o plugin **Mind Place** instalado e uma **licença válida**: sem isso, o plugin
não ativa (kill switch). A licença é um serial fornecido pela Mindtek e ativado na aba
**Configurar → Plugins → Mind Place**.

## Suporte

Mindtek — integração GLPI/Redmine.