Data sources

Data sources are components that allow you to perform operations on data, such as reading data, writing, deleting or modifying it. A data source can be a table in a database, a database query, a file on disk, a webservice, etc.

Data sources are not self-sufficient components like other components. Instead, they can be used in other components. For example, it could be Datachooser, which displays the data of a selected data source.

Defining a data source

Data sources are created based on their definition created by the user. Such a definition must contain the following elements:

1. @DataSource annotation (if the data source is not defined in the plug-in, it must come from the com.suncode package)
2. A public method marked with an annotation @Define with one parameter DataSourceDefinitionBuilder
3. A public method named datasource, which is responsible for returning an implementation of DataSourceInstance with data source logic.
4. (Optional) A public method named validator, which is responsible for returning an implementation of DataSourceValidator with data source declaration validation logic.

The definition can also contain an annotation @DataSourceScript. This annotation passes the path to the script (from classpath) that contains the definition of the dynamic form.

You can also pass the path to the scripts you want to use on the form. To do this, use the @DataSourceInjectScript annotation. You can pass paths to multiple scripts by specifying them in the form @DataSourceInjectScript({scriptPath1, scriptPath2, ..})

A data source can also provide a script that builds the appearance of parameters when it is defined in the PWE. To do this, add another annotation for the class @ComponentsFormScript with the passed path to the script (from classpath).

An example definition:

@DataSource
@DataSourceScript("js/datasource.js")
@ComponentsFormScript( "path/example-form.js" )
public class DataSourceExample
{
    @Define
    public void definition( DataSourceDefinitionBuilder builder )
    {
        builder
            .id( "example-datasource" )
            .name( "datasource.example" )
            .description( "datasource.example.desc" )
            .category( Categories.TEST )
			.operations( DataSourceOperation.READ )
            .parameter()
                .id( "tableName" )
                .name( "datasource.parameter.tableName.name" )
                .description( "datasource.parameter.tableName.desc" )
                .type( Types.STRING)
                .create();
    }
 
    public DataSourceInstance datasource( @Param String tableName )
    {
        return new DatabaseTableSource( tableName );
    }

    public DataSourceValidator validator() {
        return new TableSourceValidator();
    }

}

Data source implementation

The data source must have a method named datasource. The method can have the following types of parameters:

• a single data source parameter - the type of the parameter must conform to the defined type and must be preceded by the annotation @Param,
• parameter mapping two array parameters (key, value) - the type of the parameter must be of type java.util.Map<K,V>, where K is the defined type of the component parameter being the key, and V is the defined type of the component parameter being the value for the key. The parameter must be annotated PairedParam with defined properties (key - id of the parameter being the key, value - id of the parameter being the value).
• a single data source parameter  DataSourceInstance marked annotation  @Param - if we have such a type, the DataSourceInstance object will be injected based on the value of this parameter, which must be the id of the data source.
• Parameters - contains all the defined validator parameters with their values, this is an alternative to retrieving the parameter using the aforementioned annotation @Param,
• Translator - Translator for this component, more information here,
• UserInfo - object containing information about the user using the data source.

This method must return an object implementing the DataSourceInstance interface. In fact, this implementation should extend the AbstractDataSourceInstance class, so that there will be no compilation errors in the future if any new methods come to the DataSourceInstance interface.

Implementation example:

public class DatabaseTableSource extends AbstractDataSourceInstance
{
	private String tableName;
 
	public DatabaseTableSource( String tableName )
	{
		this.tableName = tableName;
	}
    @Override
    public CountedResult<Map<String, Object>> getCountedData()
	{
		return new CountedResult<Map<String, Object>>(0, Maps.newHashMap())
	}
 
     @Override
     public void save( Map<String, Object> data )
     {
     }

     @Override
     public void update( Object key, Map<String, Object> data )
     {
     }

	 @Override
     public void delete( Object key )
     {
     }
}

The implementation does not have to implement all methods. Only data retrieval is required, as not every source needs to support all data operations.

Data source validation

The data source can optionally have a method called validator.

Method:

• is without parameters
• returns an object implementing the DataSourceValidator interface
• the returned object should throw a DataSourceValidateException if the data source is declared incorrectly

The validator is used when saving (creating and updating) a data source.

Implementation example:

public class TableSourceValidator implements DataSourceValidator
{
    @Override
    public void validate( DataSourceDeclaration declaration )
    {
        ParameterDeclaration someParam = declaration.getParameter( "someParam" );
        if ( !someParam.isArray() )
        {
            return;
        }

        ParameterValue someValue = someParam.getValue();

        if ( someValue.getValue().equals( "zła wartość" ) )
        {
            throw new DataSourceValidateException( "Wartość jest nieprawidłowa" );
        }
    }
}

Registration of the data source in the plugin

If the data source is defined in the plugin, then you must additionally indicate that the plugin provides components. To do this, add an entry in the suncode-plugin.xml file:

<!-- Sharing autoamtic tasks--> 
<workflow-components key="components" />

Dynamic form

The dynamic form allows you to define a parameter form.

Registration of the dynamic form

PW.DataSources.register('system-database-with-build-param', { // Data source id
	buildParams: function(form){ // The `buildParam` function, which will be used to build the data source parameter form
		form.addField('param-1');
		form.addTextAreaField('param-2');
		form.addCombobox({
    		id : 'param-3',
    		values : [{id : 'activity', display : 'Activity'},
    		          {id : 'stage', display : 'Stage'},
    		          {id : 'process', display : 'Process'}]
    	});
		
		form.addTable(['param-4', 'param-5', 'param-6'], {
			tableId: 'fieldMap', name: 'Grupa', description: 'Grupa pól'
		});
 	}
});

Dostępne funkcję dynamicznego formularza

...
form.addField('param-1');
...

...
form.addField({
	id: 'custom',
	type: 'date',
	...
});
...

...
form.addTextArea('param-1');
...

...
form.addTextArea({
	id: 'param-1',
	...
});
...

...
form.addCombobox({
	id: 'param-1',
	valueField: 'id',
	displayField: 'display',
	fields: [
		{name: 'id', type: 'string'},
		{name: 'display', type: 'string'}
	],
	values : [{id : 'activity', display : 'Zadanie'},
		  {id : 'stage', display : 'Etap'},
		  {id : 'process', display : 'Proces'}],
	sort: [{
		property: 'display',
		direction: 'DESC'
	}],
	onChange: function(combo, newValue, oldValue){
		...
	}
});
...

...
form.addCombobox({
	id: 'param-1',
	valueField: 'id',
	displayField: 'display',
	fields: [
		{name: 'id', type: 'string'},
		{name: 'display', type: 'string'}
	],
	remote: {
		url: Suncode.getAbsolutePath('plugin/com.suncode.example-plugin/example-combo/get'),
		remoteSort: false,
		pageSize: 20
	},
	sort: [{
		property: 'display',
		direction: 'DESC'
	}],
	onChange: function(combo, newValue, oldValue){
		...
	}
});
...

...
form.addCheckbox('param-1');
...

var table = form.addTable();
table.addField('param-1');
table.addField('param-2');
table.addCombobox(...);

var row = form.addRow();
row.addField('param-1');
row.addField('param-2');
row.addCombobox(...);

form.addButton({
	id: 'btn-1',
	text: 'Przycisk',
	handler: function(){
	...
	}
})

...
form.addTextPassword('param-1');
...

...
form.addPassword({
	id: 'param-1',
	...
});
...

...
form.hide('param-1');
...

...
form.show('param-1');
...

...
form.getValue('param-1');
...

...
form.setValue('param-1', 'value');
...

@ComponentsFormScript( "actions/example-form.js" )

Cache

• Cache is available for any type of source
• Cache can be enabled (and time set) for a specific source definition. This is decided by the user in the GUI
• After a system update without entering the data sources tab, all plugins have cache disabled by default

• In the plugin builder (DataSourceDefinitionBuilder ) you can configure the supportsPagination parameter, which determines whether the plugin itself supports pagination. By default, it is set to true.

• If cache and pagination on the system side is enabled - all results from DS are downloaded without passing pagination, cached and subsequent calls are taken from the cache (pagination programmatically)
• If cache and pagination on the system side is disabled - each time all results from DS are downloaded and pagination is applied by software