Dataset no Fluig: o que é, tipos e como consultar

Dataset é o componente do Fluig que padroniza o acesso a dados. Formulário, evento de processo ou widget consultam da mesma forma, venha o dado do próprio Fluig, de um formulário publicado ou de um sistema externo, como o Protheus.

Essa padronização tem um ganho concreto. A documentação da TOTVS dá o exemplo de uma lista de centros de custo que começa fixa no código, depois passa para um formulário e por fim vem do ERP. Se os nomes dos campos forem mantidos, o processo que consome o dataset não precisa mudar.

Os três tipos de dataset

Internos (built-in). São datasets do próprio produto, com dados de usuários, grupos, processos e tarefas. Não podem ser alterados. Exemplos: colleague, group e colleagueGroup.

De formulário (CardIndex). Expõem os dados de um formulário publicado. Para isso, preencha o campo de nome do dataset ao publicar o formulário.

Customizados. São escritos em JavaScript. Você define as colunas e as linhas, que podem vir de valores fixos, de outro dataset ou de um serviço externo.

Como consultar um dataset

O acesso é feito por DatasetFactory.getDataset, com quatro parâmetros: nome do dataset, campos a retornar, filtros e ordenação. Passar null significa "todos" ou "ordem padrão".

var dataset = DatasetFactory.getDataset("colleague", null, null, null);

for (var i = 0; i < dataset.rowsCount; i++) {
    log.info(dataset.getValue(i, "colleagueName"));
}

No evento de processo e em outros pontos de customização, o código roda no servidor. Em um formulário, é preciso incluir a biblioteca vcXMLRPC.js antes do body:

<script type="text/javascript" src="../vcXMLRPC.js"></script>

Nesse caso o dataset é transferido para o navegador do usuário. Trazer um dataset inteiro para a tela é uma causa frequente de formulário lento.

Como filtrar com constraints

Filtros são criados com DatasetFactory.createConstraint, que recebe o campo, o valor inicial, o valor final e o tipo. Os tipos são:

• ConstraintType.MUST: o registro precisa atender à condição.
• ConstraintType.SHOULD: o registro pode atender. É o tipo usado para fazer um "ou", como valores A ou B no mesmo campo.
• ConstraintType.MUST_NOT: o registro não pode atender à condição.

var ativo = DatasetFactory.createConstraint("active", "true", "true", ConstraintType.MUST);
var campos = new Array("colleaguePK.colleagueId", "colleagueName");
var ordem = new Array("colleagueName");

var dataset = DatasetFactory.getDataset("colleague", campos, new Array(ativo), ordem);

Duas constraints especiais merecem atenção:

sqlLimit limita a quantidade de registros da consulta. O retorno pode vir menor que o limite, porque validações de permissão acontecem depois. Só o valor inicial é considerado.

var limite = DatasetFactory.createConstraint("sqlLimit", "100", "100", ConstraintType.MUST);

onlyMainCards, usada em datasets de formulário, indica se devem voltar apenas os dados do formulário principal.

Como criar um dataset customizado

O dataset customizado é uma função createDataset, que recebe campos, constraints e ordenação:

function createDataset(fields, constraints, sortFields) {
    var dataset = DatasetBuilder.newDataset();

    dataset.addColumn("sigla");
    dataset.addColumn("estado");

    dataset.addRow(new Array("RN", "Rio Grande do Norte"));
    dataset.addRow(new Array("CE", "Ceará"));

    return dataset;
}

Aqui está o erro mais comum: em dataset customizado, as constraints não filtram sozinhas. A TOTVS deixa claro que cabe ao desenvolvedor usar esses parâmetros. Se o código os ignora, o filtro simplesmente não é aplicado. É preciso ler cada constraint:

function createDataset(fields, constraints, sortFields) {
    var estado = null;

    if (constraints != null) {
        for (var i = 0; i < constraints.length; i++) {
            if (constraints[i].fieldName == "estado") {
                estado = constraints[i].initialValue;
            }
        }
    }

    // Use "estado" na consulta ao serviço externo, não depois dela
    var dataset = DatasetBuilder.newDataset();
    dataset.addColumn("codigo");
    return dataset;
}

Um detalhe pega muita gente: em nossos projetos, a constraint chegou em formatos diferentes conforme quem chamava o dataset. Em processos, ela veio como objeto com getFieldName() e getInitialValue(). Em widgets, veio com _field e _initialValue. Se o código lê só um formato, o dataset não dá erro: ele simplesmente devolve tudo. Por isso, quando o mesmo dataset atende widget e processo, leia os formatos possíveis.

Sempre que possível, repasse o filtro à origem dos dados. Buscar tudo no ERP para filtrar dentro do Fluig desperdiça tempo nos dois sistemas. Se o dataset alimenta um campo de pesquisa, leia também o guia de campo zoom. Para consultar o Protheus a partir de um dataset, veja como chamar a API REST do Protheus pelo Fluig.

Problemas comuns

O filtro parece não funcionar. Se o dataset é customizado, confira se ele trata o parâmetro constraints e se lê o formato que está chegando, como mostrado acima.

Dataset de formulário traz registros antigos. A documentação usa a constraint metadata#active para buscar apenas formulários ativos. Sem ela, confira se versões inativas estão entrando no resultado.

Formulário demora para abrir. Veja quantos datasets são chamados no carregamento e quantos registros cada um traz. Use sqlLimit e peça só as colunas necessárias.

O dataset depende de um sistema lento. Se a consulta externa é pesada e os dados mudam pouco, avalie a sincronização de datasets, recurso que existe justamente para reduzir acessos a serviços externos.

Como medir o tempo de um dataset

O log do servidor registra o tempo de execução das customizações. Procure por JSChronos:

INFO [com.totvs.technology.foundation.common.JSChronos] DatasetFactory.getDataset.dsCargos executou por 1 segundo

O formato vem da página de avaliação de lentidão da TOTVS. Se um dataset aparece com tempo alto em toda abertura de formulário, você encontrou um bom candidato a otimização. Quando o problema é maior, com a plataforma inteira lenta, siga o roteiro de como investigar um Fluig lento.

Perguntas frequentes

Qual a diferença entre dataset interno e customizado?

O interno vem com o produto e não pode ser alterado. O customizado é escrito em JavaScript por você e pode buscar dados em qualquer origem.

Dataset customizado aceita constraints?

Ele as recebe como parâmetro, mas não aplica o filtro automaticamente. Você precisa tratá-las no código.

Como testar um dataset?

No Fluig Studio, a visualização de datasets permite consultar os campos disponíveis, ver os dados e testar datasets customizados.

Datasets bem escritos são a base de formulários rápidos e integrações confiáveis. Se a sua operação sofre com telas lentas ou dados que não batem com o ERP, fale com a MyQube.