Datasul x Smart View
Página centralizadora da integração entre o produto Datasul e Smart View
Aviso
O uso do Smart View integrado ao Datasul pode exigir um custo adicional de infraestrutura. Para mais informações dos requisitos de hardware do Smart View, acesse o link.
Datasul x Smart View
- Conceito/Arquitetura Smart View
- Instalação do Smart View
- Configuração integração Smart View X Datasul
- Uso de relatório expedido para o Smart View
- Edição de um layout de relatório
- Criação de um objeto de negócio
1. Conceito/Arquitetura Smart View
A arquitetura do Smart View integra ao Datasul por meio de comunicação mútua e compartilhamento de informações, onde o Smart View irá consumir os dados do ERP Datasul e fornecer para que o usuário monte, de acordo com as necessidades da área, os relatórios com estas informações.
↑ início
2. Instalação do Smart View
O Smart View precisa estar instalado em um servidor de sua preferência para a criação dos layouts, que posteriormente serão utilizados na geração dos relatórios, bem como integrações dos objetos de negócio, retorno de dados e validações de segurança com o ERP Datasul.
Instalação
- Faça download do Instalador do Smart View Agent clicando neste link;
- Extrair todo o conteúdo do arquivo zip e execute o arquivo SMARTVIEW.AGENTINSTALLER.EXE ;
Selecione o diretório de instalação e prossiga para a próxima etapa. Recomendamos que a instalação seja feita no diretório C:\TOTVS;
- O instalador irá realizar a instalação na pasta SMART-VIEW, criada automaticamente no diretório selecionado;
- Caso o diretório SMART-VIEW já exista, o instalador perguntará se deseja sobrescrever a instalação anterior, caso não queira, um novo diretório deverá ser informado;
Após conclusão, o Smart View já se encontra disponível em seu ambiente e já pode ser configurado via navegador no endereço HTTP://LOCALHOST:7019 (ver Configurações do Smart View).
Para todas as operações será necessário que o usuário tenha privilégios de Administrador.
Copie o arquivo zip de instalação para a pasta
/usr/sbin/smart-view
Obs.: Pode ser necessário utilizar o comando, chmod
- Realize a extração do conteúdo do arquivo na raiz desta pasta
Crie o arquivo do serviço na rota e com o nome abaixo:
/etc/systemd/system/smart-view-agent.service
Abra o arquivo criado e adicione as configurações abaixo:
[Unit] Description=smart-view-agent [Service] Type=notify Environment="DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1" WorkingDirectory=/usr/sbin/smart-view ExecStart=/usr/sbin/smart-view/TReports.Agent --urls http://*:7019 [Install] WantedBy=multi-user.target
Atualize a lista de serviços do SO com o comando
sudo systemctl daemon-reload
Inicie o serviço criado
sudo systemctl start smart-view-agent
Execute o comando para conferir o status
sudo systemctl status smart-view-agent
- Pronto! O Smart View já se encontra disponível em seu ambiente e já pode ser configurado via navegador no endereço HTTP://LOCALHOST:7019 (ver Configurações do Smart View).
Maiores detalhes podem ser encontrados em: Smart View - Instalação do Sistema
↑ início
3. Configurando a integração Datasul x Smart View
É necessário realizar as três etapas a seguir para configurar a integração Datasul x Smart View.
Configurações
1 - Tela inicial
Após a instalação, é necessário efetuar as configurações do Smart View. Para isto, basta entrar no endereço: http://[SERVIDOR]:7019/startup
1.1 - Provedor de Dados
Base de dados local que conterá informações pertinentes ao Smart View.
1.2 Configurações de Integração
Aqui você poderá inserir os dados de conexão com o ERP responsável por gerenciar a segurança do Smart View e realizar configurações avançadas. Nenhum dos seus dados de acesso será armazenado.
| Campo | Descrição |
|---|---|
| Nome provedor | Nome do provedor de preenchimento manual. Exemplo: Datasul. |
| Endpoint de descoberta | Endereço do ERP Datasul responsável por retornar as informações de provedor de segurança. O endpoint de descoberta do Datasul é o http://[servidor]:[porta]/totvs-login/sv/.well-known |
| Botão Conectar ao ERP | Ao clicar neste botão, será aberta uma tela para inserção do usuário e senha do ERP. O código do usuário no campo nome do usuário será preenchido automaticamente. |
| Botão Configurações Avançadas | Abre as configurações avançadas para cadastro das informações de comunicação SSL e License Server. |
Importante
A URL de descoberta do endpoint do ERP deve estar exatamente com a mesma informação de audiência entre ERP e Smart View. Por exemplo, se no Smart View foi cadastrado: http://localhost:[porta]/totvs-login/sv/.well-known, o ERP deverá ser acessado com esta mesma informação: http://localhost:[porta]/totvs-menu. Em caso de acesso externo, será necessário cadastrar nas Propriedades de Sistema - card Propriedades JWT - aba Datasul - Identificador servidor. Sem essas informações corretas e cadastradas, a integração pode ter seu funcionamento comprometido devido controle de segurança de acesso.
1.2.1 Configurações Avançadas
Nas configurações avançadas é possível definir portas e habilitar SSL.
| Campo | Descrição |
|---|---|
| Porta | Porta SSL. |
| Caminho Certificado | Caminho onde encontra-se o certificado SSL. |
| Caminho Chave Privada | Caminho onde encontra-se a chave privada do certificado. |
| Senha | Senha do certificado. |
| Campo | Descrição |
|---|---|
| IP servidor | IP do servidor License Server. |
| Porta | Porta do servidor License Server. |
| CNPJ | CNPJ empresa. |
| Botão Verificar Disponibilidade | Ao acionar este botão, ele verifica se o License Server configurado está disponível. Caso o LS não seja configurado, o Smart View terá acesso limitado. |
1.3 - Fim da configuração
Após as configurações citadas acima, será apresentada a tela final de configuração.
Ao clicar em Abrir Smart View, será aberta a tela para o desenvolvimento de layouts.
2 - Login no Smart View
Efetue o login no Smart View com o mesmo usuário e senha definidos na etapa do Emissor.
2.1 - Conectores
Clique no botão Conectores para efetuar a parametrização dos endpoints necessários para a comunicação entre o Smart View e o ERP Datasul quando o relatório for gerado.
2.2 - Tipo de conector
Escolha a opção Provedor Nativo.
2.3 - Provedor Nativo
| Campo | Descrição |
|---|---|
| Nome | Informe um nome ao conector, o mesmo será utilizado na etapa dos layouts. |
| Endereço | O ERP Datasul disponibiliza um endereço para que seja retornado os dados e objetos de negócio para a construção do relatório. http://[SERVIDOR]:[PORTA]/api/trep/v1/provider/.well-known/treports/connector/ |
3 - Login Datasul
Efetue o login no ERP Datasul com um usuário que possua permissão de acesso a tela de propriedades.
3.1 - Propriedades Smart View
Habilite a integração e informe um usuário administrador e a URL onde o Smart View foi instalado (porta padrão 7017).
| Propriedade | Descrição |
|---|---|
| Habilitar Integração | Habilita a integração com o Smart View |
| Usuário Administrador | Código do usuário (ERP Datasul) que será responsável pela administração dos recursos na integração entre o Smart View e o ERP Datasul. Exemplo: Importação de layouts. |
| URL Smart View | URL base do servidor onde foi instalado o Smart View Observação: Por padrão, este servidor é instalado na porta 7017 |
TESTE Campos para validação da integração com o Smart View (não são persistidos no banco de dados) |
|
| Usuário (opcional) | Código do usuário (ERP Datasul) que possui acesso ao layout |
| Senha (opcional) | Senha do usuário (ERP Datasul) |
| Nome Exibição Layout (opcional) | Nome de Exibição do Layout cadastrado no Smart View Observação: Apesar da ferramenta permitir a duplicidade da informação, este nome deve ser único |
| Tipo Arquivo (opcional) | Extensão do tipo de arquivo a ser gerado (Caso não seja selecionado, o padrão é o formato .pdf) |
| Teste Integração Layout (opcional) | Efetua a geração e download do relatório integrado com o Smart View, no tipo de arquivo desejado |
↑ início
4. Uso de relatório expedido para o Smart View
Somente o Usuário Administrador do Smart View, configurado em Propriedades → Integrações TOTVS possui a permissão para efetuar a importação, compartilhamento e exclusão dos layouts.
Caso o usuário não seja administrador, somente as funcionalidades de pesquisa são liberadas.
Lista de Layouts
Funcionalidade | Descrição | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Busca Avançada | Abre uma janela Pop Up para informar os dados do filtro:
| ||||||||
| Ação (...) | Ao clicar no botão ... são exibidas as ações:
| ||||||||
| Importar Tudo | Realiza a importação/atualização de todos os layouts cadastrados no programa bas_prog_dtsul. |
Cadastro de Layout
Para novos layouts, é necessário efetuar o cadastro no programa "bas_prog_dtsul", conforme os exemplos abaixo:
Campo | Descrição |
|---|---|
| Nome externo | Local onde está armazenado o layout do recurso que será importado. |
| Nome verbalizado | Nome que será apresentado no menu, caso seja habilitada a opção "Visualiza Menu" |
Campo | Descrição |
|---|---|
| Template | Determina o tipo de recurso relacionado ao layout. (Smart View Relatório, Smart View Visão de Dados ou Smart View Tabela Dinâmica). |
| Tipo | Para layouts, preencher como "Relatório". |
Compartilhamento do Layout
Campo | Descrição |
|---|---|
| Grupos | Grupos do ERP Datasul para o compartilhamento do layout.
Dica Somente o usuário que efetuou a importação do layout possuirá sempre o acesso ao mesmo. Utilize as regras de relacionamento entre o usuário x grupo de segurança (ERP Datasul) para conceder ou limitar o acesso a um determinado layout (e consequentemente o relatório) |
↑ início
5. Edição de um layout de relatório
Informação
O intuito desta sessão não se trata de um treinamento de como desenvolver um layout. Acesse o link: https://tdn.totvs.com/pages/releaseview.action?pageId=633542507 para mais informações da ferramenta.
Os layouts são desenvolvidos na página do SmartView, acesse a página http://[SERVIDOR]:7017/ e clique no botão Relatórios → Criar novo:
Após definir os nomes adequados, selecione o objeto de negócio que será integrado ao layout conforme padrões da RFC.
Ao clicar no botão Escolher objeto de negócio, é aberta uma janela pop-up com os endpoints cadastrados na etapa 3 agrupados automaticamente pelo filtro de área de nome Datasul. Selecione qual o objeto de negócio que será relacionado ao layout em desenvolvimento.
Após desenvolver o Design e avançar, é apresentada a sessão de compartilhamento. Recomendamos que não seja utilizada pois o gerenciamento desta área deve ser realizada com telas do ERP Datasul.
↑ início
6. Criação de um objeto de negócio
Para uso com o smartview devem ser implementados os métodos:
GET objectschema
Retorna o schema, que é um descrição de campos e tipos de dados.
POST data
Dados do relatório.
Foi criado um conjunto de ferramentas que facilitam a geração do endpoint na include utp/ut-sv-utils.i.
Utilize as mesmas ferramentas que usa para construir um endpoint comum, acrescentando anossa include de ferramentas.
Abaixo destaco, na arquitetura normal de um endpoint o que deve ser feito a mais na construção do endpoint para que ele seja utilizado no Smart View.
Constantes:
Algumas constantes mudam o comportamento da geração dos dados, são elas
SV-PAGE-SIZE
Número de linhas da página de dados, seu valor dafault é 5000, essa constante é muito importante para ajustar a performance do relatório, reduza esse número caso cada registro de dado tenha muita informação ou aumente caso tenha pouca informação.
SV-PRNAME
Nome do prefixo do campo calculado, seu valor default é calc
Cada campo calculado deve ter um procedure para seu calculo essa procedure deve ter o nome dessa constane mais o nome do campo calculado.
SV-MODO
O modo como são gerados os nomes para envio ao Smart View, seu default é TBATR, que significa que se enviar a tabela impressora e o campo des_impressora será enviada uma composição entre o nome da tabela e do atributo.
Os valores possíveis são:
DBTBATR → banco tabela atributo
TBATR → tabela atributo
ATR → atributo
SV-SEP
Caractere separador na concatenação dos campos o default é _ (Underline) e pode ser usado ? para não usar nenhum separador.
Aviso
As constantes são opcionais, caso omitidas, é usado o valor default.
Procedure generateSchema
Nessa procedure deve detalhar o schema de seu endpoint.
A declaração dessa procedure é obrigatória e caso ele não exista o retorno será uma mensagem de erro de código 52611.
Nela se inclui:
- Atributos do schema seja eles relacionados a tabelas físicas ou temporárias
- Campos calculados
- Parâmetros do relatório
Foram criadas diversas formas de inclusão de atributos visando facilitar seu uso, abaixo imagem de um exemplo de implementação:
Aviso
Ao final do documento é possível fazer o download do exemplo completo.
clearSchema
Limpa a definição de Schema
addSchemaItemHandle
Adiciona um item ao schema, recebe como parâmetro:
Handle buffer-field do atributo - handle
Se o atributo permite filtro - logical
Se o atributo é obrigatório - logical
A url de filtro (opcional) - character
addSchemaItemHandleAtrNAme
Adiciona um item ao schema já atribuindo um nome para envio ao Smart View, recebe como parâmetro:
svAtrName - nome do atributo
Handle buffer-field do atributo - handle
Se o atributo permite filtro - logical
Se o atributo é obrigatório - logical
A url de filtro (opcional) - character
addSchemaTable
Adiciona todos os atributos de uma tabela, recebe como parâmetro:
Handle buffer da tabela - handle
addSchemaTableWithExceptions
Adiciona todos os atributos de uma tabela, com exceção dos enviados como parâmetro, recebe como parâmetro:
Handle buffer da tabela - handle
Lista de exceção separada por vírgula - character
delSchemaItem
Elimina um item do schema, recebe como parâmetro:
Atributo smartView - character
addSchemaItem
Adiciona manualmente um item ao Schema.
schemaItem - objeto
O objeto deve ser construido com o parâmetro add Ex.: mySchema = NEW schemaItem("add").
updSchemaItem
Altera um item ao Schema.
schemaItem - objeto
O objeto deve ser construido com o parâmetro add Ex.: mySchema = NEW schemaItem("upd").
Atribua somente as propriedades que deseja alterar e svAtrName é obrigatório pois é chave.
addSchemaParameter
Adiciona um parâmetro ao relatório, os parÂmetros são solitados quando o relatório e executado a partir do Smart View.
schemaParameter - objeto
Objeto schemaItem
As procedures de inclusão e alteração de itens recebem um objeto do tipo schemaItem que usam como referÊncia para essa operação, abaixo a lista de seus atributos
svAtrName - nome do atributo afetado é usando como chave para a operação
svDatabase - nome do banco
svTable - nome da tabela
svExt - numero do extent, use um número maior que 0 (zero) para campos extent
svField - nome do atributo ou da procedure, caso seja um campo calculado
svDisplayName - nome de display
svDescription - descrição
svAtrType - tipo de dado, usar os tipos de progress (character, logical, date ...)
svFiltered - Se o atributo permite filtro
svRequired Se o atributo é obrigatório
svType - o tipo do atributo 1-tabela 2-temp-table 3 - campo calculado
svOptionsUrl - A url de filtro (opcional) - character - Pode ser incluído um endpoint no qual é utilizado para a obtenção de valores do OptionsUrl e/ou Dropdown (Mais detalhes na sessão endpoint optionsdatakeylabel)
Objeto schemaParameter
svName - código do parâmetro
svDisplayName - nome de display
svType - tipo de dado, usar os tipos de progress (character, logical, date ...)
svMultiValue - Se o valor é multivalorado ou não
svLookupUrl - URL de lookup para permitir buscas no parâmetro (Ex.: "/btb/api/v1/meuObjetodeNegocio/lookup")
Procedure pLookup
Para habilitar o uso do lookup, realize o vinculo de uma tabela (temporária ou não) a procedure pLookup, conforme exemplo abaixo, onde o índice da tabela determina o campo em que será realizado a busca.
Após realizar o vinculo da tabela é necessário executar a função LookupParameter, na seguinte estrutura (BUFFER DA TABELA, cFilter, OUTPUT oJsonOutput), para que seja retornado o JSON no formato aceito pelo Smart View.
Procedure GetPagenr
Nessa procedure é realizado o retorno dos números responsáveis pela paginação.
Campo calculado
É possível criar um campo calculado como no exemplo abaixo:
Aviso
Ao final do documento é possível fazer o download do exemplo completo.
Como nome do banco e tabela deve informar o banco que deseja receber o buffer para os cálculos e o nome do atributo é o nome da procedure do cálculo com o prefixo da constante SV-PRNAME.
Essa procedure recebe o handle do buffer da tabela indicada e devolve o valor do cálculo no tipo do item adicionado.
Aviso
Evite colocar cálculos demorados nessa procedure, ela será executada a cada registro de sua query e pode afetar a performance.
O endpoint objectschema
O endpoint retorna o schema baseado nas definições da procedure generateSchema.
Aviso
Ao final do documento é possível fazer o download do exemplo completo.
A procedure generateProperties é a responsável por criar o schema baseado na procedure generateSchema:
generateProperties
Gera json com o SChema, recebe como parâmetro:
DisplayName - character
Name - character
Description - character
DataUrl - character
Retorna:
Json Schema - jsonObject
O parâmetro DataUrl é importante e deve ter o endereço no endpoint e é usada para montar algumas URLs durante o retorno de dados.
O catch no código serve para capturar um eventual erro
O createJsonResponse cria o json de resposta no padrão
Endpoint data
Retorna os dados do relatório, respeitando o filtro e parâmetros recebidos do SmartView.
Foram criados facilitadores para tratar os parâmetros (processParameters e processParameterMultiple) e filtros (generateFilter) que irão compor a clausula where que fará o retorno dos dados.
O procedure generateData é responsável pela montagem do Json de saída, fazendo o controle de paginação.
Aviso
Ao final do documento é possível fazer o download do exemplo completo.
Abaixo a lista de facilitadores e seus parâmetros:
processParameters
Tem por função retornar os parâmetros recebidos no json de entrada em uma string que representa uma porção da clausula where.
oJsonInput - jsonObject
string entrada - character
retorna:
string saida - character
Na string de entrada informe o nome do parâmetro precedido por &, no retorno esse valor será substituido pelo parâmetro recebido.
processParametersMultiple
Tem por função retornar um parâmetro multiplo recebido no json de entrada em uma string que representa uma porção da clausula where.
oJsonInput - jsonObject
parâmetro pesquisado - string
string de ligação - string
string entrada - character
retorna:
string saida - character
Diferente da processParameters a processParametersMultiple duplica a string de entrada a cada ocorrência de um parâmetro.
Informe o nome do parâmetro multiplo que deseja no parâmetro pesquisado e na string de entrada o mesmo parâmetro precedido por &, no retorno esse valor será substituido pelo parâmetro recebido, a string de ligação é a string que será usada entre um valor múltiplo e outro, usualmente um AND ou OR, mas pode se usar um caractere delimitador para usar em um options, por exemplo.
generateFilter
Transforma o json de filtro em uma string de filtro com sintaxe do Progress, recebe o parâmetro:
oJsonInput - jsonObject
Retorna:
filtro - character
generateData
handle de tabela ou handle de query - handle
cURI - character
cFilter - character
Retorna:
Json Data - jsonObject
O primeiro parâmetro pode ser o handle de uma query ou o handle de uma tabela
cURI - é a URL da requisição, usada na paginação
cFilter - só é valido quando recebe o handle de uma tabela, e ignorado quando é o handle de uma query.
Para o uso de temp-table como repositório de dados, é necessário realizar a definição da temp-table e após utilizar o facilitador abaixo:
generateDataTT
handle de tabela ou handle de query - handle
cURI - character
cFilter - character
QUERY-OFF-END - handle
Retorna:
Json Data - jsonObject
Confira o exemplo abaixo:
O endpoint optionsdatakeylabel
Retorna um JsonObject no padrão key-value para a utilização na obtenção de dados para os componentes Options e Dropdown (no SmartView).
Por padrão, o nome do endpoint deve ser optionsdatakeylabel, porém caso desejar, pode ser implementado um endpoint com outro nome para o retorno exclusivo de dados (Ambos configurados em generateSchema).
Aviso
Ao final do documento é possível fazer o download do exemplo completo.
clearOptions
Limpa a definição dos objetos de Options
addOptionsItem
Adiciona um item ao objeto de Options, recebe como parâmetros:
Chave - character
Valor - character
generateOptionsData
Transforma os dados enviados em um JsonObject no formato key-value (utilizados no SmartView).
Exemplos de Json
Exemplo de resultado do endpoint objectschema
Exemplo de resultado do endpoint data
Exemplo de resultado do endpoint LookupData
Anexo (Endpoint exemplo)
svUsuarDetail.p Exemplo aninhado
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas