Value from localization


Value resolver – Abstract

Purpose: Searches for a localization for a given Bundle/Resource combination and returns it or (as fallback) the Default value.

In the server context (e.g. Event handling)

In the client context (e.g. Client workflow)

images/download/attachments/177910747/image-2024-9-11_14-55-53-version-1-modificationdate-1726059353396-api-v2.png


images/download/attachments/177910747/image-2024-9-11_14-55-22-version-1-modificationdate-1726059321889-api-v2.png

NOTE◄ The selection of a Locale is not supported on the client side. The Current locale determines the localization in the client without any alternative.


The Value from localization resolver searches for a localization for a given Bundle/Resource combination in the given Locale and returns it or (as a fallback) the Default value.

If the localization or the default value assigned instead contains references to ( {0}, {1}, ...) parameters, the return values of the value resolvers configured for these Parameters will be used – if available.

No specific input value is expected. However, the input value of the value resolver serves as a reference object for value resolvers configured within.

Configuration

NOTE◄ The values of all text parameters of the value resolver can be defined either by direct input (by default) or via value resolvers. Clicking on the small gray arrow at the bottom left of the text field for direct input switches to the value resolver configuration.

Parameter

Description

Examples

Bundle

The text entered here or determined at runtime must match the bundle name of a localization entry exactly (incl. upper/lower case) for the entry to be assigned.

error
... for an entry that is applied as an error message


de.lobster.scm.doc.Document
... for an entry involving the Documents class


DIRECTIONS
... for values of a custom dynamic enumeration

Resource

The text entered here or determined at runtime must match the Resource name of a localization entry exactly (incl. upper/lower case) so that the entry is assigned.

CUSTOM_myBigFatGreekError... for an individual error code (in Bundle error)


$name
... for the name of the class identified per Bundle


NE
... for the value 'Northeast' in the Bundle of a custom dynamic enumeration DIRECTIONS (see above)

Default value

This value is returned if no localization is assigned for the Bundle and Resource combination.

It is good practice to enter the Resource value here (possibly even Bundle/Resource), so that in the absence of any localization it is recognizable from the return value which was unsuccessfully searched for.

Parameter

By clicking on the images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/add.svg symbol, entries can optionally be added to the Parameter list, the value of which is determined statically by direct input or via the optionally configurable value resolvers at runtime. Both localization entries and the Default value can refer to the values of such parameters via placeholders ({0}, {1}, ...). The index refers to the list position (ascending from 0).

Clicking the images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/forbidden.svg symbol removes an existing entry from the list.

NOTE◄ Depending on the content of the Parameter, it may be useful or necessary to generate their values again via the Value from localization value resolver.

The default localization for the localization entry (Bundle/Resource): error/CORESYSTEM_BaseDataManager_accessDenied is for the language 'English':
Access denied: No access to {0} for {1}With parameter values #0: " this object " and #1: " the requested action " the Value from localization value resolver returns the following at runtime:

Access denied: No access to this object for the requested action


Static (Optional)
and
Locale
(Value resolver or selection)


IMPORTANT◄ These parameters are only available in server-side use of the value resolver (e.g. in an event handler). Client-side (e.g. in a Client workflow) only the Current locale is available for localizations .

If the Static option is unchecked (default), then the localization text is looked up in the Locale that specifies the value resolver configuration for the Locale parameter at runtime. The return value must be of the Locale (Locale) type. A text that is supposed to identify a language by its internal name (e.g. fr) is not automatically converted.

  • In the example on the top right, the language for localization is taken from the company account of a company qualified as the 'Principal' for the registered company based on the company hierarchy (for details see Company of session).

If the Static option is checked, then instead of the value resolver configuration for the Locale parameter, a selection box appears that can be used to make a static selection for the Locale.

  • In the example below on the right, the Static option has been checked, so that the Locale can be statically selected from all languages defined as 'Supported locale' in the Locale dynamic enumeration.

The fallback for the Locale, regardless of the method used to define it, is the Current locale, which is the language with which the current session is logged in.


images/download/attachments/177910747/image-2024-9-11_14-57-53-version-1-modificationdate-1726059473045-api-v2.png

images/download/attachments/177910747/image-2024-9-11_14-58-54-version-1-modificationdate-1726059533666-api-v2.png

Examples

Simple example: Locating a message (Current locale)

At the beginning of a session, a user logging in with one of several specially privileged roles should be alerted to the role in use by a pop-up notification (of the 'Info' type).

If a localization (for the Current locale) exists for the name of the role used, it should be displayed. Otherwise the internal role name (roleName) should appear.

Runtime example:

images/download/attachments/177910747/image2022-7-1_16-27-3-version-1-modificationdate-1726058736350-api-v2.png

  • This warning message should appear at the beginning of a session when a user logs in with the role 'Document administrator' (internally: DocAdmin).

Configuration:

An event handler that reacts to the 'Client logged in' event (see Anmeldung (Ereignis) checks in the Validating rule whether the login concerns one of the 'specially privileged roles'.

As can be seen in the screenshot, the relevant Roles can literally be 'handpicked' in a Role rule by multiple selection.

NOTE◄ The multiple selection label shows the internal role names (roleName) regardless of whether there is a localization or not.

images/download/attachments/177910747/image2022-7-1_16-29-59-version-1-modificationdate-1726058736348-api-v2.png

The only Action on passed rule will need to be configured as a Show alert (Popup) event action:

  • 'Warning' is selected as the Type so that the notification appears as a 'Warning' (with the default white/orange color scheme).

  • Therefore, as a Title, the system's default label for a warning should also appear. On the system side, there is a Resource warning in the Bundle common, which is suitably localized by default ('Warning'). The Default value common/warning is only relevant in the special case that the localization entry for the Current locale AND for the default locale (if different) is missing.

  • The localization for the Role of session should be displayed in the Message. Localizations for roles refer to the Bundle rolename, where the internal name of the Roles from its rolename field must be specified as the Resource. The same configuration (Role of session and Object property value resolver for roleName) is also set up for the Default value. This is more important here than for the Title, since there is no localization for roles by default. Without localization and without default value, 'No value' ($null) would then be returned.

NOTE◄ For the Close after (seconds) parameter, the value 0 is specified here so that the warning message remains displayed 'indefinitely' (or until the user closes it). However, it remains visible even if a Fast switch to another (possibly less privileged) role is executed for which no new warning appears.

images/download/attachments/177910747/image2022-7-1_16-30-50-version-1-modificationdate-1726058736345-api-v2.png

More complex example: Localize e-mail in the recipient's language

If entities of particularly 'sensitive' types (here: user account, company account or role) are created or deleted in Lobster Data Platform / Orchestration, a notification to the responsible administrator should be triggered automatically via e-mail.

The notification should be localized in the language that this user uses to log in to Lobster Data Platform / Orchestration.

For the purpose of this example, we will only refer to the 'subject' of the e-mail.

Runtime example:

The screenshot on the right shows in the Preview for E-mails the Subject that is triggered when deleting a role with the internal ID #3302.

The following components are relevant for a localization in the Subject:

  • Event ('Delete', 'Create')

  • Entity type ('Role', 'User', 'Company account')

images/download/attachments/177910747/image2022-7-1_16-33-49-version-1-modificationdate-1726058736340-api-v2.png

For comparison, the screenshot on the right shows an example of a message that was output without localization.

  • Here, the text DELETE is the internal name of the 'Delete' event.

  • Instead of the entity type, the string mapping of the class for Roles appears.

images/download/attachments/177910747/image2022-7-1_16-32-31-version-1-modificationdate-1726058736343-api-v2.png

Configuration:

For e-mail notifications, event handling is configured as shown on the right:

  • The default Create and Delete events from the 'Common' category are selected as Triggering events.


  • The Validating rule checks by Check type whether it is one of the entity types classified as 'sensitive'. Additional elements can be added to the OR-series.


  • Exactly two Actions on passed rule are required:

    • A Set value event action assigns the account of the user to be notified to the mailToUser variable. In the example, the same user is always assigned, but instead a case distinction or search could be configured to dynamically regulate the responsibility.

    • All other configurations directly affect the following E-Mail event action.

NOTE◄ Only the localization for the 'Subject' of the e-mail is detailed below.

images/download/attachments/177910747/image2022-7-1_16-35-25-version-1-modificationdate-1726058736335-api-v2.png

The text for the Subject within the E-Mail event action is built up step-by-step here using a Concat strings value resolver:

  • The first substring of the concatenation outputs the localized name for the event that triggered the event handling.

    • Since the 'Create' and 'Delete' events both belong to the 'Common' category, we can define the name for the Bundle statically using the Class value resolver, whose string mapping names the bundle: de.lobster.scm.action.event.CommonActionEvent

    • The key value is provided by the Triggering event value resolver, whose return value can be used as a string mapping directly for the Resource parameter (values: DELETE, CREATE).

    • The Default value repeats the configuration for the Resource parameter, even though localization for common events should be ensured system-side at least by the default locale (as a fallback).

    • No values are specified for Parameters.

    • The Locale is assigned from the 'Locale' (locale) field of the user account specified via the mailToUser variable.

  • The second substring specifies a static text (' / ') as separator.

images/download/attachments/177910747/image2022-7-1_16-38-26-version-1-modificationdate-1726058736333-api-v2.png

  • The third substring outputs the localized name of the entity type that was created or deleted:

    • The entityClass variable, which is automatically filled by the system, commonly refers to the class of the reference object and, in the context of a 'Create' or 'Delete' action, to the type of entity in question.The string mapping of the class can be assigned directly to the Bundle parameter here.

    • The localized name for an entity type is retrievable by default via the Resource $name.

    • Even though system localizations should be retrievable at least for the default locale of the entity types relevant in the example, the Default value here is also assigned to the $name string. If necessary, the value of the variable entityClass could be added via Concat strings.

    • The Locale is read from the account of the contacted user, as described above.

  • The fourth substring defines a static text (' #') for separation and as a prefix for the following ID (id).

  • The fourth substring identifies the reference object for the event , i.e. the entity to be created or deleted, via its field ID (id).
    IMPORTANT◄ Since a new entity in the context of the 'Create' event does not yet have an ID, the 'Create mail content on commit' option should be selected for the E-Mail event action, otherwise the ID 0 will be issued.

images/download/attachments/177910747/image2022-7-1_16-39-45-version-1-modificationdate-1726058736330-api-v2.png


Alternative configuration:

So far, the Subject for the e-mail via Concat strings is constructed according to the following scheme:



@EVENT@ / @ENTITYCLASS@ # @ID


However, the same result can be achieved by the following configuration, which uses the Value from localization value resolver instead of concatenation to include the variable substrings in a predefined text as parameters:


{0} / {1} #{2}

The following configuration demonstrates this alternative for the Mail body builder parameter of the E-Mail event action:

Instead of the Concat strings value resolver, another instance of the Value from localization value resolver is set up in the configuration shown on the right:

  • The outer Value from localization value resolver serves here only as a platform to bring the Default value ({0} / {1} #{2}) into play. The Bundle and Resource parameters remain empty, as we are not actually looking for a localization entry value.

  • The list of Parameters can be 'taken' by copying and pasting the configurations for the corresponding substrings from the subject:

    • The first Parameter ({0}) provides the localization for the triggering event via a Value from localization value resolver (see above for details).

    • The second Parameter ({1}) provides the localization for the entity type via a Value from localization value resolver (see above for details).

    • The third Parameter ({2}) returns the ID (id) of the created or deleted entity (see above), which works without accessing the localization.


images/download/attachments/177910747/image2022-7-14_17-39-51-version-1-modificationdate-1726058736299-api-v2.png

Runtime example:

As a screenshot of the e-mail preview proves, this configuration provides the same text for the 'mail body' as the one shown above for the Subject.

The 'concat strings' per Default value is even clearer and more flexible, especially if the order of the placeholders for parameters is changed later or the same parameter is 'quoted' several times.

images/download/attachments/177910747/image2022-7-1_16-42-9-version-1-modificationdate-1726058736325-api-v2.png

NOTE◄ If the mail body is supposed to render the information summarized in the subject in a concise and structured way, it is recommended to create a separate localization entry value that uses the parameters.

Server suggestion:

Bundle

Name

Locale

Localization

custom

adminMail.Critical.Body

EN

For the sake of orderliness, we would like to notify you of the {0} of {1} entity #{2}.

DE

Der guten Ordnung halber möchten wir Sie hiermit über das {0} der Entität #{2} des Typs {1} informieren.

As the example demonstrates, it is also possible that localization in different languages 'quotes' the parameters in different sequence due to sentence order.

Once this localization entry is created, its Bundle/Resource combination can be added to the Value from localization value resolver for the Mail body builder.

IMPORTANT◄ So far, no Locale has been assigned for the outer Value from localization value resolver. To ensure that the parameterized 'text module' is used in the appropriate locale, the definition for the language from one of the parameters must be added here (locale field from the mailtoUser variable).