Integrador

De CIGAM WIKI
Revisão de 16h26min de 27 de maio de 2020 por Elizama.Dias (discussão | contribs)

Integrador > Integrador Padrão

O Integrador é a maneira oficial para que o CIGAM possa integrar-se com aplicativos de terceiros de maneira automática.
O Integrador contempla aqueles casos em que o processo de integração seja normal, ou seja, sem a necessidade de intervenções por customizações.
A ideia principal é disponibilizar um pacote (Kit) com a sua respectiva documentação de modo que não sejam necessários conhecimentos avançados ou técnicos para a implantação, treinamento e suporte.

Características Gerais

Abrangência

O Integrador disponibiliza os dados gerados no CIGAM para que aplicativos de terceiros possam ter acesso e usar essas informações conforme sua necessidade. Também é fornecida uma camada para que esses aplicativos de terceiros possam enviar dados para o processamento pelo CIGAM.
Quando o CIGAM receber dados, estes deverão estar íntegros a nível de tipagem para que sejam aceitos. A importação valida a regra de negócio e recusa os registros com problemas.
O CIGAM fornece os seus dados para outros aplicativos para que possam utilizá-los como desejarem. Em nenhum momento o CIGAM controla o status de integração com outros aplicativos.

Software e hardware necessário

Uma estrutura muito simples é suficiente para disponibilizar a camada de serviços para integrações. Poderá ser utilizado o Windows Server 2003 ou superior com IIS 6 ou superior. Contudo, a homologação do ambiente foi feita no Windows Server 2008 R2 com IIS 7 e portando esse é o ambiente indicado.
Em alguns casos, dependendo principalmente da versão do Windows Server utilizado, a configuração do IIS 6 acabou tornando-se mais trabalhosa devido a incompatibilidade dos demais serviços utilizados no mesmo servidor. Essa situação é contornada automaticamente com o uso do IIS 7, fazendo que não seja indicado o uso de versões do Windows Server que não suportam o IIS 7.
Para execução dos serviços será necessário também o Microsoft .Net Framework na versão 3.5 e o Asp.Net do servidor deverá suportar o modo compatibilidade 32 bits. O Provider (driver de acesso ao banco de dados) nativo do banco de dados também precisa estar instalado no servidor.
Ambientes com servidores Linux com Mono também torna-se uma possibilidade alternativa. Considerando as inúmeras distribuições do sistema operacional bem como as versões dos pacotes e incompatibilidades entre eles, nenhum desses ambientes foi homologado.
A nível de hardware a necessidade também é relativamente simples, considerando que a camada de serviços não irá manter sessão entre servidor e cliente, ou seja, a conexão é iniciada na requisição e encerrada após a resposta. Dessa forma, as configurações de hardware para o servidor precisarão ser avaliadas em função do número de requisições, número de rotinas utilizadas na integração e performance na execução da importação.

Estrutura de funcionamento

A camada de Web Services trabalha em conjunto com componentes do ERP CIGAM que possibilitam sistemas de terceiros realizarem consultas de modo síncrono e movimentações e cadastros de modo assíncrono, uma vez que as requisições precisam passar por regras de negócio antes de serem inseridas no sistema.
Funciona de forma passiva, os serviços entregam informações sempre que solicitado. Nos serviços de cadastros e movimentos registra o resultado da operação em uma tabela de log que pode ser consultada através de um programa no ERP e também através de serviços disponíveis na própria camada.
O Integrador deve contemplar os casos em que o processo de integração seja normal, ou seja, sem a necessidade de intervenções por customizações. Para estes casos, a necessidade de novos serviços deve ser avaliada pelas partes envolvidas.

  • A estrutura propõe as seguintes características:
  1. Camada de Webservices para que os aplicativos de terceiros possam obter os dados dos cadastros. Cada serviço terá seu nome intuitivo ao dado retornado e conterá a respectiva documentação (seja embutida ou não). Nessa camada não há qualquer processamento dos dados por parte do CIGAM, ou seja, apenas listagens.
  2. Camada de Webservices para que os aplicativos de terceiros possam enviar dados para uma rotina ou cadastro específico do CIGAM. Nessa camada os dados são pré-processados pelo CIGAM e retornado o status do aceite a nível de tabela de integração. Nesse caso, se o dado for inconsistente, um código de erro com uma mensagem será retornado ao chamador. Do contrário (caso os dados estiverem consistentes) o ID de integração será retornado para futuras conferências.
  3. Camada de objetos de banco de dados para uso alternativo a camada de Webservices. Essa camada possuirá as funcionalidades das duas camadas de Webservices listadas anteriormente. Cabe lembrar que o uso dessa camada é aconselhado somente em casos extremos (para maiores informações verificar com o Suporte Técnico do CIGAM).

Processamento dos dados

Quando as aplicações de terceiros 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).

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 será 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, será 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, será 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=10.200.0.42;Database=INFRA;User ID=TESTE;Password=ABYZ.;
       <add name="INTEGRACAO" connectionString="Server=10.200.0.42;Database=INFRA;User ID=TESTE;Password=ABYZ.;" 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 <001> podem utilizar os serviços ‘CADMAT’ e ‘CADEMP’. Os demais <002>, <003> e <004> podem utilizar todos os serviços, pois não há restrição atribuída a eles.
   Exemplo:
      <appSettings>
      <add key="pin" value="001;002;003;004"/>
      <add key="001" 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 <a class href="http://jsonlint.com/">http://jsonlint.com/</a>

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

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