Cached Values

Calculations are computationally expensive, but setting and retrieving values is fast so storing values in a cache has a speed benefit. You can perform calculations in one report run, and use them in subsequent runs. Do not store any sensitive data in the cache as it is available for all other users of the system.

ReportMagic supports up to 10,000 cached values per customer account.

Scopes

When setting a cache, there are two options for the scope parameter. Use Local unless you need to use Global:

• Local applies to just this Report Schedule
• Global applies to the entire account

If you are using Report Studio, you must use Global, as Local is not supported.

Value Types

Cached values keep the type they were stored as. When a value is retrieved, the report variable is set back to the original type, so numbers can be used directly in calculations, dates behave as dates, and JSON objects come back as real objects rather than as text. The supported types are:

• String
• Integer
• Double and Decimal
• Boolean
• DateTime and DateTimeOffset
• Guid
• JObject and JArray (JSON objects and arrays)

There are two ways to store a typed value:

• Late evaluation: when the value is supplied from a variable using late evaluation, for example value={=myVariable}, the variable's type is stored automatically.
• The type parameter: plain text can be stored as a stated type, for example value=123, type=Integer.

Plain text values without a type parameter are stored as strings, exactly as before. Values that were cached before type support was introduced are also treated as strings.

Some examples are given below. See the individual macros for more information.

Examples

[Cache.Set:]

Example: [Cache.Set:key=ABC, value=123, scope=Global, expires=2075-02-17]

The above example would set a key/value pair of ABC=123, stored as a string. When you need to retrieve the cache you will refer to the key. The expiry date that has been set is excessive - the value will be available until 2075-02-17. Please set a sensible expiry date.

Example: [Calculate: value=6 * 7, storeAsHidden=intVariable][Cache.Set:key=DEF, value={=intVariable}, scope=Global, expires=2027-01-01]

The above example calculates an integer, stores it in the intVariable variable, and then caches it using late evaluation. Because the variable is passed using late evaluation, it keeps its type - the cached value is stored as an Integer, not as text.

Example: [Cache.Set:key=Config, value=`{"threshold": 5}`, type=JObject, scope=Global, expires=2027-01-01]

The above example stores a JSON object. The type parameter tells ReportMagic to store the plain text as a JObject. Use backticks around values containing commas or square brackets.

[Cache.Get:]

Example: [Cache.Get:key=ABC]

This macro returns the value stored in the cache whose key is ABC. The value is returned as the type it was stored as - for example, a stored JObject is returned as a JObject, not as text.

Example: [Cache.Get:key=DEF, storeAsHidden=cachedNumber][Calculate: value=cachedNumber * 7]

The above example retrieves the number cached by the earlier [Cache.Set:] example into the cachedNumber variable, and uses it directly in a calculation - no re-parsing is needed because the value kept its type. This works across report runs, so a value calculated in one run can be used in the next.

[Cache.IsSet:]

Example: [Cache.IsSet:key=ABC]

This macro returns "true" if the value is stored in the cache, otherwise "false".

[Cache.Expires: ]

Example: [Cache.Expires:key=ABC]

This macro returns the expiry date if the value is stored in the cache, otherwise nothing.

[Cache.Unset:]

Example: [Cache.Unset:key=ABC]

This macro removes the value from the cache.

Managing Cached Values

Tenant Admins can manage (view, create, edit and delete) cached values in the Admin App here. The Type column shows the type each value was stored as.