Custom Datastore Server Services

Introduction

On Data Store Server (DSS) it is possible to define services that - upon request - will compute a desired output from a custom code. These services have full access on data store and Application Server (AS).

These services are created by:

Creating DSS core plugin of type services.
Implementing special logic that would be triggered upon request.

How to write a custom DSS service core plugin

Here is the recipe to create an DSS core plugin of type services:

The folder <core plugin folder>/<module>/<version>/dss/services/<core plugin name> has to be created.
In this folder two files have to be created: plugin.properties and script.py. The properties file should contain:

plugin.properties
```
class = ch.ethz.sis.openbis.generic.server.dss.plugins.JythonBasedCustomDSSServiceExecutor
script-path = script.py
```
The script file should have the function process with two arguments. The first argument is the context. It contains the methods getSessionToken() and getApplicationService() which returns an instance of ch.ethz.sis.openbis.generic.asapi.v3.IApplicationServerApi. The second argument is a map of key-value pairs. The key is a string and the values is an arbitrary object. Anything returned by the script will be returned to the caller of the service. Here is an example of a script which creates a space:

script.py
```
from ch.ethz.sis.openbis.generic.asapi.v3.dto.space.create import SpaceCreation

def process(context, parameters):
    space_creation = SpaceCreation()
    space_creation.code = parameters.get('space_code');
    result = context.applicationService.createSpaces(context.sessionToken, [space_creation]);
    return "Space created: %s" % result
```
Note, that all changes on the AS database will be done in one transaction.

How to use a custom DSS service

With the following method of the API version 3 a specified service can be executed:

public Object executeCustomDSSService(String sessionToken, ICustomDSSServiceId serviceId, CustomDSSServiceExecutionOptions options);

The serviceId can be created as an instance of CustomDssServiceCode. Note, that the service code is just the core plugin name.

Parameter bindings (i.e. key-value pairs) are specified in the CustomDSSServiceExecutionOptions object by invoking for each binding the method withParameter().

Here is a code example:

CustomDSSServiceExecutionOptions options = new CustomDSSServiceExecutionOptions().withParameter("space_code", "my-space");
Object result = service.executeCustomDSSService(sessionToken, new CustomDssServiceCode("space-creator"), options);
System.out.println(result);