---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# ScopedCacheManager - Scoped

# ScopedCacheManager - Scoped {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

The ScopedCacheManager API provides methods for retrieving, setting, and flushing cache data for scoped applications.

This API requires the Scoped Cache (com.glide.scopedcache) plugin and runs in the `sn_scoped_cache` namespace. The plugin is installed and activated by default.

These methods require one or more scoped caches and scoped cache pairs to be defined. For more information on creating scoped caches, see the [ScopedCacheManager API Developer Guide](https://servicenow-prod.fluidtopics.net/EsjGyDvAwfq0Ro3VLjZQ_Q#scoped-caches "Scoped caches allow customers to store custom data in memory for faster access, and define when it becomes invalidated. This can be useful when working with data takes longer to obtainthat from scratch, such as the results of a query across multiple tables. Use the ScopedCacheManager API to retrieve, set, and flush cache data for scoped applications.").  
Using this API with scoped caches provides several advantages, including:

* Caching strings in scoped applications that live in memory across transactions.
* Caching scoped application data in memory and flushing this data based on changes in the underlying table.
* Defining and use cache data outside the transaction life cycle.
* Caching the output of expensive operations or calculations for quick access in the future.
{#ScopedCacheManagerAPI__ul_kjm_gnl_w5b}

## ScopedCacheManager -- flushScopedCache(String catalog, String key) {#ariaid-title2}

Flushes an entire cache or a single entry from a cache.
{#ScpdCchMgr-flushScopedCache_S_S__table_yxh_w35_4tb__entry__3}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| key | String | Optional. Cache key. Set this parameter to flush a single entry from a cache. |
[Table 1. Parameters]

{#ScpdCchMgr-flushScopedCache_S_S__table_yxh_w35_4tb} {#ScpdCchMgr-flushScopedCache_S_S__table_zxh_w35_4tb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 2. Returns]

{#ScpdCchMgr-flushScopedCache_S_S__table_zxh_w35_4tb}  
The following example shows how to flush the "abc" key from a cache named myCache. To flush
the entire cache, leave out the key parameter.

    sn_scoped_cache.ScopedCacheManager.flushScopedCache("myCache", "abc");

## ScopedCacheManager -- get(String catalog, String key) {#ariaid-title3}

Gets a value from a cache.
{#ScpdCchMgr-get_S_S__table_b5d_z35_4tb__entry__3}{#ScpdCchMgr-get_S_S__sCachedMgrAPI-ph-entry-key}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| key | String | Cache key. |
[Table 3. Parameters]

{#ScpdCchMgr-get_S_S__table_b5d_z35_4tb} {#ScpdCchMgr-get_S_S__table_c5d_z35_4tb__entry__2}

| Type | Description |
|-|-|
| String | Cache entry. |
[Table 4. Returns]

{#ScpdCchMgr-get_S_S__table_c5d_z35_4tb}  
The following example shows how to count the number of incident records having short
descriptions with a number of characters greater than the key (50). In this case, there are
6 incident records with short descriptions longer than 50 characters. This value is stored
in the cache as a reusable string, so you don't have to make a calculation each time you
want to retrieve the value.

    var cache2 = "Cache 2"; // column pair type

    // Re-populate the column cache
    for (var i = 0; i < 100; i+=10) {
        var inc = new GlideRecord('incident');
        inc.query();
        var counter = 0;
        while (inc.next()) {
            if (inc.getValue('short_description').length > i)
            counter++;
        }
        sn_scoped_cache.ScopedCacheManager.put(cache2, i.toString(), counter.toString());
    }

    // script to get values from column cache
    gs.info(sn_scoped_cache.ScopedCacheManager.get(cache2, "50"));

Output:

    scoped_app: 6

## ScopedCacheManager -- getCacheEntryDetails(String catalog, String key) {#ariaid-title4}

Gets cache entry details including byte size, object type, and entry value.
{#ScpdCchMgr-getCacheEntryDetails_S_S__table_b5d_z35_4tb__entry__3}{#ScpdCchMgr-getCacheEntryDetails_S_S__sCachedMgrAPI-ph-entry-key}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. The catalog name must be prefixed with the scope name and a caret character. For example, "test_cache" in the global scope is prefixed as `"global^test_cache"`. |
| key | String | Cache key. |
[Table 5. Parameters]

{#ScpdCchMgr-getCacheEntryDetails_S_S__table_b5d_z35_4tb} {#ScpdCchMgr-getCacheEntryDetails_S_S__table_c5d_z35_4tb__entry__2}

| Type | Description |
|-|-|
| String | String in the format `<ObjectType> (<EntrySize>): <Value.toString()>`. |
[Table 6. Returns]

{#ScpdCchMgr-getCacheEntryDetails_S_S__table_c5d_z35_4tb}  
The following example shows how to display cache entry details for a scoped cache named
`test_cache`.

    sn_scoped_cache.ScopedCacheManager.put("test_cache", "key1", "val1");
    gs.info(sn_scoped_cache.ScopedCacheManager.getCacheEntryDetails("global^test_cache", "key1"));

Output:

    java.lang.String (48):
    val1

## ScopedCacheManager -- prefixFlush(String catalog, String prefix) {#ariaid-title5}

Flushes all cache entries that have keys beginning with a specified prefix.
{#ScpdCchMgr-prefixFlush_S_S__table_b5d_z35_4tb__entry__3}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| prefix | String | Prefix by which to search for keys when flushing the cache. |
[Table 7. Parameters]

{#ScpdCchMgr-prefixFlush_S_S__table_b5d_z35_4tb} {#ScpdCchMgr-prefixFlush_S_S__table_c5d_z35_4tb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 8. Returns]

{#ScpdCchMgr-prefixFlush_S_S__table_c5d_z35_4tb}  
The following example shows how to flush cache values for keys with the prefix
`a`.

    sn_scoped_cache.ScopedCacheManager.put("test_cache", "aKey1", "val1");
    sn_scoped_cache.ScopedCacheManager.put("test_cache", "aKey2", "val2");
    sn_scoped_cache.ScopedCacheManager.put("test_cache", "bKey1", "val3");

    sn_scoped_cache.ScopedCacheManager.prefixFlush("test_cache", "a");

    gs.info(sn_scoped_cache.ScopedCacheManager.get("test_cache", "aKey1"));
    gs.info(sn_scoped_cache.ScopedCacheManager.get("test_cache", "aKey2"));
    gs.info(sn_scoped_cache.ScopedCacheManager.get("test_cache", "bKey1"));

Output:

    *** Script: null
    *** Script: null
    *** Script: val3

## ScopedCacheManager -- put(String catalog, String key, String value) {#ariaid-title6}

Puts a value in a scoped cache for caches that are Table or
Table Column pair types.
{#ScpdCchMgr-put_S_S_S__table_rzq_235_4tb__entry__3}{#ScpdCchMgr-put_S_S_S__sCachedMgrAPI-ph-entry-key}{#ScpdCchMgr-put_S_S_S__sCachedMgrAPI-parm-ph-value}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| key | String | Cache key. |
| value | String | Cache entry. |
[Table 9. Parameters]

{#ScpdCchMgr-put_S_S_S__table_rzq_235_4tb} {#ScpdCchMgr-put_S_S_S__table_szq_235_4tb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 10. Returns]

{#ScpdCchMgr-put_S_S_S__table_szq_235_4tb}  
The following example shows how to define and retrieve a key called "abc" to a cache named
myCache. The cache is table-paired with the Incident \[incident\] table. The example also
shows how the cache is flushed after updating the description field of an incident
record.

    //put value in cache for key "abc"
    gs.info("put key 'abc' into cache with value 'value1'");
    sn_scoped_cache.ScopedCacheManager.put("myCache", "abc", "value1");

    // retrieve value from cache for key "abc"
    gs.info("value of 'abc' in cache: ");
    gs.info(sn_scoped_cache.ScopedCacheManager.get("myCache", "abc")+"\n");

    //update an incident record (add string to the description field)
    gs.info("Updating incident record.");
    var gr = new GlideRecord("incident");
    gr.get("<incident_sys_id>");
    gr.description= "test12345";
    if (gr.update()) {
        gs.info("Record updated successfully.\n");
    };

    //retrieve the value from cache for key "abc"
    gs.info("Retrieving 'abc' from cache. Value should be null because a table pair was updated.");
    gs.info(sn_scoped_cache.ScopedCacheManager.get("myCache", "abc"));

Output:

    scoped_app: put key 'abc' into cache with value 'value1'
    scoped_app: value of 'abc' in cache: 
    scoped_app: value1

    scoped_app: Updating incident record.
    scoped_app: Record updated successfully.

    scoped_app: Retrieving 'abc' from cache. Value should be null because a table pair was updated.
    scoped_app: null

## ScopedCacheManager -- putMultiRow(String catalog, String key, String value, Array
ids) {#ariaid-title7}

Puts an entry into the cache and sets all records with the specified sys_ids as a flush
source for that entry. This method is intended for caches that are Table
or Table Column pair types.
{#ScpdCchMgr-putMultiRow_S_S_S_A__table_b5d_z35_4tb__entry__3}

| Name | Type | Description |
|-|-|-|
| catalog | String | The catalog to be flushed. Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| key | String | Cache key for the new entry. |
| value | String | Value for new entry. |
| ids | Array | List of sys_ids of the records to be used as flush sources for the entry. These records can be from different tables. |
[Table 11. Parameters]

{#ScpdCchMgr-putMultiRow_S_S_S_A__table_b5d_z35_4tb} {#ScpdCchMgr-putMultiRow_S_S_S_A__table_c5d_z35_4tb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 12. Returns]

{#ScpdCchMgr-putMultiRow_S_S_S_A__table_c5d_z35_4tb}  
The following example shows how to use an incident and user record as flush points. The
test_cache key INC0000060 is flushed when either of the specified records is updated.

    // This example requires a table-row pair for the "incident" and "sys_user" tables assigned to a cache named test_cache
    var inc1ID = "1c741bd70b2322007518478d83673af3";
    var userID = "681ccaf9c0a8016400b98a06818d57c7";

    // update to email should invalidate the entry
    gs.info("initial put");
    putCacheEntry();
    gs.info("cache value for INC0060: " + sn_scoped_cache.ScopedCacheManager.get("test_cache", "INC0000060"));
    var gr = new GlideRecord("sys_user");
    gr.get(userID);
    gr.setValue("email", "a" + gr.getValue("email"));
    gr.update();
    gs.info("updated user email");
    gs.info("cache value: " + sn_scoped_cache.ScopedCacheManager.get("test_cache", "INC0000060"));

    // update to incident number should invalidate the entry.
    gs.info("second put");
    putCacheEntry();
    gs.info("cache value: " + sn_scoped_cache.ScopedCacheManager.get("test_cache", "INC0000060"));
    var gr = new GlideRecord("incident");
    gr.get(inc1ID);
    gr.setValue("number", gr.getValue("number") + "1");
    gr.update();
    gs.info("updated incident number");
    gs.info("cache value: " + sn_scoped_cache.ScopedCacheManager.get("test_cache", "INC0000060"));

    function putCacheEntry() {
        var incGr = new GlideRecord("incident");
        incGr.get(inc1ID);
        var userGr = new GlideRecord("sys_user");
        userGr.get(userID);
        // the cache stores that the incident is assigned to a specific user. So if the incident or user record changes, we should flush.
        sn_scoped_cache.ScopedCacheManager.putMultiRow("test_cache",incGr.getValue("number"), userGr.getValue("email"), [inc1ID, userID]);
    }

Output:

    *** Script: initial put
    *** Script: cache value for INC0060: employee@example.com
    *** Script: Updating Joe Employee's primary email device based on change to user record email address
    *** Script: updated user email
    *** Script: cache value: null
    *** Script: second put
    *** Script: cache value: aemployee@example.com
    *** Script: updated incident number
    *** Script: cache value: null

## ScopedCacheManager -- putRow(String catalog, String key, String value, String sysId) {#ariaid-title8}

Puts a value in a single row (table) of a cache. Use this method for caches that are
Table Row or Table Row and Column pair
types.
{#ScpdCchMgr-putRow_S_S_S_S__table_rzq_235_4tb__entry__3}{#ScpdCchMgr-putRow_S_S_S_S__sCachedMgrAPI-ph-entry-key}{#ScpdCchMgr-putRow_S_S_S_S__sCachedMgrAPI-parm-ph-value}

| Name | Type | Description |
|-|-|-|
| catalog | String | Name of the cache defined in the Scoped Caches \[sys_scoped_cache\] table. |
| key | String | Cache key. |
| value | String | Cache entry. |
| sysId | String | Optional. Sys_id of a row in a table, that is, the record being tracked. |
[Table 13. Parameters]

{#ScpdCchMgr-putRow_S_S_S_S__table_rzq_235_4tb} {#ScpdCchMgr-putRow_S_S_S_S__table_szq_235_4tb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 14. Returns]

{#ScpdCchMgr-putRow_S_S_S_S__table_szq_235_4tb}  
The following example uses a table row pair cache type named incident_cache. The cache adds
the incident caller ID, and the cache entries associated with the changed record's sys_id
are cleared.

    // build the cache:
    var number = 'INC0009009';
    var inc = new GlideRecord('incident');
    inc.addQuery('number', number);
    inc.query();
    inc.next();
    var entry = inc.caller_id.getDisplayValue();
    sn_scoped_cache.ScopedCacheManager.putRow("incident_cache", inc.getValue('number'), entry, inc.getValue('sys_id'));
    gs.info(sn_scoped_cache.ScopedCacheManager.get("incident_cache", number));

    // when the incident is altered, the cache entry will be flushed.
    inc = new GlideRecord('incident');
    inc.addQuery('number', number);
    inc.query();
    inc.next();
    inc.setValue('short_description', inc.getValue('short_description') + "a");
    inc.update();
    gs.info(sn_scoped_cache.ScopedCacheManager.get("incident_cache", number));

Output:

    scoped_app: John Jones
    scoped_app: null