Editando relatórios

Para editar um relatório e realizar as configurações necessárias, é preciso selecionar um relatório e logo clicar no botão EDITAR.

Relatórios flexibilizados por outra entidade através da ferramenta Orquestrador por exemplo ficam com o botão desabilitado, podendo realizar a edição apenas na base criada. Relatórios criados direto na base ficam com o botão habilitado, também fica visível nas informações do artefato a entidade flexibilizada.

Ao clicar no botão EDITAR é aberta a tela de rascunho do relatório, através desse ambiente será criado filtros, será inserido parâmetros, realizado o upload do arquivo configurado no Jasper entre outras.

Mas para que serve um rascunho?

A partir do momento que um usuário clica no botão Editar, é criado um rascunho baseado na última versão. Assim, a ferramenta cria uma versão temporária para o relatório, ou seja, tudo que for mudado não influenciará a versão original. A partir do momento que clicar no botão PUBLICAR a ferramenta grava as alterações realizadas e daí sim será gerado uma nova versão para o relatório. Quando um usuário realizar qualquer alteração, aparecerá apenas para ele, só ficará visível para os demais usuários da entidade quando publicado as alterações.

A direita da tela é exibido data, hora e a versão do relatório, esse recurso serve para orientar o desenvolvedor, ou seja, assim que algo for modificado e publicado irá subscrever as informações. Observe nas imagens abaixo:

Na tela abaixo são apresentados recursos para que o usuário possa configurá-los. Veja os detalhes abaixo:

No centro da página são exibidas informações do relatório principal, onde são mostrados a fonte, origem e natureza. Nos dois botões do lado esquerdo, o usuário desenvolvedor consegue inserir sub-relatórios e configurar a fonte.

Projeto

Quando gerado um relatório, automaticamente a ferramenta cria um arquivo e fica disponível no item PROJETO. Nele existem as configurações de parâmetros, propriedades, metadados, que estão dentro do banco de dados e ao serem incorporados em um relatório vai sendo adicionado no projeto existente. Portanto, quando um relatório é executado ele consome informações de todas essas fontes e interpreta o arquivo como um único documento. Perceba que existem dois itens em ações disponíveis: Baixar e Gerar dados pré-visualização.

Ao clicar em Baixar, é realizado o download para que seja possível editar os arquivos JRXML no Jaspersoft, é neste software que será construído o layout do relatório. Ainda nesta tela, há uma mensagem informando que os dados para pré-visualização não estão prontos. Aqui, a ferramenta informa que ao desenvolver um relatório não se tem os dados locais, ou seja, não dá pra testar no local, por isso o desenvolvedor precisa realizar o upload do projeto e testar novamente no ambiente da ferramenta.

Realizando o upload do arquivo com o novo layout é possível gerar a pré-visualização do relatório em PROJETO > Gerar dados pré-visualização.

Informe a quantidade de registros (10, 15, 100, 200) que deve aparecer ao gerar na pré-visualização e pressione o botão GERAR.

A tela de pré-visualização de dados será exibida também clicando em gerar os dados.

Geradas as informações, baixe o arquivo e visualize no Jaspersoft.

Propriedades

PROPRIEDADES são configurações iniciais realizadas ao construir um relatório, onde é possível visualizá-las e editá-las informações inseridas na primeira etapa dos relatórios e ainda, inserir outras informações como descrição, natureza e documentação. Após qualquer alteração clique em SALVAR para gravar as informações.

Neste recurso é necessário ter um pouco de cuidado ao editar o campo Fonte, pois o relatório criado busca determinados campos e ao trocá-lo não encontrará mais as informações. O desenvolvedor responsável pela mudança deve atentar-se aos impactos dessa ação e ajustar os problemas causados.

Cadastrando uma documentação que possui as opções, nenhuma, link ou arquivo a informação será exibido no Assistente F4 dos produtos ao serem executados. Mas essa informação aparecerá somente após a publicação do relatório.

Documentação cadastrada no Gerenciador de Relatórios

Informação exibida no Assistente F4

Parâmetros

A ferramenta permite que parâmetros sejam adicionados para que sejam informados dados para execução dos relatórios. Muitos desenvolvedores se confundem com parâmetros e filtros, a diferença é:

Filtro: onde pega-se o parâmetro ou um dado fixo e configurar para buscar determinadas informações da fonte;
Parâmetro: utilizado para passar os dados para o filtro como também passar internamente uma configuração pessoal de organização ou afins. Para adicionar um parâmetro, pressione o botão +PARÂMETROS.

O nome deve seguir as regras de nomenclatura de variáveis da linguagem BFCScript, sendo que não podem existir parâmetros com o mesmo nome. Insira uma descrição e se necessário uma dica de preenchimento (auxilia no preenchimento do campo), essa informação é exibida ao passar o mouse em cima do campo.

Logo abaixo há o campo Tipo do dado, que é referente a um padrão do parâmetro. Aqui, a ferramenta dispõe de nove opções, acompanhe abaixo os detalhes de cada uma delas:

Arquivo: realiza upload de um arquivo e exibe no relatório o layout de um arquivo com extensão TXT, CSV e XML;

Caracter: permite informar um dado do tipo texto, ou seja, é possível digitar uma frase, números, símbolos.

Data: define um valor padrão como uma data específica, exemplo: 30/09/2021 ou variáveis: primeiro dia do mês;

Data e hora: semelhante a opção Data, porém exibe a hora quando selecionado a opção data específica;

Inteiro: permite informar um número do tipo inteiro (sem casas decimais);

Lista múltipla: apresenta um campo chamado Opção da lista contendo as seguintes opções: Dinâmica (listagem onde a origem entrega dados a serem alimentados em uma lista dinâmica e exibe informações das fontes de dados proveniente dos sistemas. Permitindo configurá-la e selecioná-las várias opções para que as informações desejadas sejam exibidas no relatório), Estática (permite selecionar várias opções) e Indefinida (fica a critério do usuário preencher com informações que desejar, formando valores indefinidos);

Opção da lista - Dinâmica

Opção da lista - Estática

Opção da lista - Indefinida

Lista simples: possui as mesmas opções da listas Dinâmica, a única diferença é que permite selecionar apenas uma opção e Estática permite selecionar apenas um item criado pelo usuário desenvolvedor;

Opção da lista - Dinâmica

Opção da lista - Estática

Mês/Ano: define um valor padrão como mês/ano específico (09/2021) ou variáveis (próximo mês);

Valor: exibe um número fracionário de casas decimais.

É possível definir se o parâmetro será de preenchimento obrigatório ou opcional, também inserir mais de um parâmetro para o mesmo relatório.

Pode-se especificar um valor padrão, ou seja, ao abrir a tela já vem com o campo do parâmetro cadastrado preenchido quando os campos Visível e Habilitado estiverem marcados como SIM.

Preencha as informações do formulário e ao final, clique em SALVAR, SALVAR NOVO ou CANCELAR.

Todos os itens criados ficam na tela de definição de parâmetros, podendo editá-los ou excluí-los.

Ao executar o relatório, perceba que os dois parâmetros cadastrados mostrados na imagem anterior aparecem nesta tela.

Senha: é possível criar parâmetros com o tipo “Senha”, das quais possuem um comportamento semelhante aos parâmetros do tipo caracter, porém os mesmos não tem seu valor armazenado após a execução, ou exibidos no detalhamento de execuções após a finalização.

Detalhamentos sobre esse tipo de parâmetro:

Não é possível atribuir um valor padrão para parâmetros do tipo “Senha”;
O valor do parâmetro não é preenchido na reexecução;
Parâmetros do tipo senha não são convertidos para marcadores automaticamente;
Parâmetros do tipo senha não são exibidos na consulta de execuções.

ATENÇÃO!

Em tempo de execução, esse tipo de parâmetro se comporta de forma idêntica a parâmetros do tipo caracter, de forma que o desenvolvedor tem liberdade na utilização do mesmo, porém, sugere-se atenção na hora de exportar o valor do parâmetro no log ou impressão do relatório, a fim de evitar o vazamento de informações sensíveis.

Definindo layout dos parâmetros nos relatórios

Ao cadastrar os parâmetros é possível definir o layout de forma avançada, ou seja, melhorando o preenchimento no momento da execução, possibilitando também a estilização como posição e tamanho dos parâmetros. Após a criação dos parâmetros, acesse Editar > Parâmetros > Definir layout, logo, realize as mudanças desejadas. Quando o usuário realizar a execução do relatório no Gerenciador de Relatórios ou no F4 aparecerá todos os parâmetros com o layout previamente configurados desde que as alterações estejam publicadas.

É permitido ainda definir o tamanho da janela dos parâmetros. As opções são: Padrão, Média ou Grande.

Consequentemente, a configuração estabelecida ficará disponível no Assistente F4.

Padrão

Média

Grande

Visualizando marcadores

É possível definir um parâmetro como um marcador, assim o valor utilizado neste parâmetro será utilizado para identificar as execuções realizadas em um Relatório ou Script na tela de execuções das ferramentas. Ao clicar em uma extensão sendo um relatório ou script é possível visualizar os marcadores na tela da listagem das execuções dos artefatos, porém só aparecem quando preenchidos na hora da execução e que sejam habilitados na tela de parâmetros.

Para visualizar os marcadores na listagem de execuções, clique no ícone representado por um olho e selecione a opção Marcadores.

Observação: A última seleção do usuário é mantida ao retornar para a listagem de execuções.

Para que os marcadores sejam apresentados como mencionado anteriormente, é necessário habilitar a opção Utilizar como marcador onde pode-se adicionar e/ou editar um parâmetro. Porém, quando nenhum marcador for selecionado, os três primeiros parâmetros serão utilizados como marcadores. Observa-se, ainda, que parâmetros do tipo “arquivo” não suportam marcadores.

Habilitando o parâmetro mostrado no parágrafo anterior, na tela de definição dos parâmetros é apresentado um ícone em forma de lista antes do nome.

Recursos importantes da lista Dinâmica

Os parâmetros dinâmicos consistem nos parâmetros do tipo Lista simples ou Lista múltipla, que filtram informações de acordo com uma fonte de dados pré-definidos, a única diferença entre esses tipos é que: a simples aceita apenas uma opção e a múltipla permite selecionar várias, como mostrado anteriormente.

A listagem dinâmica é uma origem que entrega dados a serem alimentados dinamicamente, as informações apresentadas vêm dos catálogos de dados fornecidos pelos sistemas.

É necessário selecionar a categoria da fonte para que as fontes sejam exibidas.

A fonte de dados é uma API e possui diversos campos/atributos como uma tabela no banco de dados, portanto, ao selecionar uma API para ser a origem da listagem é necessário fornecer algumas informações, pois quando selecionado o valor da listagem essa seleção retorna um dado, com essa informação será enviado para a execução do relatório.

O campo Valor será considerado quando selecionar o valor da listagem, para isso, se faz necessário definir o atributo da fonte de dados que representará o valor para filtrar o relatório.

No campo Descrição deve ser informado o que aparecerá como descrição na listagem. Abaixo desse campo a ferramenta traz alguns dados, isso acontece porque nem tudo que se pode visualizar poderá ser filtrado. Neste item é possível inserir mais de uma informação.

No campo Filtro a ferramenta sugere o que pode ser filtrado, deixa inserir mais de uma informação e será apresentado apenas o que foi informado.

Veja abaixo como aparecem as informações inseridas anteriormente.

Quando inserido o nome do banco irá trazer a informação, pois foi especificado para filtrar esse parâmetro.

Na mesma linha da Descrição tem o nível, esse recurso mostra a quantidade de níveis da fonte de dados para compor a descrição, ou seja, as fontes tem uma espécie de hierarquia. Exemplo: dentro da fonte agências bancárias tem objetos, na expressão bairro.municipio.codigoibge possui 3 níveis, porém podem ter expressões contendo vários níveis.

A ferramenta suporta dados de grande complexidade, porém é o usuário desenvolvedor que informa a quantidade de níveis através dos símbolos de - e + que serão exibidos neste campo. Dessa forma a ferramenta vai adentrar na hierarquia dos dados dessa fonte.

Na tela Definindo parâmetros encontra-se a ordenação das informações disponíveis através dos pontos do lado esquerdo, apenas arraste para a posição que desejar.

Nessa tela estão presentes também os recursos de edição e exclusão dos parâmetros criados. Para dar início à ação desejada, pressione em um dos dois ícones mostrados na imagem abaixo.

Os campos serão visualizados na DEFINIR LAYOUT a partir da ordem estabelecida na tela de definição de parâmetros.

Ordenação

Definir a ordem das colunas através do botão ORDENAÇÃO.

Pressionando o botão mencionado anteriormente, uma tela é aberta para que sejam definidas as colunas. Ao marcar os itens, elas aparecem no lado direito em forma de colunas facilitando a visualização. Na coluna Classificação o usuário pode optar por apresentar as informações de forma crescente ou decrescente.

Filtros avançados

Filtros avançados é uma ferramenta que permite com que o usuário filtre informações de acordo com critérios. Para realizar esses filtros é necessário clicar no botão FILTROS AVANÇADOS.

Uma nova janela é aberta onde é possível editar (parte central da tela) os filtros de maneira codificada através do BFC-Script, possibilitando um nível mais avançado de filtragem de dados. No canto superior direito exibe os critérios através da expressão Como utilizar.

Clicando em Como utilizar, a ferramenta possibilita customizar e detalhar os filtros.

Metadados

Metadados, são dados que facilitam o entendimento dos relacionamentos e a utilidade das informações dos dados. Todos os dados descritivos em um documento, físico ou digital, sobre autor, data de criação, local de criação, conteúdo, forma, dimensões são metadados.

A ferramenta de Relatórios apresenta a necessidade de agrupar relatórios emitidos a partir de determinadas configurações, portanto, o intuito deste recurso é possibilitar que outras aplicações consigam identificar se um determinado relatório foi gerado e possam utilizá-los como resultado para outra finalidade.

Sua configuração pode ser por meio de um parâmetro criado no relatório ou ainda, determinar um valor desejado. Esse recurso é utilizado em relatórios com extensão PDF, utilizadas por exemplo nas assinaturas digitais possibilitando e ficando armazenado internamente como metadado. Para definir um novo metadado, pressione o botão +METADADO.

Adicionando metadados e marcadores customizados nos relatórios

Ao desenvolver um relatório é possível criar variáveis que serão adicionadas como metadados customizados do arquivo PDF, e também propagadas como marcadores para as demais ferramentas.

Todas as variáveis que tiverem o prefixo BTHMETADADO serão tratadas como um metadado customizado e um marcador.

A coleta desses valores acontece ao término de impressão de cada página do relatório, portanto para relatórios particionados é possível ter metadados customizados com valores diferentes para cada arquivo PDF gerado. Por esse motivo é importante se atentar para a correta configuração das propriedades da variável, pois impactam diretamente em como e quando o valor vai ser computado, para mais informações técnicas, favor consultar a documentação de variáveis do jasper.

Os valores dos marcadores serão coletados na impressão da última página do relatório, pois são globais para a execução, não importando se o relatório é particionado.

Caso o desenvolvedor do relatório crie algum marcador que conflite com os que são enviados pelos sistemas quando iniciam a execução, os mesmos serão ignorados, ficando com o valor fornecido pelo sistema.

A seguir temos um exemplo de criação de um metadado customizado.

Imagem1: Definição da variável com o prefixo necessário

Imagem 2: Verificando os metadados customizados no arquivo PDF gerado

Relatórios

Relatórios são conjuntos de informações utilizados para reportar resultados parciais ou totais de uma determinada atividade.

Na ferramenta de Relatórios é necessário realizar o download do arquivo contendo as informações cadastradas e levá-la para a ferramenta Jaspersoft para que seja feito todo o layout proporcionando um relatório amigável, organizado e fácil de ler.

Ao clicar em RELATÓRIO, uma nova tela é aberta para que o usuário possa baixar os arquivos com todas as informações e levar até o Jaspersoft. Após estruturá-lo, realize o upload do arquivo.

Configuração da fonte

Neste recurso são apresentadas as configurações da fonte, pois nas propriedades do relatório é inserido a fonte que se vai trabalhar. Nesse ambiente são apresentadas as seguintes ações disponíveis: Colunas, Filtros e Ordenação. Esse recurso está presente apenas para relatórios com Origem da fonte Padrão.

Colunas

Exibe as colunas do ativo da fonte para que possam ser consultados e configurados, ao lado são mostrados apenas os campos selecionados.

Disponíveis

Selecionadas

Filtros

Os filtros têm por objetivo configurar a sessão da fonte. Para montar uma expressão e realizar a filtragem pressione o botão +LINHA. A ferramenta permite criar várias linhas contendo critérios de buscas para os relatórios.

Para que seja apresentado algo no campo Valor, é necessário que os parâmetros sejam cadastrados e no campo Tipo do valor precisa ser selecionado a opção Parâmetro. Realizando esses passos é criado uma espécie de "cola" entre os parâmetros e as opções de filtros dos ativos que a ferramenta oferece. No campo Filtro a ferramenta exibe a expressão criada inseridas nos campos de cima.

Ao executar esse relatório a opção Nome é exibida como um campo de busca. Neste exemplo, ao digitar Central e executar o relatório, serão apresentadas todas as informações com o nome CENTRAL.

Ainda na tela de definição dos filtros existe o botão +GRUPO. Basicamente indicam a ordem de execução da operação booleana do filtro, de forma semelhante aos parênteses em cálculos matemáticos.

Para inserir uma nova linha é necessário inserir uma junção que pode ser E ou OU. Perceba que a expressão no campo Filtro tem bastante informações, devido a quantidades de dados inseridos.

No item AVANÇADO, o usuário desenvolvedor pode criar filtros como na aba Básico, porém usando códigos fornecidos por cada fonte de dados ou adicionando scripts. Este recurso é igual ao utilizado nos filtros avançados dos Parâmetros.

Para visualizar os critérios clique na opção Como utilizar e na sequência é aberta a tela de critérios.

Para que não haja erros na execução dos filtros com lista múltipla é necessário testar com campo vazio, com um item e dois ou mais itens. Se não apresentar erros pode publicar e ficar segura que também não apresentará erro para os clientes.