Typed attribute projection

Projection – Abstract

Purpose: Enables simplified access to values of typed attributes (without explicit configuration of a Join).

images/download/attachments/161929139/image-2023-12-5_11-36-8-version-1-modificationdate-1701772582059-api-v2.png

A Typed attribute projection searches the attributes of the attribute owner defined by the context or an explicitly defined Attribute owner path for attributes with the specified Type.

Depending on the optional selection for the Property to be evaluated, either the complete attribute value or the value in the selected Property appears in the return value of the Typed attribute projection.

If the specified (sub)Type is considered a 'plural attribute' according to the relevant dynamic enumeration (e.g. Text type, Numeric types, etc.), then the Typed attribute projection may return several values for the same attribute owner as a list.

The interpretation of multi-value return values depends on the environment in which the Typed attribute projection is used.

  • For an output column, plural return values can be bundled using a Collection projection.

  • If several restrictions within a condition refer to the same (sub)Type via several instances of the Typed attribute projection, these are all evaluated for each attribute instance.

NOTE◄ Internally, the use of a Typed attribute projection implies a Typed attribute join for the relevant Type (Join type: 'LEFT', optional):

Typed attribute projection

images/download/attachments/161929139/image-2023-12-5_11-33-59-version-1-modificationdate-1701772453487-api-v2.png

The Typed attribute projection simplifies access to a Property attribute value:

  • The Join for attribute access is generated implicitly when the Property is accessed.

  • The user does not have to differentiate between attribute (ta) and attribute value (ta.value), as the selection for the Property already refers to the attribute value (value).

Equivalent: Typed attribute join ...

images/download/attachments/161929139/image-2023-12-5_11-35-4-version-1-modificationdate-1701772518207-api-v2.png

.., and Property projection

images/download/attachments/161929139/image-2023-12-5_11-35-41-version-1-modificationdate-1701772555851-api-v2.png

If several instances of the Typed attribute projection or explicitly configured Typed attribute join (with the Join type: 'LEFT') refer to the same Type, then only a LEFT JOIN is used 'together'.

Configuration

Parameter

Type

Description

Name

String

The optional Name parameter can be used to assign an (alias) name to the projection.

  • If no Name is specified, the name for the selected Property is used as the column name (if relevant).

Attribute owner path

Entity
(Projection)

An Attribute owner path only needs to be explicitly defined by configuring a Projection 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 Entity 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 Users, Companies/Clients).

Attribute

Class
(attribute type)

In the Combobox element for the Attribute parameter, a selection must be made from the options for the attribute type offered via a dropdown. Only the attribute types 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).

Type

Dynamic enumeration value (subtype)

The Combobox element for the Type parameter offers values from the dynamic enumeration that relate to the attribute type selected by Attribute (e.g. Text type → Text attribute, Numeric types → Numeric attribute, Company type → Company and address attribute, etc.).

NOTE◄ The options in the dropdown may be restricted in the context of the configuration by applicable Enumeration filters. However, these have no influence on the processing of already configured searches.

Property

Property (of the attribute value)

The Combobox element for the Property allows an optional single selection for one of the properties of the attribute type selected by Attribute.

  • If no selection is made for the Property, the Typed attribute projection returns the complete attribute value (value).

  • For plural (sub)types, access to the index property in the attribute value can be useful.

  • There is no access to the properties of the parent-level attribute Entity (such as the id), which contains the value property.

Examples

Simple example: Restriction for a Typed Attribute with singular subtype

In the context of user accounts, a typed attribute is used for the address to qualify 'preferred' users:

    • Attribute type: 'Flag attribute' (FlagAttribute)

    • (Sub)type: Flag type: VIP

A custom overview (see Custom overviews) should only display 'VIP users'.

Configuration:

The Restriction for the custom overview (see Custom overviews) is defined as a Field restriction as shown on the right:

  • The Check value (left) is obtained via a Typed attribute projection with the following parameters:

    • A Property projection to the address property of the user account must be configured here as the Attribute owner path, as Users themselves (by default, see Custom type definitions) cannot have any indicator attributes.

    • The attribute type 'Flag attribute' (FlagAttribute) is selected in the Attribute parameter.

    • The Flag type VIP is selected as the Type, i.e. the 'feature' that the restriction is aimed at.

    • The 'payload' in the flag attribute is the 'Flag value' (flagValue) property, which is therefore selected here as Property.

  • The Compare value (right) is determined as a static value directly via a Boolean value. A match (==) with the value true should be present here so that a user is listed in the overview.

images/download/attachments/161929139/image-2023-12-5_11-32-27-version-1-modificationdate-1701772361726-api-v2.png

More complex example: Display typed attribute with plural subtype in an overview

The Datagrid preferences overview regulates, which display columns can be shown in the context of an overview, among other things. While the Add column function offers predefined column configurations for selection for typed attributes with a singular subtype, projections for typed attributes with a plural subtype must be defined as a 'Custom column' without any corresponding help. Using the example of a typed attribute for the plural Text type 'Container No' (CONTAINER_NO), a possible configuration for this purpose in the context of the entity type 'Shipment' (see Shipments) will be shown.

Configuration:

Click on the Add column button to create a new Custom column whose Projection can be configured as shown on the right:

  • Each instance of the plural text attribute with the subtype 'Container No' (CONTAINER_NO) defines exactly one 'Container number' as a character string via its text value (textValue). As the column should display one shipment per line in the context of a Shipment overview, a Collection projection is used that summarizes all container numbers per shipment as a list value.

  • The Typed attribute resolver with the following configuration is used as the Collection projection:

    • The attribute type 'Text attribute' is selected as the Attribute.

    • The Text type 'Container No' (CONTAINER_NO) can then be selected as the Type.

    • The 'Text' (textValue) property is selected for the Property parameter, which is typically the decisive characteristic of the text attribute.

images/download/attachments/161929139/image-2023-12-11_9-0-19-version-1-modificationdate-1702281624583-api-v2.png


Runtime example:

The screenshot on the right shows sample data for the output of container numbers in the column labeled 'Container':

  • The list of text values supplied by the Collection projection is automatically formatted for output as a column in the format [<Eintrag>, <Eintrag>, ... ], because this corresponds to the string image of a list.

  • As the example shows, a filter expression for the text (here: '___U%') acts as a criterion for list entries from the Collection projection. Specifically, here only Shipmentsfor which at least one 'Container number' in the fourth position contains the letter 'U' appear in the list.

images/download/attachments/161929139/image-2023-12-11_8-10-30-version-1-modificationdate-1702278636338-api-v2.png

NOTE◄ The brackets ([]) and separators (, ) are not available for filter criteria, but could be processed in the Label expression for the 'Custom column' if required:

The Label expression shown on the right uses the $replace() function with a regular expression(^.(.*).$) to eliminate the first and last character – i.e. the square brackets ([]) that are not always desired in the output – by replacement.

images/download/attachments/161929139/image-2023-12-11_9-1-9-version-1-modificationdate-1702281674964-api-v2.png