properties-handled-by-scripts.md

Properties Handled By Scripts
====
 

##### Introduction

One of the reasons why openBIS is easily extensible and adjustible is
the concept of generic entities like samples, experiments, materials and
data sets. By adding domain specific properties to the mentioned
objects, instance administrator creates a data model specific to given
field of study. Values of configured properties will be defined by the
user upon creation or update of the entities (samples etc.).

In most cases values of properties must be provided directly by the
user. The default way of handling a property in openBIS can be changed
by instance admin defining a property that should be handled by a script
written in [Jython](http://www.jython.org) or Predeployed Plugin written
in Java. Jython plugins use Jython version configured by the
service.properties property `jython-version` which can be either 2.5 or
2.7.

##### Types of Scripts

There are two types of plugins that can be used for handling properties,
and one script type to perform validations on entities:

1.  **Dynamic Property Evaluator** (for properties referred to as
    *Dynamic Properties*)  
    -   for properties that **can't be modified by users**,
    -   values of such properties will be **evaluated automatically**
        using metadata already stored in openBIS (e.g. values of other
        properties of the same entity or connected entities),
    -   the script defines an expression or a function that returns a
        value for a *Dynamic Property* specified in the script
2.  **Managed Property Handler** (for properties referred to as *Managed
    Properties*)

 

1.  -   for properties that will be **indirectly modified by users**,
    -   the script alters default handling of a property by openBIS by
        defining functions that specify e.g.:  
        -   how the property should be **displayed** in entity detail
            view (e.g. as a table),
        -   **input fields** for modifying the property,

     

    -   -   **translation** and/or **validation** of user input.

2.  **Entity Validation**
    1.  performed after each update or creation of a given entity type.
    2.  the user provided script performs a validation, which can cancel
        the operation if the validation fails

##### Defining properties

To create a property that should be handled by a script perform the
following steps.

1.  Define a property type with appropriate name and data type
    (Administration->Property Types->New).
2.  Define a script that will handle the property
    (Administration->Scripts) or deploy a Java plugin. For details
    and examples of usage go to pages:  
    -   [Dynamic Properties](/display/openBISDoc2010/Dynamic+Properties)
    -   [Managed Properties](/display/openBISDoc2010/Managed+Properties)
    -   [Entity validation
        scripts](/display/openBISDoc2010/Entity+validation+scripts)
3.  Assign the created property type to chosen entity type using the
    created script (e.g. for samples: Administration->Property
    Types->Assign to Sample Type):  
    -   select Handled By Script checkbox,
    -   select the appropriate Script Type
    -   choose the Script
4.  The validation scripts are assigned to the type in the "Edit Type"
    section. (e.g Admin->Types->Samples. Select sample and click
    edit.)

![image info](img/)

 

 

 

 

 

-   No labels
 
Dynamic Properties
------------------

### Introduction

*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
Scripts](/display/openBISDoc2010/Properties+Handled+By+Scripts).

### Defining dynamic properties

To create a dynamic property:

-   Define a property type with appropriate name and data type
    (`Admin->Plugins→Add Plugin`)  
![image info](img/)
-   Choose `Dynamic Property Evaluator` from Plugin type dropdown list
    in the upper left corner.  
![image info](img/)
-   You may evaluate script on chosen entity in Script Tester section.

### Creating scripts

To edit existing dynamic property script, edit dynamic
property (`Admin→Plugins→(click on dynamic property)→Edit plugin`)

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:

    entity.<requested method>

Currently available methods that can be called on all kinds of entities
include:

-   `code()`
-   `property(propertyTypeCode)`
-   `propertyValue(propertyTypeCode)`
-   `propertyRendered(propertyTypeCode)`
-   `properties()`

For more details see
[IEntityAdaptor](https://openbis.ch/javadoc/20.10.x/javadoc-dynamic-api/ch/systemsx/cisd/openbis/generic/shared/hotdeploy_plugins/api/IEntityAdaptor.html)
(interface implemented by `entity`) and
[IEntityPropertyAdaptor](https://openbis.ch/javadoc/20.10.x/javadoc-dynamic-api/ch/systemsx/cisd/openbis/generic/shared/hotdeploy_plugins/api/IEntityPropertyAdaptor.html)
(interface implemented by each property).

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 `Script Editor`.

 

#### Simple Examples

1.  Show a value of a Sample property which is named 'Multiplicity'

  

    entity.propertyValue('Multiplicity')

  

2\. Takes an existing property and multiplies the value by 1.5

    float(entity.propertyValue('CONCENTRATION_ORIGINAL_ILLUMINA'))*1.5

  

  

#### Advanced Examples

1.  Show all entity properties as one dynamic property:

  

    def get_properties(e):  
        """Automatically creates entity description"""
        properties = e.properties()
        if properties is None:
            return "No properties defined"
        else:
            result = ""
            for p in properties:
                result = result + "\n" + p.propertyTypeCode() + ": " + p.renderedValue()
            return result
        
    def calculate(): 
        """Main script function. The result will be used as the value of appropriate dynamic property."""
        return get_properties(entity)