Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Integração

A integrão é uma tela específica criada a partir do CRUD para que seja possível realizar integração, onde o dado é alterado para um status final onde um sistema de terceiro obtenha esses dados, por exemplo, faturamento de horas, atividades trabalhadas e etc.

Pré Requisitos

Configuração na DS Tabela Campo

Ter feito a configuração na nfs_core_ds_tabela, nela definimos em qual tela (CRUD) que será realizada a integração, geralmente são nos dados que voltam para o cliente como: OS, Boletim, Apontamento etc.

O JSON a seguir deve ser configurado na coluna OPTIONS da tabela nfs_core_ds_tabela, no exemplo, vamos supor que a integração é feita na tabela de OS (APP_OS):

{
  "favorite_name": "OS", // Não faz parte da Config. de Integração
  "favorite": true, // Não faz parte da Config. de Integração
  "integration": [
    {
      "text": "Liberar OS para realizar nova integração com o sistema ERP",
      "icon_class": "fa fa-eject",
      "field_status": "PROC_ST",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": { // Chave filter responsável por filtrar os dados que serão exibidos
        "field": "PROC_ST",
        "value": 4,
        "text": "Selecione a(s) OS(s) que já foram integradas e serão liberadas para novo processo de integração"
      },
      "action": { // Ações que vão ser executadas
        "updates": [
          {
            "field": "PROC_ST", // Coluna para ser alterada
            "value": 0 // Valor final da coluna
          },
          {
            "field": "RO",
            "value": 0
          },
          {
            "field": "PROC_REINTEGRACAO",
            "value": "1"
          },
          {
            "field": "PROC_DESC",
            "value": "OS foi liberada para novo processo de integração"
          },
          {
            "field": "PROC_DH",
            "value": "CURRENT_TIMESTAMP" // Constante dessa tela de integração para obter a data que foi feita integração
          }
        ],
        "text": "Mudar o status dos registros selecionados para 0",
        "text_button": "Executar processsamento",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "before_integration": { // Importante, é um status temporário usado no tipo batch e batchWithEntryPoint para filtrar somente os dados nesse status;
          "PROC_ST": 2,
          "PROC_DESC": "OS em processo de integração",
          "PROC_DH": "CURRENT_TIMESTAMP"
        }
      }
    }
  ],
  "icon": "fa fa-upload"  // Não faz parte da Config. de Integração
}

Field Action, botão que leva para integração

Para mostrar na tela o botão que vai enviar para integração de OS é necessário se utilizar de outra funcionalidade chamada Field Action, onde torna possível a adição de botões na listagem no CRUD e comumente usada na integraão

Configuração Field Action

INSERT INTO nfs_core_ds_field_action (`TABELA`, `DESCRICAO`, `CONFIG`,  `INS_DH`, `ATIVO`, `DELETED`, `NAME`) VALUES('OS', 'Ação de Integração de OS', '{
    "url": "/t/os?p1=proc_st&v1=4&c1=eq&v1r=Selecione a(s) OS(s) que já foram integradas e serão liberadas para novo processo de integração&integration=0&desc=''Teste''",
    "text": "Integração",
    "icon_class": "fa fa-eject",
    "button_class": "btn-lg btn-default ajaxify tooltips",
    "tooltip":"Liberar os para integração"
}', '2019-07-30 18:42:56.000', 1, 0, NULL);

O Importante é na URL no parâmetro integration, que vai pegar a primeira configuração na chave integration que configuramos na ds_tabela_campo, porque é possível ter mais de um integração, então se tivesse duas configurações uma para OS Faturamento e outra para OS Finalizada, no caso da OS Finalizada esse parâmetro iria mudar para ...&integration=1&desc='Teste 2'.

Tipos de Integração

A integração foi segmentada em três partes de acordo com uma análise interna. Para todos eles a chave importante que vai dentro da chave action é update_type: "batch|eachRow|batchWithEntryPoint"

Com excessão do tipo batchWithEntryPoint que vai ter uma chave a mais que é custom_entry_point, com o entrypoint a ser executado.

Batch

integracao_batch.png

O que já é usado em boas parte dos clientes e o PADRÃO, no caso o usuário executa uma ação na tela que altera todos os dados para um determinado status temporário configurado, depois o scheduler pega todo mundo que está com o status temporário e altera para o definitivo realizado todas as instruções necessárias, como rodar o entry point, salvar no histórico de alteração e etc. O seu objetivo é não travar a tela do usuário e executar no plano de fundo.

{
  "id-control": "fixed", // Não faz parte da Config. de Integração
  "id-value": 9999, // Não faz parte da Config. de Integração
  "menu_name": "Suportes (EIT)", // Não faz parte da Config. de Integração
  "integration": [
    {
      "text": "PCP Aprovar",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "PCP Aprovar",
        "value": " STATUS IN (2, 9)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "12",
          "PROC_DESC": "Liberado para Aprovação do PCP",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "PCP Aprovar",
        "text_button": "Aprovar",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "update_type": "batch" // Importante da configuração
      }
    }
  ]   
}

Tela de OS

  1. Na tela de OS é selecionados todos os itens que desejam ser integrados ou estornado com status da os com valor da PROC_ST definido no filter, definido na tela de integração:

Selecionar itens para enviar para integração com mais de uma condição

Também tem a opção de ter mais de uma condição para enviar para integração, o comum é enviar todos os registros com PROC_ST igual a 0, igual na nessa configuração:

"filter": {
  "field": "PROC_ST",
  "value": 0,
  "text": "Selecione a(s) OS(s) que já foram integradas e serão liberadas para novo processo de integração"
}

Porém há casos que deve haver mais de uma condição para isso utilize a seguinte configuração:

"filter": {
  "field": "sql_condition",
  "text": "Liberar boletim para integração",
  "value": " PROC_ST = 0 AND  FIM_DH IS NOT NULL ",
  "description" : "Não integrado e fechado"
}
  • sql_condition: É uma variável do NFS, usando ela o core vai identificar no value será passado uma condição.
  • description: É uma descrição das condições que vai aparecer junto com o botão que executa o processamento.
  • value: Outro ponto importante é que no value tem que passar uma condição para ser um usado no where para obter os registros que serão integrados, no caso PROC_ST = 0 AND FIM_DH IS NOT NULL.

Por padrão as variávies de integração são PROC_ST, PROC_DESC e PROC_DH, porém se em outro sistema ser diferente (igual BEVAP) é possível declarar-las da seguinte forma no JSON da coluna OPTIONS da nfs_core_ds_table:

"field_status" : "INTEGRA_ST",
"field_description": "INTEGRA_DESC",
"field_date" : "INTEGRA_DH",

A coluna OPTIONS que possui o json de configuração foi adicionada as seguintes opções dentro da chave action:

"before_integration": {
   "PROC_ST": 2,
   "PROC_DESC": "OS em processo de integração",
   "PROC_DH": "CURRENT_TIMESTAMP"
}

  1. Ao executar a ação todos os dados selecionados passaram para o status de integração configurando dentro do before_integration na chave PROC_ST conforme foi marcado no json abaixo, nisso também será salvo o usuário que fez essa ação, além do horário e uma descrição.

  2. O próximo passa a ser feito é a configuração de uma scheduler para fazer a integração de todos os dados que foram marcados com valor 9 na PROC_ST no passo anterior com o seguinte código na coluna CODE_ENTRY_POINT:

use scheduler\services\SchedulerIntegrationService;
// Tabela onde estao os dados para integracao
$tableName = 'os';
// Usuario da tabela de OS para ser salvo na execução da integracao
$columnUser = 'UPD_USUARIO_SEQ_DB' ;
// Valor temporario ques sera pego na tabela de OS para ser integrado
$status = 9;
$nameColumnStatus = "INTEGRA_ST";
SchedulerIntegrationService::makeIntegration($result, $tableName, $columnUser, $status, $nameColumnStatus);

Foi criado o método $makeIntegration na classe SchedulerIntegrationService para abstrair toda a lógica e complexidade na hora de configurar a rotina de integração no scheduler, ele tem os seguintes parâmetros:

  • $result - É um valor que sempre é necessário passar, é onde possui informações da empresa, filial, local da scheduler configurada.
  • $tableName - Nome da tabela onde é alterado o status para integração de terceiros.
  • $columnUser - A tabela configurada no item anterior deve possuir o seq_db do usuário que fez a integração.
  • $status - Valor do Status final para um sistema de terceiro buscar os dados no nosso sistema, por padrão é 2.
  • $nameColumnStatus - Nome da coluna que existe o status, como vimos no item 1 é possível que não seja PROC_ST, então deve ser passada nessa paramêtro;

Depois do scheduler configurado os dados vão ser obtidos de 100 em 100 com valor PROC_ST configurada dentro do before_integration e alterar para o valor final que é configurado dentro da chave updates no field PROC_ST e seu value que no exemplo é 0. Com isso ao salvar irá passar pelo processo de histório do usuário com essas alterações para que não seja perdido o seu histório, assim o Pentaho ou qualquer outro sistema de terceiro venha e capture esses dados para integração em seu sistema.

Primeiramente é os valores inseridos dentro de before_integration são alterados diretamente em cada registro. Já os valores inseridos dentro de updates, serão alterados somente se existir o scheduler com a função makeIntegration, são os valores:

  • CURRENT_USER_NAME: Nome atual do usuário
  • NFS_USER_EMAIL: E-mail do usuário logado no sistema
  • NFS_CURRENT_TIMESTAMP: Data atual do servidor
  • NFS_USER_TIMEZONE: Timezone do usuário

Each Row

integracao_eachrow.png

Um jeito mais simples, onde o usuário não precisa do scheduler porque os dados são poucos a serem integrados, a execução já acontece no momento da ação de integrar e já altera para o status final. Lembrando que é necessário configurar o a chave update dentro de action como está na documentação.

{
  "id-control": "fixed", // Não faz parte da Config. de Integração
  "id-value": 9999, // Não faz parte da Config. de Integração
  "menu_name": "Suportes (EIT)", // Não faz parte da Config. de Integração
  "integration": [
    {
      "text": "Limpar Programação ",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "Limpar Programação",
        "value": " STATUS IN (1, 4, 9)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "11",
          "PROC_DESC": "Liberado para Reprogramação",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "Limpar Programação",
        "text_button": "Limpar Programação",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "custom_entry_point": "reprogramacao_eng_suporte",
        "update_type": "eachRow"
      }
    }
  ]   
}

Batch With EntryPoint

integracao_batchwithep.png

Uma evolução do Batch, que ao invés de rodar um scheduler, é executado um custom_entry_point definido na action, o seu filer_or_domain vai ser igual a CUSTOM_ENTRY_POINT e o valor da coluna NOME que vai ser preenchida na configuração.

É necessário ativar uma parâmetro na nfs_core_par_parametros com o nome QUEUE_ENTRY_POINT e valor igual 1 e rodar o comando no Telegram para criar novos processamentos.

INSERT INTO nfs_core_par_parametros 
(EMPRESA, FILIAL, `LOCAL`, NOME, CONTEUDO, TIPO) 
VALUES (9999, 9999, 9999, 'QUEUE_ENTRY_POINT', '1', 1);

É criado processo para poder executar o entry point o mais rápido possível. Logo é enviado um processo para uma Fila no RabbitMQ para o Supervisor processar isso num processo isolado. Nome da Fila:

dominio_do_seu_cliente_entry_point

Que roda diretamente o entry que for configurado na integração e para isso foi criada um novo campo dentro do actions chamado custom_entry_point.

Exemplo:

{
  "id-control": "fixed", // Não faz parte da Config. de Integração
  "id-value": 9999, // Não faz parte da Config. de Integração
  "menu_name": "Suportes (EIT)", // Não faz parte da Config. de Integração
  "integration": [ 
    {
      "text": "Programar",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "Programar",
        "value": " STATUS IN (0, 7)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "10",
          "PROC_DESC": "Liberado para Programação",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "Programar",
        "text_button": "Programar",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "custom_entry_point": "programacao_eng_suporte", // Entry point chamado
        "update_type": "batchWithEntryPoint" // Tipo Importante
      }
    }
  ]   
}

Exemplo com os 3 tipos Juntos

Configuração na COLUNA OPTIONS da nfs_core_ds_tabela_campo

{
  "id-control": "fixed",
  "id-value": 9999,
  "menu_name": "Ordem de Serviço",
  "integration": [
    {
      "text": "Programar",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "Programar",
        "value": " STATUS IN (0, 7)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "10",
          "PROC_DESC": "Liberado para Programação",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "Programar",
        "text_button": "Programar",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "custom_entry_point": "programacao_eng_suporte",
        "update_type": "batchWithEntryPoint"
      }
    },
    {
      "text": "Limpar Programação ",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "Limpar Programação",
        "value": " STATUS IN (1, 4, 9)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "11",
          "PROC_DESC": "Liberado para Reprogramação",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "Limpar Programação",
        "text_button": "Limpar Programação",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "custom_entry_point": "reprogramacao_eng_suporte",
        "update_type": "eachRow"
      }
    },
    {
      "text": "Aprovar",
      "icon_class": "fa fa-upload",
      "field_status": "STATUS",
      "field_description": "PROC_DESC",
      "field_date": "PROC_DH",
      "filter": {
        "field": "sql_condition",
        "text": "Aprovar",
        "value": " STATUS IN (2, 9)",
        "description": "Pendente"
      },
      "action": {
        "before_integration": {
          "STATUS": "12",
          "PROC_DESC": "Liberado para Aprovação",
          "PROC_DH": "NFS_CURRENT_TIMESTAMP"
        },
        "text": "Aprovar",
        "text_button": "Aprovar",
        "error_message": "Erro ao atualizar",
        "success_message": "Valores atualizados com sucesso",
        "update_type": "batch"
      }
    }
  ]   
}

Queries do FIELD_ACITON e veja como é a Configuração Field Action porque também é necessário vincular ele a um grupo ou usuário para terem acesso.

INSERT INTO nfs_core_ds_field_action (`TABELA`, `DESCRICAO`, `CONFIG`,  `INS_DH`, `ATIVO`, `DELETED`, `NAME`) VALUES('OS', 'Ação de Programar OS', '{
    "url": "/t/os?p1=proc_st&v1=4&c1=eq&v1r=Selecione a(s) OS(s) que devem ser programadas&integration=0&desc=''Teste''",
    "text": "Programar",
    "icon_class": "fa fa-eject",
    "button_class": "btn-lg btn-default ajaxify tooltips",
    "tooltip":"Liberar os para integração"
}', '2019-07-30 18:42:56.000', 1, 0, NULL);


INSERT INTO nfs_core_ds_field_action (`TABELA`, `DESCRICAO`, `CONFIG`,  `INS_DH`, `ATIVO`, `DELETED`, `NAME`) VALUES('OS', 'Ação de Limpar', '{
    "url": "/t/os?p1=proc_st&v1=4&c1=eq&v1r=Selecione a(s) OS(s) para limpar sua programação&integration=0&desc=''Teste''",
    "text": "Limpar",
    "icon_class": "fa fa-eject",
    "button_class": "btn-lg btn-default ajaxify tooltips",
    "tooltip":"Liberar os para integração"
}', '2019-07-30 18:42:56.000', 1, 0, NULL);


INSERT INTO nfs_core_ds_field_action (`TABELA`, `DESCRICAO`, `CONFIG`,  `INS_DH`, `ATIVO`, `DELETED`, `NAME`) VALUES('OS', 'Ação de Aprovação de OS', '{
    "url": "/t/os?p1=proc_st&v1=4&c1=eq&v1r=Selecione a(s) OS(s) que já foram encerradas para aprovar sua integração&integration=0&desc=''Teste''",
    "text": "Aprovar",
    "icon_class": "fa fa-eject",
    "button_class": "btn-lg btn-default ajaxify tooltips",
    "tooltip":"Liberar os para integração"
}', '2019-07-30 18:42:56.000', 1, 0, NULL);