User of session

Value resolver – Abstract

Purpose: Returns the 'user data' (user account/guest user account) for the applicable login context.

images/download/attachments/201662684/image2022-2-15_18-3-7-version-1-modificationdate-1742198707412-api-v2.png

The User of session value resolver returns the 'user data' (the account) for the applicable login context.

The following scenarios can be determined at runtime:

Runtime scenario

Return value of 'User of session'

A full user (see Users) is logged in for the current session or has been specified via Login API for authentication and is considered a 'user' in the applicable login context.

User account data (type: user) that authenticates the session or access via Login API.

A guest user (see Guest users) is logged in for the current session or has been specified via Login API for authentication and is considered a 'user' in the applicable login context.

Guest user account data (type: guest user) authenticating the session or access via Login API

In the direct or indirect execution context of the value resolver, a Run as event action specifies a 'user' to temporarily define the applicable logon context different from the actual logged-on user or guest user.

User account data (type: user) defined as 'user' in the temporary login context.


►WARNING◄ Do not use return value for write accesses!

The return value of the User of session value resolver provides only a 'clone' of the account from the applicable login context, which may no longer correspond to the server-side data state for the account in question. When a user or guest user logs in to a Lobster Data Platform / Orchestration session, this clone is created as a 'snapshot' of the data from the account being used. This ensures that its data does not have to be repeatedly retrieved from the server during the session. The clone of the account valid for the user's session is only recreated if the logged-in user saves changes to their own account themselves (e.g. also through functions such as Change locale, Change profile picture, etc.).

Saving changes made to the cloned return value of the User of session value resolver – e.g. via Save changes later – fails (with error message including rollback for the transaction) if the server-side data state was updated by accesses from other sessions after the clone was created. To minimize the risk of a conflict when writing, the data of the account in question is fetched from the server immediately before write access, if possible. For this purpose, the 'ID' (id) of the account identified as User of session can be passed to the Input object (type safe) value resolver (see the 'Write access' example below).

Since the value resolver optionally returns the data of a user account or a guest user account, the GUI for the configuration defines the 'Interface > User' type for the return value of the value resolver. An Object property value resolver offers only the following very minimal selection of fields for this interface type, which are absolutely required for authentication with one or the other account types:

Field name

Localization

Data type

Meaning

Details

id

ID

Long

Absolute value identifies the 'user' account.

For Users, the ID value is specified as a positive Long value.
For Guest users, the ID value is specified as a negative Long value.

created

Created

Timestamp

Account creation date.


creatorId

Creator

Long

Absolute value identifies the 'user' account that created the returned account.

For Users, the ID value is specified as a positive Long value.
For Guest users the ID value is specified as a negative Long value.

ownerId

Owner

Long

ID of the company account that owns the 'user' account.

The value -1 signals that no owner is assigned.

However, regardless of the definition of the 'Interface > User' type, the return value always includes all the data of the account that is considered the User of session.

IMPORTANT◄ If a guest user is a User of session, the 'Interface > User' returns the value of the loginToken field for a client-side read access to the username field. Details on this special feature are illustrated in the example 'More complex use case' below.

NOTE◄ When the User of session value resolver is used in a configuration, the logic implemented should be such that any of the scenarios listed at the beginning of this section can occur. However, the possibility that deployment conditions may change in the future should be considered, even if Guest users do not play a role on a Lobster Data Platform / Orchestration system to date, or no Run as event action is used in the immediate context. For example, a configuration in which only Users are expected as User of session should take suitable precautions to ensure that 'nothing can happen' in a guest user session. However, no essential workflow step should fail with a rollback or – possibly even worse – be executed with incomplete or inappropriate data just because the User of session is of the wrong type (Guest users vs. Users) or because a Run as event action within a complex call chain has brought an 'unexpected' user account into play.

Configuration

The value resolver ignores the input value and does not use any parameters.

Examples

Example: Restriction for a custom overview

Access to most entity types is controlled by Lobster Data Platform / Orchestration 'ownership' (ownerId) or Company authorizations, so the Company of session is usually the deciding factor for which Custom overviews entities will list in their data grid. It could be said that Lobster Data Platform / Orchestration does not provide 'private ownership' of entities, because systematically only Company accounts are provided for as owners or recipients of permissions. However, automatically populated default fields 'Creator' (creatorId) and 'Last modified by ID' (lastModifierId) of an entity refer to Users and Guest users, respectively. In the following example, a 'custom overview' for users is given an additional restriction on this basis, so that only those users for which the logged-in User of session is considered to be the 'creator' are displayed.

Configuration:

A 'custom overview' for Users is newly created and provided with the configuration for the Restriction shown on the right:

  • The left side of the Field restriction addresses the 'Creator' (creatorId) user field, which contains Long values that are a reference to a user or guest user account.

  • On the right side of the Field restriction, the User of session value resolver is used to determine the user or guest user account that is referred to by the current session. The chained Object property value resolver reads the 'ID' (id) field of the account, which serves here as search criterion for the overview.

NOTE◄ The interface returns the positive value of the guest user account ID as a negative value. However, the same logic applies to the value for 'Creator'. In this respect, the custom overview with this Restriction also works without special precautions for logging in as a guest user.

NOTE◄ The ability of a guest user to create accounts for Users should normally be precluded by assigning a suitably restricted role to them. However, the Restriction in this form can be used for any entities.

images/download/attachments/201662684/image2022-2-15_18-4-10-version-1-modificationdate-1742198707409-api-v2.png

Runtime example:

images/download/attachments/201662684/image2022-2-15_18-6-38-version-1-modificationdate-1742198707406-api-v2.png

  • The custom overview 'Users created by ►ME◄' lists only the two user accounts for 'Triple Q' created by the user themselves.

  • In accordance with the Restriction for the overview (see above), the Creator column shows the user name (username) and the ID of 'Triple Q' in all rows, if this is the User of session.

Example: Write access to the account identified as User of session

To minimize the risk of improper access to data in Lobster Data Platform / Orchestration, Guest users should be able to deactivate their own account by clicking on a ribbon button.

Runtime example:

images/download/attachments/201662684/image2022-2-16_17-20-59-version-1-modificationdate-1742198707333-api-v2.png

Configuration:

The ribbon button (see above) triggers a Custom action event 'Deactivate my account', which is listed as a Triggering event for the event handling shown on the right.

The Validating rule here explicitly ensures that the event actions shown below are only executed if a guest user is specified as the User of session.

No input value is expected for the event, since the ribbon button is supposed to be offered in different contexts and not bound to the selection of a specific reference object. In this respect, a direct Check type on the 'guest user' type for the input value would be meaningless.

Instead, the Check type here is executed inside a With rule for which the User of session value resolver in the Entity property resolver parameter temporarily changes the reference object.

Even if its return value is the 'Interface > User' type (see image), a 'Guest user' object is present at runtime if Guest users are logged in.

NOTE◄ The check type in the With rule is not assumed to be the context for the Action on passed rule, unlike a direct Check type for the input value of an event handler. Instead, the context here is considered undefined ('Object').

images/download/attachments/201662684/image2022-2-16_17-23-0-version-1-modificationdate-1742198707331-api-v2.png

As an Action on passed rule, a logon context with appropriate access rights (see Role override) must first be established by a Run as event action, since it is assumed that a guest user is not authorized to change guest user accounts.

  • It is important that no selection is made for the optional User override parameter, as this would override the reference to the User of session, which is processed by the following actions.

  • To ensure that write access for the logged-in guest user account is as secure as possible, the current data status of this account should be retrieved from the server in the Object resolver of the Execute with event action. This allows the following concatenation starting from the User of session value resolver:

    • The Object property value resolver reads the field 'ID' (id) from the return value for the User of session.

    • Since the 'Interface > Users' for Guest users returns negative Long values for the ID by definition, the Calculate value value resolver must 'invert' the sign here so that the actually positive value of the ID is present as input value in the following step.

    • The calculation result, which is initially available as a 'Unit Number', must then be explicitly declared as a Long value via an Input object (type safe) value resolver before another Input object (type safe) value resolver can resolve the guest user account in question.

    • A Set value event action can be used to assign the value false to the 'Active' (active) field of the guest user account determined in this way as a reference object before this change is marked for saving via Save changes later.

images/download/attachments/201662684/image2022-2-16_17-26-9-version-1-modificationdate-1742198707313-api-v2.png

IMPORTANT◄ The concatenation in the Object Resolver of the Execute with event action could be shortened considerably by using only the first and last 'stages'.

  • User of session > Input object (type safe) with 'Guest user' type

    However, it is important not to proceed in this way, because otherwise the event actions will be executed with the 'cloned' account data at the time of the guest user login, which, in conjunction with Save changes later, can lead to a rollback error if the account has been modified since then starting from another session. This causes the clone to be considered 'outdated' by the server (see the 'Warning' in the introduction).

Example: More complex use case

It is possible to send an 'info note' (via e-mail) to other users/guest users in selected contexts via a ribbon macro, which refers to the current selection.

By clicking on the respective button, the logged-in user is able to select one of the following addressees for the notice via a context menu:

The selection list should not include any account more than once, even if it is relevant in different functions.

The solution must be structured so that the accounts involved can be either Users or Guest users.

Runtime example:

images/download/attachments/201662684/image2022-2-15_18-11-50-version-1-modificationdate-1742198707399-api-v2.png

  • The screenshot shows the ribbon button 'Info' which opened the displayed context menu.

  • The context menu shows two addressees for an info note to choose from.

Configuration:

The following describes only the configuration that concerns the opening of the context menu. The triggered notification expects the complete data object for the selected user or guest user account from the context menu in a variable.

The dynamic construction of the context menu is based on the data of the User of session (see parameter Object Resolver in the Execute with event action) in the stages shown on the right, which are described in detail below:

  • As the first step, a Set value event action stores the list of unique Long values that are references to 'relevant' user/guest user accounts to the accountIds variable.

  • In the second step, the data objects for the accounts listed in the accountIds variable are retrieved from the server. With the help of the Run as event action, the logon context is changed in such a way that the read rights required for 'Search' are provided to Users and Guest users. The 'found' accounts are passed in two list variables (users and guests).

  • In the third step, the accounts queried separately per entity type in the list variables (users and guests) are combined within the Show context menu to form a common list that defines the options for the context menu.

images/download/attachments/201662684/image2022-2-15_18-14-58-version-1-modificationdate-1742198707393-api-v2.png

For the first step, a Set value event action is configured as shown on the right to assign the list of relevant account references to the accountIds variable (left side of the assignment).

On the right side of the assignment, the list is defined by a concatenation of the following value resolvers:

  • The Create list value resolver is used here to compile a list of long values from the values of the three relevant fields (id, creatorId and lastModifierId) from the return value of User of session ('Interface > User' in context). The Object property value resolver used for this purpose has been 'collapsed' in the image in favor of a more compact view.

  • As the list compiled in this way may still contain duplicates, it is post-processed in the Collect values value resolver chained below, as only Unique values are allowed. As the Value to collect, an Input object (type safe) value resolver with the 'Long' type is used, which aims to ensure that the single input value is transferred unchanged to the list (if it does not already exist).

At runtime, based on this configuration, the variable accountIds contains a list with at least one and at most three different Long values, each pointing to a user or guest user account.

Positive Long values refer to Users and negative values to Guest users.

images/download/attachments/201662684/image2022-2-15_18-15-51-version-1-modificationdate-1742198707390-api-v2.png

For the second step, a suitable logon context is first established within a suitably parameterized Run as event action, so that there is sufficient access to the accounts that are read. In the example (not shown in the image), the 'Super user' role is claimed. This gives full access to all accounts regardless of the selection of a specific 'company'.

The call-off of the accounts for the context menu via a Search (Event action) must be done in two steps, because only one specific entity type (Users or Guest users) can be called from the server at a time.

The image on the right shows the configuration for the Search (Event action) for the Users Entity:

  • The Save result as parameter defines the variable name users for the return value.

  • The 'Search value' Mode assigns a list of instances of the Entity to the users variable when the 'Search' option is selected for the Search parameter.

  • Where checks the criterion that the value of the field projection for the 'ID' (id) is contained in the list of positive Long values in the accountIds variable. The Rule list resolver, which is linked to the Variable value resolver, returns a Resolve all as list that meets the condition '>0'.

    NOTE◄ Since there are no Users accounts with negative IDs, the restriction of the accountIds could also be omitted. In this case, however, the comparison list would contain unnecessary options.

At runtime, after executing the Search (Event action), the users variable contains a list of entities of the Users type, which can also be empty if the accountIds variable contains only negative values referring to Guest users.

NOTE◄ The Search (Event action) only 'finds' Users that can be read in the applicable login context. This depends here on the parameters of the surrounding Run as event action. Selecting this option incorrectly may result in relevant Users being 'missing' as addressees in the context menu.

images/download/attachments/201662684/image2022-2-15_18-18-6-version-1-modificationdate-1742198707387-api-v2.png

A second Search (Event action), concerning the Guest users Entity, again defines the 'Search value' Mode and a Search of the 'Search' type. The result is a list of Guest users accounts to be written to the guests (not shown in the image) variable.

For this Search (Event action), Where uses the configuration shown on the right. This is done in a similar way to Where for the Users (see above) with the following important differences.

  • The Rule list resolver (on the right) restricts the list from the variable accountsId this time to negative Long values, which are interpreted as references to Guest users.

  • Since the field projection for the 'ID' of the Guest users (on the left side of the image) only returns positive values, the sign of the negative comparison values from the variable accountIds must be reversed. This is made possible by the Calculate value value resolver, which is used for this purpose within a chained Collect values value resolver to define the Value to collect.

  • In the Calculate value value resolver, the 'formula' input defines the sign reversal for the input value (input).
    NOTE◄ As an alternative, the formula abs(input)could be used here to 'eliminate' the sign. Since the Rule list resolver only returns negative values as a subset of the values in the list variable accountIds, this makes no difference here.

  • The Input object (type safe) value resolver chained below explicitly converts the calculation result to a Long value to ensure this data type for matching with the database.

At runtime, after the Search (Event action) is executed, the guests variable contains a list of entities of Guest users type, which can also be empty if the accountIds variable contains only positive values referring to Users.

NOTE◄ The Search (Event action) only 'finds' Guest users that can be read in the applicable login context. This depends here on the parameters of the surrounding Run as event action. When this is selected inappropriately, relevant Guest users may be 'missing' as addressees in the context menu.

images/download/attachments/201662684/image2022-2-16_10-3-0-version-1-modificationdate-1742198707344-api-v2.png

The third step is to merge the accounts collected in the users and guests variables and return a unified list for Users and Guest users.

Since this list of accounts should directly define the selection options for the context menu to be opened, this formatting can be placed directly in the Show context menu event action:

  • The lists from the users and guests variables are first combined in the Root items parameter as a list of lists (with two entries) by a Create list value resolver. A Collect values value resolver follows below per concatenation, in which the option Join collections is set. An Object property value resolver without any field selection is used as the Value to collect, so that the accounts from the two source lists pass completely as entries into the 'unified' list.

  • Label expression concatenates the language entry 'note' ((common,info]) in conjunction with various literals with field contents ({username}, {address.name1}) from the specified account to build the caption for the context menu entry.

    IMPORTANT◄ With respect to {username} it should be noted that building the context menu at runtime is also client-side read access (see IMPORTANT note in the introduction) to the respective account if the Show context menu event action is executed within an event handler. This is the only reason why accessing the username field does not return 'no value' (null) for Guest users either, but the loginToken, while accessing the address.name1 field does indeed return 'no value' (null) for Guest users, so that only 'empty brackets' appear as in the image below:

    images/download/attachments/201662684/image2022-2-15_18-26-44-version-1-modificationdate-1742198707377-api-v2.png



    The following expansion step illustrates more details on this.

images/download/attachments/201662684/image2022-2-15_18-23-2-version-1-modificationdate-1742198707380-api-v2.png

On the basis of the previous configuration, the Users always appear above the Guest users in the context menu and in the order in which they are returned by the associated Search (Event action).

Although the order is not of great importance with a maximum of three entries, its effect will be demonstrated here:

A Sort list value resolver is attached to the existing concatenation for the Root items parameter within the Show context menu event action, defining the username field as a Compare value.

  • The concatenation with an Upper case value resolver also ensures that upper and lower case letters are treated equally during sorting. Otherwise, upper case letters would be sorted before lower case letters.

Runtime example:

  • The sorting result appears correctly. The guest user highlighted in the image appears with the leading digit '2' in the username (aka loginToken) before the user accounts whose 'username' also appears sorted in ascending order. The guest user account in the example was created by user Q and then modified by QQQ.

However, appearances are deceptive, as another sample in the context of another guest user proves:

images/download/attachments/201662684/image2022-2-15_18-37-34-version-1-modificationdate-1742198707365-api-v2.png

images/download/attachments/201662684/image2022-2-15_18-29-28-version-1-modificationdate-1742198707374-api-v2.png

As seen in the last 'runtime example' (above), sorting between multiple guest user entries in the context menu does not take effect with the previous configuration. The entry beginning with the digit '6' should otherwise appear at position 2. The background:

  • Although the construction of the context menu is done client-side by Show context menu, the value resolvers for the Root items are processed server-side, at least if the event action is part of an event handling, which in this context is the case.

  • Since the Sort list is done on the server side, the Object property value resolver for the username in the Compare value for Guest users is empty. Unlike client-side access, the loginToken is not automatically assigned as a fallback. This means that the comparison value for all guest users is 'no value' (or '').

In order to neutralize this problem, the configuration can be adjusted. (e.g. as shown on the right):

  • The Object property value resolver for the username has been replaced by a Concat strings for the username and loginToken fields in the image. Since only one of the two fields returns a value at any given time for a server-side read access to a user or guest user account, the Concat strings results in the 'representation rule' for the username that automatically takes effect client-side. Result:

images/download/attachments/201662684/image2022-2-15_18-39-58-version-1-modificationdate-1742198707360-api-v2.png

images/download/attachments/201662684/image2022-2-15_18-39-9-version-1-modificationdate-1742198707363-api-v2.png

NOTE◄ If the context menu is not created via event handling but via Client workflow, the fallback rule for the username also applies to the Sort list, so that the most recently added Concat strings can be omitted. However, the Run as event action is not available in a Client workflow, so sufficient read permissions must be ensured in the logon context applicable to the Client workflow to search for the accounts (in the second step).