Map item

See also: All map key value reolver, Variable value resolver

Value resolver – Abstract

Purpose: Addresses the Key of a map or the field of a 'Client object' in the input value for read or write access .

images/download/attachments/78258593/image2022-10-19_18-18-56-version-1-modificationdate-1666196336547-api-v2.png

The Map item resolver addresses the Key of a map or the field of a 'client object' in the input value for a read or write access.

IMPORTANT◄ For a 'client object' as input value only a Key of the String type is accepted.

For write access, the Map item resolver must be used in a similar way to the Variable value resolver or an Object property value resolver on the left side of a value assignment (e.g. per Set value or Set values).

Special cases:

  • If there is no data object of the map (java.util.Map) or 'client object' type as input value, the return value for read access is 'No value' ($null). Write access has no effect.

  • If there is no configuration for the Key parameter or this results in 'No value' ($null) as a 'key' at runtime, the return value for read access is 'No value' ($null). Write access has no effect.
    NOTE◄ An empty string can be used as a Key in a map and as a field name in a 'client object', but 'No value' ($null) cannot be used.

  • If the parameterized Key in the input value is not used as key value or field name, the return value for read access is 'No value' ($null).

    • Write access adds an entry to a map with the specified Key and the value determined by the assignment.

    • The field addressed via the Key is only added to a 'client object' during write access if the Key is a string.

  • If the parameterized Key is already used as a key value or field name in the input value during write access, the assigned value overwrites the existing value.

  • Assigning 'No value' ($null) to an existing Key is possible.

    • If the input value is a map, this does not delete the key set to $null from the map itself.

    • On the other hand, if the input value is a 'client object', the field set to $null is deleted from the 'client object'.

The Item type and Is collection of parameters define the data type expected for subsequent elements in the context of the configuration.

On the other hand, the two parameters are relevant for read and write accesses to map values depending on the context for the following functions similarly to the Input object (type safe) value resolver:

Function

with read access

with write access

Type conversion
for simple values (String, Long, Double usw.)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

Look up an enumeration value in the enumeration selected as Class, starting from a text key passed as value, which is compared with a key field defined for each enumeration (usually name, for Einheiten alias)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

Look up an entity of the selected Class (specific entity type), starting from a numeric value for the ID (id) of the entity

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg supported in server context
images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/error.svg not supported in Client workflow

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/error.svg not supported

Type check against the selected Class to check the class membership of a value or all values of a list (if Is collection of is selected):
→ Return value if passed: checked value (list if applicable)
→ Return value if failed: 'No value' ($null)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatic

NOTE◄ The Check type always takes place after the other functions that may be applicable. Therefore, if the look-up or type conversion is successful, the check is always passed. If an applicable function fails, the return value is 'No value' ($null), because after that the selected Class is not present.

IMPORTANT◄ If a write access uses the Map item resolver with the Class and/or Is collection of parameters on the target side of the assignment (e.g. left in a Set value event action), the failure of a type check, type conversion, or enumeration value look up will not result in the assignment of 'No value' ($null), but in a 'silent' abort of the assignment. So the Key defined as the target keeps its previous value unchanged and the execution context continues without error message. The abort via the 'Log' tab with an UnsupportedOperatonException is only understandable in the context of Tests.

Configuration

The Map item resolver always expects a map (java.util.Map) or a 'client object' as input value.

NOTE◄ The input value may need to be created via the Create instance value resolver (with java.util.Map 'type') so that read and write access can be made via the Map item resolver.

Key

In the Key parameter, value resolvers must be configured whose evaluation at runtime addresses a key (in a map) or field name (in a 'client object').

In the example on the right, the value myKey is defined as a static text (see Static values) for the Key parameter, which would be suitable both as the key of a map and as the field name of a 'client object'.

IMPORTANT◄ While the field name of a 'client object' must always be a String , any data types can be used as keys in a map. For example, the same map could simultaneously contain a Long key 1234, an Integer key with the same value (1234), and a String key with the same digits ('1234').

NOTE◄ When accessing existing keys in a map via the All map keys value resolver, the subset of keys for a given 'key type' can be requested as the return value. To retrieve all field names in the context of a 'client object', even the only supported String ' key type' must be explicitly selected.

images/download/attachments/78258593/image2022-10-19_18-19-35-version-1-modificationdate-1666196375801-api-v2.png


Class

The optional Item type parameter supports a static single selection for a class via a Auswahlfeld/Combobox. Its search function (see image on the right) considers matches for the applicable localization as well as the internal name of the class.

A selection for Item type value implies a Typprüfung for the read or assigned value, and may – if automatic conversions are provided – also cause a type conversion or lookup of enumeration values or entities with respect to the return value.

Example:

For example, if the text value 0815 (in JSON notation '0815') was assigned to the key myKey, then this can be 'read' during a read access either as a String value (0815) or as a Long value (815) depending on the selection for the Item type.

If the Item type Long was already specified in the context of assigning the 0815 text value to the myKey key, then the Long value 0815 is assigned. The information that the original string contained a 'leading zero' is lost in the process.

However, the stored long value (815) can be used to 'look up' an entity with ID (id) 815 on read access by selecting its entity type as Item type if the context supports it (see table above).

images/download/attachments/78258593/image2022-10-19_18-21-47-version-1-modificationdate-1666196507738-api-v2.png

NOTE◄ The lang character string entered here as a search term could also be confirmed as free text input for a class (not listed in the dropdown) using the [+] symbol or the enter key, although this is rarely intended.

Is collection of

The Is collection of option (unchecked by default) specifies that the read or written value should be a list. If the value is not a list, the Map item value resolver returns/writes 'no value' ($null).

If a Class is explicitly specified (see image on the right), selecting the option Is collection of implies a Typprüfung of all existing entries against this Class, so that the return value is $null if at least one entry does not match the selected Class.

Example:

The selection of the Item type Long and the option Is collection of implies a Typprüfung for the value in the Key myKey. If this does not contain a list (but e.g. only a single Long value) or a list containing entries with data types that are not Long values, the return value of the value resolver is $null.

►NOTE◄ As noted above, a write access is aborted on failure of a type check for the value on the target side of the assignment. If the configuration on the right defines the target of an assignment and a list is assigned at runtime that contains at least one value that is not a Long value, the Key myKey is not assigned 'No value' ($null). Instead, an existing value for the Key myKey remains unchanged or the Key is not created (if it does not already exist).

images/download/attachments/78258593/image2022-10-19_18-22-47-version-1-modificationdate-1666196567622-api-v2.png


When accessing 'lists' as values, the following aspects must also be taken into account:

  • If the option Is collection of is unchecked (default) and no Item type is selected then no Typprüfung takes place. So there is no way to specify that only one return value that is not a list is 'desired'.

  • As long as the option Is collection of is unchecked, a list is returned or assigned directly like any other data object stored in a variable.

  • If the option Is collection of is unchecked when accessing a list, then the Item type parameter can be used for a type conversion for the list as a whole.
    Example: A Key route contains a normal 'list' (java.util.List) of String values defined by IATA codes of flight destinations along a 'travel scheme:
    In JSON notation, the list in the value for the route Key for a 'round trip' might look like this, for example: [MUC,JFK,GIG,CDG,MUC]If the route variable is accessed by Item type 'List' (java.util.List) or without specifying a type, the return value corresponds exactly to the stored value.
    However, if the Key route is accessed by Item type 'Unique list' (java.util.Set), then the 'list' is converted to a 'unique list', which can change the order and number of entries.
    In the specific example, the return value could look like this: [GIG,CDG,MUC,JFK]

Examples

Read access to a key of a map or a client object (as default value)

An event handler reproduces selected contents (here: name and id) from a map passed by an author variable in a notification.

If the author variable does not contain a map, field values are displayed from a 'client object' generated for this purpose from statically stored JSON text.

Runtime example:

Notification with data from a provided map

images/download/attachments/78258593/image2022-10-19_17-35-47-version-1-modificationdate-1666193747349-api-v2.png

Notification with default values
(without map)

images/download/attachments/78258593/image2022-10-19_17-37-44-version-1-modificationdate-1666193864861-api-v2.png

Configuration:

The notification can be configured within an event handling as shown on the right:

  • The Object Resolver within the Execute with event action primarily accesses a map present in the author variable. If the variable returns a map, this map will be the reference object for the output of the notification via a Show alert (Popup) in the action block below.

  • If the author variable is empty or contains a data type other than a map, the Variable value resolver returns 'No value'. Then the concatenated Default value resolver becomes active and evaluates the configuration for its Default value parameter:

    • A 'client object' is created from the static string {name:NN,id:0} (see Static values) by the concatenated JSON to object value resolver.

    • The 'client object' replaces the missing map as a reference object in the output of the notification via Show alert (Popup) in the action block below.

images/download/attachments/78258593/image2022-10-19_18-23-53-version-1-modificationdate-1666196634062-api-v2.png

Within the Show alert (Popup) event action, the Message combines values from the reference object in a Concat strings value resolver with literal text characters:

  • The first text component reads the Key or the name field. Its name is assigned as static text.

  • The second text component defines literal formatting characters as static text.

  • The third text component reads the Key or the id field. Its name is assigned as static text.

NOTE◄ We assume that the type of all 'keys' relevant to the notification is in the map String. Only then does the smooth switch between 'client object' and map as input value for the Map item resolver work as demonstrated here.

NOTE◄ Creating a 'client object' in the Default value resolver is more efficient than defining a separate Default value for each read access. However, the 'default' only applies if the map is completely missing. If the map is available, but does not contain values for all relevant 'keys', then the notification appears incomplete, if 'individual default values' are waived as here.

images/download/attachments/78258593/image2022-10-19_18-24-50-version-1-modificationdate-1666196690255-api-v2.png

Collecting data in a map (write access)

A Search (Event action) with the 'search value' mode returns a list of user accounts (see Users) in a users variable, which is referred to here as a 'user group'.

The data of the 'user group' is evaluated with regard to the combinatorial analysis for the 'Locale' (locale) and 'Country' (address.countryCode) fields. The evaluation result is provided as a map that uses all the locales used in the user group as unique 'keys'. A list of the 'countries of origin' of users in whose account the respective language is selected is assigned to each key as a value.

NOTE◄ An evaluation of the combinatorics is also conceivable within the Search (Event action) if corresponding criteria are used for a grouping. In the example, however, the evaluation of the combinatorics is explicitly decoupled from the retrieval of the detailed data for the user group and with a map as the result.

Configuration:

The configuration on the right shows how the evaluation of combinatorics can be solved within an event handling:

  • Details of the initial Search (Event action) are not important here. What is important is that it provides a list of users accounts in the variable users.

  • The following Execute with event action sets a map created by Create instance with the Type 'Map' (java.util.Map) as the reference object for the further event actions. As long as all actions concerning the map can be performed in this context (e.g. Show alert (Popup) at the bottom), the created map does not need to be explicitly assigned to a variable.

  • For the context within the following For each loop, the locales variable for accessing the map is defined via the Save map in variable parameter. The Reslover for entities parameter defines an iteration over unique values for the 'Locale' (locale) field within the list of all Users of the 'user group' (in the users variable):

    • The Variable value resolver first returns all user accounts listed in the users variable.

    • The concatenated Collect values resolver reads the Object property 'Locale' (locale) from these and returns a list as return value via the Unique values option, which contains each relevant 'Locale' exactly once.

  • The Execute with event action within the loop does not define a Object Resolver, so retains the Locale as a reference object. The Save Locale in variable parameter additionally writes the decisive Locale for the respective iteration into the locale variable. This is particularly necessary in order to access the Locale in the Rule list resolver (see below), which here refers to a user as a reference object.

    • The Set value event action defines a write access to the map (locales), which on the one hand creates a Key for the current Locale and on the other assigns the desired 'country list' for the locale as a value.

      • On the left side of the assignment, a Variable value resolver establishes the reference to the map locales, which is needed as an input value for the concatenated Map item resolver. This defines the current Locale as the Key (per Variable value resolver for locale).
        NOTE◄ A specification of Item type and Is collection of is omitted here.

      • On the right-hand side of the assignment, a Variable value resolver accesses the list of Users (users) at the beginning of the value resolver chain, which is processed as follows:

        • The concatenated Rule list resolver returns all Resolve all as list for which the Entity property rule is fulfilled that the Object property 'locale' (locale) matches the current Locale (locale variable) in the iteration.

        • The concatenated Collect values resolver determines from this fraction within the 'user group' a list of unique values for the 'country' (address.countryCode) address field, provided that there is an entry for it
          NOTE$null values are simply skipped by Collect values in the given configuration.

  • After iterating over all the languages used, here we perform a Show alert (Popup) event action to output the string image of the map for demonstration purposes.

    NOTE◄ In a real use case the map can be processed otherwise.

Runtime example: (String image of the map)

{en=[US, DE], de=[DE, IT, AT], fr=[MU]}

NOTE◄ Values of the dynamic enumeration Locale serve as a Key in the map and not just the internal names of these values (as a String) that the string image outputs. Also, the list in the associated value refers to dynamic enumeration values for the Country and not only to the text values output above.

For clarification, the server XML image of a map with the same data is also shown below

images/download/attachments/78258593/image2022-10-19_18-27-39-version-1-modificationdate-1666196859113-api-v2.png images/download/attachments/78258593/image2022-10-20_10-18-57-version-1-modificationdate-1666253937301-api-v2.png

Server XML of a map with country lists in locale keys
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:core="CORESYSTEM">
<entry>
<key enumName="core:Locale" name="en" xsi:type="core:DynamicEnumValue"/>
<value xsi:type="set">
<entry enumName="core:Country" name="US" xsi:type="core:DynamicEnumValue"/>
<entry enumName="core:Country" name="DE" xsi:type="core:DynamicEnumValue"/>
     </value>
</entry>
<entry>
<key enumName="core:Locale" name="de" xsi:type="core:DynamicEnumValue"/>
<value xsi:type="set">
<entry enumName="core:Country" name="DE" xsi:type="core:DynamicEnumValue"/>
<entry enumName="core:Country" name="IT" xsi:type="core:DynamicEnumValue"/>
<entry enumName="core:Country" name="AT" xsi:type="core:DynamicEnumValue"/>
</value>
</entry>
<entry>
<key enumName="core:Locale" name="fr" xsi:type="core:DynamicEnumValue"/>
<value xsi:type="set">
<entry enumName="core:Country" name="MU" xsi:type="core:DynamicEnumValue"/>
</value>
   </entry>
</map>

This evaluation of the combinatorics of Locale and Country in the evaluated 'user group' results in plain text:

  • The locale 'English' (en) is selected for one or more users each from the USA (US) and Germany (DE)

  • The locale 'German' (de) is selected for one or more users each from Germany (DE), Italy (IT) and Austria (AT).

  • The locale 'French' (fr) is selected for one or more users from Mauritius (MU).

Dynamically determined field names in a client object (write access)

An event handling shall simulate a random 'roll' with a parameterizable number of dice (numberOfDice variable) and return a 'client object' reflecting the thrown number of points in systematically named fields (die0, die1, die2, ...).

Runtime example: 'Roll with 3 dice' (numberOfDice=3)

Client object in JSON notation
{
"die2": {
"class": "java.lang.Long",
"value": "1"
},
"die1": {
"class": "java.lang.Long",
"value": "3"
},
"die0": {
"class": "java.lang.Long",
"value": "6"
}
}

Configuration:

The sticking point for the configuration is that the Object property value resolver typically used for value assignments to fields of an object does not support dynamic assignment for the field name, but only static selection of a field in the configuration.

Therefore, the Map item value resolver must be used, whose dynamically definable Key is interpreted as a field name in the context of a client object.

In the event handling used to 'roll the dice', the event actions shown on the right are configured:

  • The surrounding Execute with event action sets a 'Client object' created by Create instance with the 'Client object' type (ASObject) as the reference object for the further event actions. The concatenated Store value as variable value resolver stores a reference to this 'client object' in the roll variable. This variable name can be referred to, for example, by the 'Result expression' parameter in a Dispatch custom action event (Form designer) behaviour (not shown in the image) as a return value.

  • The For each loop event action should execute the number of dice specified by the Long value in the numberOfDice variable. A Dispatch custom action event (Form designer) behaviour can pass this value as a call parameter.

    • Within the iteration, the Set value event action assigns a 'diced' random number (as a long value in the value range between 1 and 6) to a field of the 'client object' present as a reference object, whose name combines a prefix with the index number of the dice.

      • On the left side of the assignment, the Map item value resolver defines the field name in the Key parameter using a Concat strings:

        • The first text component is the static text die.

        • The second text component is derived from the Long value in the $index variable, which specifies the current iteration index in a For each loop event action.

      • On the right side of the assignment, the actual 'dice rolling' takes place. Details about this are not relevant here.

images/download/attachments/78258593/image2022-10-20_10-20-30-version-1-modificationdate-1666254030309-api-v2.png