Where to add a new rule

In the workflows/ directory, jflow provides a rules.py file where new types can be added.

jflow/
├── bin/
├── docs/
├── src/
├── workflows/
│   ├── components/
│   ├── extparsers/
│   ├── __init__.py
│   ├── formats.py
│   ├── rules.py   [ file where to add new jflow rules ]
│   └── types.py
├── applications.properties
└── README

How to add a new rule

Their are three types of rules : simple rules, link rules and conditional link rules.

Simple rules

To create a such rule, create a class that inherit from the SimpleRule class:

class YourRule (SimpleRule):
	def check():
		# Your code

Into the check() function, write how to check the rule.

As the rule inherit from SimpleRule class, it has some attributes already defined:

Name	Type	Description
user_args	Dict	Dictionary describing arguments given by the user: name of each parameter as key, associated with their own values.
wf_instance	Workflow instance	The workflow instance object.
parameter_name	string	Name of the parameter containing the rule.
parameter_value	string	Value of the parameter containing the rule.
all_files	List	List of all files given by the user, in any parameter.
wf_parameter	Parameter instance	The parameter object containing the rule.
is_file_list	boolean	True if the parameter is an input file list.
is_a_file	boolean	True if the parameter is an input file.
is_file	boolean	True if the parameter is an input file or an input file list.
is_directory	boolean	True if the parameter is an input directory
is_file_or_directory	boolean	True if the parameter is an input file, an input file list or an input directory.
nb_rows	Dict	Number of rows for each MultipleParameterList. Example: {sample:3, data:2}, where sample and data are the name of tow MultipleParameterList.

Link rules

These rules are like simple rules, but acts not only for the parameter into the rule is defined

To create the rule, create a class that inherit from the LinkRule class:

class YourRule (LinkRule):
	def check():
		# Your code

Into the check() function, write how to check the rule.

As the rule inherit from the SimpleRule class, it has the same attributes a Simple rule have. But it has also additional attributes:

Name	Type	Description
targets_args	List	List of arguments the rules acts on.

Conditional rules

These rules are like simple rules, but are enabled only if the parameter has one of given values.

To create the rule, create a class that inherit from the Conditional class:

class YourRule (ConditionalRule):
	def check():
		# Your code

Into the check() function, write how to check the rule.

As the rule inherit from the SimpleRule class, it has the same attributes a Simple rule have. But it has also additional attributes:

Name	Type	Description
conditions	List	List of parameter values that enabled the rule.
condition_raised	string	Value that enables the parameter if any, else None

Raise an error or a warning in a rule

Into the check() function of your rule, when the rule generate an error, use the function self.error().
Example: self.error("Parameter " + self.parameter_name + " was not correct").

If the rule generate a warning, use the function self.warning() instead.
Example: self.warning("Parameter " + self.parameter_name + " will be ignored")

How to use a new rule

To add a rule on a parameter, define the argument "rule" on the add_parameter function of the workflow. The rule is written as follow, depending of the type of rule. To use several rules on the same parameter, join them by a ";".

Rules can also be added to inputs (files, files list, directories) and multiple parameters, on their dedicated function.

Simple rules

Just write the name of the rule. Warning: this name is case-sensitive

Example: Unique

Link rules

Write the name of the rule, followed by a "=" and the list of the other parameters (targets) the rule acts on.

Example: Exclude=param_1,param_2

Conditional rules

The syntax of this rule is like that: <name_of_the_rule>?(ALL|ANY)[<conditions>].

ALL or ANY: if ALL is set, all conditions must be raised to activate the rule. If ANY is set, the condition is raised if at least one condition is raised.

Conditions are written with this structure : <parameter_name>=<parameter_value> (if parameter must be equal to value) or <parameter_name>!=<parameter_value> (if parameter must be not equal to value. The parameter name is the name of a workflow parameter. If the parameter is the one into the rule is defined, we can use the keyword self instead of its name.
Special values:

parameter_name=*: condition is raised if the parameter is given, regardless of its value
parameter_name=None: condition is raised if the parameter is not given

Example : RequiredIf?ALL[param_1=value_1,param_2!=value_2].