INTEGRAÇÃO DATASUL X TOTVS APPS

Contexto de negócio

A arquitetura da plataforma TechFin requer a ingestão recorrente de dados para a integração com demais softwares externos, entre eles o Datasul. Neste sentido, os softwares externos enviam os dados para uma área de preparação (staging), cujos dados serão posteriormente transformados e normalizados para estruturas predefinidas pelos aplicativos do TechFin.

Para assegurar a eficiência e escalabilidade da integração, a extração dos dados no produto Datasul é realizada de forma parcial, isto é, são considerados apenas os dados afetados (modificados) em um dado intervalo de tempo.

Sistemas Envolvidos

Para que os dados do produto Datasul sejam disponibilizados para os aplicativos do serviço TOTVS Apps, estão envolvidos:

TOTVS RAC;
TOTVS Apps;
TOTVS Carol.

Integração

A integração tem o objetivo de disponibilizar na área de staging do serviço TOTVS Carol os dados criados, modificados ou excluídos, de tabelas predefinidas e em um determinado período de tempo, para que as aplicações do serviço TOTVS Apps possam fazer uso destas informações . Entre os aplicativos do serviço TOTVS Apps estão o TOTVS Antecipa, o TOTVS Mais Negócios e o TOTVS Consignado.

Os dados que estão indisponíveis no ERP, dados excluídos, serão identificados na área de staging pelo campo active que indicará o valor false.

Os dados das tabelas enviados para o serviço Carol(CDS) serão enviados compactados. Para isso o produto fará uso do Gzip, que atende as especificações da RFC 1952 conforme a especificação da Carol.

Escopo

Esta integração disponibiliza dados das tabelas, indicadas pelo serviço TOTVS Apps, no serviço TOTVS Carol (CDS). Os dados são disponibilizados na área de staging para que possam ser normalizados e, por fim, utilizados pelos aplicativos.

Pré-requisitos instalação/implantação/utilização

Pré-requisitos (técnicos ou de negócio) para o funcionamento da integração:

Progress Openedge na versão 11.7.5 ou superior;
Disponibilizar as seguintes bibliotecas do Progress Openedge 11.7.5 no início do propath:
- <diretorio_instalação_progress>\gui\OpenEdge.BusinessLogic.pl;
- <diretorio_instalação_progress>\gui\OpenEdge.Core.pl;
- <diretorio_instalação_progress>\gui\OpenEdge.ServerAdmin.pl;
- <diretorio_instalação_progress>\gui\netlib\OpenEdge.Net.pl.
Datasul 12.1.29 ou superior;
Dados de acesso e certificados dos serviços - DS - TEC - Aplicação de certificados no Progress:
- TOTVS Rac;
- TOTVS Apps;
- TOTVS Carol.
Instalação do programa Gzip - Caso o sistema operacional onde será executado o RPW seja *nix.

Para a validação dos pré-requisitos e realização das configurações é possível utilizar o programa Assistente de configuração para integração com Totvs Apps.

Datasul

Configurações

As configurações necessárias para a integração são:

Parâmetros de Integração;
Parâmetros de Jornalização.

Nos parâmetros de integração serão informados os dados de autenticação e sincronização de informações e nos parâmetros de jornalização, a forma como os dados afetados serão identificados para que sejam enviados para o serviço Totvs Carol.

Parâmetros de integração

No Tomcat, nas propriedades do sistema, localize as Propriedades de integrações Totvs e informe os dados conforme orientação do manual.

Parâmetros de Jornalização

No Tomcat, nas propriedades do sistema, localize as Propriedades de Jornalização e informe os dados conforme orientação do manual.

Após configurar a integração e a jornalização, é necessário gerar as Policies para ambientes que usem banco Progress. Para os ambientes com dataserver MSSQL ou Oracle, é necessário gerar os Triggers.

Jornalização com trigger:

Geração das Triggers Audit Trail

Para isto é necessário o cadastro de bancos que serão utilizados na integração AU0001 - Manutenção Base de dados e também a execução da tarefa AU0108 - Geração das Triggers.

Jornalização com CDC:

Geração das policies

Para isto é necessária a execução da tarefa html.JournalingCDC Jornalização - Geração de Policy CDC

Os bancos unificados deverão ser configurados separados por alias e, caso seja necessária a auditoria além da integração, o cadastro de monitoramento de tabelas/ atributos - AU0002 - Monitoramento de Tabelas/Atributos deverá ser aplicada ao banco (alias) correspondente à tabela.
Caso hajam bancos cadastrados pelo alias:
- Todos os bancos lógicos relacionados ao mesmo banco físico devem ter suas triggers geradas ao mesmo tempo, em uma mesma execução, para evitar a exclusão involuntária de arquivos;
- Para evitar que a atribuição das triggers às tabela sejam excluídas involuntariamente, no cadastro dos bancos auditáveis - AU0001 - Manutenção Base de Dados, a opção ' Incorpora Base de Dados ao diretório de Triggers' não poderá ser utilizada.

Sincronização de dados Datasul x Totvs Apps

A integração dos dados se dará por meio da execução da tarefa AU0109 - Sincronização de Dados Datasul x Totvs Apps.

Informativo para ambiente que faz o uso do CDC

Sempre será executada automaticamente o processo de Geração de Policy CDC após este processo é realizado o processo de sincronização de dados.

Release 12.1.2307.3 e superiores.

Customização dos dados antes da sincronização

É possível incluir, alterar ou remover informações do JSON do TableSchema ou TableData antes que ele seja sincronizado com a Carol, para isso deverão ser seguidos os passos abaixo:

Criar um programa no diretório carol/<nome_logico_banco> com o nome <nome_tabela>_data.p. Exemplo: carol/emsfnd/usuar_mestre_data.p;
O programa deverá estar preparado para receber um parâmetro de entrada do tipo Progress.Json.ObjectModel.JsonObject e para retornar um parâmetro do tipo Progress.Json.ObjectModel.JsonConstruct;

No JSON de entrada serão enviadas as informações de dataType, dbName, tableName, company e data, conforme exemplo abaixo:

JSON Entrada

{"dataType": "TableSchema" ou "TableData",
 "dbName": "<nome_logico_banco>",
 "tableName": "<nome_tabela>",
 "company": Código da empresa que está sendo integrada,
 "data": JsonObject para o dataType TableSchema ou JsonArray para o dataType TableData
}

Exemplo de programa customizado:

Programa customizado

USING Progress.Json.ObjectModel.JsonArray.
USING Progress.Json.ObjectModel.JsonConstruct.
USING Progress.Json.ObjectModel.JsonObject.

DEFINE INPUT  PARAMETER pInput  AS JsonObject    NO-UNDO.
DEFINE OUTPUT PARAMETER pOutput AS JsonConstruct NO-UNDO.
                   
IF pInput:GetCharacter("dataType") = "TableData" THEN
    RUN customTableData IN THIS-PROCEDURE.
ELSE
    RUN customTableSchema IN THIS-PROCEDURE.
    
PROCEDURE customTableData PRIVATE:
    DEFINE VARIABLE oTableData AS JsonArray  NO-UNDO.

    ASSIGN pOutput    = NEW JsonArray()
           oTableData = pInput:getJsonArray("data").
           
    /*
       REALIZAR AS MANIPULAÇÕES NECESSÁRIAS NO OBJETO oTableData
    */          
           
    ASSIGN pOutput = oTableData.

END PROCEDURE.

PROCEDURE customTableSchema PRIVATE:
    DEFINE VARIABLE oTableSchema AS JsonObject NO-UNDO.

    ASSIGN pOutput      = NEW JsonObject()
           oTableSchema = pInput:getJsonObject("data").
    /*
       REALIZAR AS MANIPULAÇÕES NECESSÁRIAS NO OBJETO oTableSchema
    */
    oTableSchema:ADD("testeAdd","deuCerto!!!").
    
    ASSIGN pOutput = oTableSchema.

END PROCEDURE.

Foram inseridos logs no programa para facilitar a identificação de possíveis erros. Para isso foi criado o tipo de log CAROLSYNC, conforme exemplo abaixo:

CAROLSYNC

	Line 24043: [21/04/01@11:46:08.973-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableData Begin: 01/04/2021 - 11:46:08
	Line 24046: [21/04/01@11:46:08.973-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableData Params -> codBaseDados: emsfnd tableName: configur_propried dateFrom 01/04/2021 00:37:23,556-03:00 dateTo 01/04/2021 11:46:08,773-03:00
	Line 24050: [21/04/01@11:46:08.974-0300] P-005856 T-012048 1 4GL CAROLSYNC      getTableSchema Begin: 01/04/2021 - 11:46:08
	Line 24053: [21/04/01@11:46:08.974-0300] P-005856 T-012048 1 4GL CAROLSYNC      getTableSchema Params -> tableName: configur_propried
	Line 24078: [21/04/01@11:46:08.981-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Begin: 01/04/2021 - 11:46:08
	Line 24081: [21/04/01@11:46:08.988-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Input Data: c:\temp\/input_TableSchema_emsfnd_configur_propried.json
	Line 24087: [21/04/01@11:46:08.988-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData oParams: {"dataType":"TableSchema","dbName":"emsfnd","tableName":"configur_propried"}
	Line 24090: [21/04/01@11:46:08.989-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData customProgram Begin: 01/04/2021 - 11:46:08
	Line 24099: [21/04/01@11:46:08.992-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData customProgram End: 01/04/2021 - 11:46:08
	Line 24102: [21/04/01@11:46:08.994-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Output Data: c:\temp\/output_TableSchema_emsfnd_configur_propried.json
	Line 24107: [21/04/01@11:46:08.995-0300] P-005856 T-012048 1 4GL CAROLSYNC      getTableSchema End: 01/04/2021 - 11:46:08
	Line 24112: [21/04/01@11:46:08.996-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema Begin: 01/04/2021 - 11:46:08
	Line 24115: [21/04/01@11:46:08.996-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema Params -> tableName: configur_propried syncMethod: PUT
	Line 24120: [21/04/01@11:46:08.997-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema tableSchema: {"mdmStagingMapping":{"properties":{"cod_agrpdor":{"type":"character"},"cod_contexto_propried":{"type":"character"},"cod_livre_1":{"type":"character"},"cod_livre_2":{"type":"character"},"cod_propried":{"type":"character"},"dat_livre_1":{"type":"date"},"dat_livre_2":{"type":"date"},"des_propried":{"type":"character"},"fwk_last_modif":{"type":"datetime-tz"},"log_livre_1":{"type":"logical"},"log_livre_2":{"type":"logical"},"num_livre_1":{"type":"integer"},"num_livre_2":{"type":"integer"},"val_
	Line 24121: [21/04/01@11:46:08.997-0300] P-005856 T-012048 1 4GL CAROLSYNC      livre_1":{"type":"decimal"},"val_livre_2":{"type":"decimal"}}},"mdmCrosswalkTemplate":{"mdmCrossreference":{"cnfgrprp_id":["cod_propried","cod_agrpdor"]}},"testeCleber":"deuCerto!!!"}
	Line 24125: [21/04/01@11:46:08.998-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient Begin: 01/04/2021 - 11:46:08
	Line 24128: [21/04/01@11:46:08.998-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient Params -> path: /api/v2/staging/tables/&1/schema?connectorId=&2 tableName: configur_propried
	Line 24202: [21/04/01@11:46:09.006-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient End: 01/04/2021 - 11:46:09
	Line 24682: [21/04/01@11:46:09.058-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema PutHTTPRequest Begin: 01/04/2021 - 11:46:09
	Line 32759: [21/04/01@11:46:11.832-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema PutHTTPRequest End: 01/04/2021 - 11:46:11
	Line 32762: [21/04/01@11:46:11.834-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableSchema End: 01/04/2021 - 11:46:11
	Line 33016: [21/04/01@11:46:11.848-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient Begin: 01/04/2021 - 11:46:11
	Line 33019: [21/04/01@11:46:11.849-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient Params -> path: /api/v2/staging/tables/&1?connectorId=&2&&returnData=false tableName: configur_propried
	Line 33100: [21/04/01@11:46:11.861-0300] P-005856 T-012048 1 4GL CAROLSYNC      getHttpClient End: 01/04/2021 - 11:46:11
	Line 33581: [21/04/01@11:46:11.946-0300] P-005856 T-012048 1 4GL CAROLSYNC      getDataRequest Begin: 01/04/2021 - 11:46:11
	Line 33584: [21/04/01@11:46:11.946-0300] P-005856 T-012048 1 4GL CAROLSYNC      getTableSchema Params -> codBaseDados: emsfnd tableName: configur_propried dateFrom: 01/04/2021 00:37:23,556-03:00 dateTo: 01/04/2021 11:46:08,773-03:00
	Line 33600: [21/04/01@11:46:12.114-0300] P-005856 T-012048 1 4GL CAROLSYNC      getDataRequest End: 01/04/2021 - 11:46:12
	Line 33624: [21/04/01@11:46:12.119-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Begin: 01/04/2021 - 11:46:12
	Line 33627: [21/04/01@11:46:12.126-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Input Data: c:\temp\/input_TableData_emsfnd_configur_propried.json
	Line 33633: [21/04/01@11:46:12.127-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData oParams: {"dataType":"TableData","dbName":"emsfnd","tableName":"configur_propried"}
	Line 33636: [21/04/01@11:46:12.128-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData customProgram Begin: 01/04/2021 - 11:46:12
	Line 33645: [21/04/01@11:46:12.130-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData customProgram End: 01/04/2021 - 11:46:12
	Line 33648: [21/04/01@11:46:12.133-0300] P-005856 T-012048 1 4GL CAROLSYNC      customData Output Data: c:\temp\/output_TableData_emsfnd_configur_propried.json
	Line 33653: [21/04/01@11:46:12.135-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableData PostHTTPRequest Begin: 01/04/2021 - 11:46:12
	Line 41725: [21/04/01@11:46:14.423-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableData PostHTTPRequest End: 01/04/2021 - 11:46:14
	Line 41728: [21/04/01@11:46:14.423-0300] P-005856 T-012048 1 4GL CAROLSYNC      syncTableData End: 01/04/2021 - 11:46:14

Quando o nível do log estiver configurado para DEBUG (logginglevel 4 (Extended)), serão exportados os JSONs que foram enviados e recebidos do programa de customização. Para isso, será utilizado o diretório temporário para salvar os arquivos, que serão detalhados abaixo. No log CAROLSYNC será mostrado o nome do caminho completo onde foram salvas as informações.
1. input_TableSchema_<nome_logico_banco>_<nome_tabela>.json: JSON de entrada com as informações do TableSchema. Exemplo de nome: input_TableSchema_emsfnd_usuar_mestre.json.
2. input_TableData_<nome_logico_banco>_<nome_tabela>.json: JSON de entrada com as informações do TableData. Exemplo de nome: input_TableData_emsfnd_usuar_mestre.json.
3. output_TableSchema_<nome_logico_banco>_<nome_tabela>.json: JSON de saída do programa customizado com as informações do TableSchema. Exemplo de nome: output_TableSchema_emsfnd_usuar_mestre.json.
4. output_TableData_<nome_logico_banco>_<nome_tabela>.json: JSON de saída do programa customizado com as informações do TableData. Exemplo de nome: output_TableDataema_emsfnd_usuar_mestre.json.

Instalação/Atualização

Quando houver atualização do produto Datasul deve-se atentar para as seguintes necessidades:

Executar novamente a tarefa AU0108 - Geração das Triggers ou o programa html.JournalingCDC Jornalização - Geração de Policy CDC conforme o tipo de Jornalização utilizado;
Quando houver utilização do Openedge CDC, antes de gerar novas policies, é necessário garantir que os dados estejam integrados executando a tarefa AU0109 - Sincronização de Dados Datasul x Totvs Apps.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

Endereços acessados

Durante a execução dos programas relacionados a integração, alguns endereços envolvidos são requisitados e para o funcionamento correto, estes endereços devem estar liberados para acesso.

Os endereços utilizados são:

Checklist de suporte da aplicação

Instalação/Configuração

Verifique se o serviço Totvs RAC está disponível;
Verifique se o certificado do serviço Totvs RAC está instalado na pasta do progress;
Verifique as configurações de integração com o serviço Totvs RAC;
Verifique se o serviço Totvs Apps está disponível;
Verifique se o certificado do serviço Totvs Apps está instalado na pasta do progress;
Verifique as configurações de integração com o serviço Totvs Apps;
Verifique se o serviço Totvs Carol está disponível;
Verifique se o certificado do serviço Totvs Carol está instalado na pasta do progress;
Verifique as configurações de integração com o serviço Totvs Carol;
Verifique as configurações de jornalização;
Verifique as configurações de bancos do Audit Trail;
Verifique se as triggers ou policies foram criadas;
Verifique a agenda de execução.

Checklist de Verificações:

Relacione itens de verificações para que o atendente possa:

Verifique se os pedidos de execução estão sendo criados;
Verifique se não há erros na execução do pedido;
Verifique o relatório au0109 gerado no spool do servidor RPW;
Verifique o clientlog da execução do servidor RPW.

Páginas filhas

Integração entre o ERP Datasul e o serviço TOTVS Apps (Plataforma TechFin)