{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":907,"path":"api-reference/server-api-reference/ScopedCacheManagerAPI.md","title":"ScopedCacheManager - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# ScopedCacheManager- Scoped\n\nThe ScopedCacheManager API provides methods for retrieving, setting, and flushing cache data for scoped applications.\n\nThis 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.\n\nThese 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/developer-guides/scoped-caches.md).\n\nUsing this API with scoped caches provides several advantages, including:\n\n-   Caching strings in scoped applications that live in memory across transactions.\n-   Caching scoped application data in memory and flushing this data based on changes in the underlying table.\n-   Defining and use cache data outside the transaction life cycle.\n-   Caching the output of expensive operations or calculations for quick access in the future.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## ScopedCacheManager – flushScopedCache\\(String catalog, String key\\)\n\nFlushes an entire cache or a single entry from a cache.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|key|String|Optional. Cache key. Set this parameter to flush a single entry from a cache.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example shows how to flush the \"abc\" key from a cache named myCache. To flush the entire cache, leave out the key parameter.\n\n```\nsn_scoped_cache.ScopedCacheManager.flushScopedCache(\"myCache\", \"abc\");\n```\n\n## ScopedCacheManager – get\\(String catalog, String key\\)\n\nGets a value from a cache.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|key|String|Cache key.|\n\n|Type|Description|\n|----|-----------|\n|String|Cache entry.|\n\nThe 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.\n\n```\nvar cache2 = \"Cache 2\"; // column pair type\n\n// Re-populate the column cache\nfor (var i = 0; i < 100; i+=10) {\n    var inc = new GlideRecord('incident');\n    inc.query();\n    var counter = 0;\n    while (inc.next()) {\n        if (inc.getValue('short_description').length > i)\n        counter++;\n    }\n    sn_scoped_cache.ScopedCacheManager.put(cache2, i.toString(), counter.toString());\n}\n\n// script to get values from column cache\ngs.info(sn_scoped_cache.ScopedCacheManager.get(cache2, \"50\"));\n```\n\nOutput:\n\n```\nscoped_app: 6\n```\n\n## ScopedCacheManager – getCacheEntryDetails\\(String catalog, String key\\)\n\nGets cache entry details including byte size, object type, and entry value.\n\n<table id=\"table_b5d_z35_4tb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ncatalog\n\n</td><td>\n\nString\n\n</td><td>\n\nName 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\"`.\n\n</td></tr><tr><td>\n\nkey\n\n</td><td>\n\nString\n\n</td><td>\n\nCache key.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|String|String in the format `<ObjectType> (<EntrySize>): <Value.toString()>`.|\n\nThe following example shows how to display cache entry details for a scoped cache named `test_cache`.\n\n```\nsn_scoped_cache.ScopedCacheManager.put(\"test_cache\", \"key1\", \"val1\");\ngs.info(sn_scoped_cache.ScopedCacheManager.getCacheEntryDetails(\"global^test_cache\", \"key1\"));\n```\n\nOutput:\n\n```\njava.lang.String (48):\nval1\n```\n\n## ScopedCacheManager – prefixFlush\\(String catalog, String prefix\\)\n\nFlushes all cache entries that have keys beginning with a specified prefix.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|prefix|String|Prefix by which to search for keys when flushing the cache.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example shows how to flush cache values for keys with the prefix `a`.\n\n```\nsn_scoped_cache.ScopedCacheManager.put(\"test_cache\", \"aKey1\", \"val1\");\nsn_scoped_cache.ScopedCacheManager.put(\"test_cache\", \"aKey2\", \"val2\");\nsn_scoped_cache.ScopedCacheManager.put(\"test_cache\", \"bKey1\", \"val3\");\n\nsn_scoped_cache.ScopedCacheManager.prefixFlush(\"test_cache\", \"a\");\n\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"aKey1\"));\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"aKey2\"));\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"bKey1\"));\n```\n\nOutput:\n\n```\n*** Script: null\n*** Script: null\n*** Script: val3\n```\n\n## ScopedCacheManager – put\\(String catalog, String key, String value\\)\n\nPuts a value in a scoped cache for caches that are **Table** or **Table Column** pair types.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|key|String|Cache key.|\n|value|String|Cache entry.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe 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.\n\n```\n//put value in cache for key \"abc\"\ngs.info(\"put key 'abc' into cache with value 'value1'\");\nsn_scoped_cache.ScopedCacheManager.put(\"myCache\", \"abc\", \"value1\");\n\n// retrieve value from cache for key \"abc\"\ngs.info(\"value of 'abc' in cache: \");\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"myCache\", \"abc\")+\"\\n\");\n\n//update an incident record (add string to the description field)\ngs.info(\"Updating incident record.\");\nvar gr = new GlideRecord(\"incident\");\ngr.get(\"<incident_sys_id>\");\ngr.description= \"test12345\";\nif (gr.update()) {\n    gs.info(\"Record updated successfully.\\n\");\n};\n\n//retrieve the value from cache for key \"abc\"\ngs.info(\"Retrieving 'abc' from cache. Value should be null because a table pair was updated.\");\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"myCache\", \"abc\"));\n```\n\nOutput:\n\n```\nscoped_app: put key 'abc' into cache with value 'value1'\nscoped_app: value of 'abc' in cache: \nscoped_app: value1\n\nscoped_app: Updating incident record.\nscoped_app: Record updated successfully.\n\nscoped_app: Retrieving 'abc' from cache. Value should be null because a table pair was updated.\nscoped_app: null\n```\n\n## ScopedCacheManager – putMultiRow\\(String catalog, String key, String value, Array ids\\)\n\nPuts 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.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|The catalog to be flushed. Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|key|String|Cache key for the new entry.|\n|value|String|Value for new entry.|\n|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.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe 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.\n\n```\n// This example requires a table-row pair for the \"incident\" and \"sys_user\" tables assigned to a cache named test_cache\nvar inc1ID = \"1c741bd70b2322007518478d83673af3\";\nvar userID = \"681ccaf9c0a8016400b98a06818d57c7\";\n\n// update to email should invalidate the entry\ngs.info(\"initial put\");\nputCacheEntry();\ngs.info(\"cache value for INC0060: \" + sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"INC0000060\"));\nvar gr = new GlideRecord(\"sys_user\");\ngr.get(userID);\ngr.setValue(\"email\", \"a\" + gr.getValue(\"email\"));\ngr.update();\ngs.info(\"updated user email\");\ngs.info(\"cache value: \" + sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"INC0000060\"));\n\n// update to incident number should invalidate the entry.\ngs.info(\"second put\");\nputCacheEntry();\ngs.info(\"cache value: \" + sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"INC0000060\"));\nvar gr = new GlideRecord(\"incident\");\ngr.get(inc1ID);\ngr.setValue(\"number\", gr.getValue(\"number\") + \"1\");\ngr.update();\ngs.info(\"updated incident number\");\ngs.info(\"cache value: \" + sn_scoped_cache.ScopedCacheManager.get(\"test_cache\", \"INC0000060\"));\n\nfunction putCacheEntry() {\n    var incGr = new GlideRecord(\"incident\");\n    incGr.get(inc1ID);\n    var userGr = new GlideRecord(\"sys_user\");\n    userGr.get(userID);\n    // the cache stores that the incident is assigned to a specific user. So if the incident or user record changes, we should flush.\n    sn_scoped_cache.ScopedCacheManager.putMultiRow(\"test_cache\",incGr.getValue(\"number\"), userGr.getValue(\"email\"), [inc1ID, userID]);\n}\n```\n\nOutput:\n\n```\n*** Script: initial put\n*** Script: cache value for INC0060: employee@example.com\n*** Script: Updating Joe Employee's primary email device based on change to user record email address\n*** Script: updated user email\n*** Script: cache value: null\n*** Script: second put\n*** Script: cache value: aemployee@example.com\n*** Script: updated incident number\n*** Script: cache value: null\n```\n\n## ScopedCacheManager – putRow\\(String catalog, String key, String value, String sysId\\)\n\nPuts 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.\n\n|Name|Type|Description|\n|----|----|-----------|\n|catalog|String|Name of the cache defined in the Scoped Caches \\[sys\\_scoped\\_cache\\] table.|\n|key|String|Cache key.|\n|value|String|Cache entry.|\n|sysId|String|Optional. Sys\\_id of a row in a table, that is, the record being tracked.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe 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.\n\n```\n// build the cache:\nvar number = 'INC0009009';\nvar inc = new GlideRecord('incident');\ninc.addQuery('number', number);\ninc.query();\ninc.next();\nvar entry = inc.caller_id.getDisplayValue();\nsn_scoped_cache.ScopedCacheManager.putRow(\"incident_cache\", inc.getValue('number'), entry, inc.getValue('sys_id'));\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"incident_cache\", number));\n\n// when the incident is altered, the cache entry will be flushed.\ninc = new GlideRecord('incident');\ninc.addQuery('number', number);\ninc.query();\ninc.next();\ninc.setValue('short_description', inc.getValue('short_description') + \"a\");\ninc.update();\ngs.info(sn_scoped_cache.ScopedCacheManager.get(\"incident_cache\", number));\n```\n\nOutput:\n\n```\nscoped_app: John Jones\nscoped_app: null\n```\n\n"}}