Como configurar o agent Fast Analytics

TOTVS Analytics Agent extrator de dados
1

Boa tarde, pessoal!

Quais são o passo a passo para instalar o agent referente ao FAST Analytics?

2

Boa tarde, Brysley,

Segue conforme solicitado:

Este documento tem como objetivo instruir o leitor a instalar o Agent para envio de dados para a plataforma GoodData. A documentação descrita abaixo abrange:

  • Requisitos de sistema.
  • Implantação do Agent.
  • Configuração do Agent.
  • Funcionamento do Agent.

1. Requisitos de sistema

  1. Instalação do Java 8 na máquina em que o Agent for instalado.
  2. Acesso à internet e ao banco de dados (a instalação do Agent pode ser feita no servidor de banco ou no servidor de aplicação do cliente).
  3. Liberação dos IPs da GoodData no firewall (necessário apenas se o cliente optar por abrir a porta do banco de dados para que o servidor da GoodData acesse diretamente o banco de dados):É possível encontrar a lista de IPs através do link oficial da GoodData:https://help.gooddata.com/doc/free/en/data-integration/data-preparation-and-distribution/additional-data-load-reference/gooddata-ip-addresses-and-ip-whitelisting/

2. Implantação do Agent

Segue abaixo os passos necessários para a implantação do Agent para Windows :
(1) Extrair a pasta “Agent.zip” no diretório C:/

Untitled.png
Untitled.png848×572 155 KB

A instalação do Agent é imediata, sendo necessária apenas a extração de sua pasta.

Segue abaixo os passos necessários para a implantação do Agent para Linux :

(2) Extrair a pasta “Agent.zip” no diretório desejado. Insira no terminal o comando:

mkdir gooddata/mv Agent.zip gooddata/cd gooddata/unzip Agent.zipchmod -R 770 gooddata

A instalação do Agent é imediata, sendo necessária apenas a extração de sua pasta e a alteração da definição de permissão de execução.

3. Configuração do Agent

3.1 Definição dos parâmetros de configuração
Antes de configurar o Agent, é necessário ter em mãos os seguintes dados para configurá-lo:

  • Credenciais de acesso (usuário / senha) do usuário responsável por enviar os dados para a plataforma GoodData (é configurado um usuário extrator para esta tarefa). Este usuário tem o nível de “Admin” no projeto.
  • Código do projeto da GoodData que será carregado os dados (<GOODDATA_PROJECT_ID>).
  • Código do processo de ETL que será executado ao receber os dados (<GOODDATA_PROCESS_ID>).
  • Nome do processo de ETL (Em geral é o nome do ERP que o cliente possui. Ex: Protheus / Datasul / VirtualAge).

Além disso, para conexões com bancos de dados são necessários os seguintes dados:

  • IP do banco de dados.
  • Porta do banco de dados.
  • Nome da instância do banco de dados.
  • Credenciais de acesso (usuário / senha) para usuário do banco de dados. Este usuário só precisa ter acesso de leitura no banco.

3.2 Configuração do arquivo “config.properties” Este arquivo é composto por um conjunto de parâmetros, um em cada linha, formatados como “parâmetro=valor”. Sua configuração é necessária para a execução do Agent. Segue abaixo a lista de todos os parâmetros que podem ser configurados no Agent:
Parâmetros gerais

  • gdc.username – Preencher com o e-mail do usuário do GoodData. A execução do Agent apenas funciona caso a função desse usuário, dentro do GoodData, seja Administrador.
  • gdc.password – Preencher com a senha do usuário da GoodData.
  • gdc.upload_url – Preencher com a URL do servidor WebDav da GoodData que irá receber os dados.
  • gdc.upload_archive – Preencher com o nome do arquivo .zip a ser enviado para o servidor da GoodData.
  • gdc.crypto – Preencher com TRUE / FALSE. Este parâmetro define se as senhas do usuário do gooddata e do banco de dados estão criptografadas, evitando que qualquer usuário abra o arquivo config.properties e descubra a mesma. Para gerar a senha criptografada, é necessário executar o programa “encrypt_pwd.bat”, disponível dentro do Agent.
  • gdc.backup – Preencher com TRUE / FALSE. Este parâmetro define se o arquivo enviado para o servidor do GoodData será armazenado em backup por alguns dias.
  • gdc.etl.process_url – Preencher com a URL do servidor da GoodData que irá executar o ETL.
  • gdc.etl.graph – Preencher com a URL do primeiro graph (processo) de ETL a ser executado.
  • gdc.etl.param.LOAD_MODE_FCT – esse parâmetro pode ser preenchido como INCREMENTAL ou FULL_LOAD. Refere-se ao modo de carregamento dos datasets das Fatos do projeto. Uma vez configurada como INCREMENTAL, os dados serão acrescentados aos dados já carregados no GoodData. Uma vez configurada como FULL_LOAD, os dados já existentes no GoodData serão removidos e carregados novamente, de acordo com o período de extração definido no parâmetro param.START_DATE e param.FINAL_DATE.
  • gdc.etl.param.LOAD_MODE_DIM – esse parâmetro pode ser preenchido como INCREMENTAL ou FULL_LOAD. Refere-se ao modo de carregamento dos datasets de Dimensões do projeto. Uma vez configurada como INCREMENTAL, os dados serão acrescentados aos dados já carregados no GoodData. Uma vez configurada como FULL_LOAD, os dados já existentes no GoodData serão removidos e carregados novamente, de acordo com o período de extração definido no parâmetro param.START_DATE e param.FINAL_DATE.
  • gdc.etl.param.LOAD_MODE_KPI – esse parâmetro pode ser preenchido como INCREMENTAL ou FULL_LOAD.
  • gdc.etl.param.LOAD_MODE_SNAPSHOT – esse parâmetro pode ser preenchido como INCREMENTAL ou FULL_LOAD. Esse parâmetro é responsável por informar a última vez que foi realizada a carga de dados no GoodData. É interessante caso há um indicador de carga de dados, dentro do Dashboard do GoodData.
  • filesystem.input_dir – Diretório que o Agent irá ler os arquivos.
  • filesystem.wildcard – Extensões válidas de arquivos. Ou seja, caso exista algum arquivo que necessite compor o arquivo zip, é possível definir tanto o nome do arquivo quanto somente a extensão. Por exemplo, a nomenclatura “.” significa que todos os arquivos, dentro da pasta definida no parâmetro filesystem.input_dir, irão compor o arquivo zip.
  • gdc.etl.param.MONTHS_TO_LOAD – Refere-se ao período, em meses, dos dados que serão enviados para a GoodData.
  • param.DATE_MASK – Refere-se ao formato da data. Como há diversas formatações de data, esse parâmetro permite padronizar um formato de data único.
  • gdc.query_folder – Preencher com o nome da pasta que o Agent deve utilizar para ler as queries. Se não informado, o Agent irá procurar a pasta padrão “query”. Importante: Esta pasta só é considerada pelo Agent caso o projeto do GoodData seja um projeto “Oficial”, excluindo-se assim POC’s / treinamentos / demonstrações.
  • gdc.prefix – Preencher com o prefixo a ser utilizado nos nomes dos arquivos gerados pelo Agent (Ex: CLIENTE_Vendas.csv. Este parâmetro também é aplicado no arquivo .zip enviado para o GoodData. Se não informado, o arquivo irá ser gerado sem prefixo. Importante: O prefixo só é aplicado nos arquivos .csv se o Agent os gerar por meio de queries. Se o agent estiver configurado para enviar arquivos de uma pasta local para o GoodData, apenas o .zip compactado receberá o valor do prefixo.
  • gdc.query_zip – Preencher com o nome do arquivo .zip contendo as queries criptografadas. Importante: Este parâmetro é utilizado especificamente para a oferta INTERA, onde o cliente não tem direito de customizar as queries padrão.

Parâmetros para bancos de dados

  • jdbc.driver_path – Preencher o caminho onde o driver do Banco de Dados está localizado.
  • jdbc.driver – Preencha com a definição do driver, de acordo com o desenvolvedor.
  • jdbc.url – Preencher a string de conexão. Abaixo encontra-se o formato que essa string de conexão deve ser preenchida.
    • jdbc:sqlserver://:;DatabaseName=<DATABASE_NAME>
  • jdbc.username – usuário do banco de dados.
  • jdbc.password – senha do usuário do banco de dados.

Exemplo de preenchimento dos parâmetros do Agent
Segue abaixo um exemplo de preenchimento do Agent, utilizando os seguintes parâmetros:

No arquivo config.properties a configuração ficaria igual apresentada abaixo:

# Credenciaisgdc.username=extrator-analytics@totvs.com.brgdc.password=totvs123# Pasta onde o arquivo zip será adicionado.gdc.upload_url=https://secure-di.gooddata.com/project-uploads/i9jzr0tcuosk3m42x2shlnhmp49sp2oo/today/# Nome do arquivo zip.gdc.upload_archive=Analytics.zip# Parâmetro responsável por verificar se será utilizado criptografia de senhas.gdc.crypto=FALSE# Backupgdc.backup=TRUE# Configuração do caminho e job de ETL.gdc.etl.process_url=https://analytics.totvs.com.br/gdc/projects/i9jzr0tcuosk3m42x2shlnhmp49sp2oo/dataload/processes/78d04524-0901-4566-b06f-be54973ef96e/gdc.etl.graph=TOTVS-FastAnalytics-Backoffice/graph/_Main.grf#Parâmetros para carga de dados: FULL_LOAD  FULL_LOAD_DELETE_ON_EMPTY  INCREMENTAL                                               gdc.etl.param.LOAD_MODE_FCT=INCREMENTALgdc.etl.param.LOAD_MODE_DIM=INCREMENTALgdc.etl.param.LOAD_MODE_KPI=INCREMENTALgdc.etl.param.LOAD_MODE_SNAPSHOT=FULL_LOAD#Diretório que o Agent irá ler os arquivos.filesystem.input_dir=./files/log#Extensões válidas de arquivos.filesystem.wildcard=agent.log#   Configuração de conexão SQLServerjdbc.driver_path=./files/jdbc/sqljdbc4.jarjdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriverjdbc.url=jdbc:sqlserver://localhost:1433;DatabaseName=TOTVS12jdbc.username=totvsprodjdbc.password=totvs123#Mês anterior, dia 01param.START_DATE=CONVERT(VARCHAR(8),DATEADD(MONTH, -24, DATEADD(MONTH, DATEDIFF(MONTH, 0, GETDATE()), 0)), 112)param.FINAL_DATE=CONVERT(VARCHAR(8),DATEADD(MONTH, +12, DATEADD(MONTH, DATEDIFF(MONTH, 0, GETDATE()), 0)), 112)param.EXTRACTION_DATE=CONVERT(VARCHAR(8), GETDATE(), 112)gdc.etl.param.MONTHS_TO_LOAD=36param.DATE_MASK=yyyyMMdd

3.3 Agendamento do programa “run.bat” para execução diária (Windows)

O último passo para configurar o Agent é agendar o programa “run.bat”, responsável por executar o Agent, no Agendador de Tarefas do Windows. O Agendador de Tarefas está no Painel de Controle, na seção “Ferramentas Administrativas”.

Untitled__1_.png
Untitled__1_.png886×632 140 KB

No agendador de tarefas é possível definir o horário de execução do Agent, o tempo máximo de execução, entre outras configurações.

3.4 Agendamento do programa “ run.sh” para execução diária (Linux)

O último passo para configurar o Agent é agendar o programa “run.sh”, responsável por executar o Agent, no Crontab do Linux. Essa configuração é realizada da seguinte forma:
Execute no terminal o comando:

crontab -e

Então insira a linha de ação no crontab. Por exemplo, executar todos os dias às 5:00 .

0 5 * * * bash -l -c "cd /gooddata/ && ./run.sh"

Aperte a tecla ESC e digite o comando abaixo. Isso irá salvar e fechar o Crotab:

:wq

4 - Funcionamento do Agent

O Agent é o programa responsável por extrair os dados do banco de dados do cliente, enviá-los para o GoodData e ativar a execução do ETL, responsável por carregar efetivamente os dados no GoodData. A versão atual do Agent executa as seguintes instruções, na ordem em que são apresentadas abaixo:

  1. Leitura de todos os parâmetros do arquivo config.properties.
  2. Realização de um teste de conexão com a plataforma GoodData, utilizando o usuário/senha informados no arquivo config.properties.
  3. Se os parâmetros de banco de dados forem informados, o Agent irá verificar a existência de uma pasta “query” no local em que foi instalado e se conectar ao banco de dados.
  4. Se a pasta existir, todos os arquivos .txt dentro desta pasta (e suas subpastas) serão lidos pelo Agent e executados no banco de dados como queries.
  5. Se a pasta não existir, o Agent irá procurar as queries a serem executadas na tabela “I01” do banco de dados. Esta tabela “I01” (no caso do Protheus) armazena todas as queries do Fast Analytics, criptografadas.
  6. Execução de todas as queries extraídas.
  7. Se os parâmetros de banco de dados não forem informados, o Agent irá selecionar todos os arquivos presentes na pasta “Dados”, para envio para o GoodData.
  8. Compressão (.zip) de todos os resultados gerados.
  9. Conexão com a plataforma GoodData.
  10. Envio dos arquivos .zip comprimidos para o servidor WebDAV do GoodData.
  11. Execução do ETL.

Todas as execuções do Agent são armazenadas na pasta “log” do mesmo. O arquivo de log gerado pelo Agent pode ser enviado para a equipe de suporte caso algum erro venha a ocorrer em sua execução, juntamente com o arquivo “config.properties” utilizado.
Os clientes “plataforma” do GoodData têm a opção de customizar as queries padrão gravadas na tabela I01 do banco de dados. Para isto, é necessário rodar o programa “export_query.bat”, localizado na própria pasta do Agent. Este programa realiza a descriptografia das queries armazenadas na tabela I01, e as exporta em arquivos .txt de acordo com o número de empresas que o cliente possui, dentro da pasta “query”. Caso o cliente realize a customização das queries presentes na pasta “query ”, o Agent irá considerar apenas estas queries customizadas para enviar dados para o GoodData, e a tabela I01 (que contém as queries padrão) será ignorada.

Estamos à disposição.

Atenciosamente.

1 curtida