Integração GET e INFO
A integração de GET e INFO são apresentadas ao mesmo tempo, pois são semelhantes uma a outra na configuração da integração. Somente em processos internos, execução de algumas regras e no retorno das informações é que existem algumas diferenças:
GET
Retorna para o usuário somente uma mensagem de sucesso ou erro e a natureza do erro ocorrido, especificando com mais detalhes nos logs, e um retorno quantitativo de quantos registros foram inseridos e atualizados na execução. Durante a execução as informações são transformadas em query, conforme parametrização, para execução no banco de dados do CRM, inserindo e/ou atualizando os dados.
INFO
Retorna para o usuário todos os dados processados durante a execução da integração em formato JSON, além da mensagem de sucesso ou erro, e nesse caso, a natureza do erro, apresentando mais detalhes nos logs.
Dicas de usabilidade
Ordenação para a criação da integração
Sugestão de ordenação para a criação da integração, cadastrando informações entre as tabelas conforme necessidade, para facilitar a compreensão e organização dos dados. Dessa forma há um loop entre as tabelas CAMPOS_INTEGRACAO, DEPENDENCIAS e REGRAS, para que a cada informação registrada em CAMPOS_INTEGRACAO seja verificado se há a necessidade de criar registros nas demais tabelas.
Valores das variáveis
Todos os valores variáveis são escritos na linguagem do Integrador, utilizando do símbolo #, no início e final do nome da variável. E, ao configurar os SQLs de consulta, inserção e atualização, o Integrador compila o texto exatamente como se fosse código. Desta forma, o valor pode estar dentro do texto contendo ou não aspas duplas ou simples. Por exemplo, SELECT * FROM contas WHERE id = ‘#id#’.
Ordem das integrações
Ordem que são dispostas as integrações na tabela INTEGRACOES faz diferença, então devem ser colocadas em uma ordem lógica, conforme estrutura do CRM.
Ordem dos índices
Ordem dos índices da string JSON no campo CAMPO_CRM da tabela CAMPOS_INTEGRACAO não faz diferença, porém deve-se manter a estrutura lógica.
Cadastro de integrações
Nível de customização no cadastro das integrações é grande, os SQLs presentes na tabela INTEGRACOES colunas CONSULTA, SQL_CONSULTA, SQL_INSERT e SQL_UPDATE podem ser complexos e mais de um, se necessário.
Nota
É possível executar integrações de diferentes tipos em dependência (GET + SET), porém é recomendado executar em dependência apenas integrações do mesmo tipo. Primeiramente é preciso configurar a conexão com o sistema a ser integrado, e em seguida configurar os módulos e os campos.
Tabelas
O Integrador possui uma estrutura de tabelas em banco de dados onde será possível cadastrar e configuraras integrações.
Campo | Descrição | Valores possíveis |
---|---|---|
TIPO_CONEXAO | Classifica a forma de conexão da integração. |
|
NOME_CONEXAO | Informa o nome da conexão salva no arquivo de conexões do cliente dentro dos arquivos do Integrador. Cada tipo de conexão tem um layout específico para configurar a conexão no arquivo. |
Campo | Descrição | Valores possíveis |
---|---|---|
NOME | Descrição da integração. Informação importante no caso da integração INFO, pois é o índice de retorno para se chegar nas informações integradas. |
|
TIPO_SERVICO | String que representa o tipo da integração a ser executada. | |
EMPRESA_ID/ EMPRESA_FILIAL_ID | Empresa a qual a integração está disponível. | |
LINK | String que informa endereço para conexão da integração, o complemento para se chegar a um determinado serviço, e pode ser NULO em alguns casos. |
|
TABELA | Tabela onde será executada a integração. | |
CONSULTA | Texto JSON que representa a consulta dos dados feita no sistema terceiro, o texto precisa conter uma chave ‘consulta’ para que o Integrador encontre a busca e o valor pode ser NULO em alguns casos. |
|
CONEXAO_INTEGRACAO_ID | Identificador que referencia a informação da tabela CONEXAO_INTEGRACAO. | |
PORTA_WS | Refere-se à porta para execução de um determinado serviço. Utilizado somente em integrações via web service. Essa informação pode ser encontrada na documentação do WSDL do sistema a ser integrado. | |
INDICE_ARRAY_RETORNO | Representa a chave do array de retorno onde estão os dados da pesquisa de valores a serem integrados. No caso da integração via web service esse valor consta na documentação, já via banco de dados, o valor informado será adicionado como primeiro índice do array retornado da consulta. Caso a requisição seja via Web Service ou API e não tenha um índice padrão para o retorno de valores, pode-se usar a palavra reservada ‘parameters’ como indice_array_retorno. | |
INDICE_VALOR_RETORNO | Índice que será pesquisado no array de retorno do envio de valor para o sistema terceiro (integração SET), para realizar ações após sucesso na integração. Valor não utilizado na integração GET ou INFO, seu valor deve ser NULL. | |
INDICE_ERRO_RETORNO | São os índices que serão buscados os erros no array de retorno das buscas executadas pelo Integrador, ou seja, se esses índices forem encontrados com valor, o Integrador interpretará a busca como ‘com erro’. O campo pode conter vários índices separados por virgula (não pode haver espaçamento entre os índices e a vírgula). Somente o primeiro índice da lista será utilizado como validador geral, ou seja, se o primeiro índice não apresentar erros, os demais não serão contabilizados. | |
SQL_CONSULTA |
SQL que será responsável por buscar o registro no CRM, no caso da integração INFO, ou validar se o mesmo existe, para o Integrador saber qual será o próximo passo, inserir ou atualizar o registro, no caso da integração GET. Para esse campo lembre-se da dica 2. Há duas variáveis que podem ser utilizadas #empresa_id# ou #empresa_filial_id#, quando o CRM do cliente é para múltiplas empresas, além das variáveis do Integrador, que contém todos os campos mapeados no DE-PARA dos campos do CRM e sistema terceiro, e está disposto da seguinte forma: #nome# |
|
SQL_INSERT |
SQL que será responsável por inserir um novo registro no CRM caso a busca feita pela coluna SQL_CONSULTA retorne false. Não esqueça da dica 2. Para montar a query de inserção, é habilitado a injeção de valores, então há duas variáveis que podem ser utilizadas #empresa_id# ou #empresa_filial_id#, quando o CRM do cliente é para múltiplas empresas, além das variáveis do Integrador, que contém todos os campos mapeados no DE-PARA dos campos do CRM e sistema terceiro, desde que estejam com o valor true (1) na coluna VALOR_GLOBAL da tabela CAMPOS_INTEGRACAO, além dos valores mapeados no DE-PARA formatados para o INSERT, sendo: #indices#: representa as colunas; #valores#: são os valores a serem inseridos; Ex.: (#indices#) VALUES (#valores#) |
|
SQL_UPDATE |
SQL que será responsável por atualizar um registro no CRM caso a busca feita pela coluna SQL_CONSULTA retorne true. Não esqueça da dica 2. Para montar a query de atualização, é habilitado a injeção de valores, então há duas variáveis que podem ser utilizadas #empresa_id# ou #empresa_filial_id#, quando o CRM do cliente é para múltiplas empresas, além das variáveis do Integrador, que contém todos os campos mapeados no DE-PARA dos campos do CRM e sistema terceiro, desde que estejam com o valor true (1) na coluna VALOR_GLOBAL da tabela CAMPOS_NTEGRACAO, além dos valores mapeados no DE-PARA formatados para o UPDATE, sendo: #valores#: representa as colunas igualada aos valores; #id#: retorna o valor consultado na coluna SQL_CONSULTA; Ex.: #valores# WHERE id = #id# |
|
DEPENDENTE | Informa que a integração atual depende da integração com o identificador informado e a mesma será executada antes. O valor informado é o identificador da tabela INTEGRACOES. | Pode conter valores NULOS. |
DEPENDE_DE | Informa que o valor cadastrado é uma integração que depende da integração atual e a mesma será executada depois. O valor informado é o identificador da tabela INTEGRACOES. | Pode conter valores NULOS. |
PARAMETROS_OBRIGATORIOS | Informa quais são os valores devem, obrigatoriamente, estar na URL da requisição da integração. Os parâmetros devem ser separados por vírgula e devem ser exatamente iguais aos parâmetros que serão passados pela URL. | Pode conter valores NULOS. |
- Campo id: 1
- Campo nome: GET-WS-CONTAS
- Campo tipo_servico: GET
- Campo empresa_id/empresa_filial_id: 1
- Campo link: /g5-senior-services/sapiens_Synccom_senior_g5_co_cad_clientes?wsdl
- Campo tabela: contas
- Campo consulta: {"consulta":{"user":"senior","password":"senior","encryption":0,"parameters":{"codEmp":"1","codFil":"1","identificadorSistema":"CRM","quantidadeRegistros":"500","tipoIntegracao":"#tipoIntegracao#"}}}
- Campo conexao_integracao_id: 3
- Campo porta_ws: Exportar
- Campo indice_array_retorno: cliente - em integrações via web service o valor dessa coluna precisa ser identico ao valor do web service
- Campo indice_valor_retorno: não utilizado
- Campo indice_erro_retorno: erro,mensagemErro,erroExecucao
- Campo sql_consulta: SELECT id FROM contas WHERE id_erp = '#id_erp#' INSERT INTO contas (empresa_id, #indices#) VALUES (1, #valores#)
- Campo sql_insert: INSERT INTO contas (empresa_id, #indices#) VALUES (1, #valores#) - essa coluna não é usada em integrações INF
- Campo sql_update: UPDATE contas SET #valores# WHERE id = '#id#' - essa coluna não é usada em integrações INF
- Campo dependente:1 - a coluna "dependente" precisa ser o id de uma integração válida, ou seja, o id de um registro válido da tabela INTEGRACOES
- Campo depende_de: 1 - a coluna "depende_de" precisa ser o id de uma integração válida, ou seja, o id de um registro válido da tabela INTEGRACOES
- Campo parametros_obrigatorios: codEmp,codFil,tipoIntegracao - em caso de multiplos parâmetros eles devem ser separados por virgula sem espaçamento
Campo | Descrição | Valores possíveis |
---|---|---|
INTEGRACAO_ID | Identificador que referência a informação da tabela INTEGRACOES. | |
CAMPO_CRM |
Representação do campo interno do CRM, pode somente ser preenchido no formato JSON, nele deve conter a referência a tabela (INDICE) e a coluna (ATRIBUTO) nesses casos diz que há somente um nível de profundidade, ex.: ‘{“indice”:”contas”,”atributo”:”razao_social”}’. Também há casos onde é necessário mais níveis para se chegar a um determinado valor, apresenta junções de tabelas (JOIN), onde o valor é originado em outra tabela, referência a tabela (INDICE) e a coluna (ALIAS) onde se busca a informação, e a tabela (INDICE) e coluna (ATRIBUTO) originais, e pode conter N níveis, ex.: ‘{“indice”:”contas”,”atributo”:{ ”alias”:”prazo_pagamento_id”,“indice”:”prazo_pagamento”,”atributo”:”id”}}’. Em casos como esse, onde há dois níveis, entende-se que há uma dependência a ser informada, ou seja, é preciso vincular a regra CONSULTAR DEPENDENCIA na coluna REGRA_ID e cadastra uma dependência na tabela DEPENDENCIA. Nos casos em que há somente um nível pode-se cadastrar registros onde o ATRIBUTO é uma palavra-chave ou variáveis de palavras reservadas ou das informações gravadas como valores globais na coluna VALOR_GLOBAL da tabela CAMPOS_INTEGRACAO, sendo: IGNORE: ignora esse campo ao executar a ação de salvar ou exportar; COMPONENTE: carrega um componente de integração, desde que tenha o mesmo no usado na coluna NOME_COMPONENTE; Ex1.: {“indice”:”conta”,”atributo”:”ignore:razao_social”}; Ex2.: {“indice”:”conta”,”atributo”:”componente:definicoes_conta”}; |
|
CAMPO_ERP |
Representação do campo externo do CRM (sistema terceiro), pode somente ser preenchido no formato JSON nele deve conter a referência a tabela (INDICE) e a coluna (ATRIBUTO) nesses casos diz que há somente um nível de profundidade, ex.: ‘{“indice”:”cliente”,”atributo”:”nomCli”}’. Também há casos onde é necessário mais níveis para se chegar a um determinado valor, apresenta junções de tabelas/informações (JOIN), onde o valor é originado em outra tabela/nível do array, referência a tabela/índice (INDICE) e o outro nível do array (INDICE) e o valor procurado (ATRIBUTO), e pode conter N níveis, ex.: ‘{“indice”:”contas”,”atributo”:{“indice”:”historico”,”atributo”:”codCpg”}}’. Nos casos em que há somente um nível pode-se cadastrar registros onde o ATRIBUTO é uma palavra-chave ou variáveis de palavras reservadas ou das informações gravadas como valores globais na coluna VALOR_GLOBAL da tabela CAMPOS_INTEGRACAO, sendo: VALOR: informa que a string a seguir é um valor fixo. Nesse caso é necessário informar a regra ADICIONAR VALOR FIXO na coluna REGRA_ID. No caso da adição de valor fixo é possível adicionar variáveis para serem substituídas por seus respectivos valores durante o processamento do campo. Estão disponíveis palavras reservadas (dataAtual, dataHoraAtual, etc) e valores da integração que estiverem informados como valores globais, para isso a variável deve estar entre # (#dataAtual#, #dataHoraAtual#, #etc#). Ex.: {"indice":"cliente","atributo":"valor:oportunidade gerada em #dataHoraAtual#"} |
|
REGRA_ID | Identificador que referência a informação da tabela REGRAS. | |
VALOR_GLOBAL | Booleano que permite o campo, se informado como true/1¸ salvar o valor e o nome do campo em um escopo global para que o mesmo possa ser acessado de qualquer outra integração, campo ou regra. | |
USE_INSERT | Booleano que permite ao campo, se informado como true/1, ser usado em uma operação de inserção no banco de dados do CRM. O campo somente é utilizado na integração GET. | |
USE_UPDATE | Booleano que permite ao campo, se informado como true/1, ser usado em uma operação de atualização no banco de dados do CRM. O campo somente é utilizado na integração GET. | |
PARAMETROS_ADICIONAIS |
Usado para passar diversos parâmetros para uma determinada regra durante o processamento do campo. Deve ser cadastrado somente strings no formato JSON. Pode conter valores NULOS. Ex.: {"data_format_erp":"Y-m-d"}; |
- Campo id: 897
- Campo integracao_id: 10
- Campo campo_crm: {"indice":"definicoes_conta","atributo":{"indice":"prazo_pagamento","alias":'prazo_pagamento_id","atributo":"id"}}
- Campo campo_erp: {"indice":"cliente","atributo":{"indice":"historico","atributo":"codCpg"}}
- Campo regra_id: 5
- Campo valor_global: 0
- Campo use_insert: 1
- Campo use_update: 1
- Campo parametros_adicionais: null
Campo | Descrição | Valores possíveis |
---|---|---|
INTEGRACAO_ID | Identificador que referência a informação da tabela INTEGRACOES. | |
TABELA | Tabela/view onde será buscada as informações para que os registros sejam comparados ao consultar as dependências durante o processamento dos campos. | |
COLUNAS_BUSCAR | Nome da coluna da tabela informada anteriormente que contém o valor desejado. Pode ser informado mais de um campo, basta serem separados por vírgula. |
|
COLUNA_COMPARAR | Coluna que contém o valor que será comparado com o retorno da consulta ao sistema terceiro. Tem seu funcionamento parecido com a clausula ON presente no JOIN de uma query. | |
VALOR_DEFAULT | Valor que é informado, para em casos não seja encontrado um registro com o valor informado na coluna COLUNA_COMPARAR, ele é inserido, para que o campo não seja vazio. O valor informado necessariamente tem que ser um identificador válido na tabela informada na coluna TABELA. Pode conter valores NULOS. | |
EMPRESA_FILIAL_ID | Identificador que referência a informação da tabela EMPRESA_FILIAL. Separa as dependências por empresa e filial permitindo valores diferentes conforme necessidade da filial. Essa informação é somente utilizada quando a base do cliente for para múltiplas empresas. |
- Campo id: 75
- Campo integracao_id: 8
- Campo tabela: usuarios
- Campo colunas_buscar: usuario_id,nome
- Campo coluna_comparar: usuario_id_erp
- Campo valor_defaut: 383
- Campo empresa_filial_id: 1
Campo | Descrição | Valores possíveis |
---|---|---|
NOME | Informa um descritivo da regra, o nome para identificar a regra. | |
TIPO_METODO | Responsável por informar ao Integrador como a regra é executada. |
0: executa uma função, somente chama o método passado por parâmetro na coluna METODO; 1: realiza a consulta de uma dependência, o método fixo, retornando o valor conforme configurado para. Caso tenha sido informado um método na coluna METODO, o mesmo é executado após a consulta da dependência; 2: adiciona um valor fixo, a regra interpreta o valor informado da coluna CAMPO_ERP, da tabela CAMPOS_INTEGRACAO, como sendo um valor de fato, não como uma chave da consulta. Caso tenha sido informado um método na coluna METODO, o mesmo é executado após o retorno do valor fixo; 4: carrega um componente, adiciona os valores a uma variável interna do Integrador para que o Integrador interprete o componente como uma integração, com suas particularidades, e quando o componente terminar sua execução, retorna os valores formatados para a integração principal; |
METODO | Método ou função que será executada quando ocorrer uma chamada à regra. |
SQL: uma consulta com alguma condição que retorna o valor desejado; ASSINATURA DE MÉTODO: uma chave que represente um método presente nos arquivos de regras do Integrador, regras gerais ou especifica de um cliente; NULL: pode conter valores NULOS. |
- Campo id: 26
- Campo nome: Carregar/Preparar Componente
- Campo tipo_metodo: 4
- Campo metodo: null