Introduction

A reporting plugin runs on the DSS. It creates a report as a table or an URL for a specified set of data sets or key-value pairs. The user can invoke a reporting plugin in the openBIS Web application. The result will be shown as a table or a link.

A reporting plugin is one of the three following types. The differences are the type of input and output:

  • TABLE_MODEL: Input: A set of data sets. Output: A table
  • DSS_LINK: Input: One data set. Output: An URL
  • AGGREGATION_TABLE_MODEL: Input: A set of key-value pairs. Output: A table

A reporting plugin is configured on the DSS best by introducing a core plugin of type reporting-plugins. All reporting plugins have the following properties in common:

Property KeyDescription
classThe fully-qualified Java class name of the reporting plugin. The class has to implement IReportingPluginTask.
labelThe label. It will be shown in the GUI.
dataset-typesComma-separated list of regular expressions. The plugin can create a report only for the data sets of types matching one of the regular expressions. If new data set types are registered with openBIS, the DSS will need to be restarted before the new data set types are known to the processing plugins. This is a mandatory property for reporting plugins of type TABLE_MODEL and DSS_LINK. It will be ignored if the type is AGGREGATION_TABLE_MODEL.
properties-filePath to an optional file with additional properties.
servlet.<property>

Properties for an optional servlet. It provides resources referred by URLs in the output of the reporting plugin.

This should be used if the servlet is only needed by this reporting plugin. If other plugins also need this servlet it should be configured as a core plugin of type services.

allowed-api-parameter-classesA comma-separated list of regular expression for fully-qualified class names. Any classes matching on of the regular expressions is allowed as a class of a Java parameter object of a remote API call. For more details see API Security.
disallowed-api-parameter-classesA comma-separated list of regular expression for fully-qualified class names. Any classes matching on of the regular expressions is not allowed as a class of a Java parameter object of a remote API call. For more details see API Security.

Generic Reporting Plugins

DecoratingTableModelReportingPlugin

Type: TABLE_MODEL

Description: Modifies the output of a reporting plugin of type TABLE_MODEL

Configuration:

Property KeyDescription
reporting-plugin.classThe fully-qualified Java class name of the wrapped reporting plugin of type TABLE_MODEL
reporting-plugin.<property>Property of the wrapped reporting plugin.
transformation.classThe fully-qualified Java class name of the transformation. It has to implement ITableModelTransformation.
transformation.<property>Property of the transformation to be applied.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.DecoratingTableModelReportingPlugin
label = Analysis Summary
dataset-types = HCS_IMAGE_ANALYSIS_DATA
reporting-plugin.class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.TSVViewReportingPlugin
reporting-plugin.separator = ,
transformation.class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.EntityLinksDecorator
transformation.link-columns = BARCODE, GENE
transformation.BARCODE.entity-kind = SAMPLE
transformation.BARCODE.default-space = DEMO
transformation.GENE.entity-kind = MATERIAL
transformation.GENE.material-type = GENE

Transformations

EntityLinksDecorator

Description: Changes plain columns into entity links.

Configuration:

Property KeyDescription
link-columnsComma-separated list of column keys.
<column key>.entity-kindEntity kind of column <column key>. Possible values are MATERIAL and SAMPLE.
<column key>.default-spaceOptional space code for SAMPLE columns. It will be used if the column value contains only the sample code.
<column key>.material-typeMandatory type code for MATERIAL columns.

GenericDssLinkReportingPlugin

Type: DSS_LINK

Description: Creates an URL for a file inside the data set.

Configuration:

Property KeyDescription
download-urlBase URL. Contains protocol, domain, and port.
data-set-regexOptional regular expression which specifies the file.
data-set-pathOptional relative path in the data set to narrow down the search.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.GenericDssLinkReportingPlugin
label = Summary
dataset-types = MS_DATA
download-url = https://my.domain.org:8443
data-set-regex = summary.*
data-set-path = report

AggregationService

Import Note on Authorization

In AggregationServices and IngestionServices, the service programmer needs to ensure proper authorization by himself. He can do so by using the methods from IAuthorizationService. The user id, which is needed when calling these methods, can be obtained from DataSetProcessingContext (when using Java), or the variable userId (when using Jython).


Type: AGGREGATION_TABLE_MODEL

Description: An abstract superclass for aggregation service reporting plugins. An aggregation service reporting plugin takes a hash map containing user parameters as an argument and returns tabular data (in the form of a TableModel). The JythonBasedAggregationServiceReportingPlugin below is a subclass that allows for implementation of the logic in Jython.

Configuration: Dependent on the subclass.

To implement an aggregation service in Java, define a subclass of ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.AggregationService. This subclass must implement the method

TableModel createReport(Map<String, Object>, DataSetProcessingContext).

Example:

ExampleAggregationServicePlugin
package ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard;
import java.io.File;
import java.util.Map;
import java.util.Properties;
import ch.systemsx.cisd.openbis.dss.generic.shared.DataSetProcessingContext;
import ch.systemsx.cisd.openbis.generic.shared.basic.dto.TableModel;
import ch.systemsx.cisd.openbis.generic.shared.util.IRowBuilder;
import ch.systemsx.cisd.openbis.generic.shared.util.SimpleTableModelBuilder;
/**
 * @author Chandrasekhar Ramakrishnan
 */
public class ExampleAggregationServicePlugin extends AggregationService
{
    private static final long serialVersionUID = 1L;
    /**
     * Create a new plugin.
     * 
     * @param properties
     * @param storeRoot
     */
    public ExampleAggregationServicePlugin(Properties properties, File storeRoot)
    {
        super(properties, storeRoot);
    }
    @Override
    public TableModel createReport(Map<String, Object> parameters, DataSetProcessingContext context)
    {
        SimpleTableModelBuilder builder = new SimpleTableModelBuilder(true);
        builder.addHeader("String");
        builder.addHeader("Integer");
        IRowBuilder row = builder.addRow();
        row.setCell("String", "Hello");
        row.setCell("Integer", 20);
        row = builder.addRow();
        row.setCell("String", parameters.get("name").toString());
        row.setCell("Integer", 30);
        return builder.getTableModel();
    }
}

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.ExampleAggregationServicePlugin
label = My Report

JythonAggregationService

Type: AGGREGATION_TABLE_MODEL

Description: Invokes a Jython script to create an aggregation service report. For more details see Jython-based Reporting and Processing Plugins.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.jython.JythonAggregationService
label = My Report
script-path = script.py

IngestionService

Type: AGGREGATION_TABLE_MODEL

Description: An abstract superclass for aggregation service reporting plugins that modify entities in the database. A db-modifying aggregation service reporting plugin takes a hash map containing user parameters and a transaction as arguments and returns tabular data (in the form of a TableModel). The transaction is an IDataSetRegistrationTransactionV2, the same interface that is used by dropboxes to register and modify entities. The JythonBasedDbModifyingAggregationServiceReportingPlugin below is a subclass that allows for implementation of the logic in Jython. 

Configuration: Dependent on the subclass.

To implement an aggregation service in Java, define a subclass of ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.IngestionService. This subclass must implement the method 

TableModel process(IDataSetRegistrationTransactionV2 transaction, Map<String, Object> parameters, DataSetProcessingContext context)

Example:

ExampleDbModifyingAggregationService.java
package ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard;
import java.io.File;
import java.util.Map;
import java.util.Properties;
import ch.systemsx.cisd.etlserver.registrator.api.v2.IDataSetRegistrationTransactionV2;
import ch.systemsx.cisd.openbis.dss.generic.shared.DataSetProcessingContext;
import ch.systemsx.cisd.openbis.dss.generic.shared.dto.DataSetInformation;
import ch.systemsx.cisd.openbis.generic.shared.basic.dto.TableModel;
import ch.systemsx.cisd.openbis.generic.shared.util.IRowBuilder;
import ch.systemsx.cisd.openbis.generic.shared.util.SimpleTableModelBuilder;
/**
 * An example aggregation service
 * 
 * @author Chandrasekhar Ramakrishnan
 */
public class ExampleDbModifyingAggregationService extends IngestionService<DataSetInformation>
{
    private static final long serialVersionUID = 1L;
    /**
     * @param properties
     * @param storeRoot
     */
    public ExampleDbModifyingAggregationService(Properties properties, File storeRoot)
    {
        super(properties, storeRoot);
    }
    @Override
    public TableModel process(IDataSetRegistrationTransactionV2 transaction,
            Map<String, Object> parameters, DataSetProcessingContext context)
    {
        transaction.createNewSpace("NewDummySpace", null);
        SimpleTableModelBuilder builder = new SimpleTableModelBuilder(true);
        builder.addHeader("String");
        builder.addHeader("Integer");
        IRowBuilder row = builder.addRow();
        row.setCell("String", "Hello");
        row.setCell("Integer", 20);
        row = builder.addRow();
        row.setCell("String", parameters.get("name").toString());
        row.setCell("Integer", 30);
        return builder.getTableModel();
    }
}
plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.ExampleDbModifyingAggregationService
label = My Report

JythonIngestionService

Type: AGGREGATION_TABLE_MODEL

Description: Invokes a Jython script to register and modify entities and create an aggregation service report. The script receives a transaction as an argument. For more details see Jython-based Reporting and Processing Plugins.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

share-id

Optional, defaults to 1 when not stated otherwise.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.jython.JythonIngestionService
label = My Report
script-path = script.py

JythonBasedReportingPlugin

Type: TABLE_MODEL

Description: Invokes a Jython script to create the report. For more details see Jython-based Reporting and Processing Plugins.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.jython.JythonBasedReportingPlugin
label = My Report
dataset-types = MS_DATA, UNKNOWN
script-path = script.py

TSVViewReportingPlugin

Type: TABLE_MODEL

Description: Presents the main data set file as a table. The main file is specified by the Main Data Set Pattern and the Main Data Set Path of the data set type. The file can be a CSV/TSV file or an Excel file. This reporting plugin works only for one data set. 

Configuration:

Property KeyDescription
separatorSeparator character. This property will be ignored if the file is an Excel file. Default: TAB character
ignore-commentsIf true all rows starting with '#' will be ignored. Default: true
ignore-trailing-empty-cellsIf true trailing empty cells will be ignored. Default: false
excel-sheetName or index of the Excel sheet used. This property will only be used if the file is an Excel file. Default: 0
transposeIf true transpose the original table, that is exchange rows with columns. Default: false

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.standard.TSVViewReportingPlugin
label = My Report
dataset-types = MS_DATA, UNKNOWN
separator = ;

Screening Reporting Plugins

ScreeningJythonBasedAggregationServiceReportingPlugin

Type: AGGREGATION_TABLE_MODEL

Description: Invokes a Jython script to create an aggregation service report. For more details see Jython-based Reporting and Processing Plugins. There is some extra support for screening.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.screening.server.plugins.jython.ScreeningJythonBasedReportingPlugin
label = My Report
dataset-types = HCS_IMAGE
script-path = script.py

ScreeningJythonBasedDbModifyingAggregationServiceReportingPlugin

Type: AGGREGATION_TABLE_MODEL

Description: Invokes a Jython script to register and modify entities and create an aggregation service report. The screening-specific version has access to the screening facade for queries to the imaging database and is given a screening transaction that supports registering plate images and feature vectors. For more details see Jython-based Reporting and Processing Plugins.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.screening.server.plugins.jython.ScreeningJythonBasedReportingPlugin
label = My Report
dataset-types = HCS_IMAGE
script-path = script.py

ScreeningJythonBasedReportingPlugin

Type: TABLE_MODEL

Description: Invokes a Jython script to create the report. For more details see Jython-based Reporting and Processing Plugins. There is some extra support for screening.

Configuration:

Property KeyDescription
script-pathPath to the jython script.

Example:

plugin.properties
class = ch.systemsx.cisd.openbis.dss.screening.server.plugins.jython.ScreeningJythonBasedAggregationServiceReportingPlugin
label = My Report
script-path = script.py
  • No labels