You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info
![](https://docs.apigee.com/static/api-platform/images/icon_policy_traffic-management.jpg)

Configures how cached values should be written at runtime.

The Populate Cache policy is designed for writing entries in a short-term general-purpose cache.
It's used in conjunction with the [Lookup
Cache policy](https://docs.apigee.com/api-platform/reference/policies/lookup-cache-policy) (for reading cache entries) and the
[Invalidate Cache policy](https://docs.apigee.com/api-platform/reference/policies/invalidate-cache-policy)
(for invalidating entries).

For caching the responses of backend resources, see the
[Response Cache policy](https://docs.apigee.com/api-platform/reference/policies/response-cache-policy).

## Element reference

The following lists the elements you can configure on this policy.

```
<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>
```

## \<PopulateCache\> attributes

The following table describes attributes that are common to all policy parent elements:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required |
| `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. | false | Optional |
| `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional |
| `async` | This attribute is deprecated. | false | Deprecated |

## \<DisplayName\> element

Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.

```
<DisplayName>Policy Display Name</DisplayName>
```

| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## \<CacheKey\> element

Configures a unique pointer to a piece of data stored in the cache.

Cache keys are limited to a size of 2 KB.

```
<CacheKey>
    <Prefix>*string*</Prefix>
    <KeyFragment ref="*variable_name*" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Required |
| **Type:** | N/A |

`<CacheKey>` constructs the name of each piece of data stored in the
cache.

At runtime, `<KeyFragment>` values are prepended with either the
`<Scope>` element value or `<Prefix>` value. For example, the
following results in a cache key of
`UserToken__apiAccessToken__`\<*value_of_client_id\>*:

```
<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>
```

You use the `<CacheKey>` element in conjunction with
`<Prefix>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

## \<CacheResource\> element

Specifies the cache where messages should be stored.

Omit this element completely if this policy (and your corresponding LookupCache and
InvalidateCache policies) is using the included shared cache.

```
<CacheResource>cache_to_use</CacheResource>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

For more about configuring caches, see [Creating and editing an environment
cache](https://docs.apigee.com/api-platform/cache/manage-caches-environment).

## \<CacheKey\>/\<KeyFragment\> element

Specifies a value that should be included in the cache key, creating a namespace for matching
requests to cached responses.

```
<KeyFragment ref="*variable_name*"/>
<KeyFragment>*literal_string*</KeyFragment>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | N/A |

This can be a key (a static name that you provide) or a value (a dynamic entry set by
referencing a variable). All specified fragments combined (plus the prefix) are concatenated to
create the cache key.

```
<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />
```

You use the `<KeyFragment>` element in conjunction with
`<Prefix>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

### Attributes

| Attribute | Type | Default | Required | Description |
|---|---|---|---|---|
| ref | string |   | No | The variable from which to get the value. Should not be used if this element contains a literal value. |

## \<CacheKey\>/\<Prefix\> element

Specifies a value to use as a cache key prefix.

```
<Prefix>prefix_string</Prefix>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Optional |
| **Type:** | String |

Use this value instead of `<Scope>` when you want to specify your own value
rather than a `<Scope>` -enumerated value. If defined,
`<Prefix>` prepends the cache key value for entries written to the cache. A
`<Prefix>` element value overrides a `<Scope>` element
value.

You use the `<Prefix>` element in conjunction with
`<CacheKey>` and `<Scope>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

## \<ExpirySettings\> element

Specifies when a cache entry should expire. When
present, `<TimeoutInSeconds>` overrides
both `<TimeOfDay>` and `<ExpiryDate>`.

```
<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Required |
| **Type:** | N/A |

### Child elements of `<ExpirySettings>`

Use exactly one child element. The following table provides a description of the child elements of
`<ExpirySettings>`:

| Child Element | Description |
|---|---|
| `<TimeoutInSeconds>` | The number of seconds after which a cache entry should expire. ``` <ExpirySettings> <TimeoutInSeconds ref="*var-containing-duration*">expiry</TimeoutInSeconds> </ExpirySettings> ``` This element replaces the now-deprecated `TimeoutInSec` element. |
| `<ExpiryDate>` | Specifies the date on which a cache entry should expire. Specify a string in the form `mm-dd-yyyy`. ``` <ExpirySettings> <ExpiryDate ref="*var-containing-date*">expiry</ExpiryDate> </ExpirySettings> ``` If the date specified is in the past, the policy will apply the maximum time-to-live to the cached entry. This maximum is 30 days. |
| `<TimeOfDay>` | Specifies the time of day on which a cache entry should expire. Specify a string in the form `HH:mm:ss`, where HH represents the hour on a 24-hour clock, in the UTC time zone. For example, 14:30:00 implies 2:30 in the afternoon. ``` <ExpirySettings> <TimeOfDay ref="*var-containing-time*">expiry</TimeOfDay> </ExpirySettings> ``` > [!NOTE] > **Notes:** > - Specify times in the [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC) time zone. > - Populate Cache time notation follows the international standard date notation defined in International Standard [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). |

You should specify only one of the possible child elements. If you specify multiple elements,
the order of precedence is:`TimeoutInSeconds`, `ExpiryDate`,
`TimeOfDay`.

With each of the above child elements of `<ExpirySettings>`,
if you specify the optional `ref` attribute on the child element, the policy will
retrieve the expiry value from the named context variable. If the variable is not defined,
the policy uses the literal text value of the child element.

## \<Scope\> element

Enumeration used to construct a prefix for a cache key when a `<Prefix>`
element is not provided in the `<CacheKey>` element.

```
<Scope>*scope_enumeration*</Scope>
```

|---|---|
| **Default:** | "Exclusive" |
| **Presence:** | Optional |
| **Type:** | String |

The `<Scope>` setting determines a cache key that is prepended according to
the `<Scope>` value. For example, a cache key would take the following form when
scope is set to `Exclusive`:

*orgName__envName__apiProxyName__deployedRevisionNumber__proxy\|TargetName__* \[
*serializedCacheKey* \]

If a `<Prefix>` element is present in `<CacheKey>`, it
supersedes a `<Scope>` element value. Valid values include the enumerations
below.

You use the `<Scope>` element in conjunction with
`<CacheKey>` and `<Prefix>`. For more information, see [Working with cache keys](https://docs.apigee.com/api-platform/reference/policies/working-cachekeys).

### Acceptable values

|---|---|
| `Global` | Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form *orgName* __ *envName* __. If you define a `<CacheKey>` entry with the `<KeyFragment>` apiAccessToken and a `<Global>` scope, each entry is stored as `orgName__envName__apiAccessToken`, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: `apifactory__test__apiAccessToken`. |
| `Application` | API proxy name is used as the prefix. Cache key is prepended in the form *orgName__envName__apiProxyName*. |
| `Proxy` | ProxyEndpoint configuration is used as the prefix. Cache key is prepended in the form *orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName* . |
| `Target` | TargetEndpoint configuration is used as the prefix. Cache key prepended in the form *orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName* . |
| `Exclusive` | Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache. Prefix is one of two forms: - If the policy is attached to the `ProxyEndpoint` flow, prefix is of the form *ApiProxyName_ProxyEndpointName*. - If the policy is attached at `TargetEndpoint`, prefix is of the form *ApiProxyName_TargetName*. Cache key prepended in the form *orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName* For example, the full string might look like this: ``` apifactory__test__weatherapi__16__default__apiAccessToken ``` . |

## \<Source\> element

Specifies the variable whose value should be written to the cache.

```
<Source>*source_variable*</Source>
```

|---|---|
| **Default:** | N/A |
| **Presence:** | Required |
| **Type:** | String |

## Usage notes

Use this policy for general purpose caching. At runtime, the
`<PopulateCache>` policy writes data from the variable you specified in the
`<Source>` element to the cache you specified in the
`<CacheResource>` element. You can use the `<CacheKey>`,
`<Scope>`, and `<Prefix>` elements to specify a key that you
can use from the `<LookupCache>` policy to retrieve the value. Use the
`<ExpirySettings>` element to configure when the cached value should expire.

General purpose caching with the PopulateCache policy, [LookupCache policy](https://docs.apigee.com/api-platform/reference/policies/lookup-cache-policy), and [InvalidateCache policy](https://docs.apigee.com/api-platform/reference/policies/invalidate-cache-policy) uses
either a cache you configure or a shared cache that's included by default. In most cases, the
underlying shared cache should meet your needs. To use this cache, simply omit the
`<CacheResource>` element.

**Cache limits** : [Various cache limits](https://docs.apigee.com/api-platform/reference/limits)
apply, such as name and value size, total number of caches, the number of items in a cache,
and expiration.

For more about the underlying data store, see [Cache internals](https://docs.apigee.com/api-platform/cache/cache-internals). For more about configuring
caches, see [Creating and editing an
environment cache](https://docs.apigee.com/api-platform/cache/manage-caches-environment).

### About cache encryption

**Edge for Public Cloud:** Cache is encrypted **only** in
[PCI](https://docs.apigee.com/api-platform/faq/pci-configuration-guide-edge-public-cloud)-
and [HIPAA](https://docs.apigee.com/api-platform/faq/hipaa-configuration-guide-edge-public-cloud)-enabled
organizations. Encryption for those organizations is configured during organization
provisioning.

## Error codes


This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Runtime errors

These errors can occur when the policy executes.

> [!IMPORTANT]
> **Tip:** Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. See [Set up a policy fault code alert](https://docs.apigee.com/api-monitoring/alerts-notifications#fault-code-alert) for an example. See [Fault code reference](https://docs.apigee.com/api-monitoring/fault-codes) for a complete list of all fault codes that you can handle with API Monitoring.

| Fault code | HTTP Status | Occurs when |
|---|---|---|
| `policies.populatecache.EntryCannotBeCached` | 500 | An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable. |

### Deployment errors

These errors can occur when you deploy a proxy containing this policy.

> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

| Error name | Cause | Fix |
|---|---|---|
| `InvalidCacheResourceReference` | This error occurs if the `<CacheResource>` element in the PopulateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/populate-cache-deployment-errors#invalidcacheresourcereference) |
| `CacheNotFound` | The cache specified in the `<CacheResource>` element does not exist. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/populate-cache-deployment-errors#cachenotfound) |

### Fault variables

These variables are set when this policy triggers an error. For more information, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors).

| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | <var translate="no">fault_name</var> is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/populate-cache-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name = "EntryCannotBeCached"` |
| `populatecache.policy_name.failed` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `populatecache.POP-CACHE-1.failed = true` |

### Example error response

```
{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}
```

### Example fault rule

```
<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>
```

<br />