Implementing Value Maps

Table of Contents

• Value Map API
• Value Map Error Handling and Missing Data
• Value Map Definition Files
  • Value Map Definition File Headers
  • Value Map Definition File Body

Value Map API

User code implementation can use the following functions to access value maps:

• UserApi::getValueMap()
• UserApi::getValueMaps()

Value Map Error Handling and Missing Data

UserApi::getValueMap() returns NOTHING by default if there is no value for the given key, however an exception can be thrown if there is the "throws_exception" flag is set to True.

The exception error is VALUE-MAP-ERROR with description "value map 'name' does not contain value for key 'keyname'"

Value Map Definition Files

value maps can be defined and changed in the Qorus user interface or using the REST API. However, for large value maps it's much more useful to create value map files and load them with oload: Data Loading Tool and Schema Manager as a part of user code releases/deployments.

value maps are defined in *.qvmap files. The structure of the file is similar to that of a service or job definition file and uses similar headers.

Value Map Definition Example:

# name: test1
# desc: test value map
# author: Petr Vanek (Qore Technologies, sro)
# exception: true
# valuetype: raw
# define-group: EXAMPLES: example interface objects
# groups: EXAMPLES

"foo",1,true
"bar","lorem ipsum",false

# END

Value Map Definition File Headers

Value map definition file headers are as follows:

• name: (required) the unique name of the value map; loading a new value map with an already existing name removes the old key-value mappings
• [desc]: a description of the value map
• [author]: a string identifying the author of the value map
• [exception]: a flag determining the behavior of an invalid lookup (see Value Map Error Handling and Missing Data)
• valuetype: (required) Value Map Data Types
• [dateformat]: When the valuetype is set to "date", "dateformat" defines a mask for converting string input values to real dates using the Qore::date(string) function (see date format mask for more information)
• [define-group]: Allows interface groups to be defined; format is: name: description
• [groups]: One or more interface groups that the value map is a member of for access purposes (value maps cannot be enabled or disabled)

Value Map Definition File Body

The body of the *.qvmap file contains comma separated value (CSV) data in three columns defining the lookup data for the value map as follows:

• key name: this is the lookup key and must be unique in the value map
• value: the value is handled as described in Value Map Data Types
• enabled flag: (optional) if False, the key-value pair is hidden for the API; see Enabled and Disabled Values

Simple value map example:

# name: regression1
# desc: test value map
# author: Josephine Programmer (Qore Technologies, s.r.o.)
# exception: true
# category: default
# valuetype: string
# define-group: EXAMPLES: example interface objects
# groups: EXAMPLES

"key1","foo",true
"key2","bar",false
# END

Note

Complex values (lists, hashes, etc) provided for value maps of type raw should be loaded in yaml form because they will be stored as raw strings.