Index

Datasets

Fluig is a product that allows you to make information available from multiple data sources through various forms of presentation. It is common, depending on the needs of each client, to have to present or process information related to data of the product itself (such as users, groups, roles, tasks, etc.), user-created data but managed by the product (form data), external data (such as an ERP entities) or fixed values (such as a list of states or units of measurement).

Fluig has the Dataset component that enables you to standardize access to information, regardless of the source of the data, i.e. you can access information from multiple locations, such as external applications, databases or even from Fluig own features through the same component. This means that once a Dataset is available in the system, it can be called from any part of the system in a consistent way, regardless of their source.

A Dataset provides operations that allow you to view its content, such as querying what are the available columns, how many rows there are or the value of each field in each column, as well as filter the return values.

The diagram below shows a conceptual model about the Datasets.
 

Types of Datasets

There are currently three types of product-managed Datasets:

• Built-in Datasets: This type of Dataset allows you to browse data from the Fluig's own entities, such as users, groups, processes or tasks for example. These datasets are predefined in the product and cannot be changed by the user;
• CardIndex Datasets: This type of Dataset allows you to browse existing data in forms of a given form definition posted in Fluig. For a form definition to be available as Dataset, you need to fill out the Dataset Name field in the form definition post. The value provided will be used to search the Dataset in Fluig;
• Customized Dataset: This type of Dataset allows you to navigate the data returned by a customization where you can define the Dataset columns and the values of each of the records, by JavaScript encoding. Customized Datasets can be used in a wide range of situations, such as for defining a list of fixed values (such as states of a country) or for extracting data from an external service (via WebServices, for example).

Although Datasets may have separate origins, there is no difference from the view of the component that will use this Dataset. This means, for example, that if a particular component uses a Dataset called "centroCusto", its use will be exactly the same, regardless of this Dataset being prebuilt, based on form definition or customized.

This feature of the Datasets represents a great benefit to users, since the source of the Datasets can be changed without this representing rework at the points where it is used.

For example, consider a workflow process that needs to work with a list of cost centers. In a first moment, you can work with a custom Dataset that builds, in a fixed way, records pertaining to each of the required cost centers for the user.

When encoding the list becomes little flexible (due to frequent changes), you can change the cost center to be based in form definition. As long as you consider the Dataset field names, the workflow process will not be affected.

In a third moment, you can choose to migrate the Dataset back to the custom type, but this time extracting the client ERP cost centers. Again there will be no impact to the workflow process (or to the other points that use the Dataset), as long as you take into consideration the name of the fields.

Viewing Datasets

In Fluig Studio, through the Dataset View, you can query the available Datasets, as well as view their contents. With that you can check which fields are available for both filters and access, as well perform tests on customized Datasets.

The example below shows a Dataset sample being viewed:

In this example, you can view the available fields (account, title, nature and type) and the records returned by the Dataset. Note that this information is essential for the use of Datasets, especially when there is a need to restrict the data that we want to access.

Accessing a Dataset

Several points of Fluig can use the Datasets. Depending on the location where the Dataset is used, variations may occur in the form of accessing or handling it.

Via customization points

When a Dataset is accessed via a customization point as global events, process events, form definition events or even in other Datasets, this is done through JavaScript calls that will be performed on the server side.

The example below shows a simple sample of a call to a Dataset:

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

In the above example, the JavaScript code accesses the Dataset "group", which is a system internal Dataset, and returns the number of rows available (rowsCount). The object DatasetFactory is the "gateway" for accessing any Dataset. In addition to allowing the load of a Dataset, it also allows you to browse all the Datasets available in the system.

Access to a Dataset is made through the getDataset method of the DatasetFactory object, where its parameters are:

• Dataset Name: Name of the Dataset to be searched;
• Fields: Array with the fields of the Dataset that will be returned. If null is provided, returns all the fields in the Dataset;
• Constraints: Array with the Dataset search conditions. If null is provided, returns all the records in the Dataset.
• Order: Array with the fields for ordering the Dataset records. If null is provided, returns the records with the default order.

For constraint creation, you use the createConstraint method of the DatasetFactory pbject, where its parameters are:

• Field: Name of the field that will be filtered;
• Start Value: Start value of the filter range of values
• End Value: End value of the filter range of values
• Type: Type of condition, which can be:
  
  • MUST: indicates that all Dataset records must meet this condition.
  • SHOULD: indicates that the Dataset records may or may not meet the condition. This type is more common when you need the same field to have values A or B (where each will be a search condition with type SHOULD).
  • MUST_NOT: indicates that none of the records can satisfy the condition.

Example:

function doTest2() {
	//Mounts the constraints for query
	var c1 = DatasetFactory.createConstraint("activeVersion", "true", "true", ConstraintType.MUST);
	var c2 = DatasetFactory.createConstraint("publisherId", "adm", "adm", ConstraintType.MUST_NOT);
	var c3 = DatasetFactory.createConstraint("documentType", "1", "1", ConstraintType.SHOULD);
	var c4 = DatasetFactory.createConstraint("documentType", "2", "2", ConstraintType.SHOULD);
	var constraints   = new Array(c1, c2, c3, c4);
	
	//Defines fields for ordering
	var sortingFields = new Array("documentPK.documentId");
	
	//Searches the dataset
	var dataset = DatasetFactory.getDataset("document", null, constraints, sortingFields);
	
	for(var i = 0; i < dataset.rowsCount; i++) {
		log.info(dataset.getValue(i, "documentPK.documentId"));
	}
}

Special Constraints

There is a particular constraint that is used to limit the number of records in SQL query called sqlLimit. Then you can define the maximum number of records that an SQL query can return, however the number of records may be less than expected because of some validations that are made after the data return. For example: The sqlLimithas a value of 100 and a query is made on a data service from a form definition, this query returns 100 records, however, after that, validations are performed to verify that the form is active and the current user has permission to view the data, which can cause the return to be less than 100. For sqlLimit, the following syntax is used:

 DatasetFactory.createConstraint("sqlLimit", "10", "10", ConstraintType.MUST);

There is another special constraint used only for access to form definition datasets. It indicates, when you search the data service, whether ONLY the form data from the main form should be returned. The constraint is onlyMainCards and, by default, its value is false, i.e. data is returned from the main form definition forms and from child form definitions.

DatasetFactory.createConstraint("onlyMainCards", "true", "true", ConstraintType.MUST);

Examples of use of Constraints

Consider the values of the table below being used as a data service from a form definition for sampling of the examples:

Check the data return examples below:

var c1 = DatasetFactory.createConstraint("Código", "1", "4", ConstraintType.MUST);

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);

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

Via JavaScript in form

Fluig allows you to access Datasets via JavaScript code in the HTML of a form definition using the vcXMLRPC.js library. In order to do that, simply add the following row before the body tag of the HTML:

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

Example:

function showNewDatasetFull() {
	var div = document.getElementById("datasetDiv");
  	
	//Searches the dataset
  	try {
    	var dataset = DatasetFactory.getDataset("colleague");
    	div.innerHTML = showDataset(dataset);
  	} catch(erro) {
  	  	div.innerHTML = erro;
  	}
}
function showDataset(dataset) {
	var tabela = "<table>";
  	
	//Mounts the header
  	tabela += "<tr>";
  	for (var i = 0; i < dataset.columns.length; i++) {
    	tabela += "<th>" + dataset.columns[i] + "</th>";
	}
  	tabela += "</tr>";
  	//Mounts the records  	
  	for (var x = 0; x < dataset.values.length; x++) {
  		tabela += "<tr>";
    	var row = dataset.values[x];
    	for (var y = 0; y < dataset.columns.length; y++) {
    		tabela += "<td>" + row[dataset.columns[y]] + "</td>";
		}
    	tabela += "</tr>";
  	}
  	
	tabela += "</table>";
	return tabela;
}

In the above example, you can see that the way to call a Dataset is similar to the method via customization points, through the DatasetFactory. The showDataset function provides an code example that allows you to present data from the Dataset.

Just as in the method via customization points, when you need to filter a Dataset, you must create the constraints that will be used in the search. The arguments used in the getDataset method are also the same as those presented earlier:

function showNewDatasetPartial() {
	var div = document.getElementById("datasetDiv");
			
	var c1 = DatasetFactory.createConstraint("parentDocumentId", "5", "5", ConstraintType.MUST);
	var c2 = DatasetFactory.createConstraint("documentType", "1", "1", ConstraintType.MUST_NOT);
	var c3 = DatasetFactory.createConstraint("activeVersion", "true", "true", ConstraintType.MUST);
	var constraints   = new Array(c1, c2, c3);
	
	//Defines fields for ordering
	var fields = new Array("documentPK.documentId", "documentDescription", 
			"documentType", "publisherId", "accessCount");
	var sortingFields = new Array("accessCount", "documentDescription");
	
	//Searches the dataset
  	try {
    	var dataset = DatasetFactory.getDataset("document", fields, constraints, sortingFields);
    	div.innerHTML = showDataset(dataset);
  	} catch(erro) {
  	  	div.innerHTML = erro;
  	}
}

Via Tags in the Form

Fluig allows you to specify a Dataset in a select field (combo-box). When this is done, the options in the combo are automatically created according to the Dataset data. In order to do that, you need to add three additional properties to the tag:

In the example below, the "state" field was configured so that the combo options are created from the Dataset "estadosBR". For the field value, the "Acronym" field will be used, although the user will see the "State" field.  

<select name="estado" dataset="estadosBR" datasetkey="Sigla" datasetvalue="Estado"></select>

Via Web Services

Fluig provides a set of WebServices that allow you to integrate third-party applications to the product. Among the services provided, the ECMDatasetService service allows access to a Dataset. To check the list of available services in Fluig, access the URL http://<server>:<port>/webdesk/services.

The way you use a Web Service depends on the technology used by the client application. See the documentation of the chosen technology for details on how to access Web Services.

Building a Custom Dataset

A Dataset is built from a JavaScript code. Since the Dataset itself is created from a JavaScript code, you can call other Datasets, call external services or just create the Dataset from encoded values.

In the example below, a Dataset is created whose fields and values are fixed in code:

function createDataset(fields, constraints, sortFields) {
	var dataset = DatasetBuilder.newDataset();
	  
	//Creates the columns
	dataset.addColumn("Acronym");
	dataset.addColumn("State");
	dataset.addColumn("Capital");
	dataset.addColumn("Area");
	 
	//Creates the records
	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;
}

To create a new Dataset, use the method DatasetBuilder. newDataset (). From the object created, you can add the desired columns (addColumn method) as well as add rows (addRow method).

Note that the createDataset javascript function, which creates the Dataset, receives as parameters the fields, constraints and ordering. It is up to the developer to use these values in the custom Dataset implementation logic. If any of theses fields is disregarded, the filters will not be applied. The "fields" and "sortFields" parameters are String arrays that respectively have the names of the fields that will be returned and the names of fields used for ordering. However, the "constraints" parameter is an array of objects of the Constraint type, where each array object has the following properties: 

To access these properties and analyze the values of each item, you can use a repeating loop, as in the implementation below:

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; 
			}
		}
	}
	.
	.
	.
}

Custom Dataset of "parent-child" form definition

To access information from a "parent-child" of a form definition, you can use the "ECMDatasetService" WebService (from Fluig itself), a customized Dataset (Example 1), or a process event or form definition (Example 2). 

function createDataset(fields, constraints, sortFields) {
	
	//Creates the columns
	var dataset = DatasetBuilder.newDataset();
	dataset.addColumn("NumFormulario");
	dataset.addColumn("Id");
	dataset.addColumn("Peca");
	dataset.addColumn("Quantidade");
	
	//Creates the constraint to search for the active forms
	var cst = DatasetFactory.createConstraint("metadata#active", true, true, ConstraintType.MUST);
	var constraints = new Array(cst);
	
	var datasetPrincipal = DatasetFactory.getDataset("dsExemploPaiFilho", null, constraints, null);
	
	for (var i = 0; i < datasetPrincipal.rowsCount; i++) {
		var documentId = datasetPrincipal.getValue(i, "metadata#id");
		var documentVersion = datasetPrincipal.getValue(i, "metadata#version");
		
		//Creates the constraints to search for the child fields, passing the tablename, form number and version
		var c1 = DatasetFactory.createConstraint("tablename", "tabelaPecas" ,"tabelaPecas", ConstraintType.MUST);
		var c2 = DatasetFactory.createConstraint("metadata#id", documentId, documentId, ConstraintType.MUST);
		var c3 = DatasetFactory.createConstraint("metadata#version", documentVersion, documentVersion, ConstraintType.MUST);
		var constraintsFilhos = new Array(c1, c2, c3);
		//Searches the dataset
		var datasetFilhos = DatasetFactory.getDataset("dsExemploPaiFilho", null, constraintsFilhos, null);
		for (var j = 0; j < datasetFilhos.rowsCount; j++) {
			//Adds the values to the respective columns.
			dataset.addRow(new Array(
					documentId,
					datasetFilhos.getValue(j, "wdk_sequence_id"), 
					datasetFilhos.getValue(j, "peca"),  
					datasetFilhos.getValue(j, "qtde")));
		}
	}
	
	return dataset;
}

function beforeStateEntry(sequenceId) {
	
	var user = getValue("WKUser");
	
	//Creates the constraint to search for the active forms
	var cst1 = DatasetFactory.createConstraint("metadata#active", true, true, ConstraintType.MUST);
	
	//It is mandatory to inform the userSecurityId constraint to indicate the user 
	//permission will be validated in the forms
	var cst2 = DatasetFactory.createConstraint("userSecurityId", user, user, ConstraintType.MUST);
	
	var constraints = new Array(cst1, cst2);
	
	var datasetPrincipal = DatasetFactory.getDataset("dsExemploPaiFilho", null, constraints, null);
	
	for (var i = 0; i < datasetPrincipal.rowsCount; i++) {
		var documentId = datasetPrincipal.getValue(i, "metadata#id");
		var documentVersion = datasetPrincipal.getValue(i, "metadata#version");
		
		//Creates the constraints to search for the child fields, passing the tablename, form number and version
		var c1 = DatasetFactory.createConstraint("tablename", "tabelaPecas" ,"tabelaPecas", ConstraintType.MUST);
		var c2 = DatasetFactory.createConstraint("metadata#id", documentId, documentId, ConstraintType.MUST);
		var c3 = DatasetFactory.createConstraint("metadata#version", documentVersion, documentVersion, ConstraintType.MUST);
		
		//It is mandatory to inform the userSecurityId constraint to indicate the user 
		//permission will be validated in the forms
		var c4 = DatasetFactory.createConstraint("userSecurityId", user, user, ConstraintType.MUST);
		
		var constraintsFilhos = new Array(c1, c2, c3, c4);
		
		//Searches the dataset
		var datasetFilhos = DatasetFactory.getDataset("dsExemploPaiFilho", null, constraintsFilhos, null);
		for (var j = 0; j < datasetFilhos.rowsCount; j++) {
			//Uses the Dataset fields. Displaying as an example.
			log.info("FIELD 1: " + documentId);
			log.info("FIELD 2: " + datasetFilhos.getValue(j, "wdk_sequence_id"));
			log.info("FIELD 3: " + datasetFilhos.getValue(j, "peca"));
			log.info("FIELD 4: " + datasetFilhos.getValue(j, "qtde"));
		}
	}
}

Using one of the above models, you can retrieve the "child" values from active forms, i.e. the last version created. There are some mandatory parameters that must be passed through constraints, where the start and end values must be the same. The way to retrieve these values is optional. You will find below the mandatory naming conventions for each parameter:

<table border="1" tablename="tabelaPecas" addbuttonlabel="Adid Part">
	<!-- Child Fields -->
</table>

You can also display the order of the child fields, in order to do that, you should use the wdk_sequence_id field, and this cannot be used as the name of a form field.

Final result of the Dataset from example 1:

Dataset Reference Guide

Dataset Factory

Dataset