Simple property restriction
See also: Field restriction
Restrictions – Abstract
Purpose: The Simple property restriction defines a search criterion that compares a suitable Projection with a static compare value or $null.
The Simple property restriction can replace a Field restriction if the following conditions are met:
The check value can be accessed directly in the context of the search via Property projection (Projection).
The Projection returns a simple value with one of the following data types:
Text (String)
Integer (Long or Integer)
Boolean value (Boolean)
As a compare value, a static value of the same data type should be compared.
The compare type is supported for the data type to be evaluated (see Field restriction).
The Simple property restriction can also be used in the following special cases:
Special case: Testing without a compare value
If the Projection refers to a suitable property, you can check whether it is filled with any value (!=$null) or empty (==$null).
None of the compare value parameters (String value, Long value, Int value, Boolean value) may be assigned a value for the comparison.
►NOTE◄ The screenshot above shows the neutral state (==$null) of the Check box for the Boolean value, which is explicitly distinguished here from $false.
In principle, properties of all simple data types are suitable for a 'filled' or 'empty' check, as long as the path specified as a Projection can be interpreted by the database.
For properties with a complex data type that do not reference complete entities – this already includes a 'Date/Time' (DateTime) with the 'Date value' (dateValue) and 'Time zone' (timeZone) properties – the check against $null is carried out on the database side for each property.
Linked entity properties are only retained in the database as a long reference to the 'ID' of the entity instance even if the 'Reference only' option is deselected. A check without a compare value therefore refers to a simple Long property.
With regard to plural content, the following cases must be distinguished:
If a 'list field' refers to a Duplicatable entity, e.g. also the 'Line items' (lineItems) property for a Hierarchical business object, a specific property of the entity type repeated as a 'list entry' should be addressed as the check value, which excludes 'No value' ($null) as a value by definition.
For all entity types, the 'ID' (id) property of the repeated entity can be compared with $null to check whether the 'list' contains at least one entry or not.
Predefined entity types can provide plural properties for references to other entities – e.g. 'Parent companies' (parentCompanies) for Company accounts – which are mapped superficially as a multi-select (Multiselect combobox) and in the data object as a list of Long values.
In this case, only the path for the 'list field' (e.g. parentCompanies) can be selected as the Projection. The Long values available as entries are used as the check value. A comparison with 'No value' (==$null) is considered to have passed if there is no entry. The reversal of the check condition (!=$null) is fulfilled if the 'list' contains at least one Long value.
►NOTE◄ No generic construct for a plural reference is available for Custom type definition (or Custom fields). In this respect, this is a special case.
A 'list field', which, like the attributes property in the object model, combines entries of different data types, is categorically excluded as a test value for a restriction.
A comparison can only be interpreted as a restriction in a database query if the addressed 'list' is related to exactly one specific database table.
Special case: Check enumeration values
The configuration for the Simple property restriction does not provide a selection field that can be used to select enumeration values as a compare value.
Nevertheless, for a Projection that provides an enumeration value as a check value, comparisons with a static String value as a compare value are supported in certain cases, depending on the selected Compare type:
If the Projection refers to a property of an entity whose data structure establishes a clear reference to a static or dynamic enumeration, attempts will be made for comparisons using the Compare type == , =,!= ,<, <=, > , or >= to convert the specified String value into a value of the enumeration. If successful, the numerical value in the 'ordinal' (ordinal) property for the respective dynamic enumeration value is used as the check value and the compare value.
The type conversion is successful if a static String value is specified that matches the internal name (name) of a value from the relevant static or dynamic enumeration exactly (including upper/lower case letters).
If the type conversion fails, the check value and compare value for the Compare type ==, = or != are not considered to match. An error occurs for other compare types.
If the Projection refers to the 'Unit' (unit) property for a Number with unit field, an attempt is made to convert the String value specified as the compare value into the enumeration value for the corresponding unit (see Units) for comparisons with Compare type == , =,!= ,<, <=, > or >=. If this is successful, the value in the 'Alias' property for the corresponding dynamic enumeration value is used as the check value and the compare value.
The type conversion is successful if a static String value is specified that matches the alias (alias) of the unit (see Units) exactly (including upper/lower case letters).
If the type conversion fails, $null is used as the compare value and evaluated depending on the Compare type.
If the Projection refers to the field of an entity whose data structure establishes a unique reference to a dynamic enumeration, the Compare type like, not like, ilike or not ilike uses the String value specified as the compare value as the pattern for a match.
For pattern matching, the localization applicable in the execution context is used as the check value for the dynamic enumeration value provided by the Projection.
Pattern matching interprets wildcard characters (_ and %) contained in the String value. The Compare type determines whether upper/lower case letters are taken into account.
►NOTE◄ If there is no localization for a dynamic enumeration value (neither for the Current locale nor for the fallback language 'English'), the internal name (name) is used as the check value for pattern matching.
►IMPORTANT◄ The scenarios described here illustrate configuration options that are technically feasible but only recommended in a very limited way.
In a Field restriction, enumeration values can be provided 'cleanly' as a compare value via value resolvers of the Static values category (see Any static enumeration, Any dynamic enumeration and Unit, without requiring a type conversion based on a String value.
Relative comparisons (with Compare type < , <= , > or >= ) with enumeration values that refer to 'ordinal' values are generally assessed critically, as the ordinals can differ between systems (e.g. test/productive). In contrast to a match check (with Compare type ==, = or !=), the 'sorting sequence' and therefore the result of a comparison can therefore be different for each system.
Pattern matching (with Compare type like , not like, ilike or not ilike), which is required to target the localization texts for dynamic enumeration values, only works stably if it is known at configuration time which Current locale applies at runtime. Alternatively, localizations for the relevant enumeration are consistently omitted or only the fallback language English is localized. Or only patterns for which the localizations used in all languages either match or do not match are checked. However, such conventions are always vulnerable and experience has shown that they can only be 'kept on track' through great discipline or considerable regulatory effort.
► NOTE ◄ It is not always an advantage to use a Simple property restriction if these conditions are met . The savings potential for the effort involved in interactive configuration is limited and is neutralized at the latest if a change to Field restriction is subsequently required . However, it may be possible to benefit from the simpler internal structure if the restriction is used in a profile (see example below) or has to be subsequently adapted in the context of a Search (Event action).
The following table compares a Simple property restriction with an identical Field restriction using the example of a typical configuration for a condition in a search with the entity type 'User' (see Users).
|
Configuration in the user interface |
|
|
|
►NOTE◄ The effort for the interactive configuration of a Field restriction differs only minimally from that for the Simple property restriction with the same content, especially as a Property projection for the check value (top left) is already suggested when a Field restriction is added. To be more precise, the simplification only affects the selection of the value resolver (top right) for the static compare value (see Static values). |
|
Definition of the condition in the XML structure of the search |
|
<core:SimplePropertySearch projection="username" compareType="ilike" stringValue="ad%"/> ►NOTE◄ In terms of the complexity of the XML structure, the Simple property restriction differs significantly from the equivalent Field restriction shown on the right. Typically, the Simple property restriction is therefore preferred if the restriction in question is to be used in the context of a Lobster_data profile (see below). The simplified structure in XML improves the 'readability' of the structure – if relevant at all depending on the context of use – and simplifies mapping if, for example, the Compare type or the – technically still 'static' – compare value is to be assigned dynamically during Import depending on the source data. |
<core:PropertySearch> |
|
Appearance of the restriction in mapping (example Import, see Lobster_data integration) |
|
|
The restriction configured above can, for example, be copied from a configuration created for test purposes in the Search builder in the XML tab and transferred to the target structure of an Import profile via the clipboard. The screenshots above and to the right clearly show the difference in complexity. The structure shown above for a Simple property restriction (SimplePropertySearch) appears almost directly 'readable' if the columns for data type and fixed value are activated in the target structure. In contrast, it is much more difficult to understand that the Field restriction (PropertySearch) on the right 'encodes' the same restriction. |
|
Configuration
|
Parameter |
Description |
|
Projection |
As a required field, the Projection parameter must define a valid path to a data field in the context of the search, which can be specified by direct input (if necessary with the [+] symbol) or by selection in the dropdown (with search function). The dropdown provides paths to all fields that directly or indirectly affect the entity type in the context of the search or an entity additionally included via Joins. ►IMPORTANT◄ The dropdown does not restrict the selection options to paths to properties whose data type supports a Simple property restriction. Paths can therefore also be selected for which the comparison at runtime results in an error message. |
|
Compare type |
For the Compare type parameter, the dropdown offers all compare types for selection that are also available for the Field restriction (see there for details). |
|
Compare value parameter (for alternative use – see note below) |
|
|
Character string |
Static text value for text comparisons (including like/not like and ilike/not ilike) |
|
Long value |
Static Long value for numerical comparisons |
|
Int value |
Static Integer value for numerical comparisons |
|
Boolean value |
Static Boolean value for comparisons with truth values |
►NOTE◄Each change to the value for the compare value parameter causes an existing entry for one of the other compare value parameters to be deleted.
Examples
Simple use case: Identifying 'active' user accounts
A Tuple search for Users should be restricted to 'active' accounts, i.e. only those for which the Boolean property 'Active' (active) contains the value true.
Configuration:
|
A Simple property restriction defines the required Where condition for the Tuple search:
►NOTE◄ We simply have to 'know' that the 'Active' (active) property is of the Boolean data type. The system does not provide any clues about the data type of the Projection during configuration. In contrast, when configuring the same condition as a Field restriction for the compare value, the appropriate value resolver (Boolean value) is automatically suggested. However, the text value 'true' could also be specified here as a String value or an integer other than 0 as a Long value or Int value to achieve the same result, as Lobster Data Platform / Orchestration then attempts an automatic type conversion for the compare value to the type of check value. |
|
Variant:
A restriction to 'inactive' Users can be achieved with different configurations:
|
If the Boolean value Check box is unchecked, the search result only contains user accounts for which the 'Active' (active)field explicitly contains the value false. ►NOTE◄It is important to know that the data model for Users specifies that the 'Active' property must not contain the value $null (see Boolean field – option 'Nullable'). Only then will the restriction shown on the right reliably list all Users that are not defined as 'Active'. |
|
|
The variant shown on the right uses the Compare type != in conjunction with the selected Check box Boolean value. If a Boolean field is selected as the Projection that allows $null as a value, this Simple property restriction would apply with the value false as well as with the value $null as passed. |
|
|
The variant shown on the right was created based on the original solution by selecting the not menu option:
The Simple property restriction with the condition active == true is thus negated overall, i.e. 'negated'. By selecting the negation, the Simple property restriction is automatically inserted into a parent Search junction, which is required as the carrier of the negation. Even with this variant, the search could return 'matches' with the values false and $null if the Projection allowed $null as a value. |
|
