You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info
Conceptually, *flow variables* are objects that you can access from within your policies or
utilities (such as the [Trace tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) tool). They allow you to maintain state associated with an
API transaction processed by Apigee Edge.
> [!NOTE]
>
> ### Quick Start
>
> - [Related code samples:](https://docs.apigee.com/api-platform/fundamentals/introduction-flow-variables#relatedcodesamples) Many of the API proxy samples use flow variables
> - [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference): A complete list of all flow variables and their properties
### Video
The following video provides an introduction to flow variables:
## What are flow variables?
Flow variables exist within the context of an API proxy flow, and they track state in an API
transaction the way named variables track state in a software program. Flow variables store
information such as:
- The IP address, headers, URL path, and payload sent from the requesting app
- System information such as the date and time when Edge receives a request
- Data derived when a policy executes. For example after a policy executes that validates an OAuth token, Edge creates flow variables that hold information like the name of the requesting application.
- Information about the response from the target system
Some variables are "built-in" to Edge and are automatically populated whenever an API request
is received. They are available throughout an API transaction. You can also create your own
custom variables using policies like [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy), or in JavaScript, Node.js, and
Java code.
As you'll see, variables have scope, and where they are accessible depends in part on when they
are created in the API proxy flow. In general, when a variable is created, it is available to
all policies and code that execute later in the API transaction flow.
## How are flow variables used?
Flow variable are used in [policies](https://docs.apigee.com/api-platform/develop/policy-attachment-and-enforcement) and [conditional flows](https://docs.apigee.com/api-platform/fundamentals/flow-variables-and-conditions):
- **Policies** can retrieve state from flow variables and use them to do their work.
For example, a [VerifyJWT policy](https://docs.apigee.com/api-platform/reference/policies/verify-jwt-policy) can retrieve the token to be verified from
a flow variable and then perform the verification on it. As another example, a
[JavaScript policy](https://docs.apigee.com/api-platform/reference/policies/javascript-policy) can retrieve flow variables and encode the data contained within
those variables.
- **Conditional flows** can reference flow variables to direct the flow of an API through Edge, kind of like the way a switch statement works in programming.
For example, a policy to return a fault may execute only when a particular flow variable is
set. Finally, you can get and set flow variables in a Node.js target application.
Let's look at examples of how variables are used in each of these contexts.
### Flow variables in policies
Some [policies](https://docs.apigee.com/api-platform/develop/policy-attachment-and-enforcement) take flow
variables as input.
For example, the following [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) takes
the value of the flow variable `client.ip` and puts it in a request header
called `My-Client-IP`. If added to the *request* flow, this policy sets a header
that is passed to the backend target. If set on the *response* flow, the header is sent
back to the client app.
```
request{client.ip}true
```
For another example, when a [Quota policy](https://docs.apigee.com/api-platform/reference/policies/quota-policy) executes, several flow variables are populated
with policy-related values. One of these variables is
called `ratelimit.my-quota-policy.used.count` (where `my-quota-policy` is
the name of the quota policy you're interested in).
You might later execute a conditional flow
that says "if the current quota count is below 50% of maximum, and it's between 9 am and 5 pm,
enforce a different quota." This condition might depend on the value of the current quota count
and on a flow variable called `system.time`, which is one of the built-in Edge
variables.
### Flow variables in conditional
flows
[Conditional flows](https://docs.apigee.com/api-platform/fundamentals/flow-variables-and-conditions)
evaluate flow variables and enable proxies to behave dynamically. Conditions are typically used
to change the behavior of flows, steps, and route rules.
Here's a conditional flow that evaluates
the value of the variable `request.verb` in a proxy flow step. In this case, if the
request verb is POST, the [VerifyAPIKey policy](https://docs.apigee.com/api-platform/reference/policies/verify-api-key-policy) is executed. This is a common pattern used in
API proxy configurations.
```
request.verb equals "POST"VerifyApiKey
```
Now, you might wonder, where do variables like `request.verb`,
`client.ip`, and `system.time` come from? When are they instantiated and
populated with a value? To help you understand when variables are created and when they're
available to you, see [Understanding flow variable
scope](https://docs.apigee.com/api-platform/fundamentals/introduction-flow-variables#understandingflowvariablescope).
### Flow variables in JavaScript code called with the JavaScript
policy
With the [JavaScript policy](https://docs.apigee.com/api-platform/reference/policies/javascript-policy), you can execute JavaScript code from within the context of an
API proxy flow. JavaScript that is executed by this policy uses the Apigee
[JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model), which
provides your custom code access to request, response, and context objects associated with the
API proxy flow in which your code is executing. For example, this code sets a response header
with the value obtained from the flow variable target.name.
```
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
```
This techniqe of using JavaScript to read and set variables is similar to the work you can do
with the [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) (shown previously). It's just another way to accomplish the same
kinds of things on Edge. The key to remember is that JavaScript executed by the JavaScript policy
has access to all the flow variables that are exist and are in [scope](https://docs.apigee.com/api-platform/fundamentals/introduction-flow-variables#understandingflowvariablescope) within the API proxy flow.
### Flow variables in Node.js code
By requiring the `apigee-access` module, you can set and access flow variables from
within Node.js code that is deployed to Edge.
Here's a simple example where a variable called `custom.foo` is set to the value
`Bar`. Once set, this new variable becomes available to any policies or other code
that occurs in the proxy flow after the Node.js code executes.
```
var http = require('http');
var apigee = require('apigee-access');
http.createServer(function (request, response) {
apigee.setVariable(request, "custom.foo", "Bar");
response.writeHead(200, {'Content-Type': 'text/plain'});
response.end('Hello World\n');
}).listen(8124);
console.log('Server running at http://127.0.0.1:8124/');
```
You can read more about using `apigee-access` to work with variables in [Accessing flow variables in Node.js](https://docs.apigee.com/api-platform/nodejs/access-flow-variables-nodejs).
## Understanding flow variable scope
Variable **scope** is related to the flow or overall "life cycle" of an API proxy
call.
### Visualizing the flow of an API proxy
To understand flow variable scope, it's important to understand or visualize the way messages
flow through an API proxy. An API proxy consists of a series of message processing steps
organized as a flow. At every step in a proxy flow, the proxy evaluates information available to
it and decides what to do next. Along the way, the proxy may execute [policy code](https://docs.apigee.com/api-platform/develop/policy-attachment-and-enforcement) or perform
[conditional branching](https://docs.apigee.com/api-platform/reference/conditions-reference).
The following figure illustrates this sequence of flows. Notice how the flows are composed of
four main segments: ProxyEndpoint *request* , TargetEndpoint *request* ,
TargetEndpoint *response* , and ProxyEndpoint *response*.
Keep this flow structure in mind as we begin to explore flow variables through the rest of
this topic.
> [!NOTE]
>
> ### Further Reading
>
> If you'd like to read about proxy flow structure in more detail, see [Configuring flows](https://docs.apigee.com/api-platform/fundamentals/flow-configurations).
### How variable scope is related to proxy flow
As soon as you can visualize how messages flow through a proxy, as described previously, you
can begin to understand variable scope. By scope, we mean the point in the proxy flow life cycle
when a variable is first instantiated.
For example, if you have a policy attached to the
ProxyEndpoint request segment, that policy will not be able to access any variables that are
scoped to the TargetEndpoint request segment. The reason for this is that the TargetEndpoint
request segment of the flow has not executed yet, so the API proxy hasn't had a chance to
populate variables in that scope.
The following table lists the complete set of variable scopes and indicates when in the proxy
flow they become available.
> [!NOTE]
>
> ### NOTE
>
> After a flow variable is populated within its given scope, it remains available through the rest of the proxy flow life cycle. If you try to access a variable that is not yet in scope, you will receive an error or a NULL value.
| Variable scope | Where these variables are populated |
|---|---|
| proxy request | The ProxyEndpoint request segment |
| target request | The TargetEndpoint request segment |
| target response | The TargetEndpoint response segment |
| proxy response | The ProxyEndpoint response segment |
| always available | As soon as the proxy receives a request. These variables are available through the entire proxy flow life cycle. |
For example, there's a built-in Edge variable called `client.ip`. This variable has
"proxy request" scope. It is automatically populated with the IP address of the client that
called the proxy. It is populated when a request first hits the ProxyEndpoint and remains
available through the entire proxy flow life cycle.
> [!NOTE]
>
> ### NOTE
>
> Scopes for all the built-in Edge variables are listed in the [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference).
There's another built-in variable called `target.url`. This variable's scope is
"target request". It is populated in the TargetEndpoint request segment with the request URL sent
to the back-end target. If you try to access `target.url` in the ProxyEndpoint request
segment, you will receive a NULL value. If you try to set this variable before it is in scope,
the proxy does nothing---does not generate an error and does not set the variable.
> [!NOTE]
>
> ### NOTE
>
> It's possible to configure some policies to either throw an error or return NULL when an undefined variable is accessed. Refer to individual policy reference pages for details.
Here's a simple example that demonstrates how to think about variable scope. Suppose you want
to copy the entire contents of a request object (headers, parameters, body) and assign it to the
response payload to be sent back to the calling app. You can use the [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) for
this task. The policy code looks like this:
```
response
```
This policy simply copies the `request` object and assigns it to the
`response` object. But where should this policy be placed in the proxy flow? The
answer is that it must be placed on the TargetEndpoint response, because the scope of the
response variable is "target response."
## Referencing flow variables
All built-in variables in Apigee Edge follow a dot-notation naming convention. This convention
makes it easier to determine the purpose of the variable. For example
`system.time.hour` and `request.content`.
> [!IMPORTANT]
>
> ### BEST PRACTICE
>
> Apigee recommends that you use the dot-notation naming convention when you create custom flow variables. It can be useful to use the periods to organize a hierarchy of your custom variables.
>
> For example, `approval.code` and
> `approval.status` both might refer to an approval feature within the flow.
Apigee reserves various prefixes to organize relevant variables appropriately. These prefixes
include:
- `request`
- `response`
- `system`
- `target`
To reference a variable in a policy, enclose it in curly braces. For example,
the following [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) takes the value of the variable `client.ip` and
puts it in a request header called `Client-IP`.
```
request{client.ip}true
```
In conditional flows, the curly braces are not necessary. The following example condition
evaluates the variable `request.header.accept`:
```
request.header.accept = "application/json"XMLToJSON
```
You can also reference flow variables in JavaScript and Java code. For more information, see:
- [Working with variables in JavaScript](https://docs.apigee.com/api-platform/fundamentals/introduction-flow-variables#variablesInJavascript)
- [Accessing flow variables in
Node.js](https://docs.apigee.com/api-platform/nodejs/access-flow-variables-nodejs)
- [JavaScript policy](https://docs.apigee.com/api-platform/reference/policies/javascript-policy)
## Data type of flow variables
Each property of a flow variable has a well-defined data type, such as String, Long, Integer,
Boolean, or Collection. You can find the data types listed in
the [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference). For variables that were created by a policy,
refer to the specific policy reference topic for data type information.
Variables you create manually assume the type given when they were created, and depend
on the types of values that are allowed. For example, variables created in Node.js code are
restricted to Number, String, Boolean, null, or undefined.
## Using flow variables in policies
Many policies create flow variables as part of their normal execution. The [Policy reference](https://docs.apigee.com/api-platform/reference/policies/reference-overview-policy) documents
all of these policy-specific variables.
As you work with proxies and policies, be sure to consult
the policy reference to find out which variables are created and what they are used for. For
example, the [Quota policy](https://docs.apigee.com/api-platform/reference/policies/quota-policy) creates a set of variables that contain information about quota counts
and limits, expiry time, and so on.
Some policy variables are useful for debugging. You can use the [Trace tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) tool, for instance, to
see which variables were set at a particular instance in a proxy flow.
The [ExtractVariables policy](https://docs.apigee.com/api-platform/reference/policies/extract-variables-policy) lets
you populate custom variables with data extracted from messages. You can extract query
parameters, headers, and other data. For example, you can parse request and response messages
using patterns to extract specific data from the messages.
In the following example, Extract Variables parses a response message and stores specific data
taken from the response. The policy creates two custom variables,
`geocoderesponse.latitude` and `geocoderesponse.longitude`, and assigns
values to them.
```
responsegeocoderesponse$.results[0].geometry.location.lat$.results[0].geometry.location.lng
```
Again, be aware that many policies automatically create variables. You can access those
variables within the proxy flow context, and they are documented in the Policy reference under
each individual policy topic.
## Working with flow variables in JavaScript code
You can access and set variables directly in JavaScript code that is executing in the context
of an API proxy. Through the Apigee [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model), JavaScript executing on Edge has
direct access to proxy flow variables.
> [!NOTE]
>
> ### NOTE
>
> You can call JavaScript from a proxy using the [JavaScript policy](https://docs.apigee.com/api-platform/reference/policies/javascript-policy).
To access variables in JavaScript code, call getter/setter methods on any of these objects:
- `context`
- `proxyRequest`
- `proxyResponse`
- `targetRequest`
- `targetResponse`
As you can see, these object references map to the familiar segments of the proxy flow model
as explained previously in [Visualizing the flow of an API proxy](https://docs.apigee.com/api-platform/fundamentals/introduction-flow-variables#visual-flow).
The `context` object corresponds to "globally" available variables, such as system
variables. For example, you can call `getVariable()` on the `context` object
to get the current year:
```
var year = context.getVariable('system.time.year');
```
Similarly, you can call `setVariable()` to set the value of a custom variable or for
any *writable* out-of-the-box variables. Here, we create a custom variable called
`organization.name.myorg` and assign a value to it.
```
var org = context.setVariable('organization.name.myorg', value);
```
Because this variable is created with the `context` object, it will be available to
all flow segments (essentially, this is like creating a global variable).
> [!NOTE]
>
> ### NOTE
>
> The [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference) indicates which variables are writable and which are read-only. For information about the JavaScript Object Model, see [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model).
You can also get/set proxy flow variables in Java code that you execute with the
[JavaCallout policy](https://docs.apigee.com/api-platform/reference/policies/java-callout-policy).
## Accessing flow variables in Node.js applications
You can get, set, and delete flow variables from Node.js code deployed to Edge. All you need
to do is "require" the apigee-access module in your code. For details, see [Accessing flow variables in Node.js](https://docs.apigee.com/api-platform/nodejs/access-flow-variables-nodejs).
## What you need to remember
Here are a few important things to remember about flow variables:
- Some "out-of-the-box" variables are instantiated and populated automatically by the proxy itself. These are documented in the [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference).
- You can create custom variables that are available for use in the proxy flow. It's possible to create variables using policies like [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) and [JavaScript policy](https://docs.apigee.com/api-platform/reference/policies/javascript-policy), and in Node.js code.
- Variables have scope. For example, some variables are automatically populated when the first proxy receives a request from an app. Other variables are populated in the response flow segment of the proxy. These response variables remain undefined until the response segment executes.
- When policies execute, they can create and populate policy-specific variables. The documentation for each policy lists all of these relevant policy-specific variables.
- Conditional flows typically evaluate one or more variables. You need to understand variables if you want to create conditional flows.
- Many policies use variables as input or output. Perhaps a variable that is created by one policy is later used by another.
- You can get and set many flow variables from within Node.js by using straight JavaScript (and our [JavaScript object model](https://docs.apigee.com/api-platform/reference/javascript-object-model)) or the [JavaCallout policy](https://docs.apigee.com/api-platform/reference/policies/java-callout-policy), which executes code on Edge.
## Related code samples
API proxy samples are on GitHub and are easy to download and
use. See [Using the sample API proxies](https://docs.apigee.com/api-platform/samples/using-samples) for
information about downloading and using the samples. See [Samples list](https://docs.apigee.com/api-platform/samples/samples-reference) for a description of the API
proxy samples and what they do.
Sample proxies that feature the use of variables and variable processing include:
- [variables](https://github.com/apigee/api-platform-samples/tree/master/sample-proxies/variables) - Demonstrates how to extract and set variables based on transport and JSON and XML message content.
- [policy-mashup-cookbook](https://github.com/apigee/api-platform-samples/tree/master/doc-samples/policy-mashup-cookbook) - A complete application that uses policy composition to call two public APIs, combines results, and generates an enriched response for the client app. For more information on this sample, see [Using policy
composition](https://docs.apigee.com/api-platform/samples/cookbook/using-policy-composition).
- [conditional-policy](https://github.com/apigee/api-platform-samples/tree/master/sample-proxies/conditional-policy) - Implements simple conditional policy enforcement based on variable values.
> [!IMPORTANT]
>
> ### TIP
>
> You'll find a number of other samples that use variables in one way or another. Look for ones that use the [ExtractVariables policy](https://docs.apigee.com/api-platform/reference/policies/extract-variables-policy), which is commonly used to process variables in a proxy flow.
## Related topics
- All of the variables that are automatically populated in an API proxy are listed in the [Flow variables reference](https://docs.apigee.com/api-platform/reference/variables-reference). The reference also lists the type and scope of each variable.
- If you want to know which variables a specific policy populates, refer to the reference topic for the policy. For example, see [Flow variables](https://docs.apigee.com/api-platform/reference/policies/quota-policy#variables) in the [Quota policy](https://docs.apigee.com/api-platform/reference/policies/quota-policy) reference.