Manipulando Collections (Arrays) de Dados na Importação do Kankei PS

O que é uma collection?

É comum termos que trabalhar com collections (também conhecidas como "arrays"). Imagine, por exemplo, um arquivo texto que tenha mais ou menos esta estrutura:

1 JOSE DA SILVA
2 01/01/2010 1500,00
2 01/02/2010 1600,00
2 01/03/2010 1700,00
1 MARIA DE SOUZA
2 05/03/2010  400,00
1 ANTONIA LOPES
2 15/04/2010  300,00
2 15/05/2010  300,00

Aqui temos um arquivo com dois tipos diferentes de linha. Uma linha (a que inicia com o número "1") contém o nome do cliente. Já a linha que inicia com o dígito "2" contém a data de vencimento e o valor.

Configurar o Kankei PS para importar este arquivo é bastante simples:

1) Nas propriedades do arquivo texto, expandir o "Detalhe"

2) O detalhe precisará ter 2 linhas, uma para cada tipo de linha

3) Para primeira linha, definir as propriedades:

4) Para a segunda linha, definir as propriedades:

5) Incluir o campo "Nome" na linha 1 e os campos "Vencimento" e "Valor" na linha 2, configurando adequadamente as propriedades "Nome do campo", "Posição", "Comprimento" e as propriedades do grupo "Tipo dos dados" de acordo.

Com esta configuração, o sistema irá reconhecer e importar normalmente o arquivo, gerando um registro para cada cliente e em cada registro criando uma collection chamada "Parcelas", contendo a lista de parcelas com vencimento e valor, como pode ser visto na imagem abaixo:

Manipulando os dados da collection

Às vezes temos a necessidade de varrer os dados da collection fazendo algum tipo de validação ou operação com os dados através de script.

É uma boa prática nessas situações, antes de tentar acessar os dados, checar se a collection existe e se ela possui pelo menos 1 elemento. Aqui podemos considerar 2 situações:

1) É obrigatório que a collection sempre tenha pelo menos 1 registro (caso ela esteja vazia, a importação deve ser abortada)

var parcelas = obj("Parcelas");
Assert(parcelas && parcelas.count() > 0, "Nenhuma parcela informada");

2) A collection pode estar vazia e nesse caso a importação deve prosseguir

var parcelas = obj("Parcelas");
if (parcelas && parcelas.count()) > 0) {
    // Aqui a collection "Parcelas" pode ser manipulada
} else {
    // Aqui pode ser colocado código para tratar os casos
    // em que não há parcelas
}

Após verificar a existência da dados na collection, ela pode ser varrida como nos exemplos abaixo:

1) Validando os dados da collection

/*
===================================
Gera um erro de importação caso alguma parcela esteja com valor
em branco ou zerado
--
Kankei Software e Consultoria - Todos os direitos reservados
===================================
*/

var parcelas = obj("Parcelas");
Assert(parcelas && parcelas.count() > 0, "Nenhuma parcela informada");

for (var n = 1; n <= parcelas.count(); n++) {
    Assert(parcelas(n)("Valor") > 0, "Valor da parcela não informado ou inválido");
}

2) Concatenando dados da collection em um campo da raiz

/*
===================================
Concatena as datas de vencimentos das parcelas em um
campo da raiz
--
Kankei Software e Consultoria - Todos os direitos reservados
===================================
*/

var parcelas = obj("Parcelas");
Assert(parcelas && parcelas.count() > 0, "Nenhuma parcela informada");

var vencimentos = [];
for (var n = 1; n <= parcelas.count(); n++) {
    vencimentos.push( Format(parcelas(n)("Vencimento"), "dd/mm/yyyy") );
}

obj("Vencimentos") = vencimentos.join(', ');

O script acima irá gerar o campo "Vencimentos", que pode ser visualizado na imagem abaixo:

3) Efetuando totalização de um campo da collection

/*
===================================
Soma os valores de todas as parcelas e grava o resultado
no campo "ValorTotal", na raiz do registro
--
Kankei Software e Consultoria - Todos os direitos reservados
===================================
*/

var parcelas = obj("Parcelas");
Assert(parcelas && parcelas.count() > 0, "Nenhuma parcela informada");

var total = 0;
for (var n = 1; n <= parcelas.count(); n++) {
    total += parcelas(n)("Valor");
}

obj("ValorTotal") = total;

O script acima gera o campo "ValorTotal", que pode ser visualizado na imagem abaixo:

4) Ignorando registros que tenham dados inválidos

Em algumas situações, ao invés de abortar a execução, pode ser necessário ignorar o registro caso a collection esteja vazia ou contenha algum valor inválido.

Obs.: É uma boa prática usar sempre a função AddWarning() - disponível a partir do build 123 - para gerar avisos de importação quando determinado registro é ignorado.

Este primeiro exemplo faz o Kankei PS ignorar o registro todo caso a collection esteja vazia:

/*
===================================
Remove, do resultado da importação, registros que não tenham parcelas
--
Kankei Software e Consultoria - Todos os direitos reservados
===================================
*/

var parcelas = obj("Parcelas");
if (parcelas && parcelas.count() > 0) {
    // Existe pelo menos uma parcela;
} else {
    AddWarning("Linha " + obj("_LinhaOrigem") + 
               ": Registro ignorado por não possuir parcelas")
    obj.deleted = true;
}

Já este exemplo, ignora o registro caso a collection tenha um valor inválido:

/*
===================================
Remove, do resultado da importação, registros que tenham parcelas
com valor inválido
--
Kankei Software e Consultoria - Todos os direitos reservados
===================================
*/

var parcelas = obj("Parcelas");
Assert(parcelas && parcelas.count() > 0, "Nenhuma parcela informada");

for (var n = 1; n <= parcelas.count(); n++) {
    if (parcelas(n)("Valor") <= 0) {
        AddWarning("Linha " + obj("_LinhaOrigem") +
                   ": Registro ignorado devido a valor vazio ou inválido");
        obj.deleted = true;
        break;
    }
}