The KeyValueMapOperations policy provides policy-based access to a key/value store available in Apigee Edge. The store provides a lightweight persistence mechanism for data formatted as key/value pairs, which can be accessed at runtime by policies or code running on Edge. KeyValueMapOperations are typically used to store or retrieve long-lived information that needs to be reused over multiple request/response transactions.

KeyValue refers to any arbitrary data in the format key=value, for example localhost=, zip_code=94110, or first_name=felix.

In the first example, localhost is a key, and is a value.

Each key/value pair is stored in a map as an entry. A key/value map can store many entries.

For example, say you need to store a list of IP addresses associated with various backend environments. You could create a map called ipAddresses that contains a list of key/value pairs as entries. For example, this JSON might represent such a map:

  "entry" : [ {
    "name" : "Development",
    "value" : ""
  }, {
    "name" : "Staging",
    "value" : ""
  } ],
  "name" : "ipAddresses"

You could use this structure to create a store of IP addresses that could be used by policies at runtime to enforce IP whitelisting or blacklisting, to dynamically select a backend target address, and so on.

KeyValue pairs can be stored, retrieved and deleted from named maps by configuring policies that specify PUT, GET, or DELETE operations.

The following operations are supported in the KeyValueMapOperations policy.

  • PUT: Writes entries to an existing KeyValueMap
  • GET: Retrieves the value for the key specified
  • DELETE: Deletes the key or value specified

Key/Value maps can be manipulated via the KeyValueMapOperations policy, or directly via the Apigee Edge management API. Refer to the management API reference for details on the Key/Value Maps API. The API is useful, for example, for uploading large data sets to the key/value store, or creating scripts to manage key/value map entries. You will need to create a key/value map with the API before accessing it with the KeyValueMapOperations policy.


A simple example of a useful KeyValueMap is a URL 'shortening' service. The KeyValueMap could be configured to store shortened URLs along with corresponding full URLs.

KeyValueMap PUT Sample

The following policy configuration creates a KeyValueMap. The policy PUTs a key with two associated values into a key/value map named "urlMapper".

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
  <Put override="true">
      <Parameter ref="urlencoding.requesturl.hashed"/>
    <Value ref="urlencoding.longurl.encoded"/>
    <Value ref="request.queryparam.url"/>

The key in this example, urlencoding.requesturl.hashed, is an example of a custom variable. The hashed request URL would would be generated by code (JavaScript or Java, for example) and then stored in this variable, where the KeyValueMapOperations policy can access it.

For each key, requesturl.hashed, two values are stored:

  • The contents of the custom variable named urlencoding.longurl.encoded
  • The contents of the pre-defined variable request.queryparam.url

When the policy executes at runtime, the values of the variables are as follows:

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded:
  • request.queryparam.url:

The following key/value map and entry would be generated in Edge's key/value store and scoped to the API proxy to which the policy is attached:

  "entry" : [ {
    "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
    "value" : ","
  } ],
  "name" : "urlMapper"

The entry will persist until it is deleted. Key/value store entries are distributed across instances of Edge that are running the cloud.

KeyValueMap GET Sample

To retrieve the value of key/value map entry, configure a policy to GET the KeyValueMap, as follows:

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
  <Get assignTo="urlencoding.shorturl" index='1'>
      <Parameter ref="urlencoding.requesturl.hashed"/> 

When this policy is executed, if the value of the urlencoding.requesturl.hashed variable is ed24e12820f2f900ae383b7cc4f2b31c402db1be, then the custom variable named urlencoding.shorturl will be set with the value

Now that the data has been retrieved, other policies and code can access it by extracting the value from those variables.

Configuring the KeyValueMapOperation policy

Configure the KeyValueMap Operation policy using the following elements.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
Scope (Optional)
Valid values: organization, environment, apiproxy, policy
Default value: environment
Defines the boundary of accessibility for KeyValueMaps.
The default scope is environment, meaning that, by default, maps entries are shared by all API proxies running in an environment (i.e., test or prod).
If you set the scope to apiproxy, then entries in the KeyValueMap are accessible only by the API proxy that writes the values to the Map.
ExclusiveCache (DEPRECATED: Use Scope instead.)
Valid values: true/false
Default value: false
If false, the cache provided by the environment is used.
If true, a cache is created exclusively.
InitialEntries (Optional) Entry Key Parameter (Mandatory) Seed values for KeyValueMaps, which are populated in the KeyValueMap when it is initialized. A key can be composite, which means that more than one parameter can be appended to make the key. For example, userID and role might be combined constitute a key.
Value (Required) Specifies the value for a key. In the example below, the map is initialized by the two key/value entries [k1] -> [v1, v2] and [k2, k3] -> [v3, v4].
Put (Required) Key Parameter (Required) Includes an entry inside a key/value map for the specified key.
Value (Required) You can specify multiple values for a key.
Valid values: true/false
Default value: false
If true, it overrides the value for a key.
Get (Required) Key Parameter (Required) Retrieves a value for the specified key.
assignTo (Required) Assigns the retrieved value to a flow variable or simply a variable.
index (Optional) You can specify an index for a multi-valued key. For example, if index=1, the value at index 1 is fetched and assigned to the variable. If not specified, all the values of that entry are assigned to the variable as java.util.List. For an example, see Samples
Delete (Required) Key Parameter (Required) Specifies the key to be deleted.

Policy-specific error codes

The default format for error codes returned by Policies is:

  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]

The KeyValueMap Policy type defines the following error codes:

Error Code Message
SetVariableFailed Failed to set variable {0} in KeyValueMapStepDefinition {1}
RemoveVariableFailed Failed to remove variable {0} in KeyValueMapStepDefinition {1}
InvalidIndex Invalid index {0} in KeyValueMapStepDefinition {1}
KeyIsMissing Key element is not missing in KeyValueMapStepDefinition {0}
ValueIsMissing Value element is missing in KeyValueMapStepDefinition {0}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)