Entity validation scripts are a mechanism to ensure metadata consistency. For each entity type a user can define a validation procedure, which will be performed at each creation or update of the entity of that type. There are two ways to define an entity validation procedure: Jython scripts and Java plugins.
Defining a Jython validation script
- Go to Admin -> Plugins -> Add Plugin.
- Select "Entity Validator" as the plugin type
- Choose name, entity kind, and description.
- Prepare a script (see paragraph "Script specification" below)
The script should at least include the validate function, that takes two parameters. The first one is the entity being validated, and the second is the boolean stating whether it is a new entity (creation) or an existing one(update).
- the function name should be 'validate'. It will be called with two parameters.
- the first argument is the entity. It will be the object implementing the IEntityAdaptor interface
- the second argument is the boolean "isNewEntity". It will be true if the entity is new.
- The script should return None (or nothing) if the validation is successful and a string with an error message, if the validation fails.
Triggering Validation of other Entities
A plugin can specify that another entity needs to be validated as well. For example, a change to a sample could require validation of its children. The infrastructure can be informed of this dependency by calling
requestValidation with the entity that needs to be validated as an argument.
Here is the example script that validates, that the newly created entity does not have any properties defined:
Activating the validation
To make the validation active per entity type you have to select the validation script for each type:
- Admin -> Types -> <Entity Kind> you selected also in the script definition ->
- Select a Sample Type and edit it
- You find a property which is called 'Validation Script' (see screen shot below). Just select your defined Script and hit save.
Creating and Deploying Java Validation Plugins
To create a valid Java plugin for Entity Validation, one should create a class that is implementing
the ch.systemsx.cisd.openbis.generic.server.dataaccess.entity_validation.IEntityValidatorHotDeployPlugin 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.entity_validation.IEntityValidatorHotDeployPlugin class as a plugin type.
All classes needed to run the plugin have to be exported to a jar file and put into
the directory <<openBIS installation directory>>/servers/entity-related-plugins/entity-validation. The plugin will be detected and made available automatically to openBIS. No restart is required for that.
When are validations performed
Validations are performed at the end of the transaction, not at the moment of the change. So if during some longer operation there are several updates to different entities, all of them are evaluated at the end, when all changes are available to the validation script.
Therefor it is possible to write for instance a dropbox that makes some updates that break validation temporarily, and still succeeds as long as the validations succeed after all the updates have been done.
- Validation scripts should be read-only.
- In theory it is possible to edit the entity during the validation. This is a bad practice. Consider using Dynamic Properties if you want calculations being performed after the entity updates.
- Think about performance
- The plugins will be executed for every creation or update of entities of that type. This can affect the performance drastically if the plugin will be too heavy.