Entity join
An Entity join uses the On condition to include assigned instances of the entity type selected as the Entity in a search under the name specified as the Join alias.
In contrast to all other Joins, the Entity join is based exclusively on the condition explicitly formulated in the Join alias. Other relationships between entities in the search and the joined instances are neither expected nor taken into account.
The relationship to the entity type selected as the Entity can therefore be defined completely arbitrarily via the On condition.
►IMPORTANT◄ The access restrictions that may apply to the main entity of a search due to ownership, participation and Company authorizations categorically do not apply to access to instances of the entity type selected as the Entity.
Configuration
|
Parameter |
Data type |
Description |
|
Specific parameter |
||
|
Entity |
Entity type |
Any entity type can be selected as the Entity. The Combobox also offers options that cannot be selected as a (main) 'entity' for a search. Example:
|
|
Generic parameters |
||
|
Join alias |
String |
A string that uniquely identifies the entity provided by the join as a prefix in the data field path must be specified as the Join alias.
Characters that are not permitted for a Join alias (such as the space or period) are automatically replaced by an underscore:
|
|
|
||
|
Join type |
Enumeration value |
By default, the Join type 'Left' (LEFT) is preset so that the Entity join has no restrictive effect on the search even if the On condition does not return any matches. The Join type 'Inner' (INNER) can act as a restriction for the search if the Optional option is unchecked. Only results for which the Entity join has 'contributed' at least one match based on the On condition will then appear in the search result. |
|
Optional |
Boolean |
The Optional option is checked by default. The relevant Join is then only transferred to the database query at runtime if projections require this. |
|
►NOTE◄ As long as a join defined as Optional is not executed at runtime due to a lack of necessity, any errors in its configuration cannot be detected. This can give the misleading impression that a certain On condition only works in an optional join. In reality, however, the 'optional' join may not take place at all on the database side. |
||
|
On condition |
Restriction |
The On condition optionally defines which criterion (see Restrictions) must be fulfilled for a join to contribute data to the search result. Typically, the On condition relates data from entities that are 'candidates' for an assignment from the perspective of the join to data from entities that may be the target of the assignment. Projections for 'candidates' use the Join alias as a prefix. If no On condition is specified, the Entity join assigns all instances of the entity type selected by Entity. Depending on other parameters in the search, their number can multiply the number of search result rows. ►NOTE◄ In the language used for the Join type (LEFT, INNER, RIGHT), the 'candidates' are always on the 'right-hand side' of the relationship established by the join. The positioning within any Field restriction used as a check value or compare value is irrelevant in this respect:
|
... enables ... 
... is replaced by ... 
CAUTION
is interchangable to 
Examples
Simple use case: Access to the owner account of a user
Like every entity type, Users also use a Long property 'owner' (ownerId), which can be used to refer to the 'ID' (id) property of a company that is considered the 'owner' of a specific user.
The data model of the entity (here: user) only contains the Long value of the reference, so that detailed data on the owner company must be included in a search via a join if required.
Specifically, a CSV search should combine the 'username' (username) and the 'owner' (ownerId) properties from the user account with the 'account number' (address.accNumber) address property of the owner company.
Configuration:
|
The screenshot on the right shows the configuration for the CSV search with Projections and Joins:
The assignment of the 'owner' company for each user is regulated by the Entity join:
|
|
A special feature of this use case is that the join can only return exactly one or no hits for each user among the company accounts and not several,
There are two cases in which the join does not provide a company account:
The company account referenced as 'owner' no longer exists because it has been deleted.
'No owner' is referenced for a user. In this case, the 'owner' (ownerId) property is automatically assigned the value -1, which no company account can use.
In both cases, no assignment is made, which in this case (in conjunction with the 'Inner' Join type) means that the user in question does not appear in the results list.
Variant:
Instead of a CSV search, a 'normal' Search is carried out, which lists complete Users instances to which an 'owner' account has been successfully assigned.
|
In the Search builder, the 'Search type' for the existing configuration can be changed from CSV search to Search. This eliminates the Projections and only the Entity join shown on the right remains:
|
|
Special use case: SELF JOIN to search for duplicates
Many configurations such as Association criteria or Event handlingg have a 'name' (name) property in which a text can be entered that should identify the configuration element in question with appropriate precision to enable quick identification (e.g. in an overview or a dropdown).
It is not absolutely necessary for the assigned 'name' within the respective entity type to be unique, as these configurations – like all entities – are identified by the system using their unique and automatically assigned 'ID' (id).
In order to maintain a certain degree of transparency, it can do no harm, for example, to search periodically or on an ad hoc basis for names that have been assigned more than once in the context of implementation.
In the following example, a CSV search determines such 'duplicates' for Association criteria.
Configuration:
|
As a minimum, the CSV search should contain three Projections for output columns:
|
|
|
The screenshot on the right shows the On condition that maps the criterion for the assignment of duplicates as a Search junction with an AND junction from two instances of the Field restriction:
The alias data record should only be assigned to the parent data record if both conditions are met. ►IMPORTANT◄ If the search is carried out in a context in which access restrictions for reading (='searching') Association criteria are applicable, it should be noted that these only affect the main level of the search (i.e. the 'left' side of the join). The comparison is therefore not carried out according to the scheme "all association criteria" vs. "all (other) association criteria". Instead, it only checks whether there are any duplicates (alias) for all readable Association criteria with regard to the name. As no access restrictions are taken into account for the alias side of the comparison ('right' in the join), the search may also show duplicates that relate to 'unreadable' Association criteria. |
|
