Como Criar um Relatório Personalizado no PUCA - Passo a Passo

[raphael.aguiar]

Processo de Criação de Relatórios

Importante: Este tutorial explica com criar um relatório para tela de kanban, mas o passo a passo de criação serve para qualquer tela que tenha suporte ao componente de relatório personalizado

Passo 1: Acessar a Funcionalidade de Exportação

1. No puca procure pelo, clique no ícone da engrenagem

2. No menu suspenso que aparecer, selecione a opção “Exportar”. As telas que implementam esta funcionalidade são: O kanban, as listagens e a tela de detalhes do card (Botão relatórios do lado esquero da te

Passo 2: Organizar e Criar Novo Relatório

1. Crie uma nova pasta para organizar seus relatórios (exemplo: ‘relatórios’)

2. Clique em “Novo Relatório”

3. Você será direcionado para a tela “Selecione um Relatório”

Passo 3: Configuração Prévia dos Cards (Recomendado)

Antes de configurar o relatório, é recomendável configurar a visibilidade das colunas nos cards:

1. Volte para a tela de kanban

2. Clique na engrenagem

3. Selecione “Config Cards”

4. Configure as colunas de interesse para que fiquem visíveis no card

5. Benefício: As colunas exibidas no card são automaticamente adicionadas à query do relatório por padrão, facilitando a identificação

Passo 4: Configuração Inicial do Relatório

1. Defina o nome do relatório no campo “Nome do Relatório” (exemplo: “Redução de Licenças”)

2. Selecione o modelo:

• html-to-xlsx (padrão) - para gerar planilhas Excel
• chrome-pdf - para gerar arquivos PDF

*Neste tutorial focaremos no modelo *html-to-xlsx

Interface de Configuração - As 3 Abas Principais

Aba 1: Configuração de Query

Lado Esquerdo - Definição da Query:

• Aqui você define a query que será executada para buscar os dados

• A query segue a sintaxe específica do PUCA

• Documentação completa: https://comunidade.puca.app/t/como-criar-uma-query-puca/90

Configuração Prática da Query:

1. Fixe as colunas necessárias no campo fields, independentemente se elas são exibidas no card ou não

2. Configure os joins necessários para relacionar tabelas

3. Defina filtros no campo where se necessário

Exemplo de Query Completa:

{
  "args": {},
  "where": {
    "and": []
  },
  "fields": [
    "puca_flow_api_card__puca_pid",
    "puca_flow_api_card__step",
    "puca_flow_api_card__puca_created_at",
    "puca_flow_api_card__puca_key",
    "puca_flow_api_card__title",
    "puca_flow_api_card_join_assigned__username",
    "puca_flow_api_card_join_step__name",
    "user_reduzir_licenca_join_user_cliente__user_codigo_maxima",
    "user_reduzir_licenca_join_user_cliente__puca_key",
    "user_reduzir_licenca_join_user_cliente__name",
    "user_reduzir_licenca__user_licenca_reduzida",
    "user_reduzir_licenca__user_qtd_atual",
    "user_reduzir_licenca__user_observacao",
    "user_reduzir_licenca__user_qtd_lic_reduzir",
    "user_reduzir_licenca__user_qtd_reduzir",
    "user_reduzir_licenca__user_solicitante",
    "user_reduzir_licenca__user_valor_atual",
    "user_reduzir_licenca__user_valor_redu",
    "puca_flow_api_card_join_assigned__avatar_url"
  ],
  "join": [
    {
      "alias": "puca_flow_api_card_join_assigned",
      "tableName": "puca_base_api_system_user",
      "on": {
        "v1": "puca_flow_api_card_join_assigned.puca_pid",
        "v2": "puca_flow_api_card.assigned",
        "operator": "equals"
      }
    },
    {
      "alias": "puca_flow_api_card_join_step",
      "tableName": "puca_base_api_system_step",
      "on": {
        "v1": "puca_flow_api_card_join_step.puca_pid",
        "v2": "puca_flow_api_card.step",
        "operator": "equals"
      }
    },
    {
      "alias": "user_reduzir_licenca_join_user_cliente",
      "tableName": "puca_crm_api_person",
      "on": {
        "v1": "user_reduzir_licenca_join_user_cliente.puca_pid",
        "v2": "user_reduzir_licenca.user_cliente",
        "operator": "equals"
      }
    },
    {
      "alias": "user_reduzir_licenca",
      "tableName": "user_reduzir_licenca",
      "on": {
        "v1": "puca_flow_api_card.id_table_flow",
        "v2": "user_reduzir_licenca.puca_pid",
        "operator": "equals"
      }
    }
  ]
}

Lado Direito - Payload Resultante:

• O sistema demonstra automaticamente o payload que será utilizado para geração do relatório

• Este payload é o resultado da query definida no lado esquerdo

• Serve como preview dos dados que estarão disponíveis no template

• Importante: Use este payload para identificar os nomes exatos das variáveis que você usará no template HTML

Aba 2: Template (HTML para XLSX)

Esta aba é onde você define o HTML que será convertido em planilha Excel (.xlsx).

Estrutura Básica do Template:

<html>
<body>
  <table>
    <tr>
      <th>Value</th>
      <th>Value2</th>
    </tr>
    <tr>
      <td data-cell-type="number"> {{number}} </td>
      <td data-cell-type="date" data-cell-format-str="DD/MM/YYYY"> {{date}} </td>
    </tr>
  </table>
</body>
</html>

Exemplo Prático Completo:

<html>
<body>
  <table>
    <tr>
      <th>Nº Card</th>
      <th>Data de Criação</th>
      <th>Responsável</th>
      <th>Etapa</th>
      <th>ID Cliente</th>
      <th>Cód. Máxima Cliente</th>
      <th>Cliente</th>
      <th>Solicitante</th>
      <th>Licença a Reduzir</th>
      <th>Qtd. Atual</th>
      <th>Qtd. Lic. a Reduzir</th>
      <th>Qtd. a Reduzir</th>
      <th>Observação</th>
    </tr>
    {{#each data}}
      <tr>
         <td data-cell-type="number">{{puca_flow_api_card__puca_key}}</td>
         <td data-cell-type="date" data-cell-format-str="DD/MM/YYYY">{{puca_flow_api_card__puca_created_at}}</td>
         <td>{{puca_flow_api_card_join_assigned__username}}</td>
         <td>{{puca_flow_api_card_join_step__name}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca_join_user_cliente__puca_key}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca_join_user_cliente__user_codigo_maxima}}</td>
         <td>{{user_reduzir_licenca_join_user_cliente__name}}</td>
         <td>{{user_reduzir_licenca__user_solicitante}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca__user_licenca_reduzida}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca__user_qtd_atual}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca__user_qtd_lic_reduzir}}</td>
         <td data-cell-type="number">{{user_reduzir_licenca__user_qtd_reduzir}}</td>
         <td>{{user_reduzir_licenca__user_observacao}}</td>
      </tr>
    {{/each}}
  </table>
</body>
</html>

Principais Funcionalidades do HTML-to-XLSX:

1. Tipos de Célula (data-cell-type):

• number - Para valores numéricos (IDs, quantidades, valores)
• date - Para datas
• string - Para texto (padrão, não precisa especificar)
• boolean - Para valores verdadeiro/falso

1. Formatação de Células (data-cell-format-str):

• Para datas: "DD/MM/YYYY", "MM/DD/YYYY", etc.
• Para números: "#,##0.00", "0.00%", etc.

1. Estrutura HTML:

• Use <table> para criar planilhas
• <th> para cabeçalhos
• <td> para células de dados
• Suporte a múltiplas tabelas (múltiplas abas)

1. Variáveis do Template:

• Use {{variavel}} para inserir dados da query
• Loop principal: {{#each data}} ... {{/each}} para iterar pelos registros
• Condicionais: {{#if condition}} ... {{/if}}
• Use os nomes exatos das variáveis conforme aparecem no payload da query

Dicas Importantes:

• Sempre defina o tipo correto das células para que o Excel interprete os dados adequadamente

• Use nomes descritivos nos cabeçalhos das colunas

• Teste o template antes de finalizar para verificar se os dados estão sendo exibidos corretamente

Passo 5: Teste e Geração do Relatório

Testando o Relatório

1. Após configurar a query e o template, clique no botão “TESTAR”

2. Se o relatório for gerado com sucesso: O arquivo Excel será gerado e você será notificado

3. Se o relatório não for gerado: Significa que existe um erro de sintaxe no template

• Importante: A aplicação ainda não demonstra os erros de sintaxe claramente
• Revise cuidadosamente a sintaxe do HTML e das variáveis
• Verifique se os nomes das variáveis estão corretos conforme o payload

Salvando o Relatório

1. Após o teste bem-sucedido, clique em “CONFIRMAR” para salvar o relatório

2. O relatório ficará disponível na pasta criada para futuras execuções

Resolução de Problemas Comuns

Relatório não é gerado

• Causa: Erro de sintaxe no template HTML

• Solução:

  • Verifique a sintaxe do loop: {{#each data}} … {{/each}}
  • Confirme se os nomes das variáveis estão corretos
  • Verifique se todas as tags HTML estão fechadas corretamente

Dados não aparecem corretamente

• Causa: Nomes de variáveis incorretos ou query mal configurada

• Solução:

  • Compare os nomes das variáveis no template com o payload mostrado na aba 1
  • Verifique se a query está retornando os dados esperados
  • Teste a query isoladamente antes de configurar o template

Formatação incorreta no Excel

• Causa: Tipos de célula não definidos ou incorretos

• Solução:

  • Use data-cell-type="number" para números
  • Use data-cell-type="date" com data-cell-format-str="DD/MM/YYYY" para datas
  • Deixe sem tipo para texto simples

Conclusão

Este processo permite criar relatórios personalizados poderosos no PUCA, combinando:

• Queries flexíveis para buscar exatamente os dados necessários

• Templates HTML para formatação personalizada

• Geração automática de planilhas Excel com tipos de dados corretos

• Scripts opcionais para processamento avançado de dados

O sistema é especialmente útil para relatórios gerenciais, extrações de dados e análises personalizadas que vão além das funcionalidades padrão do sistema.

#Mapeamento avançado de dados:

Na na aba 3: Scripts (Interceptação e Processamento)

Os scripts permitem interceptar e modificar o body da requisição antes da geração do relatório.

Funcionalidade Principal:

• Interceptar dados antes da renderização

• Processar e transformar informações

• Adicionar lógica personalizada

• Importar bibliotecas externas

Exemplo Básico de Script:

const jsreport = require('jsreport-proxy')
const _ = await jsreport.npm.require('[email protected]')
const moment = await jsreport.npm.require('[email protected]')

async function beforeRender(req, res) {
  req.data = {
    number: 1,
    date: moment().format('YYYY/MM/DD'),
  }
}

Importação de Bibliotecas Externas:

• Use jsreport.npm.require('nome-da-biblioteca@versao') para importar libs

• Exemplos populares:

  • lodash - Utilitários para manipulação de dados
  • moment - Manipulação de datas
  • numeral - Formatação de números

Funções Disponíveis:

• beforeRender(req, res) - Executada antes da renderização

• afterRender(req, res) - Executada após a renderização

• Acesso completo aos dados da requisição via req.data

Casos de Uso Comuns:

• Formatação de dados

• Cálculos complexos

• Agrupamento de informações

• Conversão de formatos

• Validação de dados

---

Recursos Adicionais

Documentação Oficial

• Query PUCA: https://comunidade.puca.app/t/como-criar-uma-query-puca/90

• HTML-to-XLSX: https://jsreport.net/learn/html-to-xlsx

• Scripts JSReport: https://jsreport.net/learn/scripts#basics

Dicas Finais

• Sempre teste o relatório antes de confirmar

• Use nomes descritivos para facilitar manutenção futura

• Mantenha os templates organizados em pastas