Attribute join

images/download/attachments/167859883/image-2024-1-25_12-22-21-version-1-modificationdate-1706181741033-api-v2.png

As with an Attribute projection, an Attribute join returns all or selected attribute values of the attribute type selected via the Attribute parameter. This is based on the main entity of the search or a different Attribute owner path.

The possible uses for the Attribute join in the context of different attribute types are illustrated by the following case differentiation:

Cardinality of the attribute/subtype ↓

Attribute type is non-typed

Attribute type is typed

specific subtype

all subtypes

'singular' (≤1)

Default access:
Singular attribute join

(Attribute join applicable but no added value)


Default access:
Typed attribute join

(Attribute join with On condition can be used for the (sub)type)

An Attribute join evaluates instances for all singular and plural subtypes and returns a 'flat' list that can be accessed by Projections.

'plural' (≥1:)

Attribute join is the default access

  • A non-typed singular attribute can be selected as an Attribute. Technically, an Attribute join therefore provides access to the value of a singular attribute. However, the Singular attribute join provides the same result.

  • For a non-typed plural Attribute, e.g. the 'communication information' (AddressCommunicationInfo) for the entity type 'Address' (Address), an Attribute join represents the default join.

  • If the Attribute selection relates to an attribute type from the group of typed attributes (e.g. 'text attribute' or 'company and address attribute'), the Attribute join provides the attribute values of all singular and plural subtypes as a 'flat list'.

    • The typed attributes with a plural subtype therefore do not appear 'grouped' or 'bundled' per attribute owner and subtype in the return value, but as individual attribute values (with the same subtype but different index value.

In contrast to Attribute projection, the list of return values for an Attribute join can be restricted to a subset using a On condition.

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 to be 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 line item 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)

In the Auswahlfeld/Combobox element for the Attribute parameter, a selection must be made from the attribute type options offered via a dropdown. Only the attribute types supported by the implementation of the entity type of the applicable attribute owner 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: Selective access to a plural attribute

A CSV search for Users should list e-mail addresses for each 'Username' (username) specified for this user via the 'communication information' plural attribute of the user's address.

If there are multiple types of 'communication information' with the Communication type 'E-mail' (EMAIL) for a user, this should be output line by line (as multiple lines for the same user).

If a 'context' (communicationContext) is specified in the 'communication information' attribute, this text value should appear in the output column (CONTEXT).

Configuration:

The Attribute join shown on the right is created within a CSV search for Users:

  • The Attribute owner path refers to the 'Address' (address) property of the user account via Property projection.

  • The name email is arbitrarily assigned as the Join alias.

  • The Join type 'Left' ensures that Users whose 'communication information' does not contain an e-mail address also appear in the result.

  • The Optional option is irrelevant as long as at least one projection for an output column refers to the alias email.

  • In the On condition, a Field restriction ensures that the Attribute join email only assigns 'communication information' instances that refer to the " e-mail" (EMAIL) Communication type in the 'Type' (communicationType) property.

images/download/attachments/167859883/image-2024-1-25_17-22-44-version-1-modificationdate-1706199764346-api-v2.png

The output columns are defined by three instances of the Property projection:

  • The 'Username' (username) property can be taken directly from the user account.

  • The 'Value' (communicationValue) and 'Context' (communicationContext) properties are read from the attribute value via the alias email.

images/download/attachments/167859883/image-2024-1-25_17-23-14-version-1-modificationdate-1706199794985-api-v2.png

Runtime example:

username,email.communicationValue,email.communicationContext
============================================================
jbond,jb007@mi6.uk,LOGIN
jbond,info@mi6.uk,AOB
mpolo,marco.polo@historyhas.it,ALERTS
mpolo,sales@historyhas.it,AOB
fbeutel,frank.beutel@acme.de,ALERTS
fbeutel,frank.beutel@acme.de,
esblofel,ernst@blofel.de,BLACKMAIL
esblofel,stavro@blofel.de,RANSOM
esblofel,info@blofel.de,AOB
...

Special use case: Access to several subtypes of a typed attribute

The company address (as attribute owner) can be used to assign address contacts to a company account. The relevant data is in turn Addresses, which are treated as a typed attribute of the 'Address contact' (AddressContact) type, whereby a Contact type is assigned. A Tuple search for Company accounts is enriched with the address data of all address contacts whose Contact type is either 'CEO' (CEO) or 'Employee' (EMPLOYEE).

Configuration:

images/download/attachments/167859883/image-2024-1-25_17-20-3-version-1-modificationdate-1706199603688-api-v2.png

The Attribute join shown above provides the desired address contacts via the following parameterization:

  • The Attribute owner path accesses the 'Address' (address) property of the company account via a Property projection.

  • The attribute type 'Address contact' (AddressContact) is selected in the Attribute parameter.

  • The name staff is arbitrarily assigned as the Join alias.

  • The 'Inner' Join type ensures that only Company accounts for which at least one address contact exists are taken into account.

  • The Optional option is irrelevant, as Projections for output columns (see below) address the alias staff.

  • The On condition uses a Search junction that ORs two instances of the Property projection:

The output columns are defined by three instances of the Property projection as shown on the right:

  • To identify the company, the 'Name' property from the company address (address.name1) is output in the first Property projection.

  • The second Property projection outputs the Contact type from the 'Type' property of the address contact from the alias staff.

  • The third Property projection returns the complete address entity from the contactAddress property of the address contact attribute, so that the result of the Tuple search contains all the details of the contact.

images/download/attachments/167859883/image-2024-1-25_17-19-6-version-1-modificationdate-1706199546746-api-v2.png