Conditions are used in several places within Exprodo DB, most notably Searching, WorkFlows and Permissions. Understanding Conditions is essential in order to be able to configure Exprodo DB properly because of their pervasive use. Their purpose is to allow you to specify what situations activate a WorkFlow , or to which situations a Permission applies. This chapter will show how to use conditions for the more complex tasks required in WorkFlows, and Permissions.

The Anatomy Of A Condition

A Condition extracts one or two properties from the context and checks whether a relation holds true. If it does, the Condition is said to match. A Condition consists of the following items, in this order:

 

The Anatomy of a Condition

 

The Condition Type indicates the source of a property.

The Property Path tells how to reach a property from that source.

The Relation provides an operator to compare the value of that property to another value.

The Value provides a value to do the comparison against, this may be another property.

The Accuracy specifies how accurate the comparison should be (used with dates).

 

The Condition Type and Property Path are always present, but the others may not be. For example, if the user hasn't selected a Property Path, then the Relation, Value and Accuracy do not show. If the context does not specify a Biskit Type, then when a Condition is first created, it will look like this:

 

conditions_newConditionNoDataType

 

The above picture shows the default Condition Type of Value with a red border because Value cannot be used without a Biskit Type being available in the context. The Property Path also has a red border and shows there are no properties available for the same reason. Choosing a Biskit Type of anything other than Any data type changes the Property Path selector to show there are now properties that can be selected: :

 

conditions_newConditionWithDataType

 

The Property Path selector still shows in red because a Property Path is required, but hasn't been selected yet. Clicking where it says Select a property would now generate a drop-down menu with a list of all the properties that exist on the Biskit Type selected in the current context.

The Conditions Panel

Everywhere that conditions are used, they appear in a panel that looks something like this in a writeable context:

 

searchConditionAndOr

 

When there are no conditions, it looks like this in a writeable context:

 

searchConditions

 

When editing Conditions, add a new Condition by pressing the Add Condition button. At any time clicking on the green + button will add a new condition after the current one, clicking the red - button will delete the condition the button is associated with.

 

Whenever there are multiple Conditions, they will appear in the Conditions Panel, each in their own row.

The Conditions Context

A Conditions Panel is subject to the context within which it is used. There are two parts to the context that affect the way the Conditions Panel behaves: the Biskit Type the condition is being placed upon, and whether used for an update so that there are two instances of the data available (the Old Value and the New Value) or whether there is just one instance available (the Value).

 

For a Permission , it's a very similar situation. The context Bisikit Type is the Bisikit Type that the Permission controls access to, and if the Permission applies to any Bisikit Type, then the context has no Bisikit Type. The New Value is available when the action being controlled is Update and not when the action is anything else.

 

For a Search the context Bisikit Type is the Bisikit Type that the Search is on, and the only Condition Type available is Value.

 

For a WorkFlow the context contains the information from all the previous triggers.

The Conditions Type

When a condition is created or edited, the type has a number of possible values:

 

Type

Value

Old Value

New Value

Meta-Property

Source#

 

Condition Type: Value

A Condition Type of Value means the condition will be placed upon the value of a property where there is no probability of change. For a Permission this means the value of the property on an object somebody is trying to Create or Delete.

 

A Condition Type of Value is only suitable when the condition context specifies a biskit type.

 

When a Condition Type of Value is specified, the property path will show all the properties of the type defined by the context's biskit type, and any properties that can be reached from those properties. When the context bisikit type is set to a Resource, clicking where it says Select a property shows this:

 

Click to expand

 

A Resource has a number of properties, as shown. One of them, Location, is itself an object that has properties of its own that can be selected. As soon as you select a property from the drop-down, the Relation part of the condition will change from No property path selected to something appropriate for the property selected (described further below).

Condition Type: Old Value

A Condition Type of Old Value means the condition will be placed upon the value of a property before any change has been made to it. For a Permission this means the value of the property on an object somebody is trying to Update.

 

The property path will display the same as for a Condition Type of Value.

Condition Type: New Value

A Condition Type of New Value is only available when a bisikit type has been specified, and even then only in some contexts. For a Permission or Booking Rule, a Condition Type of New Value is only available for the Update action. Selecting New Value means that the condition will be placed on the value of the property after the update has occurred.

 

The property path will display the same as for a Condition Type of Value.

Condition Type: Meta-Property

A Condition Type of Meta-Property is available in all contexts. When this type is selected, the property path displays the following:

 

Click to expand

 

A Meta-Property lets you place restrictions on:

the type of the data that was Created, Updated or Deleted

the date and time that the action took place

the user that caused the action

 

This is called a Meta-Property because it's not a property of whatever was created, updated or deleted, but rather, it's a property of the action itself.

Condition Type: Source#

A Condition Type of Source# is only available in Workflows and it shows all the properties available on the Biskit provided as output to the trigger with the Source#. If the action is not Update then the New and Old properties will hold identical data.

The Property Path

As described above, the properties shown in the property path depend upon the Condition Type selected. However, each property that is shown has it own way of being displayed, regardless of how it came to be there. For example, any date/time property that is shown will display with sub-properties.

 

searchConditionProperty

 

A Resource has a number of properties, as shown. One of them, Location, is itself an object that has properties of its own that can be selected. The Relation, Value and Accuracy part of the condition will not show unless a property path has been selected. Once a property is selected, the extra parts of the condition appear, and they reflect the type of the property selected and the choice of Condition Type.

The Relation

The Relation is only shown when there's a bisikit type in the context and a property path has been selected. The options displayed in the Relation drop-down menu differ depending on the type of property selected by the property path.

 

Click to expand

This is the standard choice of relations for an integer or floating point number property.

 

 

Click to expand

A date property displays with semantically identical options, but using different words to match the English you would expect.

 

Click to expand

Not all integer properties display using the above options. That's because some integer properties are defined as a bit set of values of named integers (see Bit Sets for details). A good example of this is a user's roles. There are up to 32 roles defined, and a user may be deemed to have any number of these roles. For such properties it doesn't make sense to compare two sets of roles using greater than or less than, and so the available relations are changed to reflect this.

 

Click to expand

A text property displays with options for comparison with the starting, ending or interior characters. Also available is pattern matching using the following:

 

^         The beginning of the line.

$         The end of the line.

.          Any character.

*          Zero or more times.

+         One or more times.

?         Once or not at all.

X | Y    Either X or Y.

{n}       Exactly n times.

{n,m}   At least n times but not more than m times.

[a-z]    Characters a to z.

[^a-z]   Any character other than a to z

 

Search conditions are not case sensitive, while non-search (WorkFlows, Permission or Booking Rule) conditions are case sensitive.

 

Depending on whether the pattern matching is going to be done in Java (WorkFlows, Permission or Booking Rule) or SQL (Search) will depend on which additional matching features are available. It is recommended that users only use the options listed above.

 

Click to expand

If the property is of type Biskit  and is a collection of any Biskit contains relations are available.

 

Click to expand

All the remaining property types don't support any notion of an ordering that could be used to specify a less than relation etc. So for these, the relations available are: equal, not equal to.

 

The Value

A drop-down menu is shown giving the choice for the Value. For any property that is not a date or date-time, it shows this:

 

conditions_valueNullNonDate

 

This gives a choice between a value that is Null (a special value meaning there is no value) and Fixed or Variable.

 

If Fixed is chosen then a further item will appear so that the value can be chosen. The item shown for the value entry will be appropriate to the type of the property indicated by the Property Path.

 

Click to expand

 

If Variable is chosen then the user can choose another Condition Type and repeats the process selecting either a property or meta-property to be compared to the original property or meta-property.

 

searchproperty

 

Date Properties And Accuracy

When dealing with dates there are some other options that are available. Whenever a property is asked for which stores a date two condition lines will appear, one for the start date and one for the finish date, the relation can then be set (see table earlier in the chapter for the full list available) :

 

searchConditionDate

 

Then set how accurate the date checking needs to be. There are four options against which the comparison can be made and then a level of accuracy to be used.

 

searchConditionDateExpanded

 

Date Accuracy

Description

now

The time specified but with a level of accuracy.

now plus

Within now plus a certain amount of time with a level of accuracy.

now minus

Within now minus a certain amount of time with a level of accuracy.

specified date

The specified date exactly. (No level of accuracy may be set.

 

The now option means that the value of the property to be compared against is to be the date and time that the comparison is done. The now plus and now minus options indicate that the date to be calculated is relative to the time the comparison is done. When selecting either of these options, a further item is displayed to input how much time to add or subtract from the time of the comparison to reach the date-time that the property is being compared against. If the specified date option is selected, then a date-time entry is displayed to input the exact point in time to compare the property against.

 

The Accuracy is only shown for date or date-time properties, and it specifies how accurately the comparison is to be. For example now plus 1 month to the month, if run in December will find everything in February.

 

Then, when the Condition is checked, and Exprodo DB compares two dates, it first rounds both dates down to the year, month, day, hour, minute or second. After rounding both dates, it then compares the dates using the specified relation.

Combination Option

Once all the conditions have been created, choose how logically the conditions will work together (the combination option). Click on the drop down button in the top left corner of the condition box.

 

Click to expand

 

Combination Option

Description (For the combination to be TRUE)

All

All the individual conditions must be true. (Logical AND)

Any

At least one of the individual conditions must be true. (Logical OR)

Not All

As long as not all the individual conditions are true, this includes none of the conditions being true. (Logical NAND)

None

As long as none of the individual conditions are true. (Logical NOR)

 

This creates the following search condition:

Resources where (location.name starts with h) and (type.name equals Room) and (requireCancellationReason equals True)

At this point use OK to save the condition and Cancel to start again.

Nested Conditions

Nested conditions allow as many levels of conditions as the user requires. Each set of nested conditions also has its own combination option allowing the user to create as complex an overall condition as possible.

 

Each nested set of conditions is evaluated separately, and the overall result of the nested condition is then used as an individual condition result as part of the level above's condition calculation.

 

In order to use advanced conditions tick the Show Advanced box. Once ticked the Create Advanced Condition icon appears at the top of the condition list and on each of the current conditions.

 

searchAdvancedConditions

 

Below the conditions have been expanded using a nested condition. The nested condition has two parts, name and collectUsage and it will be True if both sub conditions are True.

 

SearchAdvancedExample

 

This creates the following search condition:

 

Resources where (location.name starts with h) or ((name starts with d) and (collectUsage equals true)) or (type.name equals Room) or (requireCancellationReason equals true)

 

In order to test the condition the following steps will be used

 

1.Check the nested condition, if both conditions are True then the nested condition is True otherwise False (All conditions apply)

2.Check the top level condition, if any of the three top level conditions are True or the nested condition is True then the whole condition is True (Any condition applies)

Referenced

Ticking Show advanced allows the use of Referenced as a Condition Type. Using Referenced it is possible to search for BiskitDefs that are referenced by other BiskitDefs. Using the Relation Statement and the Value this can be further refined to find those that are referenced a number of times. e.g. more than once, less than three times etc.

 

Click to expand

 

When using Referenced the application looks for all those BiskitDefs that have a property which points to the BiskitDef that is the object of the search. In this case the search BiskitDef is Exprodo User the application will give a drop down that lists all the BiskitDefs that have a property that points to an Exprodo User BiskitDef. Expanding a BiskitDef will list the properties that are available. For instance Report has an owner property and Report Schedule has a users property.

 

As an example to find all those users that have created Reports, set Exprodo User as the BiskitDef to be searched for and Report.owner (owner is a pointer to an Exprodo User) as the property defined in the Property Path, returned will be a list of Exprodo Users that currently have Reports in the Report Manager. If the Relation Statement and Value are set to greater than 1 times, then only those users with two or more reports will be returned.

See Also:

The examples in Permissions