Chamada de API da Senior X
Uma alternativa para popular informações de relatório é chamando um endpoint de uma API RESTful permitindo uma interação com o protocolo HTTP.
Alguns cuidados devem ser tomados, caso exista alguma autorização ao recurso requisitado, tal como informar o token e ambiente correto para a requisição. Neste tutorial será descrito como utilizar essas informações dinamicamente através de parâmetros do relatório.
Para esse tutorial, estaremos utilizando o TIBCO Jaspersoft® Studio 6.14.0 e a primitiva listUsers.
Criando o projeto para o relatório
Crie um novo projeto do tipo Jasper Reports Project
Criar um Adapter
1. Na aba *Repository Explorer*, clique com o botão direito do mouse sobre *Data Adapters*
2. Selecione *Create Data Adapater*
3. Nomeie para algum nome entendível, esse nome será necessário para exportar seu Adapter
4. Selecione *JSON File* e botão *NEXT*
5. Na caixa de digitação *File* digite um endereço http/https. Ex.(https://platform-arquitetura.senior.com.br/t/senior.com.br/bridge/1.0/rest/platform/user/queries/listUsers)
6. Clique sobre o botão **Options**
7. Em *Request Type*, selecione o método de requisição desejado (GET, POST ou PUT)
8. Em *Options*, selecione a aba *Http Headers*
9. Adicione os parâmetros com os respectivos valores:
| Name | Value | |
| Content-Type | application/json | |
| Authorization | Bearer <ACCESS_TOKEN> |
10. Selecione a aba *POST Parameters* ou *PUT Parameters*, depende da opção selecionada no item 7.
11. Selecione o checkbox *Free text in BODY*
12. Adicione o payload. Ex:
{
"pagination": {
"pageNumber": 0,
"pageSize": 2147483647
},
"ordination": {
"sortBy": "name",
"sortOrder": "ASC"
},
"includeBlocked": true,
"authenticationTypes": [
"G7"
]
}
13. Clique sobre o botão *Test *para verificar se a requisição está funcionando.
Criando o relatório
Após selecionar no projeto o tipo de relatório que irá criar, na tela de Data Source, selecione no combobox o Data Adapter criado no passo anterior.
Caso a requisição tenha sido bem sucedida, o JSON de retorno é exibido para selecionar os campos que deseja ter em seu relatório. Selecione todos os valores que deseja e clique no botão NEXT.
Então uma nova tela com os Fields que deseja no relatório será exibida para escolher.
O mesmo acontece para agrupar os Fields em Group By.
Ao finalizar, todos os campos escolhidos estarão disponíveis para o seu relatório.
Exporte o Adapter
- Retorne a aba Repository Explorer
- Clique com o botão direito do mouse sobre o Adapter criado anteriormente
- Selecione Export to File
- Selecione o projeto criado anteriormente
- Escolha um novo nome para o Adapter
- Clique sobre o botão OK
Parâmetros
Será necessário alterar os parâmetros do Relatório criado, assim também no Adapter exportado.
Eles deverão alterar de forma dinâmica o ambiente utilizado (dev, homolog, prod, etc…) e o Token de autorização para requisições das APIs da Senior.
Abra seu arquivo .jrxml e selecione a aba Source
Adicione as seguintes linhas após o último elemento de <property>
<parameter name="SENIOR_TOKEN" class="java.lang.String" evaluationTime="Early">
<property name="net.sf.jasperreports.http.data.header" value="Authorization"/>
</parameter>
<parameter name="SENIOR_REST_API_URL" class="java.lang.String" evaluationTime="Early"/>
<parameter name="SENIOR_API" class="java.lang.String" isForPrompting="false" evaluationTime="Early">
<property name="net.sf.jasperreports.http.data.url"/>
<defaultValueExpression><![CDATA[$P{SENIOR_REST_API_URL}.toString()+"platform/user/queries/listUsers"]]></defaultValueExpression>
</parameter>
Os parâmetros informados tem as seguintes funções:
| Nome | Descrição |
|---|---|
| SENIOR_TOKEN | Contém o token de autenticação do usuário que executou o relatório. |
| SENIOR_URL_API | Contém a URL do endpoint do ambiente a ser requisitado os dados para popular o relatório |
| SENIOR_API | Irá concatenar o parâmetro SENIOR_URL_API com o caminho da primitiva desejada. Ex. $P{SENIOR_REST_API_URL}.toString()+”platform/user/queries/listUsers” |
Observação: altere o caminho final do parâmetro SENIOR_API para realizar uma chamada na primitiva desejada, diferente de listUsers.
Abra o arquivo XML do Adapter exportador em um editor de texto.
Remova os elementos abaixo:
<url> <postParameter><name>Authentication</name><value>Bearer XXXX</value></postParameter> <header><name>Authorization</name><value>Bearer XXXX</value></header>
Internacionalização / I18N
Para utilizarmos um relatório utilizado globalmente, com suporte a várias línguas (ex. português, espanhol, inglês, etc…), adaptando as mensagens e textos de um produto, devemos utilizar o recurso de internacionalização. Esse recurso permite respeitar além da língua, particularidades de cada país.
No Jasper o arquivo de internacionalização é definido pelo Resource Bundle. Para o relatório Jasper, os arquivos de internacionalização tem a seguinte estrutura:
<code><NOME>_<língua>_<PAÍS>.properties</code>
| Nome arquivo | Língua | PAÍS |
|---|---|---|
| Test_en_US.properties | en = inglês | US = Estados Unidos |
| Test_es_ES.properties | es = espanhol | ES = Espanha |
| Test_pt_BR.properties | pt = português | BR = Brasil |
Definindo o arquivo
Após criar os arquivos para os idiomas que deseja, em um local no projeto de sua preferência.
Para definir os arquivos, clique sobre o relatório, visualize a propriedades e selecione o “nome” do arquivo(bundle) que irá conter as propriedades de internacionalização.
Parâmetros do JasperReports
Os parâmetros abaixo são usados pelos relatórios para utilização exclusivamente do Jasper e internacionalização dos relatórios.
| NOME | DESCRIÇÃO |
|---|---|
| REPORT_LOCALE | Inserir um objeto do tipo java.util.Locale. Este parâmetro é importante para que o JasperReports saiba corretamente qual o idioma utilizar no relatório. |
| REPORT_RESOURCE_BUNDLE | Inserir um objeto do tipo java.util.ResourceBundle contendo mensagens internacionalizadas. |
| REPORT_TIME_ZONE | Inserir um objeto do tipo java.util.TimeZone para formatar datas corretamente conforme o fuso horário. |
Preparação para publicação
Após criado o modelo do relatório este pode ser preparado para publicação.
No caso de um modelo simples, que não utiliza imagens ou outros artefatos, basta utilizar o arquivo com extensão
Neste caso, o modelo utiliza imagens e do adapter, será necessário montar um arquivo
Sub-relatórios devem estar referenciados no arquivo com a extensão .jasper (ex: “detalhe-modelo.jasper”), o executor de relatório irá compilar e gerar o arquivo jasper no mesmo local, não sendo necessário anexar este. Ex:
users.zip/ | |── users.jrxml | |── logoempresa.jpg | |── WS-ListUsers.xml
⚠ Os arquivos devem estar diretamente na raíz do zip, não em uma pasta.
⚠ O arquivo principal
Publicação de Relatórios
A publicação de um relatório pode ser feita de duas maneiras, através da API do serviço report-backend ou através do front-end do serviço de relatórios.
A API do serviço de relatórios deve ser utilizada por outros serviços da plataforma que precisam criar os seus próprios relatórios. Serviços que criarem os seus próprios relatórios devem associar o relatório ao seu dominio e serviço, dessa forma o relatório criado será listado no domínio correto.
A criação de relatórios através do front-end do serviço deve ser utilizada por administradores/consultores que desejam criar relatórios customizados para o seu tenant. Os relatórios criados através do front-end do serviço serão automaticamente associados ao domínio e serviço custom e report respectivamente.
Publicando Relatórios através do front-end
Para ir para a tela de publicação de relatório basta clicar no menu ** Tecnologia > Customização > Relatórios > Novo Relatório**.
Para publicar o relatório é obrigatório que seja informado um Nome para o relatório e anexado o modelo de relatório, os outros campos são opcionais. Aqui é possível visualizar a documentação para criação de um modelo de relatório.
Abaixo é apresentada a tela de publicação de relatório.
Ao criar um relatório também é possível criar menus para acessar a tela do relatório. Para criar um menu para o relatório basta clicar em Novo na seção Menus do Relatório.
Podem ser adicionados menus ao menu principal da plataforma (Menu lateral da Senior X Platform) e ao menu de contexto de uma tela (Menu apresentado ao clicar em … no canto inferior do menu lateral).
Para adicionar um menu ao menu principal deve ser selecionado um menu que seja agrupador de submenus, quando a opção No menu principal estiver selecionada só será permitido selecionar menus agrupadores. Para adicionar um menu ao contexto de uma tela deve ser selecionado o menu da tela desejada, Quando a opção No contexto de uma tela estiver selecionada não será possível selecionas menus que são agrupadores de submenus. Quando não for possível associar o tipo do menu do relatório a um menu será apresentado um ícone de negado antes do nome do menu.
Abaixo são apresentados os menus Configuração e Globais, nessa imagem o usuário pode selecionar o menu Configuração e não pode selecionar o menu Globais para associar ao novo menu do relatório.
Abaixo é apresentada a modal para adicionar um menu ao relatório.
Os menus do relatório serão apresentados na seção Menus do Relatório. Eles serão separados em duas subseções Menu principal e Menu do contexto de uma tela.
Abaixo é possível visualizar os menus de um relatório.
Após preencher todas informações necessárias para a criação do relatório basta clicar no botão Salvar da tela de publicação de relatório. A criação/alteração dos menus do relatório é feita de forma assíncrona, assim o usuário que criou o relatório receberá uma notificação quando o processamento de cada menu for finalizado.
Para seguir as boas práticas do SX e agiliar o desenvolvimento, faça download do template/modelo.