The session workspace is a feature of openBIS for passing temporary data between a client and an openBIS application server or data store server. These temporary files are automatically deleted when the session expires. It is useful in combination with server-side services such as upload servlet (AS), aggregation services (DSS), ingestion services (DSS), and the graph service (DSS). The session workspace can be used to provide or retrieve files processed or returned by these services.
Use Case 1 : Downloading a file generated on the server
Aggregation Services provide a way of extending the openBIS API to support installation-specific features. They can be easily invoked from clients, including webapps, and can access openBIS metadata as well as data from the file system. One potential scenario is a parameterized aggregation service that gathers information for, e.g., an experiment, and produces the result in an Excel file for a biologist to further process.
The API for aggregation services offers a straightforward way for providing parameter values, but it returns a table as a result and cannot return files. To get around this limitation, the aggregation service can generate a file and put it in the session workspace. The result of the aggregation service would contain the path to the file in the session workspace. The client could then retrieve the file from the session workspace using the information returned by the aggregation service.
Use Case 2 : Generating graphs of arbitrary data
The graph service offers a way of generating scatterplots, histograms and heatmaps as PNG images. It takes parameters that specify the type of graph to generate and which file it should use for the data. To use the graph service with data that is not in a data set, it is necessary to upload the data to the session workspace.
Use Case 3 : Registering a data set without a dropbox
Ingestion services are an alternative to dropboxes for registering data. Whereas dropboxes are triggered by activity on the file system, ingestion services are explicitly triggered when invoked by a client. They can accept a dictionary (map) of parameters to the service. The dictionary is adequate for communicating small amounts of data, but not appropriate for transmitting many MB. For this situation, the ingestion service could be implemented to accept data from the session workspace. The file to register is uploaded to the session workspace and the path to the file is provided to the ingestion service as a parameter.
Use Case 4 : Uploading a file and importing it
Upload servlet can be used to upload files to the application server session workspace. These files can be later on imported using the V3 import methods to create/update experiments/samples/datasets/materials.
Access from OpenBIS webapps
- createSessionWorkspaceUploader(uploaderContainer) - creates a session workspace file uploader inside the specified uploaderContainer element
createSessionWorkspaceDownloadUrl(filePath, callback) - creates a session workspace download url for a file with the specified filePath
- createSessionWorkspaceDownloadLink(filePath, linkText, callback) - create a session workspace download link for a file with the specified filePath
downloadSessionWorkspaceFile(filePath, callback) - downloads a session workspace file with the specified filePath
- deleteSessionWorkspaceFile(filePath, callback) - deletes a session workspace file with the specified filePath
Note: user has to be authenticated to call these methods.
Example - creating an uploader
Example - downloading a file
Example - deleting a file
The attached session-workspace-example.zip includes examples that implement the use cases 1 and 2 described above.
Download the zip file and unpack it. Inside are two folders
session-workspace folder contains the core plugins for the example. Put this folder in the core-plugins folder of your openBIS server and enable the session-workspace core plugin. This will add two webapps to the
Utilities menu, the Aggregation Service Example and the Graph Service Example.
Aggregation Service Example
The aggregation service example webapp calls an aggregation service that produces a file and then displays a link to download the file.
Graph Service Example
The graph service example webapp provides a session-workspace uploader that can be used to provide files for the graph service. Once a file is uploaded to the session workspace, the webapp displays graphs that reference this file.
Example files to try are contained in the example-data folder.
The location of the session workspace is configurable in the Application Server
By default the session workspace root dir is set to "sessionWorkspace".
Application server session workspace folders are deleted as soon as a user session expires or a user logs out. Still, to make sure all stale folders are always removed (even in case of a server crash) a special SessionWorkspaceCleanUpMaintenanceTask maintenance plugin has been created. It is responsible for cleaning up the session workspace and is automatically enabled by default.
The location of the session workspace is configurable in the Data Store Server
Beware that the session workspace folder has to be on the same file system like the