Property projection

Projection – Abstract

Purpose: Returns the value of a property of an entity from the context of the query.

images/download/attachments/155419139/image-2023-10-25_16-12-29-version-1-modificationdate-1698243150369-api-v2.png

A Property projection returns the value of a property of an entity, provided that access to the selected Property is technically representable.

The Property projection is the most important projection to get values for output columns, Restrictions and for grouping and sorting search results from the database.

  • In contrast to a Collection projection, a Property projection usually returns single values. If a Property is selected that affects the n-page in a (1:n) relation, the access via a Property projection generates (at least internally) one line for each value of the n-page.

  • Depending on the data type of the property specified in the type definition for the entity in question, a property value can be a simple value or a more or less complex data object.

►IMPORTANT◄ In order to conveniently access the fields of attributes of an entity, it is generally convenient to use one of the following specialized Projections:

Both Projections offer a Property parameter that can be used to optionally access a specific field in the value of the attribute.

►NOTE◄ If the Property projection defines an output column (in a CSV or tuple search), the field value may be subject to some 'formatting'
Example:

  • A dynamic enumeration value is generally persisted in the database as a Long value (ordinal), while its internal 'name' (name) appears in a CSV output column, and a DynamicEnumValue object (with the name XML attribute) appears in a tuple search.

  • When a Property projection 'reads' the address Property in a search for Users or Company accounts, the output in a CSV search returns the string image of the address entity (e.g. 21052:de.lobster.scm.base.address.Address@1c6bbbc7), i.e. little 'user-friendly' information apart from the prefixed ID (here: 21052). In contrast, a tuple search returns the 'address' entity completely as a complex value, so that all details can be 'extracted' from the search result afterwards.

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 'path' to the read property is assigned as column name (if relevant). The path may start with a JOIN alias defined within the search followed by one or more internal field names. The period (.) serves as a separator.
    Examples: address.name1 ('name' from the address of a Users entity), owner.address.countryCode ('country' in the address of a company account included via a Entity join with the alias owner).

Property

 
String
(Selection field)

images/download/attachments/155419139/image-2023-10-25_16-13-46-version-1-modificationdate-1698243227105-api-v2.png

From a purely technical point of view, the Property parameter is a String that must be interpretable in the context of the search as a path to a property of an entity type contained in the context of the query, otherwise an error will occur when the search is executed.

In the user interface, a Combobox element with search function appears for the Property, which offers all possible paths to properties available in the context for selection via a dropdown. If available, localization texts are used in addition to the internal names that are decisive for the path.

►NOTE◄

  • Offered paths are not suitable in every case, e.g. to define a Property projection for an immediate output column (e.g. property attributes in the context of an entity type that may have attributes).

  • An asterisk (*) after the localized property name (in the screenshot: Benuztername*) indicates that an index is maintained for the property on the database side. In view of the performance of a search, indexed properties should preferably be used to formulate Restrictions (for search or join criteria).

  • Depending on the context, selection options may appear with the alias name _parentQuery, which – e.g. in the context of a Sub search – refers generically to the parent search and allows access to its properties.

  • As shown in the image, by clicking on the [+] symbol, the Combobox element may accept text values for paths that are not included in the dropdown. However, this almost always results in errors when the search is executed.

Example

Simple example: Field restriction for a search

The Where condition of a search for any entity type should filter out those instances for the entity that have the same timestamp in the 'Last modified' (lastModified) property as in the 'Created' (created) property.

The search lists all entities of the selected type that have been saved exactly once so far – at 'creation' (see Common action event) and whose data status has not changed since then.

Configuration:

The screenshot shows the configuration for the Where condition in a search:

The Name is irrelevant here, as it will not appear in the search result.

►NOTE◄ As can be seen in the screenshot, the property name appears with an asterisk (*) in both cases. These are therefore indexed properties.

images/download/attachments/155419139/image-2023-10-25_17-26-43-version-1-modificationdate-1698247604285-api-v2.png

►IMPORTANT◄ When configuring the Field restriction, note that the context menu for the check value (left) offers only Projections for selection. For the compare value, on the other hand, either Projections or Resolvers (for constant values) can be used. The Projections appear in the context menu for the compare value (right) in a separate 'Search' category.

Simple example: Output columns' for properties in a tuple or CSV search

In the context of a tuple or CSV search, all 'output columns' must be explicitly defined by Projections.

In the result of a search for Users, the 'Username' (username) and the assigned role(s) should appear.

Configuration:

In the context of a CSV search for the 'User' (see Users) entity type, we define two output columns:

  • The first column refers via Property projection to the 'Username' (username) Property, which contains a text value (String), and assigns USER as the Name.

  • The second column refers via Property projection to the 'Roles' Property, which contains the Roles assigned to the user account as a list of Long values, and assigns ROLE as the Name.

►NOTE◄ As the following runtime example shows, the label 'ROLES' would be misleading.

images/download/attachments/155419139/image-2023-10-25_17-30-36-version-1-modificationdate-1698247836630-api-v2.png

Runtime example:

As the query result (right) shows, multiple lines appear for the same USER if it has more than one role to choose from.

The Property projection on the 'multi-value' roles property leads to the multiplication of the user data (here: USER) per role. The ROLE column always outputs exactly one ID of a role.

 
USER,ROLE
ABC,1001
ABC,501
DEF,1201
DEF,501
DEF,1351
DEF,1001
GHI,1352
GHI,1
XYZ,1352

►NOTE◄ To output multiple roles within the same USER line, one could use a Collection projection.

More complex example: Obtain 'role name' instead of ID via JOIN

Based on the previous example, the role should no longer be identified by ID but by role name (roleName).

Since only the Long reference is included in the user account, we need to explicitly add each referenced role entity to the context of the CSV search to access the role name.

We can do this, for example, using a Entity join.

Configuration:

To the CSV search from the previous example, we add a Entity join that is parameterized as shown on the right:

  • The Entity of the data object for the join is 'Role' (Role).

  • As a Join alias we arbitrarily choose the abbreviation r (for Role).

  • As a Join type we choose 'Inner', because we can assume that a 'Role' is found for each role ID.

  • The On condition uses a Field restriction to describe the relationship between the 'User' entity type searched for and the 'Role' (r) entity type added via a Join:

    • As a check value (left), we use a Property projection to pull the 'Roles' property in the user account.

    • As a compare value (on the right) we use another Property projection for the 'ID' (id) property within the role (r). The path 'r.id' is automatically provided in the dropdown and even appears partially localized as 'r.ID'.

►NOTE◄ Since the On condition refers to a 'multi-value' field of the entity, the condition is checked against all single values listed in the 'Roles' property. The join assigns the referenced role (r) to each roles entry.

images/download/attachments/155419139/image-2023-10-25_17-32-22-version-1-modificationdate-1698247943376-api-v2.png

Once the Entity join is configured, the range for paths expands in the context of our Projections:

  • The Property projection USER remains unchanged.

  • In the Property projection ROLE we now change the property from the 'Roles' (roles) property to the recently available path r.roleName, which is offered in the dropdown as 'r.roleName' (partially localized).

images/download/attachments/155419139/image-2023-10-25_17-34-39-version-1-modificationdate-1698248079557-api-v2.png

Laufzeitbeispiel:

USER,ROLE
ABC,Querificus
ABC,Super user limited
DEF,Super user limited
DEF,Querificus
DEF,Upload
DEF,Administrator
GHI,Tester
GHI,Super User
XYZ,Tester

We now use the existing Projection as a basis for ordering the results list

A Property projection for a projection can be copied to the clipboard via the context menu (see menu symbol at the top left within the Property projection) and then pasted in the context of the Order by via the context menu as a projection added using the images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/add.svg symbol.

As you can see in the screenshot, our sorting should be done first by role name and then by user name.

►NOTE◄ A reference to an already defined 'output column' via the column alias (here: ROLE, USER) cannot be established based on the Order by (and also Group by). The same projection must therefore be created multiple times if required (as in our example). The Name used is irrelevant, but was 'taken along' here when copying.

images/download/attachments/155419139/image-2023-10-25_17-35-3-version-1-modificationdate-1698248103556-api-v2.png

Laufzeitbeispiel:

USER,ROLE
DEF,Administrator
ABC,Querificus
DEF,Querificus
GHI,Super User
ABC,Super user limited
DEF,Super user limited
GHI,Tester
XYZ,Tester
DEF,Upload