Was this Helpful?

 Extract Variables policy

About | Samples | Element reference | Error codes | Schemas | Usage notes | Related topics

What

Extract content from messages, including headers, URI paths, payloads, and query parameters, for use in a condition statement. The policy then applies a text pattern to message content and upon finding a match sets a designated variable.

Where

This policy can be attached in the following locations. 

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

These policy code samples illustrate how to extract variables from the following types of artifacts:

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Consider the sample policy code above. The <URIPath> element tells the ExtractVariables policy to extract information from the URI path. The <Pattern> element specifies the pattern to apply to the URI path. The pattern is treated as a simple template, with the curly braces denoting the varying portion of the URI path.

The name of the variable to be set is determined by the value specified in the <VariablePrefix> element, as well as the value enclosed in curly braces {} in the <Pattern> element. The two values are joined by an intervening dot, resulting in a variable name of urirequest.id for example. If there is no <VariablePrefix> element, then the variable name is just the value enclosed in curly braces.

Consider the sample policy code above working with the following incoming request:

GET http://org1-test.apigee.net/accounts/12797282

When Apigee Edge applies the ExtractVariables policy code above to this incoming request, it sets the variable urirequest.id to 12797282. After Apigee Edge executes the policy, subsequent policies or code in the processing flow can refer to the variable named urirequest.id to get the string value 12797282.

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>
Consider the sample policy code above. Suppose that your API design stipulates that incoming requests must carry a query parameter named code. code holds a term that looks like DBNXXXXX, where DBN is fixed and the XXXXX denotes a varying string. You can use this policy to extract the varying string.

 

Consider the sample policy code above working with the following incoming request:

GET http://org1-test.apigee.net/accounts/12797282?code=DBN88271

When Apigee Edge applies the ExtractVariables policy code above to this incoming request, it sets the variable queryinfo.dbncode to 88271. After Apigee Edge executes the policy, subsequent policies or code in the processing flow can refer to the variable named queryinfo.dbncode to get the string value 88271.

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <VariablePrefix>geocoderesponse</VariablePrefix>
   <JSONPayload>
      <Variable name="latitude">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
</ExtractVariables>
The ExtractVariables policy can extract values from complex structures, such as JSON messages. The sample policy code above shows how to extract a variable from a portion of a JSON message payload. The <JSONPayload> element tells the policy to extract a variable from a JSON payload. You specify the portion to extract using a JSON path expression in which the $ character refers to the root node of the JSON message.

 

Consider the following JSON response payload:

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

When Apigee Edge applies the ExtractVariables policy code above to this JSON message, it sets two variables: geocoderesponse.latitude and geocoderesponse.longitude. Both variables use the same variable prefix of geocoderesponse. The suffix for these variables is specified explicitly by the <Variable> element's name attribute.

The variable geocoderesponse.latitude gets the value 37.42291810. The variable geocoderesponse.longitude gets the value -122.08542120.

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <VariablePrefix>directionsresponse</VariablePrefix>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F"</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>
The ExtractVariables policy can extract values from complex structures, such as XML messages. The sample policy code above shows how to extract a variable from a portion of a XML message payload. The <XMLPayload> element tells the policy to extract a variable from an XMLpayload. You specify the portion to extract using XPath and explicitly named variables.

 

Consider the following XML response payload:

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</DirectionsResponse>

When Apigee Edge applies the ExtractVariables policy code above to this XML message, it sets three variables: directionsresponse.travelmode, directionsresponse.duration, and directionsresponse.timeunit. All variables use the same variable prefix of directionsresponse. The suffix for these variables is specified explicitly by the <Variable> element's name attribute.

The variable directionsresponse.travelmode gets the value DRIVING. The variable directionsresponse.duration gets the value 19. The variable directionsresponse.timeunit gets the value minutes.


Element reference

The element reference describes the elements and attributes of the ExtractVariables policy.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName>Extract Variables 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="name"/>...</FormParam>
   <Variable name="name"/>...</Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>//test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

<ExtractVariables> attributes

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required

<URIPath> element

Extracts the value of a variable from the specified URI path of the specified message.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

<QueryParam> element

Extracts the value of a variable from the specified query parameter of the specified message.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

Attributes

Attribute Default Presence Type
name

N/A

Required String

<Header> element

Extracts the value of a variable from the specified HTTP header of the specified message.

<Header name="Authorization">
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

Attributes

Attribute Default Presence Type
name

N/A

Required String

<FormParam> element

Extracts the value of a variable from the specified form parameter. Form parameters can be extracted only when the contentType of the specified message is application/x-www-form-urlencoded.

<FormParam name="name"/>...</FormParam>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

Attributes

Attribute Default Presence Type
name

N/A

Required String

<Variable> element

Names the variable to be set.

<Variable name="name"/>...</Variable>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

Attributes

Attribute Default Presence Type
name

N/A

Required String

<IgnoreUnresolvedVariables> element

Set to true to treat any unresolvable variable as an empty string (null). Set to false if you want the policy to throw an error when any referenced variable is unresolvable.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Default: False
Presence: Optional
Type: Boolean

<JSONPayload> element

Specifies the JSON-formatted message from which the value of the variable will be extracted.

<JSONPayload>
   <Variable name="name">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

<JSONPayload>/<Variable> element

Specifies the variable where the extracted value will be assigned.

<Variable name="name">
   <JSONPath>{example}</JSONPath>
</Variable>
Default: N/A
Presence: Required
Type: N/A

Attributes

Attribute Description Default Presence Type
name

Specifies the name of the variable where the extracted value will be assigned.

For example, suppose the name value is set to customer:

  • If <VariablePrefix> is not specified, the extracted values are assigned to customer.
  • If <VariablePrefix> is specified as MyVariable, the extracted values are assigned to MyVariable.customer.

N/A

Required String

<JSONPayload>/<Variable>/<JSONPath> element

Specifies the JSON path used to extract the value of a variable from a JSON-formatted message. JSON payloads are extracted only when the contentType of the specified message is set to application/json.

<Variable name="name">
   <JSONPath>{example}</JSONPath>
</Variable>
Default: N/A
Presence: Required
Type: String

<Source> element

Specifies the message to be parsed. The value of Source defaults to message. The message value is context-sensitive. In a request flow, message resolves to the request message. In a response flow, message resolves to the response message.

If the <Source> variable cannot be resolved, or resolves to a non-message type, the policy will fail to respond.

In advanced configurations, <Source> can resolve to a variable containing a message generated by another policy, such as one generated from a ServiceCallout.

<Source clearPayload="true|false">request</Source>
Default: message
Presence: Optional
Type: String

Attributes

Attribute Description Default Presence Type
clearPayload

Set to true if you want to clear the request payload after the request is sent to the HTTP target.

Use the <clearPayload> option only if the request message is not required after the ServiceCallout is executed because <clearPayload> allocates memory during message processing.

False

Optional Boolean

<VariablePrefix> element

The complete variable name is created by joining the <VariablePrefix>, a dot, and the name you define in {curly braces} in the <Pattern> element. For example: myprefix.id, myprefix.dbncode, or myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>
Default: N/A
Presence: Optional
Type: String

<XMLPayload> element

Specifies the XML-formatted message from which the value of the variable will be extracted.

<XMLPayload stopPayloadProcessing="false">
   <Namespaces/>
   <Variable name="name" type="boolean">
      <XPath>//test/example</XPath>
   </Variable>
</XMLPayload>
Default: N/A
Presence: Optional. However, you must include at least one of the following: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, or <XMLPayload>.
Type: N/A

Attributes

Attribute Description Default Presence Type
stopPayloadProcessing

Set to true to stop XPath evaluation.

False

Optional Boolean

<XMLPayload>/<Namespaces> element

Specifies the namespace to be used in the XPath evaluation. XML payloads are extracted only when the contentType of the message is text/xml , application/xml , or application/*+xml .

<XMLPayload stopPayloadProcessing="false">
   <Namespaces/>
   <Variable name="name" type="boolean">
      <XPath>//test/example</XPath>
   </Variable>
</XMLPayload>
Default: N/A
Presence: Optional
Type: String

<XMLPayload>/<Variable> element

Specifies variable to which the extracted value will be assigned.

<Variable name="name" type="boolean">
   <XPath>//test/example</XPath>
</Variable>
Default: N/A
Presence: Optional
Type: N/A

Attributes

Attribute Description Default Presence Type
name

Specifies the name of the variable to which the extracted value will be assigned. If there is a VariablePrefix element, then this name will be appended, as variableprefix.name .

For example, suppose the value of name is "user".

  • If <VariablePrefix> is not specified, the extracted values are assigned to a variable named user.
  • If <VariablePrefix> is specified as MyPrefix, the extracted values are assigned to a variable named MyPrefix.user.

name

Required String
type Specifies the data type of the variable value. Boolean Optional

String. Select from:

  • string
  • boolean
  • integer
  • long
  • float
  • double
  • nodeset (returns an XML fragment)

 

<XMLPayload>/<Variable>/<XPath> element

Specifies the XPath defined for the variable. Only XPath 1.0 expressions are supported.

<Variable name="name" type="boolean">
   <XPath>//test/example</XPath>
</Variable>
Default: N/A
Presence: Required
Type: String

Error codes

The default format for error codes returned by policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}
	
The ExtractVariables policy defines the following error codes:
Error Code Message
NothingToExtract ExtractVariables {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
NONEmptyPrefixMappedToEmptyURI ExtractVariables {0}: Non-empty prefix {1} cannot be mapped to empty uri
DuplicatePrefix ExtractVariables {0}: Duplicate prefix {1}
NoXPathsToEvaluate ExtractVariables {0}: no xpaths to evaluate in variable {1}
EmptyXPathExpression ExtractVariables {0}: XPath expression is empty in variable {1}
NoJSONPathsToEvaluate ExtractVariables {0}: no jsonpaths to evaluate in variable {1}
EmptyJSONPathExpression ExtractVariables {0}: JSONPath expression is empty in variable {1}
MissingName ExtractVariables {0}: Required attribute name is missing in {1}
InstantiationFailed Failed to instantiate the ExtractVariables stepDefinition {0}
ExecutionFailed Failed to execute the ExtractVariables: {0}
SetVariableFailed Failed to set variable {0} value {1} from ExtractVariables: {2}
ImmutableVariable Variable {0} is immutable from ExtractVariables: {1}
InvalidPattern Pattern {0} is invalid in ExtractVariables stepDefinition {1}
PatternWithoutVariable Pattern {0} should have at least one variable in ExtractVariables stepDefinition {1}
NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable {0} message is not available for ExtractVariable: {1}
VariableResolutionFailed Failed to resolve variable {0}
CannotBeConvertedToNodeset ExtractVariables {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
XPathCompilationFailed ExtractVariables {0}: Failed to compile xpath {1}. Context {2}
JSONPathCompilationFailed ExtractVariables {0}: Failed to compile jsonpath {1}. Context {2}
UnsupportedOperation ExtractVariables {0}: Unsupported operation for flow variables {1}
JsonPathParsingFailure ExtractVariables {0}: Json path parsing failed for for flow variables {1}
InvalidJSONPath Invalid JSON path {0} in policy {1}.
UnableToCast Unable to cast value {0} as {1}.

Schemas

See our GitHub repository samples for the most recent schemas.

Usage notes

API developers build policies that behave differently based on the content of messages, including headers, URI paths, payloads, and query parameters. Often, they will want to extract some portion of this content for use in a condition statement. Use the ExtractVariables policy to do this. Choose the names of the variables to be set, the source of the variables, and how many variables to extract and set. The policy then applies a text pattern to the content and upon finding a match sets a designated variable with the selected content.

Other policies and code can then consume those variables to enable dynamic behavior, or to send business data to Analytics Services.

To see how ExtractVariables can be used to build content-driven Analytics reports, see Analyze API message content using custom analytics.

Apigee Edge sets numerous variables automatically during request processing. See Variables reference. Use the ExtractVariables policy to set additional variables.

Related topics

Analyze API message content using custom analytics

Variables reference

 

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?)