IN CIGAM Integrador

De CIGAM WIKI
Revisão de 20h56min de 30 de novembro de 2022 por Elizama.Dias (discussão | contribs) (→‎Genérico)

Voltar
Integrador > Integrador padrão

Quando as aplicações estiverem obtendo dados do CIGAM via consumo do respectivo serviço ou da respectiva camada de objetos de banco de dados, os parâmetros de data e hora do controle de gravação dos registros serão solicitados. Dessa forma se torna possível filtrar os registros de acordo com a data e hora em que estes sofreram alterações. Quando não informados, todos os dados do respectivo cadastro serão retornados. Nenhum controle por flag de leitura ou de integração será controlado pelo CIGAM e caso seja necessário, tal controle será feito pelos aplicativos dos terceiros em suas tabelas.

Para integração deve-se informar parâmetros para a chave-única do cadastro para que se possa obter dados de apenas um registro (quando informado). O controle de acesso se feito através do parâmetro para a informação do PIN (que será detalhado mais adiante).

Quando as aplicações de terceiros estiverem enviando dados para o CIGAM, tais dados serão inseridos na tabela de integração caso tenham sido aceitos. A importação/processamento somente será feita quando o programa específico da Aplicação de Importação for executado. Caso o dado não seja aceito, nenhum registro será inserido na tabela de integração e apenas a mensagem de erro (com código do erro e descrição) será enviada ao chamador.

Para controle de existência de registros as camadas de consultas irão disponibilizar uma lista com todos os registros cadastrados na tabela. Essa lista conterá somente os campos chaves e com ela será possível que a aplicação do terceiro compare com sua base cadastrada para saber quais registros foram excluídos.

Caso a tabela tenha um grande número de registros ou se existem muitas exclusões, poderá ser criada uma trigger a qual consome o respectivo serviço a cada exclusão (cabe lembrar que a utilização de triggers interfere na performance da aplicação agravando-se ainda mais quando utilizada por requisições de webservices).

Serviços disponíveis

Compras

Configurador

Estoque

Faturamento

Financeiro


Genérico

Materiais

Estrutura dos registros

A tabela de integração deve receber os registros a serem importados pelo CIGAM. Nessa tabela, todos os tipos de cadastros serão incluídos e um campo ‘Tipo’ irá identificar o tipo de registro/rotina que irá fazer a importação.
   Exemplo:
      MATCAD Cadastro de materiais
      EMPCAD Cadastro de empresas

Essa tabela tem um grande número de campos para contemplar qualquer tipo de cadastro do CIGAM. Somente os campos de ID e tipo serão indexados.
A camada de serviços é a porta de entrada para as integrações. Existirá um serviço para cada tipo de cadastro/registro. Nesse serviço, além dos parâmetros necessários, existirá também o parâmetro PIN que identificará o usuário/aplicativo que está fazendo a requisição.
Existirá um campo para controle do status do registro na tabela de integração. Esse controle será feito no registro máster quando houver relacionamento máster detalhe. Esse controle é necessário para que somente seja importado o relacionamento inteiro e evite que o programa de importação execute um ciclo exatamente no momento em que os dados estejam sendo inseridos na tabela de integração. Logicamente, o status do registro máster será liberado somente após todos os registros de detalhe terem sido incluídos. Também existe a estratégia que o programa que faz a importação sempre inicie pelo registro máster, e nesse caso, inserindo-o por último na tabela de integração, também será garantia de integridade.
Existirá um webservice para listagem da tabela de integração que permitirá a filtrar a consulta por ID da tabela, data da inclusão do registro ou por tipo do registro e ou ambos. Essa consulta auxilia as aplicações de terceiros a controlarem se tal registro integrado já foi importado.

Validação de parâmetros

No momento da requisição do serviço, caso haja algum parâmetro definido como obrigatório e não informado, é retornada uma mensagem de erro com o nome do parâmetro. Caso tenha mais de uma ocorrência, os demais nomes de parâmetros também serão listados.
Para parâmetros que possuem dependência de outro parâmetro, é exibido um asterisco (<*>) após o nome.

Tabela de integração e log

   Nomes-lógicos: GEINTEGRADOR (integração) e GEINTEGRADORLOG (log)

Todas as alterações de dados requisitadas para o CIGAM ficarão na tabela de integração até seu processamento pela Aplicação de Integração. Sempre que uma das camadas alterarem os dados dessa tabela será adicionada uma linha da tabela de log.
Como a tabela de integração e log possuem campos com nomes genéricos a qualquer cadastro ou rotina do CIGAM, a consulta bem como a inclusão de dados deverá ser feita pelas respectivas camadas as quais apresentarão os nomes dos campos adequadamente.
As tabelas de integração e log ficarão em um banco separado. Esse banco será acesso pelo Database CIGAM_INTEGRA em aplicações do CIGAM e pela Aplicação de Integração (componente CGIntegrador.ecf)
Se o banco de dados for diferente ao utilizado pelo CIGAM (inclusive se mudar apenas o database/usuário), deve-se informar uma connection string chamada INTEGRACAO no arquivo de configuração.

Também deve ser informado o banco de dados nessa nova conexão no parâmetro providerName.
   Exemplo:
       <add name="CIGAM" connectionString="Server=servidor;Database=BD;User ID=USER;Password=SENHA;
       <add name="INTEGRACAO" connectionString="Server=servidor;Database=BD;User ID=USER;Password=SENHA;" providerName="02"/>

O código de banco de dados do CIGAM deve ser informado na configuração BANCO_DADOS da aplicação.
   Exemplo:
      <add key="BANCO_DADOS" value="03" />

Registros correlatos

A tabela de integração poderá ter registros correlatos pendentes de importações, como por exemplo, pedidos versus itens versus grade do item. Neste caso quando o pedido for importado será feita uma verificação se existem itens para esse pedido. Da mesma forma, quando o item do pedido for importado será verificado se existe grade do item. Nesse ponto, somente os registros com status liberado serão avaliados e importados/recursados.
Os registros correlatos que não estão liberados, não serão tratados e, portanto jamais serão reavaliados. Para evitar registros perdidos na tabela de integração, será executada uma rotina de limpeza que irá excluir os registros com ID correlato cujo registro máster não esteja mais pendente de importação. Essa exclusão registrará um log específico.

Segurança

Não será utilizado o cadastro de usuário nem de direitos do CIGAM, até porque as aplicações de terceiros não podem controlar adequadamente esses dados.
O PIN irá identificar quem está fazendo a requisição e deve estar inserido no arquivo de configurações do ambiente do Web Service (seção <appSettings>).
Conforme exemplo abaixo, as requisições com o PIN <XW@#25Qo> podem utilizar os serviços ‘CADMAT’ e ‘CADEMP’. Os demais <@#0Q1o2>, <W#12@Abfg> e <20020004> podem utilizar todos os serviços, pois não há restrição atribuída a eles.

  • Exemplo:
    • <appSettings>
    • <add key="pin" value="XW@#25Qo;@#0Q1o2;W#12@Abfg;20020004"/>
      • Indicado que o valor do pin tenha uma complexidade alta devido manter a sergurança de transição dos registros
    • <add key="XW@#25Qo" value="CADMAT;CADEMP"/>


Requisição e resposta dos Webservices

Serão suportadas as tecnologias SOAP e Rest/JSon sendo que nessa segunda opção os parâmetros devem ser enviados por POST e o nome do método junto na URL. As respostas dos serviços também estarão disponíveis nessas duas tecnologias.
Quando o retorno contiver mais de um registro, a exportação será feita com duas coleções (objetos), uma para as colunas e outra para os dados. Neste caso as colunas ganham cabeçalhos nomeados para referenciar os dados (c1, c2...).
A opção EXPORT_HEADERS pode ser inserida no arquivo de configurações do ambiente do Web Service (seção <appSettings>) para indicar se a exportação deve ocorrer sempre usando os cabeçalhos ou não, independentemente da quantidade de registros.
    Exemplo:
       <appSettings>
       <add key="EXPORT_HEADERS" value="N"/>
É possível incluir no arquivo Settings.
Quando o nome da coluna da tabela no banco de dados for diferente do nome utilizado no CIGAM/CGData, na coleção dos nomes de colunas existirá uma tag com essa identificação.
Não serão exportados campos ainda não nomeados (exemplo: Campo31, Campo32...). Exceção: Campos de usuário que são os iniciados com nome <Usr>.
No formato JSON será necessário atributar ambas as propriedades, pois não há como colocar um valor para a tag principal como no XML. Neste caso, o apelido da coluna deverá ficar na tag <db_alias>.
Como primeiro nó da árvore, em ambos os formatos será utilizado o valor da tradução do Nome Lógico da tabela exportada. As colunas serão agrupadas na coleção <col> e os campos de cada registro na coleção <reg>. Os dados serão formatados com decodificação UTF-8.
    Exemplos de resposta:

XML JSON 
<esmateri>
      <col>
         <cd_material>c1</cd_material>
         <descricao>c2</descricao>
         <valor_imposto>c3</valor_imposto>
      </col>
      <reg>
         <c1>001</c1>
         <c2>Material Teste 1</c2>
         <c3>10</c3>
      </reg>
      <reg>
         <c1>002</c1>
         <c2>Material Teste 2</c2>
         <c3>20</c3>
      </reg>
   </esmateri>







{
       "col": [
      {
          "cd_empresa": "c1",
          "descricao": "c2",
          "valor_imposto": {
          "db_column": "campo3",
          "db_alias": "c3"
       }
     }
     ],
       "esmateri": [
       {
          "c1": "001",
          "c2": "Material Teste 1",
          "c3": "10"
       },
       {
          "c1": "002",
          "c2": "Material Teste 2",
          "c3": "20"
     }
     ]

Existe um validador para o padrão JSON em http://jsonlint.com

Tipos especiais

Alguns dados terão formatos especiais na requisições e respostas.

Tipo do dado Formato Máscara Exemplo Onde
Data XML DateTime (conforme ambiente em que o Serviço está rodando) 01-jan-2013 Requisição
Data XML dd/mm/yyyy 01/01/2013 Resposta
Data JSON dd/mm/yyyy

ou

dd-mmm-yyyy		 01/12/2013

ou

01-dec-2013		 Requisição e Resposta
Booleano XML Bool (conforme tipagem) True Requisição
Booleano XML True

ou

False		 True

ou

False		 Resposta
Booleano JSON TRUE,True,true

ou

FALSE,False,false		 True

ou

false		 Requisição
Booleano JSON True

ou

False		 True

ou

False		 Resposta
Time XML e JSON 161050 161050 Requisição e Resposta
Numéricos XML e JSON Sem separador de milhar e com ponto (“.”) como separador decimal 150

120.00

1250.33222		 Requisição e Resposta

Quando utilizar o formato XML, os valores enviados para parâmetros de tipos especiais, no serviço SOAP o próprio serviço garante o dado de entrada correto. Quando exportado irá seguir conforme a tabela anterior.
Quando utilizar o formato JSON, para os campos do tipo data o dado terá que vir no formato conforme a tabela anterior e para campos do tipo booleano terá que vir um “true” (não importando a capitalização) para que seja verdadeiro, pois para qualquer outra coisa será considerado como falso.

Para campos de dados do tipo hora, terão o dia com 24 horas e sem dois pontos “:” (HHMMSS)

Configurações especiais do banco de dados

Para que os serviços acessem corretamente os dados do tipo Date e DateTime, é obrigatório que a sessão com o banco de dados permita a informação de filtros por datas no formato americano “dd-mmm-yyyy” Exemplo: 01-jan-2013, 20-feb-2013 e 12-oct-2013. Para bancos de dados SQLServer essa parametrização já vem por padrão.
Para bancos de dados Oracle esse parâmetro pode variar de acordo com o idioma do Sistema Operacional no momento da instalação. Neste caso, verifique se o parâmetro de sessão “nls_language” está definido como “AMERICAN”. Esse valor pode ser ajustado no Registro do Windows para que todas as sessões sejam inicializadas dessa forma. Observar também se o Web Server que hospeda os serviços está com o modo 32bits/x86 habilitado, pois neste caso também é necessário ajustar os “nls_language” do Client32 do Oracle.

Log

A tabela de log é praticamente uma cópia da tabela de integração com a adição dos campos para a data e hora da ocorrência/execução. O processo de criação e registro dos Logs será feito da seguinte forma:

  1. O Webservice recebe a requisição e verifica se todos os parâmetros são válidos. Caso não sejam, retorna um erro ao usuário e não registra qualquer tipo de inserção na tabela de integração ou de log.
  2. Se os parâmetros passados para o webservice forem válidos, insere na tabela de integração, retorna uma mensagem e sucesso ao usuário sem registrar log.
  3. Quando o programa da aplicação de integração executar e importar o registro da tabela de integração, o log é criado com os dados importados (inclusive o usuário logado no CIGAM que fez a importação). Após isso, o registro da tabela de integração será apagado.
  4. No log é um campo para saber se o registro foi importado ou recusado. Caso recursado, armazena também o código e a mensagem de erro. Isso se faz necessário para que os registros com erro não fiquem na tabela de integração.

  5. Após liberar os registros pendentes será registrado log. Se tentar liberar um registro inexistente será retornado um erro e não será registrado log. Não será testado se está sendo liberado um registro já liberado pois teria também que ser feito um controle para a liberação dos correlatos.


Em Genéricos/Pesquisas/Rotinas existe uma tela on-line para que o usuário/administrador/DBA possa visualizar a tabela de Log.
A tabela de log não é indexada para ganho de performance. Se a tabela do log for grande, poderão ser criados os índices de acordo com as necessidades.
Não é gerado log sobre as consultas de dados efetuadas.

O log poderá ser limpo ou mantido apenas “n” dias conforme a necessidade do administrador do banco de dados (a limpeza será manual por segurança).

Aplicação de Integração

A camada de serviços e ou de banco de dados garantem “apenas” que o dado chegue até à tabela de integração. A importação dos dados é feita por um programa específico da aplicação de integração chamado Integrador.

Ao indicar statusRegistro igual a pendente o registro enviado não será integrado ao ERP CIGAM até que tenha seu status igual a liberado. Sendo possível sua liberação através do método LiberarPendentes. Também é possível criar o registro com o status Liberado sem a necessidade de requisitar um novo método para liberação.

Utilizando o retorno dos Serviços

Xml

Os serviços que utilizam o protocolo SOAP, tem como retorno uma String no formato Xml, para melhor visualização destes dados, está disponível na classe “Xml”, do namespace Cigam.Utils, um método estático chamado “XmlStringToDataTable”. Este retorna um objeto do tipo System.Data.DataTable. Segue abaixo um exemplo de implementação.

Exemplo 1

Também pode ser utilizada a classe XmlDocument, do namespace System.Xml para fazer a manipulação dos dados. Segue abaixo um exemplo de implementação.

Exemplo 2

Json

Os serviços que utilizam o protocolo REST, tem como retorno uma String no formato JSon, para trabalhar com estes dados, está disponível a classe “JSonDocument” no namespace Cigam.Utils. Esta classe fornece a interpretação da string retornada além de propriedades e métodos para manipulação dos dados. Seguem abaixo exemplos de como instanciar e alimentar a classe.

   Exemplo 1:
Exemplo 1

   Exemplo 2:
Exemplo 2

   Exemplo 3:
Exemplo 3

Esta classe também fornece uma propriedade contendo uma lista genérica que guarda objetos do tipo Cigam.Utils.JSonObject, e esta lista fornece informações sobre os registros da consulta, como o nome da coluna e o valor. Através desta classe também é possível obter o nome original das colunas, caso a consulta possua um cabeçalho de apelidos, ou saber se a consulta retornou exception, success ou query. Veja os exemplos abaixo:
   Exemplo 1:
Exemplo 1
   Exemplo 2:

Exemplo 2

Disponível em "https://www.cigam.com.br/wiki/index.php?title=IN_CIGAM_Integrador&oldid=86534"