Este guia tem o objetivo de apresentar o conceito de Dataset, suas possíveis parametrizações e sua importância na plataforma fluig.
Para que se tenha uma compreensão completa destas informações, alguns conhecimentos são considerados pré-requisitos, entre eles:
O fluig é uma plataforma que permite disponibilizar informações provindas de várias fontes de dados através de formas variadas de apresentação, dependendo da necessidade de cada cliente. Esse recurso é atendido pelo componente Dataset, que padroniza o acesso às informações, independente da origem dos dados. É possível apresentar ou processar informações referentes a:
Um Dataset disponibiliza operações que viabilizam sua consulta como: consultar quais são as colunas disponíveis, quantos registros foram retornados na consulta, os valores de cada campo, e filtrar os valores de retorno.
O diagrama abaixo apresenta um modelo conceitual sobre os Datasets.
Existem três tipos de Datasets gerenciados pela plataforma:
As nomenclaturas dos tipos simples e avançados foram adotadas a partir da atualização 1.6.5. Antes disso, os tipos de Datasets eram chamados de gerados ou customizados, respectivamente. |
Ainda que os Datasets possam ter origens distintas, não existe qualquer diferença sob a perspectiva do componente que realizará consultas neste Dataset. Esta característica representa um grande benefício para os usuários, uma vez que a fonte dos Datasets pode ser alterada sem que isto represente retrabalho nos pontos onde ele é utilizado.
Para entender melhor, considere um processo workflow que precise trabalhar com uma lista de centros de custo. Em um primeiro momento, pode-se trabalhar com um Dataset simples que monte, de forma fixa, os registros referentes a cada um dos centros de custo necessários para este processo.
Uma vez que codificar a lista se torne pouco flexível (devido a alterações frequentes nos dados), é possível definir que a fonte de dados seja baseada em um Dataset de formulário, desde que se observe o nome dos campos do Dataset, não haverá qualquer impacto sobre o processo workflow.
Em um terceiro momento, pode-se optar por mudar o Dataset novamente, desta vez extraindo os centros de custo do ERP do cliente. Novamente não haverá impacto para o processo workflow (ou para os demais pontos que utilizem o Dataset), desde que se mantenha a estrutura do Dataset inalterada.
A consulta aos dados retornados pelo Dataset pode ser feita pelo fluig Studio ou pela própria plataforma (via painel de controle ou widget).
Para que um usuário que não é administrador da empresa possa acessar os datasets via fluig Studio é necessário que ele possua a permissão "Configurar Datasets". Esta permissão pode ser concedida pelo administrador através do item Permissões disponível no Painel de Controle do fluig. |
Pelo fluig Studio, através da visão Visualização de Dataset, é possível consultar os Datasets disponíveis bem como visualizar o seu conteúdo. Com isto é possível verificar quais os campos disponíveis, tanto para filtros quanto para acesso, bem como fazer testes sobre Datasets avançados.
O exemplo abaixo apresenta um exemplo de Dataset sendo visualizado:
Neste exemplo, é possível visualizar os campos disponíveis (conta, título, natureza e tipo) e os registros retornados pelo Dataset. Note que estas informações são essenciais para o uso dos Datasets, principalmente quando há necessidade de restringir os dados que queremos acessar.
Veja a seguir o vídeo how to que demonstra a consulta de dados de um Dataset interno pelo fluig Studio.
A partir da atualização 1.6.2, a plataforma disponibiliza o facilitador de integração, um editor visual que possibilita configurar a consulta em dados de sistemas terceiros sem qualquer tipo de codificação.
O administrador do sistema pode consultar o que o Dataset está retornando, acessando Painel de Controle > Datasets, localizando o Dataset desejado, e acionando Mais ações > Consultar. Os dados retornados serão apresentados de forma semelhante à janela abaixo.
Pelo fluig, através da widget Listar registros de datasets, é possível consultar os Datasets disponíveis bem como visualizar o seu conteúdo. Com isto é possível verificar quais os campos disponíveis, tanto para filtros quanto para acesso. Através desta widget, visualizações de datasets podem ser publicadas em páginas ou comunidades.
|
Vários pontos do fluig podem fazer uso dos Datasets. Dependendo do local onde o Dataset é utilizado, podem ocorrer variações na forma de acessá-lo ou de manuseá-lo. Para saber mais sobre as formas de acesso ao dataset, consulte a documentação Acessando Datasets.
Os Datasets de fontes externas também podem ser sincronizados, para reduzir o número de acessos a serviços de dados e tráfego de informações. Para saber como funciona a sincronização, consulte Sincronização de Datasets.
Um Dataset é construído a partir de um código JavaScript. Uma vez que o próprio Dataset é criado a partir de um código JavaScript, é possível fazer chamadas a outros Datasets, chamadas a serviços externos ou apenas criar o Dataset a partir de valores codificados.
Para que um usuário que não é administrador da empresa possa construir datasets via fluig Studio é necessário que ele possua a permissão "Configurar Datasets". Esta permissão pode ser concedida pelo administrador através do item Permissões disponível no Painel de Controle do fluig. A partir da atualização 1.6.5, os administradores do sistema conseguem editar o código fonte do Dataset pela plataforma, acessando a opção "Editar em modo avançado", na tela de Datasets no Painel de Controle. |
No exemplo abaixo é criado um Dataset cujo os campos e valores estão fixos no código:
function createDataset(fields, constraints, sortFields) { var dataset = DatasetBuilder.newDataset(); //Cria as colunas dataset.addColumn("Sigla"); dataset.addColumn("Estado"); dataset.addColumn("Capital"); dataset.addColumn("Area"); //Cria os registros dataset.addRow(new Array("AM", "Amazonas", "Manaus", 1570746)); dataset.addRow(new Array("PA", "Pará", "Belém", 1247690)); dataset.addRow(new Array("MT", "Mato Grosso", "Cuiabá", 903358)); dataset.addRow(new Array("TO", "Tocantins", "Palmas", 277621)); dataset.addRow(new Array("PI", "Piauí", "Teresina", 251529)); return dataset; } |
Para criar um novo Dataset, é utilizado o método DatasetBuilder.newDataset(). A partir do objeto criado é possível adicionar as colunas desejadas (método addColumn) bem como adicionar linhas (método addRow).
Note que a função javascript createDataset, que cria o Dataset, recebe como parâmetros os campos, as constraints e a ordenação. Cabe ao desenvolvedor utilizar estes valores na lógica de implementação do Dataset avançado. Caso seja desconsiderado algum desdes campos, os filtros não serão aplicados. Os parâmetros "fields" e "sortFields" são arrays de String, que possuem, respectivamente, os nomes dos campos que serão retornados e os nomes dos campos utilizados para ordenação. Já o parâmetro "constraints" é um array de objetos do tipo Constraint, onde cada objeto deste array possui as seguintes propriedades:
Propriedade | Descrição |
---|---|
fieldName | Nome do campo |
initialValue | Valor inicial para filtro neste campo |
finalValue | Valor final para filtro neste campo |
contraintType | Tipo do filtro deste campo, podendo ter os valores abaixo: MUST: O valor informado precisa estar nos resultados SHOULD: O valor informado pode estar ou não nos resultados MUST_NOT: O valor informado não pode estar nos resultados |
Para acessar estas propriedades e analisar os valores de cada item, pode-se utilizar um laço de repetição, conforme implementação abaixo:
function createDataset(fields, constraints, sortFields) { var company; var initialDate; var finalDate; if (constraints != null) { for (var i = 0; i < constraints.length; i++) { if (constraints[i].fieldName == "company") { company = constraints[i].initialValue; } else if (constraints[i].fieldName == "date") { initialDate = constraints[i].initialValue; finalDate = constraints[i].finalValue; } } } . . . } |
Veja aqui um exemplo de implementação de um dataset avançado que considere a utilização de uma constraint:
function createDataset(fields, constraints, sortFields) { var dataset = DatasetBuilder.newDataset(); dataset.addColumn("DDD"); dataset.addColumn("Fone"); dataset.addColumn("Nome"); var tempDataset = getDefaultValues(); // consulta a fonte de dados do dataset if(constraints!=null && constraints.length){ //se tiver constraint filtra if(constraints[0].constraintType==ConstraintType.MUST) { // implementação somente para o MUST for(var a=0;a< tempDataset.length;a++){ // se o valor inicial da constraint for igual ao valor do campo na constraint adiciona a linha if(constraints[0].initialValue==tempDataset[a][constraints[0].fieldName]){ dataset.addRow(new Array(tempDataset[a]["DDD"], tempDataset[a]["Fone"],tempDataset[a]["Nome"])); } } } } else { // se não tiver constraint adiciona todas as linhas for(var a=0;a< tempDataset.length;a++){ dataset.addRow(new Array(tempDataset[a]["DDD"], tempDataset[a]["Fone"],tempDataset[a]["Nome"])); } } return dataset; } function getDefaultValues(){ // retorna valores default para serem filtrados return [{ DDD: "47", Fone: "1111-1111", Nome: "Marcos" }, { DDD: "47", Fone: "2222-2222", Nome: "Roberto" }, { DDD: "41", Fone: "3333-3333", Nome: "Maria" }, { DDD: "31", Fone: "4444-4444", Nome: "Francisco" }, { DDD: "11", Fone: "5555-5555", Nome: "Michel" }]; } |
Consulta da constraint:
function createDataset(fields, constraints, sortFields) { var c1 = DatasetFactory.createConstraint("DDD", "47", "47", ConstraintType.MUST); var dataset = DatasetFactory.getDataset("exemploFiltro", null, new Array(c1), null); return dataset; } |
A partir da atualização 1.4.10, também é possível obter o código da empresa e do usuário autenticado através do método getValue(), conforme exemplo abaixo:
function createDataset(fields, constraints, sortFields) { var companyId = getValue("WKCompany"); var currentUser = getValue("WKUser"); . . . } |
Veja a seguir o vídeo How To que demonstra a criação de um dataset avançado com dados fixos.
Através do uso de Datasets avançados é possível realizar uma série de buscas compostas.
|
Para acessar informações de um "pai-filho" de uma definição de formulário pode ser utilizado o WebService "ECMDatasetService" (do próprio fluig), um Dataset avançado (Exemplo 1), ou ainda um evento de processo ou definição de formulário (Exemplo 2).
|
Utilizando um dos modelos acima, é possível recuperar os valores "filhos" dos formulários ativos, ou seja, a última versão criada. Existem alguns parâmetros obrigatórios que devem ser passados através de constraints, onde o valor inicial e final devem ser iguais. A forma de recuperar esses valores é opcional. Segue abaixo a nomenclatura obrigatória de cada parâmetro:
Parâmetro | Descrição | |
---|---|---|
tablename | Atributo utilizado para nomear cada tabela filha do HTML. Exemplo:
| |
metadata#id | Número do formulário. | |
metadata#version | Número da versão do formulário | |
userSecurityId | Código do usuário que será validada a permissão no formulário
|
Também é possível exibir a ordem dos campos filhos, para isso deve-se utilizar o campo wdk_sequence_id, sendo que este não poderá ser utilizado como nome de algum campo do formulário.
Resultado final do Dataset do exemplo 1:
Retorno | Método e Descrição |
---|---|
SearchConstraint | createConstraint(java.lang.String field, java.lang.String initialValue, java.lang.String finalValue, ConstraintType type) Cria uma nova constraint para a seleção de registros do Dataset. |
java.util.List<java.lang.String> | getAvailableDatasets() Retorna uma lista de todos os Datasets disponíveis no sistema. |
DefaultDataset | getDataset(java.lang.String name, java.lang.String[] fields, SearchConstraint[] constraints, java.lang.String[] order) Carrega os dados de um Dataset. |
Retorno | Método e Descrição |
---|---|
void | addColumn(java.lang.String colName) Adiciona uma coluna ao Dataset. |
void | addRow(java.lang.Object[] values) Adiciona uma linha ao Dataset. |
java.lang.String | getColumnName(int colNum) Retorna o nome de uma coluna do Dataset. |
java.lang.String[] | getColumnsName() Retorna um array com os nomes das colunas do Dataset. |
int | getColumnsCount() Retorna a quantidade de colunas de um Dataset. |
java.util.ArrayList<java.util.HashMap<java.lang.String,java.lang.Object>> | getMap() Retorna os valores do Dataset na forma de uma lista contendo mapas, onde cada registro do Dataset corresponde a um mapa com o nome da coluna como chave. |
int | getRowsCount() Retorna a quantidade de linhas disponíveis no Dataset. |
DefaultDataset | getSubDataset(java.lang.String field, java.lang.Object value) Retorna um subconjunto dos dados do Dataset, na forma de um novo Dataset. |
java.lang.Object | getValue(int row, int col) Retorna o valor armazenado no Dataset, na linha e coluna passadas por parâmetro. |
java.lang.Object | getValue(int row, java.lang.String colName) Retorna o valor armazenado no Dataset, na linha passada e campo passados por parâmetro. |
java.lang.Object[][] | getValues() Retorna todos os valores de um Dataset, na forma de um array bidimensional. |
java.sql.ResultSet | toResultSet() Retorna um ResultSet contendo os dados do Dataset. |
Veja mais vídeos how to sobre datasets em: Datasets - Consulta, criação e registros. |