Variable

See also: Store value as variable, Input object (type safe)

Value resolver – Abstract

Purpose: Establishes the reference to a variable in the execution context for read or write access, supporting type checks, type conversions and lookup functions similar to the Input object (type safe) value resolver.

images/download/attachments/177908063/image-2024-8-13_10-34-33-version-1-modificationdate-1723538073359-api-v2.png

The Variable value resolver establishes the reference to a variable in the execution context for read or write access. The input value is ignored in both cases.

NOTE◄ The Variable value resolver can be used on the left side of a Set value event action to assign a value to a variable. Often 'write access' can also be achieved without any disadvantages via the Store value as variable value resolver. This is more versatile (e.g. also in Association criteria, where Event actions are not available) and allows more efficient configurations, since, for example, within a value resolver chain any intermediate result can literally be 'casually' assigned to a variable.

The Key parameter defines the name of the variable that will be created during write access if it does not already exist.

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

The two parameters are relevant for read and write accesses to variables depending on the context for the following functions in a similar way to the Input object (type safe) value resolver:

Function

for read access

for write access

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

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 per enumeration (usually name, for Units alias).

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

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

Lookup of 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 the Client workflow

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

Check type against the selected Class
Checks the class affiliation of a value
or all values of a list (if Is collection of is checked):
→ 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 lookup 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 Variable value resolver with the Class and/or Is collection of parameters of on the target side of the assignment (e.g. on the left in a Set value event action), the failure of a type check, type conversion, or lookup of an enumeration value will not result in the assignment of 'No value' ($null), but in a 'silent' abort of the assignment. So the variable defined as the target keeps its previous value unchanged and the execution context continues without any error message. Only in the context of Tests is the abort traceable via the 'Log' tab an UnsupportedOperatonException.

Configuration

The input value is basically ignored by the Variable value resolver (in contrast to the Store value as variable value resolver).

Key

By default, a Text field is displayed for the Key parameter for direct entry of a static text for the variable name.

NOTE◄ To address already existing variables, the upper/lower case letters must exactly match the variable name used for write access.

Direct input of a static text:

images/download/attachments/177908063/image-2024-8-13_10-36-47-version-1-modificationdate-1723538206975-api-v2.png

As an alternative to direct input, after clicking on the small gray arrow at the bottom left of the Text field, value resolvers can be configured for direct input, which should return a string suitable as Key.

If no text has been entered yet when clicking on the arrow, a placeholder for the configuration of value resolvers will then appear:

images/download/attachments/177908063/image-2024-8-13_10-42-22-version-1-modificationdate-1723538542393-api-v2.png



Value resolver configuration:

images/download/attachments/177908063/image-2024-8-13_10-40-27-version-1-modificationdate-1723538426987-api-v2.png

  • In the example, a custom date calculation is executed via a Relative date with time and the four-digit year number is 'resolved' as text for the calculated point in time via Format date.

  • The surrounding Concat strings value resolver associates the year with a static text year as a prefix to assign a dynamic variable name such as year2037 or year1984 as a Key depending on the calculation.

NOTE◄ The dynamically assigned variable could be used, for example, to calculate key figures per calendar year in the context of a loop over raw data.

Class

The optional Class parameter supports a static single selection for a class via a 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 the Class implies a Check type for the value of the variable and may – if automatic conversions are provided – also cause a type conversion or a lookup of enumeration values or entities with respect to the return value.

images/download/attachments/177908063/image-2024-8-13_10-45-29-version-1-modificationdate-1723538728580-api-v2.png

NOTE◄ Using the [+] symbol or the Enter key, the string entered here as a search term range could also be confirmed as a free text entry for a class (not listed in the dropdown), although this is probably only rarely intended.

Is collection of

The option Is collection of (unchecked by default) specifies that the value of the variable should be a list. If the value is not a list, the Variable value resolver returns 'no value' ($null).

If a Class is explicitly specified (see image on the right), checking the Is collection of option implies a Check type of all list entries against this Class , so that the return value is $null if at least one of these entries does not match the selected Class.


images/download/attachments/177908063/image-2024-8-13_10-47-3-version-1-modificationdate-1723538823496-api-v2.png

Selecting the Type Long and the Is collection of option implies a Check type for the value of the companyIds variable. If the variable does not contain a list (but e.g. only a single Long value) or a list that contains a check-relevant entry that is not a Long value, the return value is $null.


With regard to 'lists' stored in a variable, it should also be noted:

  • If the option Is collection of is unchecked (default) and no Classs is checked then no Check type takes place. So it is not possible to specify in this way that only one return value is 'desired', which is not a list.

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

  • If the option Is collection of is unchecked when accessing a list, then the Class parameter can be used for a type conversion for the list as a whole.
    Example: A route variable contains a normal 'list' (java.util.List) of String values defined by IATA codes of flight destinations along a 'trip schema':
    In JSON notation, the list in the route variable for a 'round trip' could look like this, for example: [MUC,JFK,GIG,CDG,MUC]If the route variable is accessed by the Class 'List' (java.util.List) or without specifying a type, the return value is exactly the same as the saved value.

    If, on the other hand, the route variable is accessed by Class 'Unique list' (java.util.Set), then the 'List' is converted into a 'Unique list', which can change the order and the number of entries. In the specific example, the return value could look like this: [GIG,CDG,MUC,JFK]

Examples

Simple write access (with and without type conversion)

An approximate value for π/2 (radian measure value for 90°) is written as a decimal number into a rightAngle variable.

Configuration:

Within a Set value event action, the Variable value resolver is used to identify the target for the assignment:

  • The Key is defined by direct input as static text (rightAngle).

  • The Class specification is omitted. This means that the data type is stored that is returned by the value resolver chain on the right side of the assignment (here: 'Big Decimal'/java.math.BigDecimal).

images/download/attachments/177908063/image-2024-8-13_14-36-36-version-1-modificationdate-1723552596027-api-v2.png

Result: (XML image of the variables as entry in the storage map)


<entry>
<key xsi:type="xsd:string">rightAngle</key>
<value xsi:type="xsd:decimal">0.785398163397448309615</value>
</entry>

Within the previous configuration, the Class 'Double' (java.lang.Double) is now selected for write access via the Variable value resolver (on the left side), which stores the calculation result in the variable less precisely.

images/download/attachments/177908063/image-2024-8-13_14-37-40-version-1-modificationdate-1723552659766-api-v2.png

Result: (XML image of the variables as entry in the storage map)


<entry>
<key xsi:type="xsd:string">rightAngle</key>
<value xsi:type="xsd:double">0.7853981633974483</value>
</entry>

Simple read access (with and without type conversion/lookup)

An origin variable contains static text that specifies a 'home country' via the internal name of a value from the Country dynamic enumeration.

In a notification (via Show alert (Popup) event action), the static text is to be reproduced in the 'Title' and its localization as 'Message'.

Runtime example:

images/download/attachments/177908063/image2022-9-29_15-29-30-version-1-modificationdate-1723534694549-api-v2.png

Configuration:

In a Client workflow (in the context of a form), a Show alert (Popup) event action can be configured as shown on the right to achieve the desired result:

  • In the Title, the String value (CN) stored in the origin variable is accessed directly (per Key origin and without selection for the Class) via the Variable value resolver.

  • In the Message, the Variable value resolver with the Key origin is again used to access the variable. However, 'Country' (Country) is selected as the Class here. At runtime, a type conversion of the text value in the origin variable to a value from the dynamic enumeration Country will be performed. If no Country is found with an internal 'Name' that matches the text value, 'no value' ($null) is returned..

IMPORTANT◄ The return value for the Message is a dynamic enumeration value (DynamicEnumValue) if the type conversion is successful, which must be converted back to a String value in the context of the Message parameter for display in the notification. The string conversion for the Country value only takes the applicable localization into account in the client context (here: Client workflow). In the server context (e.g. in Event handling), on the other hand, the 'Name' is output as a string. Then the Title and Message in the example display CN.

images/download/attachments/177908063/image-2024-8-13_14-41-30-version-1-modificationdate-1723552890477-api-v2.png

Read access to a list of entities from a search in the context of a loop

A typical use case where a variable contains a list of entities is the execution of a Search (Event action) of the 'Search' type for which the 'Search value' mode is selected.

In the following example, the search should return all addresses that refer to a region defined by a list of countries (see Country) (here: 'Benelux' with the country codes BE, NL, LU).

A loop then iterates over all 'found' addresses to determine statistical key figures.

Since a Search (Event action) can only be executed as an event action and not as a value resolver, the name of a variable into which the result of the search is saved at runtime must be specified during configuration via the Save result as parameter.

  • In our example, Addresses are searched for, so this entity type must be selected in the Entity parameter.

  • The 'Search value' Mode specifies that a list of all 'found' entities of the selected type should be returned.

  • In addition, the 'Search' option must be selected in the Search parameter so that complete entities are listed in the result and not just tuples with selected projections from their data.

  • Where checks exactly one condition, namely whether the value for the 'Country' (countryCode) field of the address is contained in a positive list with the statically defined enumeration values 'Belgium' (BE), 'Netherlands' (NL) and 'Luxembourg' (LU).

NOTE◄ The Search (Event action) lists only addresses for the 'addresses' entity that can be accessed via Address book entries in the given execution context.

images/download/attachments/177908063/image-2024-8-13_15-37-47-version-1-modificationdate-1723556266955-api-v2.png

The following For each loop event action iterates over all 'found' addresses. A Variable value resolver is therefore used as the Resolver for entries and configured as follows:

  • The Key is the name of the addrBNL variable, which was arbitrarily specified in the Save result as parameter of the Search (Event action) (see above).

  • The 'Address' entity type is selected as Class, like the Entity parameter in the Search (Event action) (see above).

  • The Is collection of option is checked because the 'Search value' Mode for the Search (Event action) (see above) returns a list of entities of the searched type.

Accordingly, the expected data type (at the bottom of the value resolver 'Address[]' is shown and the type 'Address' for the action block of the loop.

images/download/attachments/177908063/image-2024-8-13_14-27-36-version-1-modificationdate-1723552056365-api-v2.png

NOTE◄ The selection for Class could technically also be omitted, since all entries passed into the addrBNL list variable with the Mode 'Search value' must be of the 'Address' entity type. If no entries are found, the variable contains an empty list, so no iterations of the loop are executed. The selection for Class here is mainly for declaring the variable content so that it can be transparently traced in the configuration of the loop and the contained Execute with event action and the 'right' elements (e.g. value resolvers) are offered as 'suitable' for the context.

Read access to an entity via its ID in an association criteria.

An association criterion (see Association criteria) is assumed to be true if the following condition is met:

  • The logged in company (Company of session) either owns the user or guest user account (User of session) used for logging in or owns the company that owns this account.

It could also be formulated: The User of session should be owned either by the Company of session or by the company that owns it.

The configuration for an association criteria shown on the right checks the criteria described above in the context of an Entity property rule:

  • On the left side, the registered company is determined by the Company of session value resolver and its ID (id) is used for an In list comparison by a concatenated Object property value resolver.

  • On the right side, a list is compiled with the IDs of the two company accounts that, according to the requirement above, should be considered 'acceptable' candidates in the sense of the criterion:

    • The first candidate is the 'owner' of the logged-in user account returned by the User of session value resolver.

      • The concatenated Object property value resolver accesses its 'owner' (ownerId) field, whose value contains the ID (id) of the relevant company account relevant for the comparison.

      • The concatenated Store value as variable value resolver stores this ID in the variable myOwnerId, since the company account in question must be accessed to determine its owner as the second candidate.

    • The second candidate is the 'owner' of the company that owns the User of session. To determine this, the company account in question must be evaluated:

      • The Variable value resolver reads the ID stored in the myOwnerId variable and – since this is a numeric value and the Class 'Company account' (CompanyAccount) is selected – looks up the respective company account as return value.

      • The concatenated Object property value resolver then accesses the 'owner' (ownerId) field as above to provide the 'ID' (id) of the relevant company account as a comparison value.

NOTE◄ Instead of using the myOnwerId variable, the second candidate could also start the value resolver chain at the User of session and look up the owning company via the ownerId field as an input value for an Input object (type safe) value resolver to then get its ownerId.

images/download/attachments/177908063/image-2024-8-13_15-50-5-version-1-modificationdate-1723557005218-api-v2.png