Redmine/docs/TEMPLATES.md

Templates de Payload (2.0)

A partir da versão 2.0, o plugin deixa de ter o corpo das requisições ao Redmine "chumbado" no código: cada operação passa a ter um template de payload editável, para que o plugin se adapte às peculiaridades de cada Redmine (campos personalizados obrigatórios, campos extras, textos fixos) sem precisar de alteração de código.

Retrocompatível: sem template ativo, o plugin se comporta exatamente como nas versões 1.x. Você adota os templates quando (e se) quiser.

Onde fica

Configurar → Plugins → Redmine Integration → "Templates de Payload (avançado)".

Há um card por operação:

Operação	Quando dispara	Endpoint Redmine
Criar tarefa (issue)	1º lançamento de tempo de um chamado	POST /issues.json
Lançar tempo	tarefa (TicketTask) marcada como Feito	POST /time_entries.json
Atualizar status	mudança de status do chamado	PUT /issues/{id}.json
Criar projeto	vínculo "criar novo" na aba Redmine	POST /projects.json

O conceito: "DE → PARA"

• DE (variáveis do GLPI): o que o plugin tem para oferecer — chamado.titulo, tarefa.horas, vinculo.projeto_redmine, etc. Aparecem como autocomplete no campo de valor de cada linha (e há uma lista de referência colapsável).
• PARA (campos do Redmine): o que o seu Redmine espera em cada operação — descoberto automaticamente (campos padrão + campos personalizados via GET /custom_fields.json), com marcação de obrigatório e valores possíveis. Clicar num campo do "PARA" adiciona a linha no editor com o caminho já pronto.

Fluxo recomendado

1. Sincronizar Metadados (aba Conexão) — é o que descobre trackers, status, atividades e campos personalizados do seu Redmine.
2. No card da operação, clique em Gerar template — cria o ponto de partida equivalente ao comportamento padrão + os campos obrigatórios do seu ambiente.
3. Ajuste as linhas (o autocomplete ajuda a achar as variáveis do GLPI).
4. Clique em Testar:
   • Preview — mostra o JSON final renderizado com dados de exemplo (seguro).
   • Teste real (opcional) — cria e apaga um objeto de teste no Redmine e, se recusado, traduz o erro ("Atividade não pode ficar vazio → mapeie esse campo").
5. Marque Ativo e clique em Salvar (o botão único no fim da página grava tudo).

Sintaxe das tags

{{ variavel }}                     → valor da variável
{{ variavel | filtro }}            → aplica um filtro
{{ variavel | filtro:arg }}        → filtro com argumento
{{ mapa[chave.dinamica] }}         → lookup indexado (ex.: map.status[chamado.status])

Regra de tipos: quando a tag ocupa todo o valor, o resultado sai com o tipo nativo da variável (número, array, booleano — sem aspas no JSON). Quando a tag está no meio de um texto, vira interpolação de string. Campos que resolverem para vazio/nulo são omitidos do payload.

Filtros disponíveis

Filtro	Efeito
truncar:N	corta a string em N caracteres (ex.: subject no limite de 255)
sem_html	remove HTML/entidades
minusculo	tudo minúsculo
identificador	normaliza para identificador Redmine válido (minúsculas, -)
padrao:'texto'	valor fixo quando a variável estiver vazia

Variáveis do GLPI (o "DE")

Grupo	Variáveis
chamado.*	id, titulo, descricao, status, entidade, tecnico
tarefa.*	id, horas, segundos, descricao, comentario, data, autor
vinculo.*	projeto_redmine, issue_redmine, categoria_padrao
config.*	tracker_padrao, prioridade_padrao, atividade_padrao, observadores
map.status	mapa de status GLPI→Redmine (use como map.status[chamado.status])
form.* (criar projeto)	nome, identificador, descricao, publico, subprojeto_de, trackers, modulos, cf_<id>

Autoria: chamado.tecnico e tarefa.autor são texto (para usar em comentários, por exemplo). A autoria real da issue/tempo continua automática, via impersonation — não é um campo do template.

Segurança e robustez

• As tags são um mini-motor de substituição (mustache-like), não executam código (não é Twig completo) — seguro para edição por administradores.
• Template com JSON inválido não é salvo (aviso na tela).
• Se um template ativo falhar no render em produção, o plugin cai no comportamento 1.x e registra no log — nunca perde um lançamento.

Exemplo (o que o "Gerar template" produz para log_time)

{
  "time_entry": {
    "issue_id":    "{{ vinculo.issue_redmine }}",
    "hours":       "{{ tarefa.horas }}",
    "comments":    "{{ tarefa.comentario }}",
    "activity_id": "{{ config.atividade_padrao }}"
  }
}