Singular attribute join

images/download/attachments/167860455/image-2024-1-31_13-8-9-version-1-modificationdate-1706702889434-api-v2.png

A Singular attribute join returns the value of the attribute type selected by the Attribute parameter, in the same way as a Singular attribute projection, based on the main entity of the search or a different Attribute owner path, provided the On condition is met.

NOTE◄ Unlike Joins, the Singular attribute join always returns exactly one (or no) attribute(s) as a return value for all other attribute types. This corresponds to the singular characteristic for the attribute types that can be selected as an Attribute.
In this context, the On condition can effectively only prevent any existing individual attribute from being returned or it has a restrictive effect on the relevant search as a whole in conjunction with the Join type 'Inner'.

Configuration

Parameter

Data type

Description

Specific parameters

Attribute owner path

Entity
(projection)

An Attribute owner path only needs to be explicitly defined by configuring a projection (see Projections) if the entity in the context of the search is not the owner of the attributes that are evaluated.

This is relevant in the following cases, for example:

  • The attribute owner is an entity included in the search via Datenobjekt Join.

  • The attribute owner is a position of an entity in the context of the search.

  • The attribute owner is an entity embedded in the entity data in the context of the search, e.g. the 'address' (address) of an account (see Benutzer, Firmen).

Attribute

Class
(attribute type)

A selection must be made in the Auswahlfeld/Combobox element for the Attribute parameter from the options offered via a dropdown for the attribute type.

Only the attribute types for singular attributes that the entity type of the applicable attribute owner supports per implementation are available for selection here.

NOTE◄ If no options are available for the Attribute or if options are missing, then the Attribute owner path may not have been set appropriately (e.g. the 'address' of an account for which no attributes are implemented).

Generic parameters

Join alias, Join type, Optional, On condition

see Entity join

Examples

Typical use case: Multiple projections on a singular attribute

Within a CSV search for a user-defined entity type 'Point of Interest' (POI), which can have a user-defined singular attribute 'PositionXyz' (PositionXyz), several properties from the attribute value (x, y, z) should be included as output columns.

Configuration:

The screenshot on the right shows the configuration for a Singular attribute join that controls multiple access to the singular attribute 'PositionXyz' (PositionXyz):

  • No Attribute owner path is required to access the attributes of the main entity of the CSV search.

  • 'PositionXyz' (PositionXyz) is selected as the Attribute.

  • The name pos is randomly assigned as the Join alias.

  • For Join type and Optional, the default (Left/Optional) is retained so that 'Points of Interest' without position information are also considered matches.

  • It is not necessary to define a On condition.

images/download/attachments/167860455/image-2024-1-31_13-7-32-version-1-modificationdate-1706702852335-api-v2.png

The detailed data from the PositionXyz attribute can be addressed via the Join alias pos for the Singular attribute join with multiple instances of the Property projection in Projections for output columns:

  • The first Property projection names the 'point of interest' based on a property of the main entity.

  • The following three Property projection instances first refer to the Join alias pos and then retrieve a specific detail (x, y, z) from its value property.

    NOTE◄ The use of descriptive column names (such as LATITUDE, LONGITUDE, ELEVATION) has only been omitted here so that the paths can be read when collapsed.

images/download/attachments/167860455/image-2024-1-31_13-4-45-version-1-modificationdate-1706702685609-api-v2.png

Runtime example:

As shown on the right, the CSV search may also return output lines for which no position information is available.

NOTE◄ The same result could be achieved if the Singular attribute join were omitted and three instances of the Singular attribute projection were used instead.

POI_NAME,pos.value.x,pos.value.y,pos.value.z
================================================
GREENWICH_PRIME_MERIDIAN,51.47781,-0.00148,223.0
TAJ_MAHAL,27.175,78.04194,240.0
PLANET_EARTH,,,
TOUR_EIFFEL,48.85822,2.2945,108.0

Variant:

The existing CSV search is adapted so that only 'point of interest' instances for which a position specification is available appear in the list.

Configuration:

The Singular attribute join can be adjusted as shown on the right to exclude 'point of interest' instances without any position information:

  • The Join type has been changed to 'Inner'.

  • The Optional option can remain checked.

  • A Field restriction has been introduced as an On condition, which checks whether the value property of any attribute found is not (!=) empty.

IMPORTANT◄ If the On condition was omitted, the case would not be covered if a 'point of interest' was saved at least once with a position specification whose detail fields (x, y, z) have since been deleted. An empty shell then remains for the attribute, unless this is removed by an explicitly configured event handling when saving.

images/download/attachments/167860455/image-2024-1-31_13-6-27-version-1-modificationdate-1706702788101-api-v2.png

Special use case: Conditional access to the singular attribute

The On condition in the previous example should now be adapted so that the CSV search lists all 'point of interest' instances, but the columns for the position specification only contain values if a certain Role rule is fulfilled for the session context.

Configuration:

The On condition shown on the right does not evaluate data from the Singular attribute join as an exception, but refers to the context of the session in a Field restriction with a trick:

  • A Literal projection provides the static Boolean value true as the check value (left).

  • The compare value (right) is also a static boolean value from the perspective of the search, which is obtained as the return value of a Role rule via a Rule value resolver before the search is executed. The Role rule checks whether a specific Role of session (here: 'Querificus') is registered, or whether the Role of session is directly or indirectly subordinate to this role.

IMPORTANT◄ Based on the variant (above), the Join type must be changed to 'Left'. With the Join type 'Inner', not only would the output columns for the position remain empty, but all result rows would be excluded.

images/download/attachments/167860455/image-2024-1-31_13-5-19-version-1-modificationdate-1706702719410-api-v2.png

Runtime example:

Role

Join type

Output

Querificus

Left

GREENWICH_PRIME_MERIDIAN,51.47781,-0.00148,223.0
TAJ_MAHAL,27.175,78.04194,240.0
PLANET_EARTH,,,
TOUR_EIFFEL,48.85822,2.2945,108.0
...

Other role (not 'Querificus' subordinate)

Left

GREENWICH_PRIME_MERIDIAN,,,
TAJ_MAHAL,,,
PLANET_EARTH,,,
TOUR_EIFFEL,,,
...

Inner

empty