...

...

...

...

Índice

Problema

O TOTVS | ECM é um produto que permite disponibilizar informações provindas de várias fontes de dados através de formas variadas de apresentação. Dentre estas formas, destacam-se os processos Workflow, Formulários e Portais.

É comum que, dependendo da necessidade de cada cliente, seja necessário apresentar ou processar informações referentes a dados do próprio aplicativo (como usuários, grupos, papéis tarefas, etc.), dados criados pelo usuário mas gerenciados pelo produto (dados das fichas), dados externos (como entidades de um ERP) ou ainda valores fixo (como uma lista de estados ou unidades de medida).

No Webdesk 2.04, cada componente que faria uso da informação era responsável pela sua extração. Em outras palavras, se os dados de um determinado fichário devessem ser apresentados em um portal, cabia ao portlet responsável pela formatação a extração destes dados. Da mesma forma, se um determinado processo workflow exigisse o uso deste mesmo fichário, também ele deveria fazer a extração destes dados. O diagrama abaixo apresenta um esquema básico da organização deste modelo.

Image Added

Datasets

O TOTVS | ECM introduz um novo conceito de componente – Dataset – que permite padronizar o acesso às informações, independente da origem dos dados. Isto significa que, uma vez que um Dataset esteja disponível no sistema, ele poderá ser invocado de qualquer parte do sistema e de forma consistente, independente da sua origem.

Um Dataset disponibiliza um conjunto de operações que permite navegar sobre o seu conteúdo, como consultar quais são as colunas disponíveis, quantas linhas existem ou o valor de cada campo, em cada coluna.

O diagrama abaixo apresenta um modelo conceitual sobre os Datasets.

Image Added

Tipos de Datasets

Atualmente existem três tipos de Datasets gerenciados pelo produto:

• Built-in Datasets: Este tipo de Dataset permite navegar em dados das entidades do próprio produto, como colaboradores, grupos, processos, tarefas, etc. Os Datasets "built-in" são pré-definidos no produto e não podem ser alterados pelo cliente;
• CardIndex x Datasets: Este tipo de Dataset permite navegar nos dados existentes nas fichas de um determinado fichário. Para que um fichário seja disponibilizado como Dataset, é preciso configurar o campo nome do serviço de dados nas propriedades do fichário. O nome definido neste campo será utilizado para a busca do Dataset no sistema.
• CustomizedDataset: Os Datasets customizados permitem que o usuário defina manualmente quais as colunas de um Dataset e os valores de cada um dos registros, através da codificação em JavaScript. Os Datasets customizados podem ser utilizados em uma grande gama de situações, como para definição de uma lista de valores fixos (como estados de um país) ou para a extração de dados de um serviço externo (via WebServices, por exemplo).

Ainda que os Dataset possam ter origens distintas, não existe qualquer diferença sob a perspectiva do componente que fará uso deste Dataset. Isto significa, por exemplo, que se um determinado componente fizer uso de um Dataset chamado “centro de custo”, o seu uso será exatamente o mesmo, independente deste Dataset ser pré-construído (o que não é o caso), baseado em fichário ou customizado.

Esta característica dos Datasets 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.

Por exemplo, considere um processo workflow que precise trabalhar com uma lista de centros de custo. Em um primeiro momento, pode-se trabalhar com um Dataset customizado que monte, de forma fixa, os registros referentes a cada um dos centros de custo necessários para o usuário.

Uma vez que codificar a lista se torne pouco flexível (devido à alterações freqüentes), é possível trocar o centro de custo para que seja baseado em fichá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 migrar o Dataset novamente para o tipo customizado, mas 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 observe o nome dos campos.

Visualizando Datasets

Pelo painel de controle é possível navegar pelos 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 customizados.
O exemplo abaixo apresenta um exemplo de Dataset sendo visualizado.

Image Added

Neste exemplo, é possível visualizar os campos disponíveis (seq, name e desc) 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.

Acessando um Dataset

Vários pontos do sistema 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.

Via pontos de customização

Quando um Dataset é acessado via um ponto de customização, como eventos de um fichário ou de um processo, isto é feito através de chamadas JavaScript que serão executadas no lado servidor.

O exemplo abaixo apresenta um exemplo simples de chamada a um Dataset.

function doTest1() { var dataset = DatasetFactory.getDataset("group", null, null, null); return dataset.rowsCount; }

A classe DatasetFactory é a “porta de entrada” para o acesso a qualquer Dataset. Além de permitir a carga de um Dataset, ela também permite navegar entre todos os Datasets disponíveis no sistema.

No exemplo acima, o código JavaScript faz o acesso ao Dataset “group”, que é um Dataset interno do sistema, e retorna a quantidade de linhas disponíveis (rowsCount).

function doTest2() { // Monta as constraints para consulta var c1 = DatasetFactory.createConstraint("documentPK.documentId", null, "675", ConstraintType.MUST); var c2 = DatasetFactory.createConstraint("documentTypeId", "", "", ConstraintType.MUST_NOT); var c3 = DatasetFactory.createConstraint("colleagueId", "Dir", "Dir", ConstraintType.SHOULD); var c4 = DatasetFactory.createConstraint("colleagueId", "TI", "TI", ConstraintType.SHOULD); var constraints = new Array(c1, c2, c3, c4);
// Define os campos para ordenação
var sortingFields = new Array("documentPK.documentId");
// Busca o dataset var dataset = DatasetFactory.getDataset("document", null, constraints, sortingFields);
if(dataset.rowsCount != expectedValues.length) return false;
for(i = 0; i < dataset.rowsCount; i++) { print(dataset.getValue(i, "documentPK.documentId")); } }

O exemplo acima invoca o método getDataset passando alguns argumentos extras como parâmetros:

• Nome do Dataset: Neste caso, buscando o Dataset de documento (document).
• Campos: Retorna apenas os campos recebidos no array informado. Caso null, retorna todos os campos.
• Constraints: Vetor com as condições de busca do Dataset. Em cada

Problema

O TOTVS | ECM é um produto que permite disponibilizar informações provindas de várias fontes de dados através de formas variadas de apresentação. Dentre estas formas, destacam-se os processos Workflow, Formulários e Portais.

É comum que, dependendo da necessidade de cada cliente, seja necessário apresentar ou processar informações referentes a dados do próprio aplicativo (como usuários, grupos, papéis tarefas, etc.), dados criados pelo usuário mas gerenciados pelo produto (dados das fichas), dados externos (como entidades de um ERP) ou ainda valores fixo (como uma lista de estados ou unidades de medida).

No Webdesk 2.04, cada componente que faria uso da informação era responsável pela sua extração. Em outras palavras, se os dados de um determinado fichário devessem ser apresentados em um portal, cabia ao portlet responsável pela formatação a extração destes dados. Da mesma forma, se um determinado processo workflow exigisse o uso deste mesmo fichário, também ele deveria fazer a extração destes dados. O diagrama abaixo apresenta um esquema básico da organização deste modelo.

Image Removed

Datasets

O TOTVS | ECM introduz um novo conceito de componente – Dataset – que permite padronizar o acesso às informações, independente da origem dos dados. Isto significa que, uma vez que um Dataset esteja disponível no sistema, ele poderá ser invocado de qualquer parte do sistema e de forma consistente, independente da sua origem.

Um Dataset disponibiliza um conjunto de operações que permite navegar sobre o seu conteúdo, como consultar quais são as colunas disponíveis, quantas linhas existem ou o valor de cada campo, em cada coluna.

O diagrama abaixo apresenta um modelo conceitual sobre os Datasets.

Image Removed

Tipos de Datasets

Atualmente existem três tipos de Datasets gerenciados pelo produto:

• Built-in Datasets: Este tipo de Dataset permite navegar em dados das entidades do próprio produto, como colaboradores, grupos, processos, tarefas, etc. Os Datasets "built-in" são pré-definidos no produto e não podem ser alterados pelo cliente;
• CardIndex x Datasets: Este tipo de Dataset permite navegar nos dados existentes nas fichas de um determinado fichário. Para que um fichário seja disponibilizado como Dataset, é preciso configurar o campo nome do serviço de dados nas propriedades do fichário. O nome definido neste campo será utilizado para a busca do Dataset no sistema.
• CustomizedDataset: Os Datasets customizados permitem que o usuário defina manualmente quais as colunas de um Dataset e os valores de cada um dos registros, através da codificação em JavaScript. Os Datasets customizados podem ser utilizados em uma grande gama de situações, como para definição de uma lista de valores fixos (como estados de um país) ou para a extração de dados de um serviço externo (via WebServices, por exemplo).

Ainda que os Dataset possam ter origens distintas, não existe qualquer diferença sob a perspectiva do componente que fará uso deste Dataset. Isto significa, por exemplo, que se um determinado componente fizer uso de um Dataset chamado “centro de custo”, o seu uso será exatamente o mesmo, independente deste Dataset ser pré-construído (o que não é o caso), baseado em fichário ou customizado.

Esta característica dos Datasets 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.

Por exemplo, considere um processo workflow que precise trabalhar com uma lista de centros de custo. Em um primeiro momento, pode-se trabalhar com um Dataset customizado que monte, de forma fixa, os registros referentes a cada um dos centros de custo necessários para o usuário.

Uma vez que codificar a lista se torne pouco flexível (devido à alterações freqüentes), é possível trocar o centro de custo para que seja baseado em fichá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 migrar o Dataset novamente para o tipo customizado, mas 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 observe o nome dos campos.

Visualizando Datasets

Pelo painel de controle é possível navegar pelos 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 customizados.
O exemplo abaixo apresenta um exemplo de Dataset sendo visualizado.

Image Removed

Neste exemplo, é possível visualizar os campos disponíveis (seq, name e desc) 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.

Acessando um Dataset

Vários pontos do sistema 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.

Via pontos de customização

Quando um Dataset é acessado via um ponto de customização, como eventos de um fichário ou de um processo, isto é feito através de chamadas JavaScript que serão executadas no lado servidor.

O exemplo abaixo apresenta um exemplo simples de chamada a um Dataset.

function doTest1() { var dataset = DatasetFactory.getDataset("group", null, null, null); return dataset.rowsCount; }

A classe DatasetFactory é a “porta de entrada” para o acesso a qualquer Dataset. Além de permitir a carga de um Dataset, ela também permite navegar entre todos os Datasets disponíveis no sistema.

No exemplo acima, o código JavaScript faz o acesso ao Dataset “group”, que é um Dataset interno do sistema, e retorna a quantidade de linhas disponíveis (rowsCount).

function doTest2() { // Monta as constraints para consulta var c1 = DatasetFactory.createConstraint("documentPK.documentId", null, "675", ConstraintType.MUST); var c2 = DatasetFactory.createConstraint("documentTypeId", "", "", ConstraintType.MUST_NOT); var c3 = DatasetFactory.createConstraint("colleagueId", "Dir", "Dir", ConstraintType.SHOULD); var c4 = DatasetFactory.createConstraint("colleagueId", "TI", "TI", ConstraintType.SHOULD); var constraints = new Array(c1, c2, c3, c4);
// Define os campos para ordenação
var sortingFields = new Array("documentPK.documentId");
// Busca o dataset var dataset = DatasetFactory.getDataset("document", null, constraints, sortingFields);
if(dataset.rowsCount != expectedValues.length) return false;
for(i = 0; i < dataset.rowsCount; i++) { print(dataset.getValue(i, "documentPK.documentId")); } }

O exemplo acima invoca o método getDataset passando alguns argumentos extras como parâmetros:

• Nome do Dataset: Neste caso, buscando o Dataset de documento (document).
• Campos: Retorna apenas os campos recebidos no array informado. Caso null, retorna todos os campos.
• Constraints: Vetor com as condições de busca do Dataset. Em cada condição de busca (constraint) deve-se informar o nome do campo que será filtrado, a faixa de valores inicial e final, e o tipo de Constraint. Os tipos podem ser:
  MUST: Indica que todos os registros do Dataset devem satisfazer a esta condição.
  SHOULD: Indica que os registros do Dataset podem ou não atender à condição. Este tipo é mais comum quando se necessita que um mesmo campo tenha valores A ou B (onde cada um será uma constraint SHOULD).
  MUST_NOT: indica que nenhum dos registros pode satisfazer a condição.
• Ordenação: Vetor com a lista de campos que será utilizada para ordenação dos registros no Dataset.

...

Existe outra constraint especial utilizada somente para acesso a dataset de fichários, ela indica se ao buscar o serviço de dados devem ser retornados APENAS os dados das fichas do fichário principal. A constraint é a onlyMainCards e por padrão seu valor é false, ou seja, são retornados os dados das fichas do fichário principal e sub-fichários.

...

...

Exemplificação

Considere os valores da tabela abaixo sendo utilizadas como um serviço de dados a partir de um fichário para exemplificação dos exemplos:

...

Exemplos de retorno de dados

• Para retornar as linhas que os códigos estejam entre 1 á 4.
  
  

var c1 = DatasetFactory.createConstraint("codigo", "1", "4", ConstraintType.MUST);

Será retornado:

...

• Para retornar somente as linhas que os nomes sejam „Noemi Roiger‟, „Javier Naramore‟ e „Lonnie Cadwallader‟ ou que a cidade seja Brasília.
  
  

var c1 = DatasetFactory.createConstraint("nome", " Noemi Roiger", " Noemi Roiger", ConstraintType.SHOULD);
var c2 = DatasetFactory.createConstraint("nome ", " Javier Naramore", " Javier Naramore", ConstraintType.SHOULD);
var c3 = DatasetFactory.createConstraint("nome ", "Lonnie Cadwallader", "Lonnie Cadwallader", ConstraintType.SHOULD);
var c4 = DatasetFactory.createConstraint("cidade", "Brasília", "Brasília", ConstraintType. SHOULD);

Será retornado:

• Para retornar todas as linhas exceto onde a cidade seja Brasília.
  
  

var c1 = DatasetFactory.createConstraint("cidade", "Brasília", "Brasília", ConstraintType.MUST_NOT);

Será retornado

...

Via JavaScript em formúlário

...

...

Via Tags no Formulário

O TOTVS | ECM permite especificar um Dataset em um campo select (combo-box). Quando isto é feito, as opções do combo são automaticamente criadas de acordo com os dados existentes no Dataset.

...

No exemplo acima, o campo “estado” foi configurado para que as opções do combo sejam criadas a partir do Dataset “estadosBR”. Como valor do campo será utilizado o campo “Sigla”, embora para o usuário será apresentado o campo “Estado”.

Via Site

Os Datasets também podem ser utilizados para permitir gerar conteúdo dinâmico em páginas de Sites. A sintaxe utilizada para o acesso e navegação aos fichários é muito similar aos casos anteriormente vistos, embora adaptada para o uso pelo FreeMarker (engine utilizado pelo Site).

...

[#assign myDataset = DatasetFactory.getDataset("workflowProcess", null, null, null) ]
<table>
[#list myDataset.getMap() as processos]
<tr>
<td>${processos.processInstanceId}</td>
</tr>
[/#list]
</table>

...

Via Web Services

O TOTVS | ECM disponibiliza um conjunto de WebServices que permitem integrar aplicações de terceiros ao produto. Dentre os serviços disponibilizados, o serviço DatasetService permite fazer o acesso a um Dataset. Para verificar a lista de serviços disponíveis no produto, acesso a url http://<servidor>:<porta>/webdesk/services.

A forma de uso de um Web Service varia de acordo com a tecnologia utilizada pela aplicação cliente. Consulte a documentação da tecnologia escolhida pra obter detalhes sobre como acessar Web Services.

Construindo um Dataset Customizado

...

Um Dataset pode ser 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 à serviços externos ou apenas criar o Dataset a partir de valores codificados.

...

Note que o código JavaScript que cria o Dataset recebe como parâmetros os campos, as constraints e a ordem dos campos. Cabe ao código que implementa um JavaScript customizado utilizar estes valores na sua lógica. Caso o script desconsidere algum destes campos, o engine que gerencia os Datasets não fará o filtro. 

Dataset customizado de fichário "pai-filho"

...

function beforeTaskSave(colleagueId,nextSequenceId,userList) { //Cria as constraints para buscar as fichas ativas var cst1 = DatasetFactory.createConstraint("metadata#active", "true", "true", ConstraintType.MUST); // É obrigatório informar a constraint X para indicar o usuario que sera validada a permissão nas fichas var cst2 = DatasetFactory.createConstraint("userSecurityId", getValue("WKUser"), getValue("WKUser"), ConstraintType.MUST); var constraints_principal = new Array(cst1, cst2); var datasetPadrao = DatasetFactory.getDataset("fichaexemplo ", null, constraints_principal , null); for(i = 0; i < datasetPadrao.rowsCount; i++) { //Cria as constraints para buscar os campos filhos, passando o tablename, número da ficha e versão (no caso a última). var c1 = DatasetFactory.createConstraint("tablename", "nome_tabela" ,"nome_tabela", ConstraintType.MUST); var c2 = DatasetFactory.createConstraint("metadata#id", datasetPadrao.getValue(i, "metadata#id"), datasetPadrao.getValue(i, "metadata#id"), ConstraintType.MUST); var c3 = DatasetFactory.createConstraint("metadata#version", datasetPadrao.getValue(i, "metadata#version"), datasetPadrao.getValue(i, "metadata#version"), ConstraintType.MUST); // É obrigatório informar a constraint X para indicar o usuario que sera validada a permissão nas fichas var c4 = DatasetFactory.createConstraint("userSecurityId", getValue("WKUser"), getValue("WKUser"), ConstraintType.MUST); var constraints_filhos = new Array(c1, c2, c3, c4); // Busca o dataset var datasetFilhos = DatasetFactory.getDataset("fichaexemplo", null,constraints_filhos , null); for(j = 0; j < datasetFilhos.rowsCount; j++) { //Utiliza os campos do Dataset. Exibindo como exemplo. log.info(" CAMPO 1 " + datasetFilhos.getValue(j, "peca")); log.info(" CAMPO 2 " + datasetFilhos.getValue(j, "wdk_sequence_id")); log.info(" CAMPO 3 " + datasetFilhos.getValue(j, "qtde")); log.info(" CAMPO 4 " + datasetPadrao.getValue(i, "metadata#id")); } } }

Exemplo 2

Utilizando um dos modelos de Dataset acima, é possível recuperar os valores “filhos” das fichas ativas, 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:

...

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 exemplo 1:

Image Removed

Guia de Referência de Datasets

DatasetFactory

Image Removed

Dataset

Image Removed

...

id, sendo que este não poderá ser utilizado como nome de algum campo do formulário.

Resultado final do exemplo 1:

Image Added

Guia de Referência de Datasets

DatasetFactory

Image Added

Dataset

Image Added

Adobe, Flash, Flex, Flex Builder, PostScript and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Apache is a trademark of The Apache Software Foundation.

Apple is a trademark of Apple Inc., registered in the U.S. and other countries

Firefox and Mozilla are registered trademarks of the Mozilla Foundation.

Google, Android and Google Chrome are trademarks of the Google Inc.

IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license

JavaScript is a trademark of Oracle Corporation.

Liferay, Liferay Portal, and the Liferay logo are trademarks or registered trademarks of Liferay, Inc., in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Microsoft, Active Directory, Excel, Internet Explorer, Outlook, PowerPoint, SQL Server, Windows and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

MySQL is a trademark of Oracle Corporation and/or its affiliates.

openDBcopy is an open-source project by Anthony Smith, published under the terms of the GNU General Public License

OpenLDAP is a registered trademark of the OpenLDAP Foundation

Oracle, Java and OpenOffice.org are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Progress and OpenEdge are trademarks or registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries.

Red Hat and JBoss are registered trademarks of Red Hat, Inc. in the United States and other countries.

This product includes software developed by the Visigoth Software Society (http://www.visigoths.org/).

Any other third party trademarks are the property of their respective owners.