Conditions
Contents
Conditions are used in several places within Calpendo, most notably Searching, WorkFlows and Permissions and Booking Rules. Understanding Conditions is essential in order to be able to configure Calpendo 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 or Booking Rule applies. This chapter will show how to use conditions for the more complex tasks required in WorkFlows, and Permissions and Booking Rules.
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 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:
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: :
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.
Everywhere that conditions are used, they appear in a panel that looks something like this in a writeable context:
When there are no conditions, it looks like this in a writeable context:
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.
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.
For Booking Rules, the context Bisikit Type is Booking. The New Value is available when the action being controlled is Update and not when the action is anything else.
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:
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:
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.
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.
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 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.
|
This is the standard choice of relations for an integer or floating point number property.
|
|
A date property displays with semantically identical options, but using different words to match the English you would expect. |
|
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. |
|
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. |
|
If the property is of type Biskit and is a collection of any Biskit contains relations are available. |
|
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. |
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:
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.
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.
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) :
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.
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 Calpendo 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.
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.
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 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.
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.
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)
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.
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