Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Conteúdo

Índice
minLevel2


01. Objetivo

Esta documentação tem a finalidade de servir como uma guia no momento da integração com o TOTVS Privacidade de Dados. Para mais informações sobre a ferramenta, acesse TOTVS Privacidade de Dados.

Para tanto, abaixo seguem as instruções para que a integração seja realizada corretamente.



02. Informações

Leia os documentos de referência do TOTVS Privacidade de Dados.

O produto Datasul faz o uso do Smart Link, que é um mecanismo de troca de mensagens entre aplicações TOTVSApps e aplicações OnPremises (ou remotas).

  • Foi utilizada a biblioteca Smart Link Client Java, que por meio deste foi implementado o processador de mensagens.
  • O processador de mensagens é uma aplicação java 

Obtenha informações (client, secret, name e id) do seu tenant para poder realizar as configurações necessárias nos prximos passos. 




03. Instalação


Copiar arquivo compactado


O arquivo está localizado no diretório do Foundation src/interfac/smart-link/dts-smart-link-client.zip



Extrair os arquivos do arquivo compactado



Extrair os arquivos em um deretório de sua escolha, sugerimos o uso do nome do seu tenant para complementar e facilitar a organização dos aterfatos.   

Abaixo um exemplo:

  • O nome da pasta extraida é dts-smart-link-client, e o complemento com o nome do tenant para exemplo é -totvs-fwk.
    • Exemplo: C:\TOTVS\dts-smart-link-client-totvs-fwk
  • Como resultado temos a estrutura abaixo:
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\README.txt
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\lib\application.yml
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\lib\dts-smart-link-client.jar
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\install.bat
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\JavaService.exe
    • C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\uninstall.bat



Instalador de serviço para Windows

Editar o arquivo "C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\install.bat"

Expandir
titleNome do serviço
  • Sugerimos o uso do nome do seu tenant para complementar e facilitar a organização do serviço.
  • Exemplo: TOTVS-DTS-SMART-LINK-CLIENT-totvs-fwk (O nome do serviço é TOTVS-DTS-SMART-LINK-CLIENT, e o complemento é -totvs-fwk)
Expandir
titleDescrição do serviço
  • A descrição também pode ser alterada.
Expandir
titleJAVA
  • Deve ser utilizado JAVA 11
  • No arquivo estamos utilizando o %JAVA_HOME% como padrão, caso necessário faça a alteração para utilizar a sua váriavel de ambiente já existente.
Expandir
title Parâmetros
  • Informe a localização do arquivo dts-smart-link-client.jar no parâmetro -Djava.class.path
    • "C:\TOTVS\dts-smart-link-client-totvs-fwk\lib\dts-smart-link-client.jar" 
  • Informe a localização da pasta onde está localizado o arquivo dts-smart-link-client.jar no parâmetro -current
    • "C:\TOTVS\dts-smart-link-client-totvs-fwk\lib"

Instalação do serviço:

  • Execute Prompt de Comando como administrador
  • Acesse o o arquivo "C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\install.bat"
  • Serviço instalado:



Desinstalador de serviço para Windows

Editar o arquivo "C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\uninstall.bat"

  • Informe o nome do serviço definido na etapa anterior (Instalação)

Desinstalação do serviço:

  • Execute Prompt de Comando como administrador
  • Acesse o o arquivo "C:\TOTVS\dts-smart-link-client-totvs-fwk\service\Windows\uninstall.bat"




03. Configuração


Arquvio de configuração

O arquivo de configuração application.yml está localizado na pasta lib

  • Utilizando a pasta de exemplo dos passos anteriores, podemos encontrar o arquivo em: C:/TOTVS/dts-smart-link-client-totvs-fwk/lib/application.yml  



Configurações do arquivo application.yml


Aviso

Leia com atenção o detalhamento das configurações abaixo:

# SERVER

A porta de acesso da aplicação pode ser alterado na prorpriedade:

Bloco de código
themeRDark
# -------------------------------------------------
# SERVER
# -------------------------------------------------  
server:
  port: 8777
https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.server.server.port


# SPRING

Por padrão estamos utilizando 10MB para poder trafegar metadado no formato JSON.

Bloco de código
themeRDark
# -------------------------------------------------
# SPRING
# ------------------------------------------------- 
spring:
  codec:
    max-in-memory-size: 10MB

https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.core.spring.codec.max-in-memory-size


# LOG

O nome do arquivo de log pode ser alterado na propriedade:

Bloco de código
themeRDark
# -------------------------------------------------
# LOG
# -------------------------------------------------    
logging:
  file:
    name: log/smart-link-client-datasul.log

# SMART LINK CLIENT

Bloco de código
themeRDark
# -------------------------------------------------
# SMART LINK CLIENT
# -------------------------------------------------
totvs:
  link:
    auth:
      url: https://INORMAR-NOME-TENANT.rac.INFORMAR-DEV-PROD-STAGING.totvs.app/totvs.rac/connect/token
      client: INFORMAR-CLIENT
      secret: INFORMAR-SECRET
    client:
      subscriptions:      
        - SGDPDataCommand
        - SGDPMaskCommand
    server:
      host: link.INFORMAR-DEV-PROD-STAGING.totvs.app
      port: 443
      secure: true
  tenant:
    name: INORMAR-NOME-TENANT
    id: INORMAR-ID-TENANT   
  datasul:
    url: 'INFORMAR_URL_DATASUL'
    username: 'INFORMAR_USUÁRIO_DATASUL'
    password: 'INFORMAR_SENHA_USUÁRIO'
    #linkClientUrl: 'INFORMAR_URL_SMART_LINK_CLIENT'
    companies:
      - 'INFORMAR_CÓDIGO_EMPRESA'      
    tpdDisabled: false
    jboss: false
Aviso

Leia com atenção o detalhamento das configurações abaixo:

Expandir
titleSmart Link Client Java

O Smart Link Client Java é uma bibloteca que facilita o desenvolvimento de um LINK Client para a plataforma Java, sendo necessária a implementação de uma aplicação que implemente um processador de mensagens (LINK Client Java Application mais abaixo).

No Smart Link Client Java utiliza o protocolo GRPC, sendo necessária a seguinte configuração:

Bloco de código
themeRDark
totvs:
  link:
    server:
      host: link.INFORMAR-DEV-PROD-STAGING.totvs.app
      port: 443
      secure: true
  • INFORMAR-DEV-PROD-STAGING: Subistituir pelo tipo do seu ambient tenant (dev, prod, staging)
  • Exemplo: link.staging.totvs.app

Deve ser informada também uma lista de subscrições, onde somente mensagens com determinados "types" são efetivamente enviadas para o Smart Link Client. 

No Smart Link Client Java é necessária a seguinte configuração:

Bloco de código
themeRDark
totvs:
  link:
    client:
      subscriptions:
        - SGDPDataCommand
        - SGDPMaskCommand

O produto Datasul está preparado para processar os tipos SGDPDataCommand e SGDPMaskCommand, o arquivo application.yml já possui essa configuração.


Expandir
titleSmart Link Client Single Tenant

O produto Datasul suporta apenas o single tenant, é necessária a seguinte configuração:

Bloco de código
themeRDark
totvs:
  link:
    auth:
      url: https://INORMAR-NOME-TENANT.rac.INFORMAR-DEV-PROD-STAGING.totvs.app/totvs.rac/connect/token
      client: INFORMAR-CLIENT
      secret: INFORMAR-SECRET
  • INFORMAR-DEV-PROD-STAGING:  Subistituir pelo tipo do seu ambient tenant (dev, prod, staging).
  • INFORMAR-CLIENT: Subistituir pelo valor do seu client.
  • INFORMAR-SECRET:  Subistituir pelo valor da sua secret.


Expandir
titleTenant

Informar os valores do seu Tenant:

Bloco de código
themeRDark
totvs:
  tenant:
    name: INORMAR-NOME-TENANT
    id: INORMAR-ID-TENANT 
  • INORMAR-NOME-TENANT: Subistituir pelo valor do seu tenant.
  • INORMAR-ID-TENANT:  Subistituir pelo valor do id do seu tenant.


Expandir
titleDatasul

A  comunicação acontece nos dois sentidos (TOTVS Privacidade de Dados > Datasul) e (Datasul > TOTVS Privacidade de Dados) por meio das configurações abaixo:

Bloco de código
themeRDark
totvs:
  datasul:
    url: 'INFORMAR_URL_DATASUL'
    username: 'INFORMAR_USUÁRIO_DATASUL'
    password: 'INFORMAR_SENHA_USUÁRIO'
    #linkClientUrl: 'INFORMAR_URL_SMART_LINK_CLIENT'
    companies:
      - 'INFORMAR_CÓDIGO_EMPRESA'
    tpdDisabled: false
    jboss: false
  • INFORMAR_URL_DATASUL: Subistituir pelo valor do seu ambiente Datasul.
    • Exemplo: 'http://localhost:8080'
  • INFORMAR_USUÁRIO_DATASUL:  Subistituir pelo valor de um usuário existente no Datasul. 
  • INFORMAR_SENHA_USUÁRIO:  Subistituir pelo valor da senha do usuário.
  • INFORMAR_CÓDIGO_EMPRESA: Subistituir pelo valor do código da empresa
    • A integração pode ser para mais de uma empresa, basta adicionar na sequencia respeitando o espaçamento do arquivo .yml
    • Bloco de código
      totvs:
        datasul:
          companies:
            - '10'
            - 'TST' 
            - 'E11' 
  • Configuração tpdDisabled: Caso tenha a necessidade em desativar a integração altere o valor para true 
  • Configuração jboss: Caso utilize a antiga arquitetura Jboss altere o valor para true
  • Configuração linkClientUrl:
    • Essa configuração recebe por padrão o valor ''http://SERVIDOR:PORTA''
      • SERVIDOR:  Servidor que está executando o processador de mensagens dts-smart-link-client.jar
      • PORTA: Valor da porta (server: port) da configuração #SERVER



04. 

Como redefinir a senha

Para redefinir a senha, utilize o serviço passwordReset existente no contexto totvs-login, seguindo as premissas: 

Iniciar o serviço instalado



Após ter realizados as etapas anteriores, basta iniciar o serviço instalado e verificar se tudo ocorreu com sucesso por meio do log.

  • Started Application
    • Bloco de código
      themeRDark
      INFO 3528 --- [main] com.totvs.link.client.Application        : Started Application in 8.771 seconds (JVM running for 9.392)
  • Para facilitar a visualização de alguns log foi adicionada a infomação [SMART-LINK-CLIENT]
  • Bloco de código
    themeRDark
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.readyEvent]
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration (totvs.datasul)
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration jboss: false
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration tpdDisabled: false
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration username: ----
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration url: http://----:8380/
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration password: *********
    INFO 3528 --- [main] c.totvs.link.client.ApplicationStartup   : [SMART-LINK-CLIENT][ApplicationStartup.showConfiguration] Configuration companies: [10] 
    INFO 3528 --- [main] c.t.l.c.d.DatasulSyncDefaultMetadata     : [SMART-LINK-CLIENT][DatasulSyncDefaultMetadata.sync]
    INFO 3528 --- [main] c.t.l.client.datasul.DatasulSendMessage  : [SMART-LINK-CLIENT][DatasulSendMessage.send][REQUEST][GET][HTTP_1_1] to http://----:8380/api/sec/v1/sgdp/metadata/default
    INFO 3528 --- [main] c.t.l.client.datasul.DatasulSendMessage  : [SMART-LINK-CLIENT][DatasulSendMessage.send][RESPONSE][GET][200] from http://----:8380/api/sec/v1/sgdp/metadata/default
    INFO 3528 --- [main] c.t.l.c.d.DatasulSyncDefaultMetadata     : [SMART-LINK-CLIENT][DatasulSyncDefaultMetadata.sync] Sending message to Smart Link Server - type: SGDPUpdateApplicationMetadata - metadado: {"header":{"type":"SGDPUpdateApplicationMetadata"},"content":{"models":{},"codes":{},"package":"Datasul","productId":"Datasul","readOnly":true,"smartLink":"singleTenant","localLogs":false,"applicationId":"Datasul"}}
    INFO 3528 --- [main] c.t.l.c.d.DatasulSyncDefaultMetadata     : [SMART-LINK-CLIENT][DatasulSyncDefaultMetadata.sync] Sent to Smart Link Server
    INFO 3528 --- [main] c.t.l.c.datasul.DatasulUpdateProperties  : [SMART-LINK-CLIENT][DatasulUpdateProperties.update]
    INFO 3528 --- [main] c.t.l.c.datasul.DatasulUpdateProperties  : [SMART-LINK-CLIENT][DatasulUpdateProperties.update] {"subscriptions":"SGDPDataCommand,SGDPMaskCommand","linkClientUrl":"http://----:8777","tpdDisabled":false}
    INFO 3528 --- [main] c.t.l.client.datasul.DatasulSendMessage  : [SMART-LINK-CLIENT][DatasulSendMessage.send][REQUEST][POST][HTTP_1_1] to http://----:8380/api/btb/v1/properties/integrations/totvslinkclient
    INFO 3528 --- [main] c.t.l.client.datasul.DatasulSendMessage  : [SMART-LINK-CLIENT][DatasulSendMessage.send][RESPONSE][POST][200] from http://----:8380/api/btb/v1/properties/integrations/totvslinkclient
    INFO 3528 --- [main] c.t.l.c.datasul.DatasulUpdateProperties  : [SMART-LINK-CLIENT][DatasulUpdateProperties.update] OK

O método de requisição é do tipo POST 

Não possui autenticação na requisição.

A autorização para redefinição de senha será por meio do código de acesso.

Expandir
titleDeve ser enviado um JSON no corpo da requisição

guid: É o código de acesso, que o usuário recebeu por e-mail;

newPassword: É a nova senha do usuário;

confirmNewPassword: É a confirmação da senha do usuário;

Exemplo:

Image Removed

Expandir
titleCaso não atenda os requisitos acima será retornado erro

Erros sem mensagens: Erro de sintaxe inválida, terá como retorno status 400 Bad RequestExemplo: Corpo da requisição errada ou sem valor.

Erros com mensagens: são retornadas no formato JSON.

Image Removed

http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset

Image Removed

05. Como modificar a mensagem do e-mail

A modificação da mensagem do e-mail ocorre por meio de um programa registrado, que será responsável pela criação da mensagem do e-mail. A chave do registro do programa deve ser enviada no parâmetro keyTemplate.  

http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset?email=<E-MAIL_DO_USUÁRIO>&keyTemplate=<CHAVE_DO_REGISTRO> 

Image Removed

Expandir
titleCaso não exista registro para chave, será utilizado o e-mail padrão

Image Removed

Expandir
titleExemplo de e-mail modificado, recebido pelo usuário

Image Removed

Desenvolvendo o programa para modificar a mensagem do e-mail.

A mensagem deve ser criada em formato HTML;

A mensagem não pode utilizar a tag <script>;

Criar programa progress para retornar a mensagem do e-mail, neste programa deve existir a procedure pi-html, tendo como parâmetro de entrada JsonObject e parâmetro de saída CHARACTER.

Expandir
titlePrograma de exemplo

O parâmetro de entrada é do tipo JsonObject, será enviado com a estrutura e valores abaixo:

Bloco de código
themeRDark
{
  "guid": "Código de acesso do usuário",
  "cod_usuario": "Código do usuário",
  "nom_usuario": "Nome do usuário"
  "url": "Servidor e porta configurados em Parâmetros Gerais, Para mais informações leia o conteúdo 02. Configuração",
}

O parâmetro de saída é do tipo CHARACTER, onde deve ser retornada a mensagem HTML.

Bloco de código
themeRDark
titleAssinatura da Procedure
USING Progress.Json.ObjectModel.*.

{include/i-prgvrs.i EXEMPLO 2.00.00.001 }

PROCEDURE pi-html:
    DEFINE INPUT   PARAMETER jsonIn    AS JsonObject NO-UNDO.
    DEFINE OUTPUT  PARAMETER htmlOut   AS CHARACTER  NO-UNDO.
	
	//Implementar Lógica para criar o retorno HTML    
END PROCEDURE.

Programa de exemplo:

View file
nameexemplo.zip
height250

Expandir
titleResultado do e-mail

Image Removed

Como registrar um programa.

O método de requisição é do tipo POST 

A requisição precisa de autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul, deve se atentar com os modos de autenticação para DATASUL e DATASUL FOR THF.

Não será realizada validação do programa ao registrá-lo. 

Caso aconteça algum erro em tempo de execução com o programa registrado, será lançado erro no arquivo de log do servidor de aplicação Progress e será retornada mensagem padrão.

Expandir
titleDeve ser enviado um JSON no corpo da requisição

key: Não pode passar o limite de 20 caracteres. Exemplos: fnd_access_code, app_rh_access_code.

value: Informar o programa responsável pela modificação da mensagem do e-mail.

Bloco de código
themeRDark
{
  "key": "fnd_access_code",
  "value": "sec/exemplo.r"
}

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates

Image Removed

Como atualizar o registro de um programa.

O método de requisição é do tipo PUT

A requisição precisa de autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul, deve se atentar com os modos de autenticação para DATASUL e DATASUL FOR THF.

Expandir
titleDeve ser enviado um JSON no corpo da requisição

value: Informar o programa responsável pela modificação da mensagem do e-mail.

Bloco de código
themeRDark
{
  "value": "sec/exemplo.r"
}

Informar a chave do registro na URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code

Image Removed

Como remover um programa registrado.

O método de requisição é do tipo DELETE

A requisição precisa de autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul, deve se atentar com os modos de autenticação para Antiga Arquitetura (JBOSS) e Nova arquitetura DTS4THF(TOMCAT).

Informar a chave do registro na URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code

Image Removed

Como retornar um programa registrado.

O método de requisição é do tipo GET

A requisição precisa de autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul, deve se atentar com os modos de autenticação para DATASUL e DATASUL FOR THF.

Informar a chave do registro na URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code

Image Removed

Como retornar todos os programas registrados.

O método de requisição é do tipo GET

A requisição precisa de autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul, deve se atentar com os modos de autenticação para DATASUL e DATASUL FOR THF.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates

Image Removed