Eventos de Importação do Kankei PS

Os templates de importação do Kankei PS permitem uma completa customização do processo de importação do arquivo.

Isso é feito através dos chamados Eventos de Importação.

Para o Kankei PS, um evento é um determinado momento do processo da importação, para o qual podem ser definidos comandos de importação. Existem 4 tipos de comando:

- SET: Permite criar um novo campo ou atribuir um valor para um campo existente

- GLOBALSET: Idem ao comando SET, mas funciona apenas para campos auxiliares, que não são incluídos na tabela de dados importados, mas que podem ser utilizados para criar lógicas de processamento

- ASSERT: Efetua uma validação dos dados; se os dados não forem considerados válidos, a importação será abortada

- SCRIPT: É o comando mais poderoso, que permite que seja definido um script usando a linguagem KankeiScript para fazer inúmeras tarefas, como validação, formatação de dados, e diversos outros tipos de tratamento

Vale lembrar que nem todos estes comandos podem ser usados em todos os eventos. Os comandos SET e ASSERT estão disponíveis apenas para eventos que se referem a um único registro. Ex.: O evento "Ao Iniciar Importação" não permite SET e ASSERT, mas o evento "Após Ler Registro" permite. 

Lista de Eventos Suportados pela Importação do Kankei PS

A versão mais recente do Kankei PS tem os seguintes eventos de importação:

1) Ao Iniciar Importação

Este evento é executado logo no início da importação, antes que o sistema tenha aberto o arquivo a ser importado. Aqui pode ser definida qualquer lógica de inicialização que seja necessária, como por exemplo, a inicialização de contadores. Exemplo:

globals('ValorTotal') = 0; // Esta variável será usada para somar o valor de cada registro

2) Ao Iniciar Leitura do Arquivo

Na maioria dos casos, este evento é similar ao "Ao Iniciar Importação". No entanto, em alguns casos, um mesmo processo de importação pode efetuar a leitura de mais de um arquivo durante o mesmo processo de importação. Nestes casos, o evento "Ao Iniciar Leitura do Arquivo" é executado antes de começar a importação de cada um dos arquivos de origem.

Neste evento, o nome do arquivo sendo importado pode ser acessado através da variável auxiliar "ArquivoOrigem". Exemplo:

var nomeDoArquivo = globals('ArquivoOrigem');

3) Antes de Ler Registro

Este evento é executado antes da leitura de cada registro do arquivo. Pode ser usado para definir valores padrão para determinados campos, que possam existir ou não no arquivo sendo importado. Isso é útil para certos tipos de arquivo onde a lista de campos a ser importada não é definida na template, como por exemplo arquivos .xls.

Perceba, no entanto, que se a coluna existir na planilha, mas a célula estiver em branco para o registro atual, o valor que tiver sido definido neste evento será substituído por um valor vazio.

// Se o campo 'NOME' não existir na planilha sendo importada, o valor do campo será 'ANÔNIMO'
// Como este evento é executado antes da leitura do registro, se o campo existir, o valor
// definido abaixo será sobreposto
obj('Nome') = 'Anônimo';

Obs.: O evento "Antes de Ler Registro" também é executado durante o processo de agrupamento de dados (ver evento "Antes de Agrupar"). O evento será executado antes que os dados de cada registro agrupado sejam gerados. Para saber se o evento está sendo executado durante o agrupamento, deve-se testar o valor do campo "KBS_Group".

if (obj("KBS_Group")) {
    // Comandos aqui serão executados apenas durante o agrupamento
} else {
    // Comandos aqui serão executados na leitura do arquivo
}

4) Antes dos Cálculos Bancários

Este evento é executado imediatamente depois que o registro foi lido, portanto qualquer atribuição de valores irá sobrepor os dados importados do arquivo.

Usa-se este evento para definição de campos necessários para os cálculos bancários (cálculo de dígitos verificadores e geração de código de barras e linha digitável para boletos bancários). Exemplo:

// Ativa os cálculos bancários do ITAÚ
obj("CodigoBanco") = "341";
obj("CodigoCarteira") = "123";
obj("CodigoAgencia") = "0123";
obj("CodigoCedente") = "12345";

// Obs: Os campos 'ValorTitulo', 'Vencimento', 'NossoNumero' e 'NumeroDocumento'
// Também são obrigatórios para este cálculo, mas geralmente estes dados
// já foram importados do arquivo neste momento.

Obs.: O evento "Antes dos Cálculos Bancários" também é executado durante o processo de agrupamento de dados (ver evento "Antes de Agrupar"). O evento será executado depois que os dados de cada registro agrupado tenham sido gerados. Para saber se o evento está sendo executado durante o agrupamento, deve-se testar o valor do campo "KBS_Group".

if (obj("KBS_Group")) {
    // Comandos aqui serão executados apenas durante o agrupamento
} else {
    // Comandos aqui serão executados na leitura do arquivo
}

5) Após Cálculos Bancários

Evento executado imediatamente após os cálculos bancários (geração de código de barras e linha digitável). Este evento não é executado caso nenhum cálculo bancário tenha sido executado.

// Insere alguns espaços em branco antes dos dígitos da linha digitável
// (para, por exemplo, fazer um melhor ajuste do posicionamento dos dados no layout)
obj("LinhaDigitavel") = "    " + obj("LinhaDigitavel");

Obs.: O evento "Após Cálculos Bancários" também é executado durante o processo de agrupamento de dados (ver evento "Antes de Agrupar"). O evento será executado após os cálculos bancários, caso eles tenham ocorrido. Para saber se o evento está sendo executado durante o agrupamento, deve-se testar o valor do campo "KBS_Group".

if (obj("KBS_Group")) {
    // Comandos aqui serão executados apenas durante o agrupamento
} else {
    // Comandos aqui serão executados na leitura do arquivo
}

6) Após Ler Registro

Este evento, na verdade, é executado após os cálculos bancários. Idêntico ao evento "Após Cálculos Bancários", exceto pelo fato de que "Após Ler Registro" sempre é executado.

Este evento costuma ser o mais utilizado, pois todos os dados estão disponíveis para serem validados e/ou manipulados de acordo com a necessidade.

Este evento é executado antes da geração de campos padrão (como, por exemplo, os campos de FAC).

// Validação de campos obrigatórios
Assert(obj("CEP"), "Campo CEP não foi preenchido");

// Campos calculados
obj("Desconto") = obj("ValorTitulo") * obj("PercentualDesconto");

// Campos com valor acumulado
globals("ValorTotal") += obj("ValorTitulo");
obj("ValorAcumulado") = globals("ValorTotal");

Obs.: O evento "Após Ler Registro" também é executado durante o processo de agrupamento de dados (ver evento "Antes de Agrupar"). O evento será executado após os cálculos bancários. Para saber se o evento está sendo executado durante o agrupamento, deve-se testar o valor do campo "KBS_Group".

if (obj("KBS_Group")) {
    // Comandos aqui serão executados apenas durante o agrupamento
} else {
    // Comandos aqui serão executados na leitura do arquivo
}

7) Ao Término do Arquivo

Este evento é executado logo depois que todos os registros do arquivo foram processados. Ver descrição do evento "Ao Iniciar Leitura do Arquivo" para maiores informações.

Este evento pode ser útil em situações onde é necessário realizar alguma operação que dependa do nome ou do número de arquivos processados, como por exemplo fazer uma de totalização de dados por arquivo.

// Valida a quantidade de registros lida do arquivo
Assert(globals("FileRecordCount") <= 100, "O arquivo " + globals("ArquivoOrigem") 
    + " é inválido, pois possui mais de 100 registros");

// Grava o nome do arquivo importado e o número de registros em um arquivo de LOG
WriteLineToFile("C:\\TEMP\\FILE.LOG", "Arquivo importado: " + globals("ArquivoOrigem"));
WriteLineToFile("C:\\TEMP\\FILE.LOG", "Número de registros: " + globals("FileRecordCount"));

8) Antes de Agrupar

É possível definir um ou mais campos para servirem de chave de agrupamento na template (propriedade "Agrupar Por" do tipo de importação). Quando isso é definido, o sistema iniciará um processamento de agrupamento logo depois que a leitura do arquivo tiver sido concluída.

O evento "Antes de Agrupar" é executado imediatamente antes do início deste processamento. É possível definir neste evento, por exemplo, lógicas de inicialização para variáveis auxiliares a serem usadas durante o agrupamento.

Durante o processo de agrupamento, o sistema irá executar os eventos "Antes de Ler Registro", "Antes dos Cálculos Bancários", "Após os Cálculos Bancários" e "Após Ler Registro", seguindo as mesmas regras do processo de importação normal. No entanto, a variável "obj" irá representar um registro agrupado, ao invés de um registro lido diretamente do arquivo.

// Esta variável poderá ser usada em eventos como "Após Ler Registro"
// durante o agrupamento
globals('ValorTotal') = 0;

9) Após Agrupar

Este evento é executado no final do processo de agrupamento (ver evento "Antes de Agrupar" para maiores informações).

// Valida o número de registros agrupados
Assert(globals("RecordCount") > 10, "O número de registros agrupados precisa ser maior que 10");

10) Antes da Geração de Campos Padrão

Após o término da leitura de todos os arquivos (a importação pode processar mais de um, ver evento "Ao Iniciar Leitura do Arquivo"), o sistema inicia o processo de geração de campos padrão. Isso inclui diversos campos especiais, como os dados de FAC.

Este processo percorre todos os registros importados (ou os registros agrupados, caso tenha ocorrido agrupamento) gerando os campos para cada registro.

O evento "Antes da Geração de Campos Padrão" ocorre imediatamente antes dos campos padrão serem gerados. Útil para fazer validações finais, como por exemplo validação de campos essenciais para o processo, como o CEP.

// Aborta a importação, caso o CEP esteja vazio
Assert(ToString(obj("CEP")) != "", "CEP Inválido: " + obj("CEP"));

11) Após Geração de Campos Padrão

De forma similar ao evento anterior, este evento ocorre durante o processo de geração de campos padrão, sendo executado logo após o processamento de cada um dos registros.

Este evento pode ser usado para criação de campos que sejam derivados dos campos padrão, ou para fazer validação dos dados gerados automaticamente pelo sistema.

// Neste evento, os campos padrão, como os de FAC, estão disponíveis,
// o que permite a geração de campos derivados
obj("InicioSIF") = Mid(obj("KBS_SIF"), 1, 4);

12) Ao Término da Importação

Este evento é executado após a conclusão de todas as etapas da importação (leitura do arquivo, agrupamento e geração de campos padrão).

Pode ser útil para validar o número de registros processados ou para qualquer outra operação que precise ser executada neste momento do processamento.

// Assumindo que globals("ValorTotal") tenha sido incrementada em eventos como
// "Após Ler Registro" ou "Após Geração de Campos Padrão". 
Assert(globals("ValorTotal") >= 10000, 
  "O valor total dos registros importados não pode ser inferior a 10.000,00");

Ordem de Execução dos Eventos

Caso 1: Template simples, sem agrupamento, sem cálculos bancários e importando um único arquivo com 2 registros:

Caso 2: Idem ao anterior, mas importando 2 arquivos com 2 registros cada:

Caso 3: Importação com 1 arquivo com 1 registro, com cálculos bancários, mas sem agrupamento:

Caso 4: Importação com 1 arquivo com 2 registros, sem cálculos bancários, mas com agrupamento (considerando que o agrupamento irá unir os 2 registros importados em 1 único registro final):

Diferenças em Relação a Versões Anteriores ao Build 122

Versões mais antigas, inferiores ao build 122 da versão 2007, têm algumas diferenças neste mecanismo.

As principais alterações efetuadas no build 122 foram:

1) Incluído o evento "Antes da Geração de Campos Padrão". Este evento é novo e não existia nas versões anteriores.

2) Evento "Após Geração de Campos Padrão" agora é executado em outro momento. Nas versões anteriores, a geração de campos padrão era efetuada logo após o evento "Após Ler Registro" e o evento "Após Geração de Campos Padrão" era executado em seguida. O evento também era executado durante o agrupamento, o que deixou de ocorrer.

3) Evento "Após Cálculos Bancários" sempre era executado nas versões anteriores. Agora, este evento só é executado quando tiverem sido realizados cálculos bancários.

A imagem abaixo ilustra, de forma esquemática, as mudanças efetuadas: