Webapps are HTML5 apps that interact with openBIS. Webapps can be distributed as core-plugins. To supply a webapp plugin, create a folder called webapps in the as. Each subfolder of the webapps folder is treated as a webapp plugin. A webapp plugin requires two things, a file, as with all plugins, and a folder containing the content of the webapp. This folder can have any name and needs to be referenced in the file with the key webapp-folder.

The webapp is then served by the same web server (jetty) that serves openBIS. The name of the webapp defines the URL used to access it. See the example below. The file index.html is used as a welcome page if the user does not specifically request a particular page.

An openBIS webapp is not a J2EE webapp. It has more in common with an app for mobile devices.



This is an example of a webapp. In a real webapp, the name of the webapp can be any valid folder name. The same goes for the folder in the webapp containing the the code. The name of the webapp folder is what is used to define the URL. The name of the folder containing the code is neither shown nor available to the user.

Directory Structure

# The properties file for an example webapps plugin
# This file has no properties defined because none need to be defined.
webapp-folder = html


If openBIS is served at the URL, the above webapps will be available under the following URLs:

Server Configuration

There are two things to consider in the server configuration. The injection of webapps is done through Jetty, which is the web server we use for openBIS. If you use the default provided jetty.xml configuration, then you do not need to do anything extra; if, on the other hand, you have a custom jetty.xml configuration, then you will need to update your jetty.xml file to support webapps. 


Jetty Configuration

If your openBIS server has a custom jetty.xml file, you will need to modify the file to include support for injecting web apps. To do this, you will need to replace org.eclipse.jetty.deploy.providers.WebAppProvider by ch.systemsx.cisd.openbis.generic.server.util.OpenbisWebAppProvider in addAppProvider call to your jetty.xml.

<Call name="addBean">
    <New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager">
      <Set name="contexts">
        <Ref id="Contexts" />
      <Call name="addAppProvider">
          <New class="ch.systemsx.cisd.openbis.generic.server.util.OpenbisWebAppProvider">
            <Set name="monitoredDir"><Property name="jetty.home" default="." />/webapps</Set>
            <Set name="scanInterval">0</Set>
            <Set name="extractWars">true</Set>

Embedding webapps in the OpenBIS UI


Webapps can be used as both standalone applications as well as can be embedded in the OpenBIS web UI. Standalone webapps are built to completely replace the original OpenBIS web interface with customer adjusted layout and functionality. Users of the standalone webapps are usually completely unaware of the default OpenBIS look and feel. The webapp itself provides them with all the functionality they need: login pages, web forms, searches, images, charts etc. The standalone webapp is a right choice when you want to build a very specific and fully featured web interface from scratch. If you want to use the default OpenBIS UI but extend it with some custom functionality then embedding a webapp in the OpenBIS UI is probably a way to go. To make a webapp visible as a part of the default OpenBIS UI you have to define where the webapp should be shown using "openbisui-contexts" property. Moreover some of the contexts also require additional information describing when the webapp should be shown. For instance, to embed a webapp in the experiment details view that will be displayed for experiments with type "MY_EXPERIMENT_TYPE" your file should look like:

webapp-folder = html
openbisui-contexts = experiment-details-view
experiment-entity-types = MY_EXPERIMENT_TYPE

Configuring embedded webapps

A full list of supported properties is presented below.

Property KeyDescriptionAllowed values
Place where the webapp is shown in the OpenBIS UI.
    • webapp is an item in the modules top menu
    • webapp is a tab in the experiment details view
    • requires experiment-entity-types to be defined
    • webapp is a tab in the sample details view
    • requires sample-entity-types to be defined 
    • webapp is a tab in the data set details view
    • requires data-set-entity-types to be defined
    • webapp is a tab in the material details view
    • requires material-entity-types to be defined

Accepts a comma separated list of values with regular expressions, e.g. "modules-menu, .*-details-view"

The label. It will be shown in the GUI.String

Sorting of the webapp. Webapps are sorted by "sorting" and "folder name" ascending with nulls last (webapps without sorting are presented last).

Types of experiments the webapp should be displayed for.Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"
Types of samples the webapp should be displayed for.Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"
Types of data sets the webapp should be displayed for.Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"
Types of materials the webapp should be displayed for.Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"

Creating embedded webapps

Embedded webapps similar to the standalone counterparts are HTML5 applications that interact with OpenBIS. Because embedded webapps are shown inside the OpenBIS UI they have access to additional information about the context they are displayed in. For instance, a webapp that is displayed in the experiment-details-view context knows that it is displayed for an experiment entity, with a given type, identifier and permid. Having this information the webapp can adjust itself and display only data related to the currently chosen entity. Apart from the entity details, a webapp also receives a current sessionId that can be used for calling OpenBIS JSON RPC services. This way embedded webapps can reuse a current session that was created when a user logged in to the OpenBIS rather than provide their own login pages for authentication. A sample webapp that makes use of this context information is presented below:

    <!-- include jquery library required by the openbis.js -->
    <script src="/openbis/resources/js/jquery.js"></script>
    <!-- include openbis library to gain access to the openbisWebAppContext and openbis objects -->
    <script src="/openbis/resources/js/openbis.js"></script>

<div id="log"></div>


        // create a context object to access the context information
        var c = new openbisWebAppContext();
        $("#log").append("SessionId: " + c.getSessionId() + "<br/>");
        $("#log").append("EntityKind: " + c.getEntityKind() + "<br/>");
        $("#log").append("EntityType: " + c.getEntityType() + "<br/>");
        $("#log").append("EntityIdentifier: " + c.getEntityIdentifier() + "<br/>");
        $("#log").append("EntityPermId: " + c.getEntityPermId() + "<br/>");

        // create an OpenBIS facade to call JSON RPC services
        var o = new openbis();

        // reuse the current sessionId that we received in the context for all the facade calls

        // call one of the OpenBIS facade methods
            $.each(response.result, function(index, value){
                 $("#log").append(value.code + "<br/>");  


Embedding openBIS Grids in Web Apps

Users of openBIS will have encountered the advanced and powerful table views used in the application. These views allow for sorting and filtering. It is possible to take advantage of these views in custom web UIs.


It is possible to use openBIS table views in a web UI when the data for the table comes from an aggregation service. The parameters to the aggregation service are passed as URL query parameters, thus an additional requirement is that all the aggregation service parameters can be passed this way. A final requirement is that the web UI be exposed as an embedded webapp (this is necessary because of the way openBIS keeps track of the user of the system). If these requirements are met, then it will be possible to embed an openBIS table view display the aggregation service data in a web UI.


To embed a table view, add an iframe to the web UI. The URL of the iframe should have the following form:

{openbis url}?viewMode=GRID#action=AGGREGATION_SERVICE&serviceKey={aggregation service key}&dss={data store server code}[& gridSettingsId][& gridHeaderText][& service parameters]


An aggregation service that will be used for generating the data for the grid.
A code of a data store that will be used for generating the data for the grid.

An identifier of the grid that will be used for storing the grid settings (visibility of columns, sorting, filters etc.). If not specified then the serviceKey parameter is used.

A header of the grid. If not specified then the header is not shown.



Full Example

<!DOCTYPE html>
<html xmlns="" xml:lang="en-US" lang="en-US">
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<title>Embedded Grid Example</title>
<iframe src="http://localhost:8888/openbis-test/index.html?viewMode=GRID#action=AGGREGATION_SERVICE&serviceKey=sp-233&dss=standard&gridSettingsId=myTestGridSettingsId&gridHeaderText=myTestGridHeaderText&name=hello" width="100%" height="95%" style="border: none">