Importante
Caro Cliente,
O TOTVS ECM 3.0 foi fundamentado na tecnologia de interface Flash, do qual a Adobe irá descontinuar seu suporte em 31/12/2020.
Recomendamos que nossos clientes avaliem a utilização do TOTVS Fluig Plataforma, que proporciona uma maior abrangência de recursos e importantes inovações tecnológicas. São inúmeras novidades não só em ECM e BPM que o Fluig entrega aos seus mais de 4 mil clientes, mas também conta com recursos de portais, social e identidade única.
Entre em contato com seu executivo de conta para saber mais detalhes desta oferta.
O objetivo deste documento é descrever o desenvolvimento, publicação e visualização de relatórios no TOTVS | ECM, para facilitar a compreensão será detalhado um exemplo de relatório de colaboradores.
Para o desenvolvimento de relatórios é necessário possuir o Java™ JDK/JRE superior a 1.6. Endereço para download: http://java.sun.com/javase/downloads/index.jsp.
O TOTVS | ECM utiliza o BIRT como motor de execução de relatórios, por esse motivo para o desenvolvimento de relatórios deve-se utilizar o padrão e a metodologia do BIRT.
Recomenda-se o uso BIRT Report Designer para o desenvolvimento de relatórios para o TOTVS | ECM. Através do endereço http://download.eclipse.org/birt/downloads/ é possível baixar a sua versão atual. É recomendado utilizar a versão All-in-One do, pois já conta com o Eclipse e o plugin do BIRT instalado por padrão.
O BIRT Report Designer conta com várias funcionalidades que auxiliam no desenvolvimento de relatórios. Entre elas destacam-se: ajuste de layout, configuração de acesso a dados e formatação do relatório.
Em caso de execução do TOTVS | ECM em ambiente SaaS, não é recomendado o uso de relatórios, pois é possível criar relatórios que retornem informações de outras empresas via consulta JPQL ou Dataset. Para garantir a não execução, é necessário definir o valor “true” para a variável “SaaS” localizada em: %JBOSS_HOME%\server\default\deploy\wdk-service.xml.
Ex: <jndi:binding name="webdesk/SaaS"><jndi:value>true</jndi:value></jndi:binding>
Através do BIRT Report Designer é possível criar vários relatórios para o TOTVS | ECM, acessar dados do banco de dados do produto via consulta JPA, JDBC. É possível acessar os dados de outros produtos por conexão JDBC, Web Service ou arquivos XML.
Para facilitar a compreensão a respeito do desenvolvimento de relatórios para o TOTVS | ECM, será demonstrado um exemplo de criação de relatórios. A seguir os passos necessários para a criação do relatório de colaborador, sendo este com dados providos do TOTVS | ECM através da consulta JPA. O fonte do exemplo citado neste documento encontra-se em: “Documentos de Customização\Arquivos Adicionais\Template de Relatorio\Colleague Report”.
Abra o BIRT Report Designer selecione o menu File -> Project conforme a figura 1.
Figura 1 – Novo projeto.
Ao abrir a janela New Project, selecione a opção Business Intelligence and Reporting Tools -> Report Project, clique no botão Next e defina o nome colleague_report como nome para o projeto do relatório, selecione a localização do projeto e clique em Finish conforme a figura 2.
Figura 2 – Tipo de projeto.
Após a criação do projeto na área Navigation clique com o botão direito do mouse sobre o projeto colleague_report e selecione New -> Report, conforme a figura 3.
Figura 3 – Novo relatório.
Ao abrir a janela New Report defina report.rptdesign como nome do relatório, clique no botão Next e selecione a opção Blank Report para template do relatório, em seguida clique no botão Finish conforme a figura 4.
Figura 4 – Definindo o tipo de relatório.
Um Data Source é mecanismo que guarda os dados de conexão com a fonte de dados, por exemplo, configurações JDBC, Web Service, entre outros. No caso desse relatório será utilizado o acesso aos dados via linguagem JavaScript.
Ao criar o novo relatório, selecione a aba Data Explorer, clique com o botão direito do mouse sobre o item Data Source em seguida selecione a opção New Data Source conforme a figura 5.
Figura 5 – Novo Data Source.
Ao abrir a janela New Data Source, selecione a opção Scripted Data Source e define o nome dsColleague como Data Source Name em seguida clique no botão Finish, conforme a figura 6.
Figura 6 – Tipo de Data Source.
Na aba Data Explorer clique com o botão direito do mouse sobre o item Data Sets em seguida clique na opção New Data Set conforme figura 7. Data Set é uma tabela temporária do BIRT no qual os dados são armazenados do Data Source e renderizados no relatório.
Figura 7 – Novo Data Set.
Ao abrir a janela New Data Set define colleagueDataSet como Data Set Name, clique no botão Next em Output Columns clique no botão Add e adicione todas as os registros do DataSet:
Column Name | Data Type | Column Alias | Display Name |
---|---|---|---|
colleagueId | String | Vazio | Vazio |
Login | String | Vazio | Vazio |
colleagueName | String | Vazio | Vazio |
String | Vazio | Vazio | |
active | String | Vazio | Vazio |
adminuser | String | Vazio | Vazio |
Em seguida clique no botão Finish conforme a figura 8.
Figura 8 – Colunas do Data Set.
É possível incluir parâmetros no relatório a serem solicitados para o usuário antes da sua renderização, auxiliando no filtro de consulta aos dados gerando um relatório específico.
Selecione a aba Data Explorer, em seguida clique com o botão direito do mouse no item Report Parameters, selecione a opção New Parameter conforme a figura 9.
Figura 9 – Parâmentros do Relatório.
A figura 10 ilustra a janela de inclusão de parâmetros.
Figura 10 – Configuração de parâmetros.
Ao abrir a janela New Parameter inclua os seguintes parâmetros:
Matrícula
Mostrar usuários
Selection Values
Value | Display Text |
* | Todos |
true | Ativos |
false | Inativos |
Ordenar por
Selection Values
Value | Display Text |
c.colleaguePK.colleagueId | Matrícula |
c.colleagueName | Nome |
c.login | Login |
O TOTVS | ECM disponibiliza TAG’s de substituição que auxiliam no desenvolvimento e na segurança da geração das informações do relatório, são elas:
As TAG’s são úteis em casos de informações que só devem ser geradas a respeito da empresa em que o usuário está autenticado, ou em relatórios que mostrem somente informações a respeito do usuário autenticado no TOTVS | ECM.
No exemplo apresentado neste documento será populado o relatório através de dados providos de consultas JPA acessando o banco do TOTVS | ECM, porém é possível utilizar outros recursos para popular o Data Set: XML, Web Service e JDBC.
O BIRT renderiza o relatório através da execução de seus eventos, são muitos os eventos disponibilizados pelo BIRT, nesse exemplo serão utilizados:
Através dos eventos é possível desenvolver a lógica de consulta e geração de dados através da linguagem de programação JavaScript , além disso é possível fazer uso de vários recursos e bibliotecas da linguagem Java™.
Selecione a aba Script na pagina do relatório e em seguida selecione o evento initialize, em inclua o seguinte código conforme figura 11:
Figura 11 – Evento initialize
importPackage(Packages.java.io); importPackage(Packages.com.datasul.technology.webdesk.dataset.service); importPackage(Packages.java.util); var query = null; var resultSet = null; var rowMap = null; var count = 0; var sqlJpa = "";
O código a cima importa as bibliotecas Java™ e a biblioteca disponibilizada pelo TOTVS | ECM para consulta aos dados do produto via JPA, além de realizar a inicialização das variáveis utilizadas pelo relatório.
Detalhes sobre o código:
Selecione a aba Data Explorer, expanda o item Data Sets e clique no colleagueDataSet em seguida clique na aba Script então selecione o evento beforeOpen conforme a figura 12.
Figura 12 – Evento onBeforeOpen.
Em seguida, inclua o seguinte código:
try { query = new QueryDelegate(); sqlJpa = "SELECT c from Colleague c"; sqlJpa = sqlJpa + " WHERE c.colleaguePK.companyId = ${WKCompany}"; if(params["Matricula"].value != null) { if (params["Matricula"].value != "*") { sqlJpa = sqlJpa + " AND c.colleaguePK.colleagueId = '" + params["Matricula"].value + "'"; if(params["paramEnable"].value != null) { if (params["paramEnable"].value != "*") { sqlJpa = sqlJpa + " AND c.active = " + params["paramEnable"].value; } } } else { if(params["paramEnable"].value != null) { if (params["paramEnable"].value != "*") { sqlJpa = sqlJpa + " AND c.active = " + params["paramEnable"].value; } } } } sqlJpa = sqlJpa + " ORDER BY " + params["paramSort"].value; resultSet = query.getResultQuery(sqlJpa); } catch (e) { } finally { }
O código acima monta a consulta do relatório através da consulta JPA e inclui os filtros da solicitação de acordo com os parâmetros definidos pelo usuário.
Detalhes sobre o código:
Para incluir o resultado da consulta no Data Set e formatar os dados do relatório, selecione o evento fetch na área de Script, conforme figura 13.
Figura 13 – Evento fetch.
Em seguida inclua o seguinte código:
if (resultSet != null) { if(count < resultSet.size()){ var rowMap = resultSet.get(count); row["colleagueId"] = rowMap.get("colleagueId"); row["login"] = rowMap.get("login"); row["colleagueName"] = rowMap.get("colleagueName"); row["mail"] = rowMap.get("mail"); var active = rowMap.get("active"); if (active == "true") { row["active"] = "Sim"; } else { row["active"] = "Não"; } var adminUser = rowMap.get("adminUser"); if (adminUser == "true") { row["adminUser"] = "Sim"; } else { row["adminUser"] = "Não"; } count++; return true; } } return false;
O código acima verifica se houve resultado na consulta JPA, caso houver ele incluí os dados no Data Set e formata os campos usuário ativo e administrador.
Detalhes sobre o código:
Uma forma alternativa de obtenção de dados para criação de relatórios é a utilização de JDBC. É necessário criar um Data Source que se conecte com o banco de dados, nele serão armazenados os dados para conexão, via JDBC, ao banco de dados.
Selecione a aba Data Explorer, clique com o botão direito do mouse sobre o item Data Source em seguida selecione a opção New Data Source conforme a figura 14.
Figura 14 – Novo Data Source
Ao abrir a janela New Data Source, selecione a opção JDBC DataSource e define o nome JDBC-DataSource como Data Source Name em seguida clique no botão Next, conforme a figura 15.
Figura 15 – Tipo Data Source
Na próxima janela a conexão com o banco de dados deve ser configurada. No campo Driver Class selecione o driver de conexão com o banco de dados, neste caso, a conexão será feita com o banco MySQL®. Se o driver necessário não estiver listado, basta adiciona-lo clicando em Managed Drivers...
Informe também os valores para Database URL, User Name e Password de acordo com o banco de dados escolhido, conforme a figura 16.
Figura 16 – Configurando conexão com banco de dados.
Na aba Data Explorer clique com o botão direito do mouse sobre o item Data Sets em seguida clique na opção New Data Set conforme figura 17.
Figura 17 – Criando Novo Data Set.
Selecione o Data Source criado (JDBC-DataSource), no campo Data Set Type selecione SQL Select Query, informe um nome para o Data Set e clique em next, conforme a figura 18.
Figura 18 – Configurando Data Set
Na próxima tela informe a SQL que busca os dados no banco de dados, neste exemplo, serão buscados os colaboradores da empresa autenticada no TOTVS | ECM, conforme a figura 19.
Figura 19 – Criação da Query SQL
SELECT colaborador.CD_MATRICULA, colaborador.COD_EMPRESA, colaborador.NM_COLABORADOR, colaborador.E_MAIL FROM colaborador WHERE colaborador.COD_EMPRESA = ${WKCompany}
A Query acima busca no banco de dados todos os colaboradores da empresa do usuário autenticado no TOTVS | ECM, este código é obtido através da TAG ${WKCompany}.
Observação
Poderá ocorrer um erro quando concluir a criação do Data Set pois a TAG ${WKCompany} não existe no contexto do BIRT. A figura 20 apresenta o erro devido à utilização da TAG, este é um erro de sintaxe no SQL e indica que ${WKCompany} não é um comando SQL. Porém quando o relatório for executado no ECM, ela retornará o código da empresa normalmente, com isso a TAG será substituída pelo código da empresa do usuário autenticado no ECM, corrigindo o erro de sintaxe.
Figura 20 – Erro do Birt pelo uso da TAG ${WKCompany}
Atenção:
A criação de relatório no Birt utilizando conexão JDBC exige atenção com relação à segurança da publicação do relatório no ECM, uma vez que o arquivo .rptdesign (XML do relatório Birt) deixa exposto os parâmetros de conexão com o banco de dados, porém o campo senha fica ofuscado com base64. Por este motivo e pela facilidade de busca das informações do TOTVS | ECM, sempre recomendamos a criação de relatórios com fontes de dados via Dataset do ECM ou query JPA.
Se a criação de relatórios utilizando JDBC for necessária, recomendamos que ao publicar um relatório no ECM as configurações de permissão sejam definidas apenas para leitura. Usuários que possuem permissão de manutenção podem fazer o download dos anexos e com isso terão acesso aos dados de conexão com o banco de dados.
É necessária a inclusão dos componentes de renderização do relatório. Clique na aba Layout para visualizar a página do relatório que está em branco e em seguida selecione a aba Palette conforme a figura 21.
Figura 21 – Relatório em branco.
Na aba Pallets é possível incluir vários componentes de visualização e renderização de dados entre eles destacam-se:
É possível incluir imagens da internet, incluir imagens de arquivo ou ainda embutir a imagem no XML do relatório. Neste exemplo será usada uma imagem em anexo para posteriormente mostrar como publicar relatórios com anexo.
Arraste um componente Image no relatório, ao abrir a janela Edit Image Item, selecione a opção Image file in shared resources, selecione o arquivo da imagem na opção Enter resource file e em seguida clique no botão Insert conforme figura 22.
Figura 22 – Componente Imagem.
Arraste um componente Text no relatório, ao abrir a janela Edit Text Item selecione a opção HTML e na área de texto inclua a seguinte informação formatada em HTML:
<H1><B>TOTVS S/A</B></H1> Av. Santos Dumont, 831 – Bom Retiro <br> CEP 89.222-900 – Joinville – SC – Brasil <br>Telefone: +55 (47) 2101-7000 <br> Fax: +55 (47) 2101-7070 </br>
Em seguida clique no botão OK conforme figura 23.
Figura 23 – Componente Text.
Arraste um componente Label no relatório, clique duas vezes sobre o componente incluído e digite Relatório de Colaboradore na aba Properties Editor -> Properties clique em General e defina a formatação da label, conforme figura 24.
Figura 24 – Título do relatório.
Arraste um componente Table, ao abrir a janela Insert Table defina 6 colunas e 1 detalhe e clique no botão OK conforme figura 25.
Figura 25 – Configuração da Tabela.
Na tabela adicionada ao relatório inclua um componente Label para cada coluna da linha Header Row defina os seguintes valores:
Formate as labels incluídas definindo cor da fonte e cor de fundo conforme figura 26.
Figura 26 – Título das Colunas.
Selecione a aba Data Explorer e expanda o colleagueDataSet criado anteriormente e em seguida arraste cada item do Data Set para a coluna Detail Row da tabela criada anteriormente conforme figura 27.
Figura 27 – Data Set.
Faça o download de relatórios que irão listar os documentos e solicitações pendentes de usuários inativos:
Após a conclusão do desenvolvimento do relatório, é necessária a autenticação no TOTVS | ECM com um usuário válido para realizar a sua publicação. Selecione a opção Navegação de Documentos, escolha a pasta de publicação, em seguida selecione a opção Novo Relatório, conforme a figura 28.
Figura 28 – Pasta de publicação.
A publicação de relatórios é semelhante à inclusão de documentos no GED do TOTVS | ECM, possui as mesmas propriedades, inclusive: aprovação, segurança e propriedades herdadas.
Ao abrir a janela Editando Relatórios defina as propriedades do relatório no GED, em seguida na aba Arquivos de Publicação clique no botão Upload conforme figura 29.
Figura 29 – Publicação de relatório.
O BIRT Report Designer gera um arquivo em formato XML com a extensão rptdesign, é necessário publicá-lo no TOTVS | ECM e defini-lo como “Principal” para que o relatório seja executado. Os demais arquivos utilizados devem ser publicados e definidos como “Anexo”.
Ao abrir a janela Upload de arquivo clique no botão Procurar selecione a pasta do projeto do desenvolvimento do relatório de colaboradores e importe os arquivos report.rptdesign e LogoTOTVS.png e clique botão Abrir conforme figura 30.
Figura 30 – Upload de arquivos do relatório.
Na janela Upload de Arquivo clique no botão Upload e em seguida no botão Fechar. Defina o arquivo report.rptdesign como Principal e o arquivo de imagem utilizado no relatório como Anexo. Para concluir a operação clique no botão Confirmar conforme figura 31.
Figura 31 – Concluindo publicação.
Após concluir a publicação, para visualizá-lo, clique sobre ele no GED do TOTVS | ECM.
Uma nova janela deverá abrir, para iniciar a execução do relatório de colaboradores desenvolvido anteriormente é necessária a inclusão de parâmetros, defina os seus valores e em seguida clique no botão OK conforme a figura 32.
Figura 32 – Parâmetros do relatório.
O relatório deverá mostrar todos os colaboradores cadastrados no TOTVS | ECM para a empresa em que o usuário está autenticado, conforme figura 33.
Figura 33 – Relatório de Colaboradores – Resultado.
A ferramenta de visualização de relatório do TOTVS | ECM possui várias funcionalidades:
Figura 34 – Funcionalidades do visualizador de relatórios.
O TOTVS | ECM suporta através de consultas JPA e seu banco de dados, o uso de funções de agregação, tais como: AVG, SUM, COUNT, MAX e MIN. Permite também utilizar agrupamentos: GROUP BY e HAVING.
Tabela de entidades
Código dataset | Entidade JPA | Tabela banco de dados |
---|---|---|
AccessLog | AccessLog | HISTOR_ACES |
ActivityDim | ActivityDim | ACTIVITY_DIM_CAP |
advancedProcessProperties | AdvancedProcessProperties | PROPRIED_AVANCAD_PROCES |
businessPeriod | BusinessPeriod | PERIOD_EXPED |
colleague | Colleague | COLABORADOR |
colleagueGroup | ColleagueGroup | GRUPO_COLABORADOR |
destinationArea | DestinationArea | AREA_DEST |
document | Document | DOCUMENTO |
documentSecurityConfig | DocumentSecurityConfig | CONFIGUR_SEGUR_DOCTO |
FactActivityCost | FactActivityCost | FACT_ACTIVITY_COST_CAP |
FactFlowVolume | FactFlowVolume | FACT_FLOW_VOLUME_CAP |
FactProcesCost | FactProcesCost | FACT_PROCES_COST_CAP |
FactProcesVolume | FactProcesVolume | FACT_PROCES_VOLUME_CAP |
FlowDim | FlowDim | FLOW_DIM_CAP |
globalCalendar | GlobalCalendar | CALEND_GLOBAL |
group | Group | GRUPO |
knowledge | Knowledge | CONHECIMENTO |
processAttachment | ProcessAttachment | ANEXO_PROCES |
processDefinition | ProcessDefinition | DEF_PROCES |
processDefinitionVersion | ProcessDefinitionVersion | VERS_DEF_PROCES |
processHistory | ProcessHistory | HISTOR_PROCES |
processState | ProcessState | ESTADO_PROCES |
processTask | ProcessTask | TAR_PROCES |
ProcesVersionDim | ProcesVersionDim | PROCES_VERSION_DIM_CAP |
TimeDim | TimeDim | TIME_DIM_CAP |
topic | Topic | ASSUNTO |
UserDim | UserDim | USER_DIM_CAP |
workflowColleagueRole | WorkflowColleagueRole | PAPEL_WORKFLOW_COLABORADOR |
workflowProcess | WorkflowProcess | PROCES_WORKFLOW |
workflowRole | WorkflowRole | PAPEL_WORKFLOW |
A tabela acima referencia a relação entre o código de dataset, a entidade de persistência JPA utilizada nas consultas, e a respectiva tabela no banco de dados.
As colunas das entidades de persistência são as mesmas apresentadas no dataset.
importPackage(Packages.com.datasul.technology.webdesk.dataset.service); importPackage(Packages.java.util); var qd = null; var rs = null; var rowMap = null; var sqlJpa = ""; qd = new QueryDelegate(); sqlJpa = "SELECT count(d.documentPK.documentId), d.publisherId from Document d WHERE d.documentPK.companyId = ${WKCompany} GROUP BY d.publisherId"; rs = qd.getResultQuery(sqlJpa); var rowMap = rs.get(0); //Busca o valor do Count rowMap.get("d.publisherId"); //Busca o Codigo do documento rowMap.get("count(d.documentPK.documentId)");
A partir da classe DatasetFactory é possível acessar dados de fichários publicados no TOTVS | ECM.
Para popular um relatório através de dados de fichários é necessário a importação das seguintes bibliotecas:
importPackage(Packages.com.datasul.technology.webdesk.dataset.service); importPackage(Packages.com.datasul.technology.webdesk.dataset); importPackage(Packages.com.datasul.technology.webdesk.search.controller);
Através da classe DatasetFactory é possível buscar dados de fichários, incluir filtros e ordenação. Exemplo de utilização:
// Monta as constraints para consulta var factory = DatasetFactory.getInstance(${WKCompany}); //Filtra Clientes de 1 a 5 var c1 = factory.createConstraint("cod_cli", "1", "5", ConstraintType.MUST);var constraints = new Array(c1); //Ordena o resultado pelo nome do Cliente var sortingFields = new Array("name_cli"); dataset = factory.getDataset("cad_cli", null, constraints, sortingFields);
O exemplo acima invoca o método getDataset passando alguns argumentos extras como parâmetros:
- MUST: Indica que todos os registros do Dataset devem satisfazer a esta condição.
- SHOULD: Indica que os registros do Dataset podem ou não atender à condição. Este tipo é mais comum quando se necessita que um mesmo campo tenha valores A ou B (onde cada um será uma constraint SHOULD).
- MUST_NOT: indica que nenhum dos registros pode satisfazer a condição.
- Ordenação: Vetor com a lista de campos que será utilizada para ordenação dos registros no Dataset.
O fonte do exemplo citado acima se encontra em: “Documentos de Customização\Arquivos Adicionais\Template de Relatorio\ Customer CardIndex”.
Para realizar consultas via Dataset com filtros do tipo Data, é necessário antes salvar o campo da ficha no formato aaaa/mm/dd (ano/mês/dia) para que seja possível realizar a busca via Dataset.
Exemplo de consulta:
// Monta as constraints para consulta var factory = DatasetFactory.getInstance(${WKCompany}); //Filtra Clientes de 1 a 5 var c1 = factory.createConstraint("campo_data", "2010/01/25", "2010/05/02", ConstraintType.MUST); var constraints = new Array(c1); //Ordena o resultado pelo nome do Cliente var sortingFields = new Array("name_cli"); dataset = factory.getDataset("cad_cli", null, constraints, sortingFields);