Projection – Abstract

Purpose: Combines suitable return values from several Concat projections into a common string.

images/download/attachments/155420061/image-2023-11-3_9-55-35-version-1-modificationdate-1699001750978-api-v2.png

The Concatenated projection combines suitable return values from several Concat projections into a common string.

The number of concatenation projections is variable. The following cases must be distinguished:

Concatenated projections	Return value	Notes
multiple projections	Concatenation of the return values of all concatenated projections converted into character strings	Default case 'concatenation' The return values of all concatenation projections must be character strings or must be able to be converted into character strings in the database. The result of a type conversion may depend on the type of database system used or the settings made there. If a type conversion fails, the search as a whole results in an error. Special case 'type conversion to `String`': The Concatenated projection can be used to convert a value given by a projection into a string (`String`) according to the rules applicable in the database system. This is achieved by a purely formal 'concatenation' with an empty string ('') or `null` value (see example below).
exactly one projection	Return value of the single concatenation projection without type conversion	Special case 'no concatenation' The database-side SQL statement does not use the CONCAT() function, but returns the Concatenated projection directly. Its return value is not converted into a character string (`String`). In this respect, complex values (e.g. a 'date range with time' or an 'address' entity) can also be processed as an exception.
no projection	Empty string ('')	Special case 'no projection'

Configuration

Parameter	Type	Decription
Name	String	The optional Name parameter can be used to assign an (alias) name to the projection. If no Name is specified, the applicable column names from the Concat projections are concatenated without separators.
Concat projections
		The configuration for Concat projections is displayed in an Expandable element, which initially always appears 'collapsed'. The neighboring Text field element shows the number of Concat projections already configured. Clicking on the [+] symbol expands the detail area of the Expandable element.
		Initially, the list of Concat projections is empty. Only the read-only 'template' for the configuration then appears in the detail area. A click on the icon is then required to configure the first concatenated projection. In principle, any Projections can be used as concatenated projections within the Concatenated projection as long as they provide suitable return values.
		If Concat projections have already been set up, clicking on the icon inserts an additional concatenated projection below (='to') the one clicked on. ►IMPORTANT◄ A configuration must also be made for each concatenation projection instance created, otherwise an error message (`NullPointerException`) will occur when the search is executed. An 'undefined' concatenation projection such as the following must therefore be "specified" by clicking on the menu icon (left) or removed again using the dustbin icon (far right).
		To subsequently adjust the sequence of already configured Concat projections, they can be copied to the Lobster Data Platform / Orchestration clipboard using the context menu functions 'Copy' or 'Cut' in order to paste them in another position. On the other hand, the arrangement can also be easily edited in the tree view (on the left in the editor) by moving an individual interlinking projection to the new target position using drag & drop. In the specific example, the `countryCode-zipcode` concatenation' can be converted to `zipcode-countryCode` in two moves. This technique is also useful if you want to add an additional concatenation projection before the first instance. As usual, you can only add one subsequent instance to the list using the icon. However, this can then be easily moved to position 1 via the tree view.
		The more or less extensive list of Concat projections can be 'collapsed' again by clicking on the [-] symbol of the Expandable element. The configuration interface of the Concatenated projection then only shows how many concatenated projections there are, but no indication of their content.
		Clicking on the minus symbol (top right) minimizes the configuration interface so that the Concatenated projection is only displayed as a whole. Then, as can be seen in the image on the left for the specific case, the column names for the contained concatenated projections appear as text concatenations. However, this is only the case as long as the Name parameter is not used to explicitly assign a column name (e.g. `COUNTRY_ZIP`).

Examples

Typical use case: Concatenate property values

In the context of a CSV search for Users, the 'username' (username) and 'ID' (id) properties are concatenated using an underscore (_) as a separator in order to populate a 'proUser' column.

Configuration:

The screenshot on the right shows the configuration for the Concatenated projection:

The desired column name for the output is entered as the Name: proUser
Three Concat projections are configured:
- The first Property projection returns the value of the 'username' (username) property.
- The Literal projection includes the underscore (_) as a statically defined text character.
- In the third position, the Property projection provides the internal 'ID' (id) of the user account. The primary Long value provided is automatically converted into a string here.

images/download/attachments/155420061/image-2023-11-3_10-2-1-version-1-modificationdate-1699002136527-api-v2.png

Runtime example:

proUser

admindent_4151
adent2_2653
adent_2651
...

Special use case: Type conversion to a string (String)

In general, the 'Creator' (creatorId) and 'Last modified by ID' (lastModifierId) properties of an entity of any type directly reference the value in the 'ID' (id) property of the relevant user account.

However, the respective Long property (creatorId or lastModifierId) must not only be able to reference Users, but also Guest users. After all, if they are sufficiently authorized, they can also be responsible for 'creating' or 'modifying' an entity.

The 'ID' values for Users and Guest users are only unique within the respective entity type. When referencing (creatorId or lastModifierId), the 'ID' of a guest user is therefore mapped as a negative Long value.

If detailed data for referenced Guest users is included in the context of a search, the 'sign reversal' in the reference requires special precautions.

In the specific use case, a Subsearch projection determines the 'Login token' of the guest user, which is referenced in the 'Creator' property by a negative reference value 'indirect'.

This must be taken into account:

For normal Users, the Field restriction shown on the right in the condition of a Subsearch projection returns the matching user account (id) to the reference in the 'Creator' property (_parentQuery.creatorId) of the entity to which the parent search refers.

The comparison here refers to Long values on both sides (test value/compare value).

images/download/attachments/155420061/image-2023-11-3_9-54-49-version-1-modificationdate-1699001704764-api-v2.png

For Guest users, there must be a 'sign change' in the Subsearch projection condition for one of the two sides (check value/compare value), as the internal 'ID' for a guest user is not really negative. Unfortunately, Lobster Data Platform / Orchestration does not provide any calculation functions via Projections. Instead, we have to literally fabricate 'comparable' values by other means in order to resolve references for Guest users.

Configuration:

The following configuration is aimed at ...

.... converting negative values in the 'Creator' (creatorId) property into a string and ...
... creating comparable character strings based on the positive values for the 'ID' (id) of the referenced Guest users.

Both tasks can be solved using a Concatenated projection, as the following configuration for the condition shows:

images/download/attachments/155420061/image-2023-11-3_9-54-19-version-1-modificationdate-1699001675253-api-v2.png

On the left-hand side (check value), the Concatenated projection is used to prefix the positive 'ID' (id) in the Subsearch projection of the guest user account to be evaluated with a minus sign (-). The Long value is automatically converted into a String during concatenation.
On the right-hand side (compare value), the Concatenated projection is used exclusively to formally convert the negative value from the reference into a String. This is achieved by concatenating the return value of the Property projection for the 'Creator' property (_parentQuery,.creatorId) a second concatenated projection with a static empty string ('').

►NOTE◄ Depending on the database system used, comparisons between String and Long values are also possible without explicit type conversion. This configuration could then be simplified somewhat. However, the condition may no longer work if the database system is changed or the configuration is transferred to a Lobster Data Platform / Orchestration system that uses a different database system. With the explicit type conversion to String via the Concatenated projection, the condition should be applicable across the board.