Histórico da Página

...

Projeto Interno

O objetivo deste guia é ajudar os membros da equipe a entender a composição do projeto e como nos organizamos para planejar, desenvolver, testar e documentar o TAF TSI.
A documentação oficial publicada para os clientes consta em TSI - TAF Service Integration.
O projeto consta no diretório: .../Master/Fontes/TAF/Integração/TSI, sendo composto por fontes na raiz (genéricos) , subpasta ERP (extração dos módulos do protheus) e subpasta TAF (APIS que fazem operações nas tabelas legados do TAF).
O controle com o nome dos fontes, descrição e analista que desenvolveram o TSI, fica disponível no google docs \Tabelas TAF.
Atualmente o pacote centralizador do TSI no AtuSx é o 009134 (release 33). Aqui tem a criação dos campos stamp nas tabelas do TAF e a criação da tabela de log V5R.
Pontos de melhorias, dúvidas ou discussões sobre a execução, podem ser colocados no dontpad do TSI, para posterior implementação, se necessário expor em review ou retrospectiva.

Divisão na execução

Quando é necessário criar um novo leiaute no TSI, precisamos trabalhar em alguns pontos, são eles:

Extração do ERP

Aqui é contemplado a regra de extração apenas do ERP Protheus, que em muito(s) casos a(s) regra(s) consta(m) nos extratores:

• extrator fiscal (...\Master\Fontes\Livros Fiscais\Extrator\ExtFisxTaf.prw),
• extrator financeiro(...\Master\Fontes\Adm\FINA989.prw) ou
• extrator contábil (...\Master\Fontes\Adm\ECD\CTBS001.prw e CTBS103.prw).

1. Entender e elaborar a regra de extração.
2. Nessa etapa são levantados todos os campos necessários na extração,  a planilha interna com o layout consta em google drive em Layout TAF.xlsx
3. Aqui também é necessário utilizar o pacote centralizador do TSI no atusx, para criar o campo STAMP na tabela legado do SIGATAF.
4. Conforme DOD dessa tarefa, aqui também é esperado a geração do JSON com o conteúdo dos campos do layout nas tags pré definidas para integração.
5. Controle do Stamp criado na Tabela do ERP e Mecanismo de validação do STAMP entre Protheus x TAF finalizado.
   Lembrando que seguimos a regra que deve ser integrado registros onde o stamp do erp é superior ao do TAF ou se no erp é diferente de nulo e no taf está vazio.

Integração TAF (+ Hash )

Etapa onde o layout já está sendo extraído pelo TSI (geração do json mencionado na etapa 4 da extração do ERP) e agora será construído a integração das informações para o TAF.

1. Construir Hash do JSON para o TAF (pai, filho e netos).
2. Realizar o processo de gravação dos dados através de um mecanismo que irá receber o JSON e realizar a integração com o TAF.
3. Colocar a rotina dentro do Schedule.

...

Open API

Fontes e Tabelas

...

SFT\SF3\SF1\

SD1\SF2\SD2

...

C20\C30\C35\

C39\C2F\C2D

...

O que é TSI?

• É o novo serviço de integração do SIGATAF com o ERP-Protheus.
• O TAF Service Integration ( TSI ) foi criado exclusivamente para clientes que usam o TAF como módulo do ERP-Protheus, ou seja, ambos no mesmo banco de dados.

Pré Requisitos

• 1. Requer um banco de dados homologado.
• 2. Requer um TOTVS Application Server build 7.00.170117A com geração superior a 23/09/2019.
• 3. Requer um TOTVS DbAccess  igual ou superior a 19/11/2019
• 4. Executar o UpdDistr ( sdfbra.txt referente ao pacote acumulado do SIGATAF ).
• 5. Aplicar a patch com os fontes atualizados do acumulado ( .ptm da expedição contínua ).

Banco de Dados Homologados

• A integração com TSI depende do novo campo S_T_A_M_P_ e sua criação está disponível para os Banco de Dados MSSQL, ORACLE e  POSTGRES.

O que é stamp?

• Um campo interno para tabelas do DBAccess, não visíveis na estrutura de acesso pelo AdvPL, que registra um datetime e/ou timestamp para cada registro inserido e/ou alterado na base de dados.
• O tipo do campo criado na tabela é DATETIME (para MSSQL) e TIMESTAMP (para Postgres e Oracle).
• Para recuperar o campo de controle S_T_A_M_P_ com a informação completa ( data e horário ), por exemplo no formato yyyy-mm-dd hh:MM:ss.mmm,
  deve ser feito um CAST. Confira mais sobre stamp na documentação do DbAccess: Implementação - Campo de controle adicional no DBAccess - S_T_A_M_P_

Exemplo de STAMP em uma tabela no TAF:

Image Added

Exemplo de STAMP em uma tabela do ERP:
Image Added

Exemplo de query em MSSQL realizando o cast para converter o campo em string:

Select cast( to_char(SA1.S_T_A_M_P_,'DD.MM.YYYY HH24:MI:SS.FF') AS VARCHAR2(23) ) From SA1T10

Configuração

Dicionário

• Já foi incorporado no segregado e agora está disponível no portal através do pacote acumulado 21/01/2022.
• No dicionário constam os campos stamp nas tabelas do TAF, a criação da tabela de log V5R ( logs ) e V80 ( data e hora de corte ), conforme:
  
  
• Campos C/ STAMPS

• V80

• V5R

Wizard Configuração TAF

• Para que a opção do "TSI - TAF SERVICE INTEGRATION" seja exibida no Wizard do TAF, é necessário ter executado os pré-requisitos e que exista ao menos uma nota escriturada no fiscal ( SF3/SFT ).
• A wizard de configuração do TAF ganhou uma nova opção para criação dos campos S_T_A_M_P_, basta executar marcando a nova opção, [X] TSI - TAF Integration Service
  
  

Image Added

Execute a wizard, resultando em sucesso, será apresentada a tela com a mensagem conforme abaixo.

Image Added

Tabelas Afetadas ( Criação STAMP )

• As tabelas do Protheus que sofrerão a criação do campo S_T_A_M_P_ são:
  SB1, SFT, SF4, SB5, SA1, SA2, SA4, SAH, CT1, F2Q, CDN, SE1, SE2, CCF, SF1, SF2, SF3, CCE, SYD, CDH, SON e CKX.
  Obs: Em breve a CDT e CDG serão disponibilizadas com S_T_A_M_P_.
  

Schedule Configurador

• O TSI deverá ser incluído no agendamento ( schedule do SIGACFG ) como um serviço ( job ) sempre ativo.
  Desta maneira, ao incluir ou alterar um novo cadastro ou movimento no ERP, o JOB se encarregará de executar a integração automaticamente de forma transparente ao usuário.
  O controle é feito através da comparação dos campos do ERP-Protheus S_T_A_M_P_  Vs  XXX_STAMP do TAF.
  Exemplo de configuração:

Image Added

Usabilidade ( menus )

Menu Log de Integração

• Através desta rotina é possível  visualizar o detalhamento das mensagens de integração que apontaram falhas no processamento ( tabela V5R ) e não foram integradas ao TAF. 

Browse com Log
Image Added

Detalhamento dos Erros

Image Added

Menu Filtro Data de Corte

• Através desta rotina é possível  visualizar o último processamento por layout, a tabela V80 foi criada para melhorar o desempenho do filtro, referente ao registros que ainda não foram processados.

Browse com Log

Image Added

Como identificar erros

Quando acionar o TAFCONOUT para verificar possíveis falhas

• Caso não ocorra integração ou deseje acompanhar em que passo está a integração é possível ligar o log de mensagem do TSI, para isso basta atualizar o appserver.ini:
  [GENERAL]
  TAFCONOUT=1

Onde avaliar os erros de integração

• Consultar o console para verificar se o serviço está em execução ou se ocorreu alguma falha.
• Pode ser verificado na tabela V5R, através da chave do registro (  TAFA564 - Cadastro de Log de integração ).
• Consulte a aba "Erros de Integração" na documentação TSI - TAF Service Integration, para maiores informações sobre as mensagens de erros e suas possíveis soluções
• Consulte a aba "Análise Técnica" na documentação TSI - TAF Service Integration, para maiores informações sobre as mensagens de erros.

Image Added

Image Added

Image Added

Estrutura de Log na V5R

• Os erros são aglutinados e gravados em uma única linha na V5R (por chave do cadastro) por registro, substituindo o erro anterior caso exista.
• A filial é gravada no campo V5R_CODFIL e não na V5R_REGCHAVE.
• Caso seja realizado o ajuste no registro e o mesmo seja integrado no TAF, o log é apagado na sequência.
  
  

As principais validações no TSI são por modelo do mvc (VldData) ou regras específicas:

• Por tipo de dados, ex: data, numérico, lógico ou caractere (FWNOSTRUCT);
• Obrigatório (OBRIGAT);
• Se código existe na consulta padrão F3 (NOTFOUND);
• Se o tamanho é excedido (FWNOWIDTH);
• Se o conteúdo consta no combox (FWNOLIST);
• Se o registro existe na origem (NOTEXIST);
• Se o conteúdo pode ser editado (FWWHEN);
• Regra de modelo específico, exemplo: Se a nota necessita de item (TAFHLPNF017);
• Se o commit do modelo é válido e não estoura o uniqline (UNIQUELINE);
• Se o formato de data é válido (DATE);
• Se é válido apagar uma chave estrangeira (FWFORMCANCEL);
• Se houve falha na atribuição de conteúdo (LOADVALUE)

Quais tabelas são utilizadas

Índice do Banco de Dados Sugeridos ( Performance )

CREATE NONCLUSTERED INDEX SFTT10ESP ON SFTT10(FT_FILIAL, [FT_NFISCAL] ,[FT_SERIE], [FT_CLIEFOR], [FT_LOJA],[FT_IDENTF3], [FT_ENTRADA],[FT_ESPECIE],[FT_PRODUTO], R_E_C_N_O_, D_E_L_E_T_)

CREATE NONCLUSTERED INDEX SF3T10ESP ON SF3T10(F3_FILIAL, [F3_NFISCAL] ,[F3_SERIE], [F3_CLIEFOR], [F3_LOJA],[F3_IDENTFT], [F3_ENTRADA],[F3_ESPECIE], R_E_C_N_O_, D_E_L_E_T_)

CREATE NONCLUSTERED INDEX SFT010STP ON SFT010(FT_FILIAL, S_T_A_M_P_, R_E_C_N_O_, D_E_L_E_T_)

Onde encontrar as documentações

Documentação Oficial SIGATAF TSI para Clientes

Implementação - Campo de controle adicional no DBAccess - S_T_A_M_P_

Fontes Envolvidos

Rotinas Envolvidas

Projeto Interno ( DEVS )

O objetivo deste guia é ajudar os membros da equipe a entender a composição do projeto e como nos organizamos para planejar, desenvolver, testar e documentar o TAF TSI.
A documentação oficial publicada para os clientes consta em TSI - TAF Service Integration.
O projeto consta no diretório: .../Master/Fontes/TAF/Integração/TSI, sendo composto por fontes na raiz (genéricos) , subpasta ERP (extração dos módulos do protheus) e subpasta TAF (APIS que fazem operações nas tabelas legados do TAF).
O controle com o nome dos fontes, descrição e analista que desenvolveram o TSI, fica disponível no google docs \Tabelas TAF.

Divisão na execução do Desenvolvimento

Quando é necessário criar um novo leiaute no TSI, precisamos trabalhar em alguns pontos, são eles:

Extração do ERP

Aqui é contemplado a regra de extração apenas do ERP Protheus, que em muito(s) casos a(s) regra(s) consta(m) nos extratores:

• extrator fiscal (...\Master\Fontes\Livros Fiscais\Extrator\ExtFisxTaf.prw),
• extrator financeiro(...\Master\Fontes\Adm\FINA989.prw) ou
• extrator contábil (...\Master\Fontes\Adm\ECD\CTBS001.prw e CTBS103.prw).

1. Entender e elaborar a regra de extração.
   
   

2. Nessa etapa são levantados todos os campos necessários na extração,  a planilha interna com o layout consta em google drive em Layout TAF.xlsx
   
   
3. Aqui também é necessário utilizar o pacote centralizador do TSI no atusx, para criar o campo STAMP na tabela legado do SIGATAF.
   
   
4. Conforme DOD dessa tarefa, aqui também é esperado a geração do JSON com o conteúdo dos campos do layout nas tags pré definidas para integração.
   
   
5. Controle do Stamp criado na Tabela do ERP e Mecanismo de validação do STAMP entre Protheus x TAF finalizado.

Integração ERP e TAF ( Json x Hash )

Etapa onde o layout já está sendo extraído pelo TSI (geração do json mencionado na etapa 4 da extração do ERP) e agora será construído a integração das informações para o TAF.

1. Construir Hash do JSON para o TAF pai, filho e netos (se houver), o modelo dos fontes com hash consta em TAF\Integração\TSI\TAF\WSTAFXXX.prw.
   
   
2. Realizar o processo de gravação das tabelas do TAF, através de um mecanismo que irá receber os dados do JSON  (utilizar o motor de cadastro básico TAFA565 ou motor pai, filho e netos TAFA585).
   Integração do JSON com o TAF finalizado para o evento, iremos instanciar o modelo do respectivo cadastro que será integrado e alimentá-lo com as informações extraídas do Protheus.
   
   
3. Validar se o Commit foi possível (Tabelas do TAF gravadas com os dados do JSON), se sim grava o campo TAFSTAMP com o mesmo valor do STAMP trazido do Protheus para o respectivo evento
   (Controle do STAMP nas tabelas do TAF implementado), precisa ser a última instrução da função.
   
   Ponto de atenção: não é necessário instanciar o modelo a cada novo registro de integração, todo o processo acima precisa estar dentro de controle de transação, ou seja, se cair a conexão durante o processo
   o campo TAFSTAMP não será preenchido e o registro será reintegrado no novo processamento do TSI.
   
   
4. Gravação da tabela V5R para os erros de integração, caso não seja possível a integração gravar a tabela de "Erros de Integração TSI" (Tabela V5R), veja os principais itens a serem validados em estrutura de log.
   
   
5. Para auxiliar a equipe de suporte, ou na análise de um possível problema, devemos avaliar pontos onde é válido adicionar conouts (TAFCONOUT), ver em documentação oficial TAF Service Integration \ Análise Técnica \ Lista de Erros.
   
   
6. Colocar a rotina dentro do Schedule ( TAFA573 ).

Construção APIS

Aqui será construídas as APIS para substituir o layout TAF.

1. Construir API que recebe mensagem JSON e grava no cadastro MVC do TAF o respectivo leiaute.
   
   

2. Construir as APIs com os seguintes tipos de requisição:
   
   PUT ( pode receber um código ou uma lista para atualizar )
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/63013000/?sourceBranch=T1D MG 01
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1D MG 01 (+Body)
   
   DELETE ( pode receber parâmetros ou uma lista para apagar ) 
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice?sourceBranch=T1D MG 01&operationType=1&modelIdentificationCode=55&taxDocumentSeries=1&taxDocumentNumber=000000002 &fiscalDocumentDate=20201015&participatingCode=CSP000101
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01 (+Body)
   
   POST ( pode receber uma lista para inserir )
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1D MG 01 (+Body)
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01 (+Body)
   
   GETID ( pode retornar um único código )
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/63013000/?sourceBranch=T1D MG 01
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/idTsiinvoice/?sourceBranch=T1D MG 01&taxDocumentNumber=NTSAIDA
   
   GETLIST ( pode retornar uma lista com paginação, tratar os parâmetros: HasNext, Page, PageSize, Do Código, Até Código, ordenação, etc... )
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1M SP 03&Page=1&PageSize=50&invoiceOf= &invoiceUp=ZZZZ
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01&commonExternalTariffOf=63013000&commonExternalTariffUp=63014000

   Bloco de código
   language java title ex: json no body collapse true
   { "invoice": [ { "stamp": "2020-11-19 13:44:42.480", "finalDocumentNumber": "0000000003", "AIDFNumber": "", "electronicKeyDocument": "", "identificationSituation": "00", "federativeUnitOrigin": "SP", "shippingIndicator": "1", "valueOfGoods": 9000, "valueOfServices": 0, "documentType": "00", "fiscalDocumentDate": "15/10/20", "insuranceAmount": 0, "documentValue": 9000, "placeOfDelivery": "", "freight": 0, "untaxedAllowanceAmount": 0, "taxDocumentIssuer": "0", "taxDocumentSeries": "1", "valueReducedISSMaterials": 0, "modelIdentificationCode": "55", "participatingCode": "CSP000101", "taxDocumentNumber": "00000000", "typeOfPayment": "1", "amountOfAccessoryExpenses": 0, "discountAmount": 0, "operationType": "1", "taxDocumentEntryAndExitDate": "15/10/20", "otherExpenses": 0, "fiscalDocumentItems": [ { "itemNumber": "0001", "cfopIndicator": "5933", "itemAdditions": 0, "originIdentCode": "1", "operationNature": "503", "accountingValue": 6000, "socialSecurityExemption": "2", "itemAmount": 1, "itemValue": 6000, "discountValue": 0, "physicalMovement": "", "itemTotalValue": 6000, "acessoryExpense": 0, "unitOfMeasurement": "UN", "itemCode": "ISS", "serviceCode": "", "cityServiceCode": "", "serviceType": "", "dipamCode":"" } ] } ] }

3. Definimos que a tabela de log de erros será gravada nas integrações via REST para todas as validações necessárias, as mensagens precisam ser criadas a nível de usuário, sem nenhum detalhe técnico com relação ao erro encontrado.
   
   
4. Criar o mecanismo de integração via REST para as linhas e via função para o Protheus (item deve ser alinhado com a etapa de integração do ERP Protheus).
   
   
5. Layout Integrado na tabela específica do TAF.

OPEN API

Aqui serão catalogadas e disponibilizadas as APIS construídas para os nossos clientes.

Implementar a estrutura para a documentação do API.TOTVS.COM.BR. Utilizar o cost center como exemplo.

*Ainda não publicar mas ao final da entrega iremos sim publicar a API para uso dos clientes;

Poderá ser feito com o openAPI Preview in Browse ou com o swagger.

• Baixar o TTalk
  https://github.com/totvs/ttalk-standard-message
  cd C:\api
  git clone https://github.com/totvs/ttalk-standard-message.git

• TTALK STANDARD MESSAGE
  renomear para standard-message (constará uma pasta 1xAPI 1xSchemma)
  
  
• instalar (no terminal -->  npm install )

• Baixar tafintegrationservices_1-000j.json e TafIntegrationService_v1_000.json (estão anexos a issue de cada leiaute).
  Importante renomear com "_1"
  → tafintegrationservices_1-000j.json  em schemas → C:\api\standard-message\jsonschema\schemas
  → TafIntegrationService_v1_000.json em apis → C:\api\standard-message\jsonschema\apis

• baixar plugin x vs ( openapi-designer )
  
  
• Mudar referencia por causa do preview, alterar no v1
  de ./jsonschema/schemas
  para ../schemas
  Salvar
  
  
• ctrl + shift + P ( openApi Preview In Browse )
  Image Added
• Posicionar no V1
  Voltar o v1 para ./jsonschema/schemas
  de ../schemas
  para ./jsonschema/schemas
  Salvar
  
  
• executar npm run test
  de 32655 passing (2m)
  para 32656 passing
  
  
• Verificar se existe branch e subir, exemplo: oficial (master), homologação em definição*.

Dependência de Fontes

Lista dos fontes que não estão pasta $/Protheus_Padrao/Fontes_Doc/Master/Fontes/TAF/Integração/TSI do TFS mas foram alterados para o TSI.

Processos

Estrutura HashMap

O hash é montado nos fontes que constam na pasta TAF\Integração\TSI\TAF (API TSI).
Para cada pai, possuímos o hash com informações genéricas para auxiliar na gravação do modelo.
Para cada tabela possuímos um hash com o "de/para" ( Tag x Campo).
Todos os hashs são estáticos, ou seja a estrutura é montada apenas no início do chamado do programa.

• Exemplo de Informações Genéricas
  
  HMSet( oHash, 'm_o_d_e_l_' , 'TAFA062' )
  HMSet( oHash, 'm_o_d_e_l_C_2_0_', 'MODEL_C20' )
  HMSet( oHash, 's_o_u_r_c_e_' , 'TAFA062' )
  HMSet( oHash, 'a_r_e_a_' , 'C20' )
  HMSet( oHash, 'o_r_d_e_r_' , 1 )
  HMSet( oHash, 'k_e_y_' , cKey )
  HMSet( oHash, 's_e_e_k_' , cSeek )
  HMSet( oHash, 't_a_g_i_d_' , 'invoiceId' )
  
  Para cadastros ou movimentos, na estrutura pai, filho e neto, existem as tags de o model, submodel e submodel2, exemplo na utilização da apuração de ICMS:
  
  HMSet(oHash, 'm_o_d_e_l_' , 'MODEL_C2S')
  HMSet(oHash, 's_u_b_m_o_d_e_l_' , {{'MODEL_C2T'/*model filho*/,'adjustmentApuration' /* tag filho*/, 'HashC2T()' /* hash filho*/ }} )
  HMSet(oHash, 's_u_b_m_o_d_e_l_2' , {{'adjustmentApuration'/* tag filho*/,'MODEL_T02'/*model neto*/,'accumulatedAdjust'/*tag neto*/, 'HashT02()' /*hash neto*/}} )
  
  
• Exemplo com "de/para"
  
  Apenas o campo:          SetHashKey(oHashC20, "taxDocumentNumber"   ,"C20_NUMDOC" )
  
  Com consulta padrão:  SetHashKey(oHashC20, "participatingCode"         ,"C20_CODPAR#F3##F3#")
  
  Tipo data:                      SetHashKey(oHashC20, "fiscalDocumentDate"      ,"C20_DTDOC#DT##DT#" )