Data Import - Padrão Simova

Introdução

Esse módulo visa a Importação de Dados através de Planilhas preenchidas de acordo com os Templates fornecidos pelo próprio módulo.

Fique atento!

Todo processo se baseia nas definições da tabela "nfs_core_ds_tabela_campo";

Planilhas Compatíveis / Testadas: MS Excel / LibreOffice Calc;

Rotinas Executadas: Inserção / Atualização.

IMPORTANTE: Por se tratar de processo de importação, o processo depende do volume de dados importados e das configurações definidas para os processos PHP/NGINX. Nos scripts PHP o tempo de execução máximo é definido dinamicamente. No NGINX, requer a definição do parâmentro a seguir:{.is-danger}

# /etc/nginx/<dominio>
location ~ \.php(/.*)?$ {
   ...
   fastcgi_read_timeout 1500
   ...

Pré-requesitos

São pré-requisitos para esse módulo:

Permissão na tabela de rotas para /dataImport;
Tabelas "nfs_core_ds_import" e "nfs_core_ds_import_file" criadas na seguinte estrutura:

CREATE TABLE `nfs_core_ds_import` (
  `SEQ_DB` bigint(20) NOT NULL AUTO_INCREMENT,
  `TITLE` varchar(100) DEFAULT NULL,
  `CONFIG` varchar(4000) DEFAULT NULL,
  `INS_DH` timestamp NULL DEFAULT CURRENT_TIMESTAMP,
  `ENABLED` int(11) DEFAULT '1',
  `DELETED` int(11) DEFAULT '0',
  UNIQUE KEY `SEQ_DB_UNIQUE` (`SEQ_DB`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 ROW_FORMAT=COMPACT;

CREATE TABLE `nfs_core_ds_import_file` (
  `SEQ_DB` bigint(20) NOT NULL AUTO_INCREMENT,
  `EMPRESA` int(11) NOT NULL,
  `FILIAL` int(11) NOT NULL,
  `LOCAL` int(11) NOT NULL,
  `INS_DH` timestamp NULL DEFAULT CURRENT_TIMESTAMP,
  `INS_USUARIO_SEQ_DB` bigint(20) unsigned NOT NULL,
  `TABLENAME` varchar(60) DEFAULT NULL,
  `UPLOAD_SEQ_DB` bigint(20) unsigned DEFAULT NULL,
  `SIT_PROCESS` tinyint(1) NOT NULL DEFAULT '0',
  `JSON_STATUS` varchar(500) DEFAULT NULL,
  `REPORT_UPLOAD_SEQ_DB` bigint unsigned DEFAULT NULL,
  UNIQUE KEY `SEQ_DB_UNIQUE` (`SEQ_DB`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 ROW_FORMAT=COMPACT;

Configurações

Tabela nfs_core_ds_import

Possui as definições principais do ambiente, sendo:

TITLE: Título do ambiente;

TITLE='Importação de Dados'

CONFIG: Configuração do ambiente de importação;

{
  "TABELAS": ["TALHAO", "OPERADOR"],
  "COLUNAS": {
    "TALHAO": ["CODIGO", "DESCRICAO", "FAZENDA", "ATIVO"]
  },
  "KEYS": {
    "TALHAO": "CODIGO",
    "CLIENTE": "CODIGO",
    "FUNCAO": "CODIGO",
    "FAZENDA": "CODIGO",
    "SETOR": "CODIGO",
    "OPERADOR": "CRACHA"
  },
  "NOME_PLANILHA": {
    "OPERADOR": "OPER"
  },
  "CUSTOMIZATION": {
    "STANDARD_CELL_COLOR": "FF00FF00",
    "STANDARD_FONT_COLOR": "FF0000FF",
    "REQUIRED_CELL_COLOR": "FFFF0000",
    "REQUIRED_FONT_COLOR": "FFFFFF00"
  }
}

Onde:

TABELAS: lista de tabelas principais passíveis de importação. Também serão importados dados das tabelas relacionadas (os relacionamentos serão criados usando as colunas TIPO e LINK da tabela "nfs_core_ds_tabela_campo", sendo a coluna TIPO FK e a tabela relacionada a especificada na coluna LINK);
COLUNAS: lista as colunas que farão parte da importação (que estarão disponíveis no template quando este for baixado no módulo). Se este grupo não estiver presente será usada a regra disposta em ORIENTAÇÕES GERAIS desse documento;
KEYS: chaves de todas as tabelas envolvidas no processo de importação. A coluna especificada para cada tabela funcionará como chave primária, PK, durante o processo de importação, assim permitindo a devida criação das chaves estrangeiras, FK, nas rotinas de inserção/atualização;
NOME_PLANILHA: essa propriedade é usada como um apelido que para os nomes das planilhas dentro do arquivo;

O nome da planilha não pode ser maior que 31 caracteres. Para tabelas que possuem um valor maior que 31 caracteres essa configuração é obrigatória.
CUSTOMIZATION: possibilita a personalização do cabeçalho da planilha de importação de dados. A configuração deste item é opcional, quando utilizado permite que seja alterada a cor da fonte e a cor da célula dos campos presentes no cabeçalho, podendo por exemplo diferenciar visualmente campos obrigatórios de campos não obrigatórios.
- Parâmetros de customização: Todos os parâmetros são opcionais, podendo ser configurado apenas um ou todos eles, conforme necessidade. São eles:
  1. "STANDARD_CELL_COLOR": Cor da CÉLULA de campo NÃO OBRIGATÓRIO.
  2. "STANDARD_FONT_COLOR": Cor da FONTE de campo NÃO OBRIGATÓRIO.
  3. "REQUIRED_CELL_COLOR": Cor da CÉLULA de campo OBRIGATÓRIO.
  4. "REQUIRED_FONT_COLOR": Cor da FONTE de campo OBRIGATÓRIO.

Em caso de não adoção de um dos parâmetros, a configuração default é aplicada, onde a CÉLULA assume cor AZUL e a FONTE do texto assume cor BRANCA.

As CORES a serem utilizadas devem seguir o padrão HEXADECIMAL de 8 caracteres (incluindo os 2 primeiros dígitos de transparência, recomenda-se “FF” para 0% de transparência aplicada), e passadas em formato string sem o uso do caracter “#”, como no exemplo acima.

Chaves Composta e Relacionamentos LOVN!

Em alguns clientes/estrutura de dados, faz-se necessária a criação de chaves compostas por N Colunas. Para esses caso, as colunas devem ser separadas por ":" (dois pontos) na configuração da KEY usada para aquela tabela. Ao preencher a planilha com valores compostos, o caracter usado como separador será o "|" (pipe). Mais detalhes no exemplo a seguir.

Exemplo:

{
  "TABELAS": [
    "ESTADO",
    "OS",
    "OS_TECNICO",
    "STATUS_OS",
    "CLIENTE",
    "FUNCIONARIO"
  ],
  "KEYS": {
    "OS": "CODIGO",
    "OS_TECNICO": "OS:FUNCIONARIO",
    "STATUS_OS": "DESCRICAO",
    "CLIENTE": "CODIGO:LOJA",
    "FUNCIONARIO": "CRACHA",
    "ESTADO": "SIGLA",
    "FAMILIA_EQUIPAMENTO_GRUPO_PRODUTO": "FAMILIA_EQUIPAMENTO:GRUPO_PRODUTO"
  },
  "NOME_PLANILHA": {
    "FAMILIA_EQUIPAMENTO_GRUPO_PRODUTO": "FAMLIA_EQP_GRP_PRODUTO"
  }
}

Usando a configuração acima, o processo de importação usará os valores das colunas OS e FUNCIONARIO da planilha/aba OS_TECNICO para criar uma chave na tabela OS_TECNICO, que no caso seria o CODIGO da OS e o CRACHA do funcionário (sendo essa composição única na importação).

O preenchimento de valores compostos deve usar o pipe (|) como separador. Tomando como base o exemplo anterior, seria informado o valor da coluna CODIGO da aba OS e o valor da coluna CRACHA da aba FUNCIONARIO: "OO1|CRACHÁ 001".

2. Relacionamento LOVN

Para contemplar os relacionamentos LOVN, ao preencher a coluna desse relacionamento, informar os valores separados por ";" (ponto e vírgula).

Exemplo:

{
  "TABELAS": ["CHECK_GRUPO_QUESTAO", "CHECK_TIPO_RESPOSTA", "CHECK_QUESTAO"],
  "KEYS": {
    "CHECK_GRUPO_QUESTAO": "DESCRICAO",
    "CHECK_TIPO_RESPOSTA": "DESCRICAO",
    "CHECK_QUESTAO": "DESCRICAO",
    "EQP_CLASSE": "CODIGO"
  }
}

IMPORTANTE! Os relacionamento LOVN só serão deletados (ATIVO = 0, DELETED = 1) através desse módulo se a coluna que representa o(s) relacionamento(s) estiver preenchida com a tag LIMPAR_REGISTROS!

Tabela nfs_core_ds_import_file

Estrutura de dados criada para manter histórico de todos os processo executados, sendo:

TABLENAME: Nome da tabela principal;

MAIN_TABLE='TALHAO'

UPLOAD_SEQ_DB: SEQ_DB da tabela NFS_UPLOAD, responsável pelo armazenamento da planilha enviada;

UPLOAD_SEQ_DB=1

SIT_PROCESS: status do processo, sendo [0 = Criado, 3 = Iniciado, 5 = Concluído];

SIT_PROCESS = 0

JSON_STATUS: Status final do processo de importação [NULL || JSON];

{
  "ID": "1",
  "tabelas": {
    "CLIENTE": {
      "descricao": "Cliente",
      "importados": 2,
      "atualizados": 0,
      "erro": 0
    },
    "SETOR": {
      "descricao": "Setor / Regi\u00e3o",
      "importados": 5,
      "atualizados": 0,
      "erro": 0
    },
    "FAZENDA": {
      "descricao": "Fazenda",
      "importados": 4,
      "atualizados": 0,
      "erro": 1
    },
    "TALHAO": {
      "descricao": "Talh\u00e3o",
      "importados": 22,
      "atualizados": 0,
      "erro": 1
    }
  },
  "EXECUTION_TIME": 6
}

REPORT_UPLOAD_SEQ_DB: SEQ_DB da tabela NFS_UPLOAD, responsável pelo armazenamento da planilha com o resultado do processo de importação;

REPORT_UPLOAD_SEQ_DB=1

É necessário executar as consultas a seguir (seguindo a ordem e, ao executar as inserções 2, 3 e 4, substituir os SEQ_DB'S nas consultas seguintes).

-- 1. raiz do menu
INSERT INTO nfs_core_menu (EMPRESA, FILIAL, `LOCAL`, DESCRICAO, `TYPE`, ATIVO, FATHER, MENUORDER, URL, ICON) VALUES(1, 9999, 9999, 'Gerenciamento de Dados', 'MENU', 1, NULL, 998, '', 'fa fa-database');
-- 2. permissão para raiz
INSERT INTO nfs_acl_grupo_permissao (EMPRESA, FILIAL, `LOCAL`, MENU_SEQ_DB, TABELA_NOME, SIUD, GRUPO_SEQ_DB, CAMPOS_PERMITIDOS) VALUES(1, 9999, 9999, **SEQ_DB_RAIZ**, NULL, '1111', 1, '');
-- 3. item do menu
INSERT INTO nfs_core_menu (EMPRESA, FILIAL, `LOCAL`, DESCRICAO, `TYPE`, ATIVO, FATHER, MENUORDER, URL, ICON) VALUES(1, 9999, 9999, 'Importação de Dados   ', 'MENU', 1, **SEQ_DB_RAIZ**, 1, 'dataImport/', 'fa fa-database');
-- 4. permissão para item de menu
INSERT INTO nfs_acl_grupo_permissao (EMPRESA, FILIAL, `LOCAL`, MENU_SEQ_DB, TABELA_NOME, SIUD, GRUPO_SEQ_DB, CAMPOS_PERMITIDOS) VALUES(1, 9999, 9999, **SEQ_DB_ITEM_MENU**, NULL, '1111', 1, '');

Orientações Gerais

As Tabelas Principais são as especificadas na configuração;
Em Relacionamentos temos as Dependências, que são as tabelas com dados que serão usados no processo de importação. Esses dados são dispospos em Planilhas/Abas no template, e cada uma delas representa uma Chave Estrangeira (FK) para a Tabela Principal ou para outras Tabelas Relacionadas;
Em Relacionamentos temos os Complementos, que são tabelas com dados opcionais ao processo de importação. Esses dados são dispostos em Planilhas/Abas no template, e cada uma delas representa uma Chave Estrangeira (FK) para uma Tabela LOVN ou para outras Tabelas Relacionadas;
As Colunas disponíveis no template são aquelas que possuem as propriedades GRID = 1 e DISABLED = 0 ou que são especificadas no grupo COLUNAS previstas na Configuração;
Ao selecionar o arquivo com os dados que serão importados é possível gerar um relatório de todo o processo de importação, selecionando a opção "Gerar Relatório". No final do processo esse relatório estará disponível para download através do botão "Baixar Relatório";
Todas as colunas geradas possuem em seu Cabeçalho informações referentes ao Tipo de Dado e preenchimento (se o preenchimento é Obrigatória e/ou Valor Padrão);
Os tipos de dados devem ser respeitados! O processo de importação faz algumas conversões, mas não é possível determinar precisamente todos os dados.

Importação de campo GPS_POINT

Necessário que o campo esteja com GRID = 1;
Ao baixar o TEMPLATE em Gerenciamento de Dados -> Importação de Dados, verificar se a coluna POSICAO está com o valor 1. Este valor definirá que o campo está ativo para ser enviado pela importação;
Atentar para a forma de formatação dos campos de POSICAO_PLAT e POSICAO_PLON, que devem estar separados por .(Ponto) e não ,(Vírgula);

Simova Docs