747 Business Intelligence

Módulo Business Intelligence

O cadastro Business Intelligence define os relatórios, consultas e painéis utilizados no Touch ERP. Nele são configurados a origem dos dados, os parâmetros, a apresentação, os formatos de saída e as liberações de acesso.

Acesso: Business Intelligence > BI > Business Intelligence — recurso 747.

Este recurso é destinado aos responsáveis pela configuração dos BIs. Para executar um relatório já disponibilizado, utilize 748 — Iniciar Business Intelligence.

Entenda as partes de um BI

Parte	Finalidade
Fonte de dados	Determina como os registros são obtidos: objetos do ERP, consulta SQL/HQL, código Java ou arquivo/XML.
Dados adicionais	Definem os parâmetros e filtros, seus valores padrão e as possibilidades de alteração pelo usuário.
Layout	Define a apresentação do relatório quando o modelo e o formato utilizados exigem um layout.
Formatos de saída	Determinam quais opções de geração são disponibilizadas, como PDF ou planilha.
Segurança	Define grupos de usuários, vínculos com recursos e restrições de disponibilidade por empresa.
Perfil de uso	Guarda preferências utilizadas na geração. Não substitui a definição dos parâmetros no cadastro do BI.

Alterar apenas o layout não muda os registros selecionados pela consulta. Alterar apenas os filtros não garante que novos campos sejam apresentados: confira também a fonte de dados e a apresentação.

Como preparar um novo BI

Defina a finalidade, os dados necessários e quem utilizará o relatório.
Inicie um cadastro e informe Nome do BI, Título do relatório e uma descrição de sua funcionalidade.
Na aba Tipo BI, selecione e configure a fonte de dados.
Na aba Dados adicionais, configure os parâmetros necessários à seleção.
Na aba Dados BI, confira opções de saída, classificação e parâmetros opcionais de impressão.
Na aba Layout, escolha o tipo de layout, inclua ou gere os arquivos necessários e libere os formatos de saída.
Na aba Segurança, configure os grupos, os recursos associados e o filtro de disponibilidade por empresa.
Salve o cadastro. Um BI novo precisa da primeira gravação antes de utilizar Testar.
Clique em Testar, confira os parâmetros, o formato, os dados e a apresentação.
Salve os ajustes finais e confira o acesso por um usuário e uma empresa previstos na liberação.

No cadastro novo, o BI inicia ativo, com a empresa logada, a data atual, layout JasperReports e versão de estrutura corrente. Confira esses valores antes de disponibilizar o relatório.

Identificação e situação

Campo	Como utilizar
Nome do BI	Identificação utilizada para localizar o relatório. É obrigatório.
Título do relatório	Título destinado à apresentação, conforme o layout utilizado.
Descrição do BI	Explique a finalidade, a abrangência e as premissas do relatório. Essa descrição também ajuda na identificação de conteúdo enviado ao repositório.
Situação	Ativa ou inativa o BI. Confira a situação antes de liberar ou retirar um relatório de uso.
Motivo da inativação	Informação apresentada quando o BI está inativo, para documentar o motivo.
Identificador, número e data de cadastro	Informações de identificação e acompanhamento. O número do BI e o identificador local não devem ser tratados como se fossem sempre o mesmo código.

Aba Tipo BI: fonte de dados

Escolha a fonte adequada ao relatório e configure o painel correspondente.

Fonte	Como funciona
Objetos	Monta a seleção a partir das entidades e campos disponíveis no ERP, com critérios, ordenações e demais opções do editor.
HQL	Utiliza uma consulta baseada nas entidades mapeadas do sistema. Exige conhecimento da estrutura e da linguagem utilizada.
SQL	Utiliza uma consulta ao banco de dados, com os campos e relacionamentos necessários ao relatório.
Código Java	Utiliza código específico para produzir os dados ou a saída prevista no BI. Exige compilação e manutenção por responsável técnico.
Arquivo/XML	Utiliza a modalidade de arquivo/XML, com a tag inicial e as demais definições exigidas pelo fluxo de entrada.

Ao salvar, somente a fonte selecionada é mantida como fonte do BI. Trocar o tipo não é uma forma de armazenar várias versões de consulta no mesmo cadastro. Preserve uma cópia quando precisar comparar alternativas.

BI por objetos

Selecione a entidade de origem.
Escolha os campos que farão parte do resultado.
Confira as descrições dos campos selecionados; elas precisam ser preenchidas e não podem se repetir.
Configure os critérios de seleção, as ordenações e as agregações necessárias, conforme as opções do editor.
Confira a consulta ou o resultado produzido antes de preparar o layout.

É necessário selecionar uma classe de origem e pelo menos um campo. As relações disponíveis dependem da estrutura do ERP; não presuma que campos com nomes semelhantes em entidades diferentes representem a mesma informação.

Quando o cadastro for aberto a partir da seleção de campos de outra tela, confira os campos resolvidos e os avisos de campos não encontrados. A montagem inicial não substitui a conferência do resultado.

SQL, HQL e subconsultas

Preencha a consulta principal e confira as consultas subordinadas, quando houver. Cada consulta cadastrada precisa ter conteúdo válido, inclusive nos níveis internos da árvore.

Use os parâmetros definidos em Dados adicionais de forma compatível com a consulta. Um parâmetro cadastrado na tela não restringe os dados se a fonte não o utilizar.

Executar consulta

A ação Executar consulta permite conferir a consulta SQL ou HQL selecionada, com os valores informados para a simulação.

Executa a consulta escolhida em modo de leitura.
Apresenta as primeiras linhas, as colunas, o tempo de execução e informações de parâmetros sem valor, conforme o resultado.
Utiliza limite padrão de 100 linhas, com teto de 1.000, e limite de tempo de consulta de 60 segundos na rotina documentada.
Não monta o layout nem executa automaticamente a árvore completa de subconsultas.

Ao simular uma subconsulta, informe os valores que normalmente seriam recebidos da linha da consulta superior. Um resultado parcial ou truncado não representa necessariamente todos os registros do BI.

Se a consulta retornar erro, confira a mensagem sobre campos, parâmetros, sintaxe ou compatibilidade. Corrija e execute novamente antes de avaliar o layout.

Código Java

Informe o nome completo da classe, conforme o código preparado.
Inclua ou edite o código-fonte.
Clique em Compilar.
Confira a situação e o Log de compilação.
Teste e salve quando a compilação estiver correta.

Qualquer alteração no fonte exige nova compilação antes de salvar ou testar. O BI executa o conteúdo compilado; o cadastro confere se ele corresponde ao fonte atual.

Em erros de compilação, confira primeiro o log. Incompatibilidades de código e dependências devem ser avaliadas pelo responsável técnico. A documentação anterior também orienta conferir se o ambiente de compilação, incluindo JAVA_HOME quando utilizado, aponta para um JDK válido no ambiente que executa o processo.

Aba Dados BI

Opções

Confira as opções de impressão, a impressora quando houver seleção específica, o nome do arquivo gerado e a senha de proteção quando aplicável ao formato e ao fluxo utilizado.

O Nome do arquivo gerado permite definir a identificação da saída conforme a configuração do BI, em vez de depender somente do nome automático. Não confunda esse campo com o nome usado para localizar o BI na listagem ou com o título impresso.

A configuração de impressora não garante impressão direta no navegador. No fluxo WEB de prévia, Visualizar e Imprimir são apresentados em PDF; confira o comportamento na operação de destino.

Versionamento

Esta seção reúne responsável, classificação, números e controles do BI, versão de estrutura e opções relacionadas ao versionamento.

As classificações disponibilizadas incluem Individual, Listagem, Etiqueta e Painel. Escolha a correspondente à finalidade do BI; ela não substitui a configuração da fonte ou do layout.

A opção Não versionar automaticamente registra o usuário responsável pela marcação. Utilize-a conforme o processo de manutenção dos relatórios, conferindo o vínculo com o repositório e as alterações locais.

Ao clonar um BI, a cópia recebe uma nova identidade de cadastro e não mantém os números e controles de vínculo com o repositório do original. Revise suas liberações e finalidade antes de utilizá-la.

Parâmetros opcionais de impressão

Nos layouts que utilizam os padrões do Touch ERP, os parâmetros opcionais permitem controlar elementos como:

Data de geração e usuário responsável pela emissão.
Parâmetros utilizados na seleção.
Título, razão social e nome fantasia.
Logo, CNPJ e inscrição estadual da empresa.
Telefone e informações de rodapé.
Fecho e assinaturas do relatório.

Selecione a opção de impressão desejada, adicione-a e informe seu valor conforme a configuração apresentada. O efeito depende de o layout utilizar essa opção; um desenho personalizado não passa a exibir um campo apenas porque o parâmetro foi incluído.

Aba Segurança

Seção	Como utilizar
Grupos	Inclua os grupos de usuários para os quais o BI deverá ser disponibilizado.
Vinculação de recursos	Associe o BI aos recursos em que deverá aparecer na seleção de relatórios, como pelo botão BI da barra de ferramentas.
Filtro por empresa	Quando habilitado, configure a lista de empresas abrangidas pela disponibilidade do BI.

Liberação de acesso e filtragem dos dados são configurações diferentes. A lista de empresas desta aba controla a disponibilidade do BI. Confira também se a consulta restringe os registros às empresas pretendidas por meio de seus parâmetros e critérios.

Depois de salvar, confira a seleção no recurso 748 — Iniciar Business Intelligence com a empresa e o grupo de usuário previstos. Um teste no cadastro não comprova que todas as liberações de uso estejam completas.

Aba Dados adicionais: parâmetros e filtros

Os dados adicionais definem os parâmetros apresentados na utilização do BI. A árvore permite organizar itens e condições, inclusive com intervalos inicial/final.

Adicione o parâmetro ou condição desejada.
Informe uma identificação compreensível para o usuário e a chave utilizada pela consulta.
Escolha o tipo do parâmetro e a forma de informar o valor.
Defina o valor padrão, as opções de seleção ou a expressão aplicável.
Configure a pesquisa de cadastros, quando necessária.
Confira se o preenchimento é obrigatório e se o usuário pode alterar o valor.
Teste a correspondência entre parâmetro, consulta e resultado.

Configuração	Finalidade
Descrição do parâmetro	Identifica a informação solicitada ao usuário. É obrigatória.
Chave	Referência utilizada pela fonte de dados para receber o parâmetro. Preserve a correspondência com a consulta.
Tipo e valor	Definem a natureza do conteúdo e como será informado, sugerido ou selecionado.
Valor obrigatório	Exige preenchimento compatível na geração.
Permitir alterar valor	Define se o usuário pode modificar o conteúdo ao utilizar o BI. Quando desmarcado, o cadastro exige um valor definido.
Critério de pesquisa	Define a origem e o comportamento da pesquisa de cadastros utilizada pelo parâmetro.
Usar condição IN	Opção para utilização de seleção em conjunto, quando compatível com a consulta e com o parâmetro.
Organizacional, texto formatado e demais opções	Ajustam a apresentação e o comportamento do filtro conforme o tipo utilizado. Confira seu efeito no teste e no fluxo de utilização.

Ao organizar a árvore, confira a relação entre parâmetros principais e filhos. Remover ou renomear uma chave pode exigir ajustes na consulta, nas subconsultas e em integrações que a utilizem.

Filtros fixos

Para definir um valor que o usuário não poderá alterar na geração:

Selecione o parâmetro em Dados adicionais.
Informe o valor adequado ao tipo de campo.
Desmarque Permitir alterar valor.
Teste o relatório e confira a seleção efetiva dos registros.

O parâmetro precisa ser utilizado pela fonte de dados. Torná-lo fixo na tela não acrescenta sozinho uma condição que não existe na consulta.

Valores sugeridos e filtros dinâmicos

Os valores podem ser sugeridos a partir de informações disponíveis na execução, como usuário e empresa logados. Na opção de valor sugerido por reflexão, utilize Padrões para consultar as referências disponíveis e selecione um caminho de campo existente.

Exemplos mantidos da documentação anterior:

Finalidade	Expressão
Identificador do usuário logado	`[usuarioLogado].identificador`
Identificador da empresa logada	`[empresaLogado].identificador`
CNPJ da empresa logada	`[empresaLogado].pessoa.cnpj`

Outras referências disponibilizadas incluem grupo da empresa, pessoa da empresa, pessoa do usuário e grupo de usuários. Nem todo campo existe em toda referência; confira o caminho e o tipo retornado.

Um valor sugerido não equivale necessariamente a um filtro fixo: confira também Permitir alterar valor e a forma como a consulta utiliza a informação.

Parâmetro a partir de outro recurso

O critério de pesquisa pode relacionar um parâmetro à entidade de um cadastro. Por exemplo, um parâmetro baseado em Produto e Identificador pode receber o produto do contexto quando o relatório é aberto pelo fluxo correspondente.

Para esse uso, confira a associação do BI com o recurso, o critério do parâmetro e como a ação de origem fornece os dados. Abrir o BI diretamente pelo recurso 748 não é o mesmo contexto de abrir a partir de um registro específico.

Imagens adicionais

A seção de imagens permite incluir conteúdo utilizado pelo relatório. Informe a descrição de cada imagem e confira sua referência no layout. Incluir a imagem no cadastro não a posiciona automaticamente na apresentação.

Aba Layout

Selecione o tipo de layout, como JasperReports ou Word, e mantenha os arquivos correspondentes ao modelo utilizado.

Informação	Como utilizar
Nome do arquivo	Identifica o layout e precisa ser preenchido. Preserve os nomes esperados pelas referências entre relatório e sub-relatórios.
Chave do layout	Identifica um conjunto ou alternativa de layout conforme a configuração do BI.
Arquivo principal	Indica o arquivo principal do conjunto. Não pode haver mais de um principal para a mesma chave de layout.
Fonte carregada / Compilado carregado	Indicam a presença dos conteúdos necessários na linha. Para Jasper, confira o fonte JRXML e o compilado Jasper.

Na gravação, os arquivos incluídos precisam ter nome e os conteúdos exigidos pelo cadastro. Um nome na grade sem o conteúdo do arquivo não equivale a um layout pronto para uso.

Adicionar, exportar e atualizar arquivos

Utilize Adicionar arquivos para carregar os layouts preparados.
Utilize a exportação de uma linha ou Exportar todos para obter os arquivos de layout, conforme as opções apresentadas.
Após editar externamente, carregue novamente os arquivos atualizados e confira o fonte e o compilado.
Mantenha as referências e os arquivos subordinados necessários ao relatório.

Exportar layouts não é o mesmo que exportar o cadastro completo do BI nem gerar um relatório com dados.

Vincular pasta e carregar automaticamente

Quando o navegador disponibilizar acesso a pastas locais:

Utilize Vincular pasta e selecione a pasta de trabalho dos layouts.
Autorize o acesso solicitado pelo navegador.
Confira os nomes dos arquivos na grade e na pasta.
Ative Carregar automaticamente para acompanhar alterações enquanto trabalha na tela.
Se o navegador solicitar nova autorização ao retornar, utilize Reativar pasta.

O carregamento procura os arquivos correspondentes aos nomes da grade. Na modalidade Jasper, são relidos os arquivos .jrxml e .jasper alterados; o fluxo também pode compilar um JRXML atualizado quando necessário.

Carregar arquivos para a tela não salva o cadastro automaticamente. Teste e salve os layouts que deseja manter. A pasta vinculada é uma pasta de trabalho autorizada no navegador, não uma configuração geral de acesso a qualquer diretório do servidor.

Gerar template

A ação Gerar Template prepara arquivos de layout a partir dos dados e parâmetros do BI. Confira a orientação de página quando solicitada.

Salve inicialmente o BI, se ainda for novo.
Abra a ação e informe perfil, formato e parâmetros necessários.
Aguarde a geração e confira os arquivos adicionados à grade.
Leia os avisos, inclusive quando não houver dados suficientes para montar a apresentação pretendida.
Teste o resultado e salve para manter o layout.

O template é um ponto de partida. Confira títulos, campos, larguras, agrupamentos, totais e quebras de página antes de disponibilizar o relatório.

Gerar layout com a Nanda

Quando a capacidade correspondente estiver disponível, a opção da Nanda na aba Layout auxilia a criação ou o ajuste do layout principal a partir dos dados e das instruções informadas.

Descreva o resultado esperado de forma concreta, por exemplo: campos a apresentar, ordem, agrupamentos e destaque de totais. Aguarde o processamento, confira os avisos, os arquivos retornados e a prévia.

O retorno fica na edição do cadastro até ser salvo. Confira dados, totais e apresentação antes da gravação. Essa ação de criação de layout é diferente de Analisar com a Nanda no recurso 748, que utiliza os dados do BI para uma conversa de análise.

Formatos de saída

Na lista de formatos, marque Liberar para as opções que deverão ser utilizadas. A lista pode apresentar todos os formatos cadastrados; somente estar listado não significa estar liberado.

Confira a compatibilidade de cada formato com a fonte e o layout. Planilhas de relatório e exportações diretas de dados podem apresentar conteúdos organizados de maneiras diferentes.

Testar sem substituir a gravação

Salve o BI pelo menos uma vez para obter sua identificação e permitir os perfis.
Clique em Testar.
Selecione perfil e formato e preencha os parâmetros.
Gere e confira os dados e a apresentação.
Volte à edição, ajuste e repita quando necessário.
Salve o cadastro para tornar definitivas as alterações de sua estrutura.

O teste utiliza o BI como está na tela, inclusive alterações ainda não gravadas, mas não salva essas alterações no cadastro. Os parâmetros e as preferências de geração podem ser gravados no perfil utilizado.

No teste, as opções de perfil, fecho e assinaturas permitem conferir esses elementos conforme o modelo do relatório. Fecho e assinaturas dependem de um layout preparado para apresentá-los.

Se o teste informar que a sessão de prévia não está mais disponível, feche e abra Testar novamente para carregar a versão atual da edição.

Parâmetros padrão e perfis: por que resultados podem mudar

O recurso 748 — Iniciar Business Intelligence utiliza os parâmetros e formatos do perfil selecionado pelo usuário.

Outras ações do ERP podem gerar um BI a partir de um registro, de parâmetros definidos na própria operação ou dos valores padrão cadastrados no recurso 747. Nem todo fluxo utiliza o perfil pessoal do usuário.

Exemplo mantido da wiki anterior: o envio de um BI por uma Ordem de Compra pode utilizar os padrões e o contexto da ordem, enquanto a geração manual do mesmo BI pelo recurso 748 utiliza as seleções do perfil.

Quando o resultado diferir:

Confira os valores padrão em Dados adicionais.
Confira os valores do perfil usado na geração manual.
Confira se a ação de origem recebe um perfil específico ou informa seus próprios parâmetros.
Compare o mesmo registro e a mesma seleção antes de concluir que a consulta está incorreta.

Quando o fluxo utilizar configurações carregadas na entrada do sistema, confira também a necessidade de nova entrada para atualizar os parâmetros, conforme a operação.

Importação, exportação, repositório e Marketplace

As opções dependem das permissões e do estado do cadastro.

Ação	Finalidade e conferência
Importar	Carrega um arquivo de cadastro de BI. Confira o resultado, as dependências e as liberações antes de utilizá-lo.
Exportar	Produz o arquivo do cadastro salvo para transporte ou manutenção. Confira a conclusão da tarefa. Salve as alterações que devem fazer parte da exportação.
Recompilar todos	Executa uma rotina abrangente de recompilação dos BIs. Acompanhe a tarefa e seus erros; não equivale a compilar somente o código em edição.
Enviar ao repositório	Encaminha o BI conforme o fluxo de versionamento, com informações da alteração e demais campos solicitados. Confira o cadastro e os dados do envio antes de confirmar.
Abrir Marketplace	Abre o acesso ao catálogo de BIs. Instalar ou obter um BI não dispensa conferir suas liberações e seu funcionamento na empresa.

Enviar ao repositório é uma ação distinta de salvar localmente. Confira o destino e o conteúdo que será compartilhado segundo o processo da empresa.

Exemplo de configuração: listagem de produtos

Defina um nome e um título que identifiquem a listagem.
Em Tipo BI, escolha Objetos e selecione a entidade Produto.
Inclua os campos necessários, como identificador e nome, conforme a estrutura disponível. Dê descrições diferentes aos campos.
Configure os critérios e a ordenação desejados.
Se houver filtro informado na geração, configure seu parâmetro e confira o vínculo com o critério da seleção.
Gere ou carregue um layout adequado e libere PDF, se compatível.
Configure os grupos e as empresas de uso, quando aplicável.
Salve, teste com uma seleção conhecida e confira os registros.
Salve os ajustes e confira a geração pelo recurso 748.

Esse exemplo ilustra o processo; campos e critérios devem ser escolhidos conforme a necessidade da empresa. Para uma exportação direta de dados, confira o formato apropriado em vez de supor que a apresentação será idêntica à do PDF.

Problemas e soluções

Situação	O que verificar
O cadastro não salva	Confira nome do BI, tipo de layout e as mensagens dos campos específicos da fonte, dos arquivos, dos parâmetros e das imagens.
O BI por objetos informa descrições repetidas	Preencha descrições distintas para os campos selecionados.
SQL/HQL informa consulta obrigatória	Confira a principal e todas as consultas subordinadas na árvore.
O código foi alterado depois de compilar	Compile novamente, confira o log e só então teste ou salve.
Há erro de arquivo principal	Confira se existe mais de um principal na mesma chave de layout.
O layout aparece na grade, mas falta conteúdo	Confira os indicadores de fonte e compilado e carregue os arquivos correspondentes.
Um parâmetro fixo não é aceito	Com Permitir alterar valor desmarcado, informe um valor compatível no cadastro.
O BI funciona no teste, mas não aparece para o usuário	Confira situação, grupos, filtro por empresa, associação com o recurso e gravação das alterações.
O relatório de uma ação do ERP difere do gerado no 748	Compare parâmetros padrão, contexto do registro e perfil efetivamente utilizado em cada fluxo.
O formato desejado não aparece na geração	Confira Liberar na grade de formatos e a compatibilidade com o sistema e o BI utilizado.
Alterei a edição, mas o usuário continua com o relatório anterior	Testar e carregar layouts não substituem Salvar. Confira também se o usuário está utilizando o mesmo BI e layout.

Assinaturas e layouts antigos

A wiki anterior registra uma orientação para layouts antigos com problema na apresentação de assinaturas: revisar o sub-relatório de fechamento na banda summary e sua propriedade Stretch Type, para permitir o redimensionamento conforme o conteúdo. Confirme o ajuste no editor e na versão do layout utilizados.

Não utilize somente o código de uma mensagem para atribuir a causa ao layout. Na versão documentada, a mensagem V.ERP.0747.023 também identifica falta de valor em parâmetro fixo. Leia o texto completo e confira em qual etapa o erro ocorreu.

Integração com outros sistemas

BIs também podem ser utilizados em integrações para geração ou exportação de dados, conforme a autenticação, as permissões e os parâmetros do fluxo correspondente.

Consulte Integração BI por Web Services para o assunto específico. A disponibilidade de um BI no cadastro não o transforma automaticamente em uma consulta pública.