Dynamic Properties are one of two types of properties that use Jython scripts for providing special functionality to OpenBIS. To understand the basic concept read about Properties Handled By Plugins.
Defining dynamic properties
To create a dynamic property:
- Define a property type with appropriate name and data type (
- Define a script which should be used to calculate the value of your dynamic property (
- Assign the created property type to chosen entity type using the created script (e.g. for samples:
Administration->Property Types->Assign to Sample Type):
Handled By Scriptcheckbox,
Dynamic Property Evaluatorradio option for script type,
- choose the appropriate
To browse and edit existing scripts or add new ones, select Administration->Scripts from the top menu.
The scripts should be written using standard Jython syntax. Unlike custom columns and filters (which also require Jython syntax), dynamic properties can have more than one line of code. If the Script contains only one line, it will be evaluated and used as the value of appropriate dynamic property. If on the other hand a multi line script is needed, the function named
"calculate" will be expected and the the result will be used as property value.
To access the entity object from the script, use the following syntax:
Currently available methods that can be called on all kinds of entities include:
It is also possible to acces the complete Java Object by calling
"entityPE()" method, but this is appropach is not recomended, as the returned value is not a part of a well defined API and may change at any point. You may use it as a workaround, in case some data are not accessible via well defined API, but you should contact OpenBIS helpdesk and comunicate your needs, so the appropriate methods can be added to the official API.
You can test your script on selected entities (samples/experiments/materials/data sets) using the testing environment - part of
- Show a value of a Sample property which is named 'Multiplicity'
2. Takes an existing property and multiplies the value by 1.5
- Show all entity properties as one dynamic property:
2. Calculate a new float value based some other values
3. Calculate a time difference between two time stamps:
4. Illumina NGS Low Plexity Pooling Checker: checks if the complexity of a pooled sample is good enough for a successful run:
Any data type that can be used by openBIS properties is supported by dynamic properties. The script always returns just a string representation of a property value. The value is then validated and in special cases converted before being saved. The string formats and validation rules are the same as in batch import/update of samples/experiments/data sets/materials.
The non-trivial cases are properties with data type:
- CONTROLLED VOCABULARY - use code of vocabulary term as string representation,
- MATERIAL - use function
material(code, typeCode)to create the string representation.
Creating and Deploying Java Plugins
To create valid Java plugin for Dynamic Properties, one should create a class that is implementing
ch.systemsx.cisd.openbis.generic.server.dataaccess.dynamic_property.calculator.api.IDynamicPropertyCalculatorHotDeployPlugin interface. The class should be annotated with
ch.ethz.cisd.hotdeploy.PluginInfo annotation specifying the name of the plugin, and
ch.systemsx.cisd.openbis.generic.server.dataaccess.dynamic_property.calculator.api.IDynamicPropertyCalculatorHotDeployPlugin class as a plugin type.
Such a plugin should be exported to a jar file and put into
<<openBIS installation directory>>/servers/entity-related-plugins/dynamic-properties directory. The plugin will be detected automatically and will be automatically available to openBIS. No restart is needed.
Dynamic properties evaluator
Evaluation of dynamic properties may be very time consuming, therefore it is not done automatically after each metadata update. To make sure that the potential inconsistencies are repaired, the maintenance task can be defined (
service.properties), that runs in specified intervals:
If the value of a dynamic property has not yet been calculated, it will be shown as