Send Docs Feedback

Extract Variables policy

 

What

Extract content from a variable. Often the source variable contains a request or response messages, including headers, URI paths, JSON/XML payloads, form parameters, and query parameters. The policy works by applying a text pattern to the message content and, upon finding a match, sets a variable with the specified message content.

While you often use this policy to extract information from a request or response message, you can use it to extract information from any variable. For example, you can use it to extract information from an entity created by the Access Entity policy, or extract information from an XML or JSON object.

After extracting the specified message content to the variable, you can reference the variable in other policies as part of processing a request and response. 

Note about Service Callouts: You aren't required to use this policy to extract variables from Service Callouts. The Service Callout policy has its own request and response variables that you can use directly, for example in an Assign Message policy.

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:


These links point to working API proxy samples that you can deploy and run on Edge. They use ExtractVariables and are located in Apigee's api-platform-samples repository on GitHub. The READMEs explain how ExtractVariables is used in each case, and how to deploy and run each sample. 

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <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 Extract Variables 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 Extract Variables 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.

You can now access the variable urirequest.id in your proxy. For example, the following AssignMessage policy copies it to the payload of the request:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetURIPath</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractURI>{urirequest.id}</ExtractURI>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <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 Extract Variables 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.

You can now access the variable queryinfo.dbncode in your proxy. For example, the following AssignMessage policy copies it to the payload of the request:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="w">
      <Pattern ignoreCase="true">{firstWeather}</Pattern>
   </QueryParam>
   <QueryParam name="w.2">
     <Pattern ignoreCase="true">{secondWeather}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Suppose your API design allows you to specify multiple query paramaters with the same name. You can use this policy to extract the value of multiple instances of the query parameter "w". ​To reference these query parameters in the Extract Variables policy, you use indexes, where the first instance of the query parameter has no index, the second is at index 2, the third at index 3, etc.

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

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

When Apigee Edge applies the Extract Variables policy code above to this incoming request, it sets the variable queryinfo.firstWeather to Boston and the variable queryInfo.secondWeather to Chicago

You can now access the variable queryinfo.firstWeather and queryinfo.secondWeather in your proxy. For example, the following AssignMessage policy copies it to the payload of the request:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
    <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>
The Extract Variables 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 Extract Variables 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.

You can now access the variable geocoderesponse.latitude in your proxy. For example, the following AssignMessage policy copies it to a header named "latitude" in the response:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add> 
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>
<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <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>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>
The Extract Variables 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 Extract Variables 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.

You can now access the variable directionresponse.travelmode in your proxy. For example, the following AssignMessage policy copies it to a header named "tmode" in the response:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Setting Content-Type: When extracting variables from XML messages (including SOAP), the variable extraction works only when Content-Type is set in the message header (or SOAP header); for example, application/xml.


About the Extract Variables policy

API developers build API proxies that behave differently based on the content of messages, including headers, URI paths, payloads, and query parameters. Often, the proxy extracts some portion of this content for use in a condition statement. Use the Extract Variables 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 Extract Variables 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 Extract Variables policy to set additional variables.

If you do not see the newly extracted variable show up in the Trace tool, try removing the <VariablePrefix> element if you added it. For more information, refer to this Apigee Community topic.

About matching and variable creation

The Extract Variables policy extracts information from a request or response and writes that information to a variable. For each type of information that you can extract, such as URI path or XML data, you specify the pattern to match and the name of the variable used to hold the extracted information. 

However, the way pattern matching works depends on the source of the extraction. The following sections describe the two basic categories of information that you can extract.

Matching URI paths, query parameters, headers, form parameters, and variables

When extracting information from a URI path, query parameters, headers, form parameters, and variables you use the <Pattern> tag to specify one or more patterns to match. For example, the following policy example shows a single matching pattern for the URI path:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

In this example, the urirequest.pathSeg variable is set to whatever appears in the pathsuffix after "/a/". For example, suppose the base path for your API Proxy is /basepath/v1 . With an inbound request to http://myCo.com/basepath/v1/a/b the variable is set to "b".

Specifying multiple patterns

You can specify multiple patters to match, corresponding to <Pattern> tags, where:

  • All patterns are tested for match.
  • If none of the patterns match, the policy does nothing and the variable(s) is not created.
  • If more than one pattern matches, the pattern with longest path segments is used for extraction.
  • If two matched patterns has same longest path segments, then the pattern specified first in the policy is used for extraction.

In the next example, you create a policy that contains three matching patterns for the URI path:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Suppose, for an API Proxy with a basepath of /basepath/v1 , the inbound request URL to the API proxy is of this form:

http://myCo.com/basepath/v1/a/b

In this example, the first pattern matches the URI and the urirequest.pathSeg variable is set to "b".

If the request URL is:

http://myCo.com/basepath/v1/a/b/c/d

...then the third pattern matches and the urirequest.pathSeg variable is set to "d".

Specifying patterns with multiple variables

You can specify multiple variables in the matching pattern. For example, you specify a matching pattern with two variables:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Again supposing an API Proxy with a base path of /basepath/v1 , for the inbound request URL:

http://myCo.com/basepath/v1/a/b/c/d

...the urirequest.pathSeg1 variable is set to "b" and the urirequest.pathSeg2 variable is set to "d".

Matching multiple instances in the pattern

You can also match patterns when there are multiple instances of an item with the same name. For example, you can make a request that contains multiple query parameters or multiple headers with the same name. The following request contains two query parameters named "w":

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

To reference these query parameters in the Extract Variables policy, you use indexes, where the first instance of the query parameter has no index, the second is at index 2, the third at index 3, etc. For example, the following policy extracts the value of the second query parameter named "w" in the request:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <QueryParam name="w.2">
      <Pattern ignoreCase="true">{secondW}</Pattern>
   </QueryParam>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

The urirequest.secondW variable is set to "2". If the second query parameter is omitted from the request, then the urirequest.secondW variable is empty. Use indexing any time there are multiple items with the same name in the request.

Using special characters in the pattern

When matching URI paths, you can use the "*" and "**" wildcard characters in the pattern, where:

  • "*" matches any one segments of the path
  • "**" matches multiple segments of the path

For example, you specify patterns to the <URIPath> element as shown below:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

The first pattern matches requests with pathsuffixes (the portion of the URI path following the basepath) such as "/a/b/c", "/a/foo/bar", etc. The second pattern matches any number of path segments after "/a/", such as "/a/foo/bar/baz/c", as well as "/a/b/c" and "/a/foo/bar".

When specifying patterns to query parameters, headers, and form parameters, the "*"character specifies to match any number of characters. For example, when matching a header, specify the pattern as:

*;charset={encoding} 

This pattern matches the values "text/xml;charset=UTF-16" and "application/xml;charset=ASCII".

If the value passed to the Extract Variables policy contains a special character, such as "{", use the "%" character to escape it. The following example escapes the "{" and "}" characters in the pattern because they are used as literal characters in the value of the query parameter:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

In this example, the pattern matches the value "{user} Steve" but not the value "user Steve". 

Matching JSON and XML

When extracting data from JSON and XML, you specify one or more <Variable> tags in the policy. The <Variable> tag specifies the name of the destination variable where the extracted information is stored, and the JsonPath (JSON) or XPATH (XML) to the extracted information.  

All <Variable> tags in the policy are evaluated, so that you can populate multiple variables from a single policy. If the <Variable> tag does not evaluate to a valid field in the JSON or XML, then the corresponding variable is not created. 

The following example shows an Extract Variables policy that populates two variables from the JSON body of a response:

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

Writing to the same variable in multiple places

Take care when choosing the names of variables to set. The policy executes sequentially from the first extraction pattern to the last. If the policy writes a value to the same variable from multiple places, the last write in the policy determines the value of the variable. (This may be what you want.)

For example, you want to extract a token value that can be passed either in a query parameter or in a header, as shown below:

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

Controlling what happens when no match occurs

If the pattern does not match, then the corresponding variable is not created. Therefore, if another policy references the variable, it can cause an error.

One option is to set <IgnoreUnresolvedVariables> to true in a policy that references the variable to configure the policy to treat any unresolvable variable as an empty string (null):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Element reference

The element reference describes the elements and attributes of the Extract Variables 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="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </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">

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
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
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 the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<Source> element

(Optional) Specifies the variable 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.

While you often use this policy to extract information from a request or response message, you can use it to extract information from any variable. For example, you can use it to extract information from an entity created by the Access Entity policy, from data returned by the Service Callout policy, or extract information from an XML or JSON object.

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

<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 payload specified in <Source> after extracting data from it.

Use the <clearPayload> option only if the soruce message is not required after ExtractVariables is executed. Setting to true frees up the memory used by the message.

false

Optional Boolean

<VariablePrefix> element

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

<VariablePrefix>myprefix</VariablePrefix>

 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.
Default: N/A
Presence: Optional
Type: String

<IgnoreUnresolvedVariables> element

(Optional) 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

<URIPath> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified URI path of a request source message. If the source message resolves to a message type of response, then this element does nothing.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

Or for multiple <Pattern> tags:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/employees/{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

Attributes

Attribute Description Default Presence Type
ignoreCase Specifies to ignore case when matching the patern.

false

Optional Boolean

<QueryParam> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified query parameter of a request source message. If the source message resolves to a message type of response, then this element does nothing.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

If multiple query parameters have the same name, use indexes to reference the parameters:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</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 Description Default Presence Type
name Specifies the name of the query parameter. If multiple query parameters have the same name, use indexed referencing, where the first instance of the query parameter has no index, the second is at index 2, the third at index 3, etc. 

N/A

Required String

<Header> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified HTTP header of the specified request or response message. If multiple headers have the same name, their values are stored in an array.

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

If multiple headers have the same name, use indexes to reference individual headers in the array:

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

Or the following to list all the headers in the array:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</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 Description Default Presence Type
name Specifies the name of the header from which you extract the value. If multiple headers have the same name, use indexed referencing, where the first instance of the header has no index, the second is at index 2, the third at index 3, etc. Use .values to get all headers in the array.

N/A

Required String

<FormParam> element

(Optional, but see the Presence row in the table below for more information.) Extracts a value from the specified form parameter of the specified request or response message. Form parameters can be extracted only when the contentType of the specified message is application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</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 Description Default Presence Type
name The name of the form parameter from which you extract the value.

N/A

Required String

<Variable> element

(Optional, but see the Presence row in the table below for more information.) Specifies the name of a variable from which to extract a value. 

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

To extract two values from the variable:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</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 Description Default Presence Type
name The name of the variable from which to extract the value.

N/A

Required String

<JSONPayload> element

(Optional, but see the Presence row in the table below for more information.) Specifies the JSON-formatted message from which the value of the variable will be extracted. JSON extraction is performed only when message's Content-Type is application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <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

(Required within the JSONPayload element.) Specifies the variable where the extracted value is assigned. You can include multiple <Variable> tags in the <JSONPayload> element to populate multiple variables.  

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>
Default: N/A
Presence: Required within the JSONPayload element. 
Type: N/A

Attributes

Attribute Description Default Presence Type
name

Specifies the name of the variable to which the extracted value will be assigned. 

name

Required String
type Specifies the data type of the variable value. N/A Optional

String. Select from:

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

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

(Required within the JSONPayload:Variable element.) Specifies the JSON path used to extract a value from a JSON-formatted message. 

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
Default: N/A
Presence: Required
Type: String

<XMLPayload> element

(Optional, but see the Presence row in the table below for more information.) Specifies the XML-formatted message from which the value of the variable will be extracted.  XML payloads are extracted only when the contentType of the message is text/xml application/xml , or application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee: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 after one variable is populated. This means only a single variable is populated by the policy.

false

Optional Boolean

<XMLPayload>/<Namespaces> element

(Optional) Specifies the namespace to be used in the XPath evaluation. If you're using namespaces in your XPath expressions, you must declare the namespaces here, as shown in the following example.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

Omit the namespace definition of there is none:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces/>
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>
Default: N/A
Presence: Optional
Type: String

Attributes

Attribute Description Default Presence Type
prefix

The namespace prefix.

N/A

Optional String

<XMLPayload>/<Variable> element

(Optional) 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. 

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

(Required within the XMLPayload:Variable 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>

Example with a namespace. If you use namespaces in your XPath expressions, you must declare the namespaces in the <XMLPayload><Namespaces> section of the policy.

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

Using parent, ancestor, following, and preceding in XPath expressions is not supported in Edge. To get the same matching results, try explicit node name matching or indexing. For example:

  • <XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
    gets the value of foo_attribute.
  • <XPath>/Attributes/Attribute[4]/Value</XPath>
    gets the value of the 4th attribute.

Error codes

Errors returned from Edge policies follow a consistent format as described in the Error code reference.

The Extract Variables policy returns the following error codes and error messages in error responses. For guidance on handling errors, see Fault handling. See also this Apigee Community post that illustrates a FaultRule pattern you can use to test for API key errors. 

NothingToExtract

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy without setting one of these required elements in the policy:

  • <URIPath>
  • <QueryParam>
  • <Header>
  • <FormParam>
  • <XMLPayload>
  • <JSONPayload>
Resolution

You must set at least one of the required elements to successfully deploy. For example:

<JSONPayload>
    <Variable name="firstName">
        <JSONPath>$.firstName</JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory.

 

NONEmptyPrefixMappedToEmptyURI

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy with an invalid configuration of the <XMLPayload> element. For example, in this case the prefix is apigee, but the namespace URI is missing:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee"></Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Resolution

Be sure to specify the Namespace URI in the <XMLPayload> element. For example, here the prefix is apigee and the namespace URI is http://www.apigee.com:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: Non-empty prefix <Prefix Name> cannot be mapped to empty uri

 

DuplicatePrefix

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy with an invalid configuration of the <XMLPayload> element. For example, in this case the prefix apigee is used twice:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="apigee">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Resolution

Do not have duplicate prefixes in the <XMLPayLoad> element:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: Duplicate prefix <Prefix Name>

 

EmptyXPathExpression

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy with an invalid configuration of the <Variable> child element of an <XMLPayload>element:

For example, in this case <Variable> element contains an empty <XPath> child element:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath></XPath>
  </Variable>
</XMLPayload>
Resolution

Do not have an empty XPath expression in the <XMLPayLoad> element:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: XPath expression is empty in variable <Variable Name>.

 

NoJSONPathsToEvaluate

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you do not specify a <JSONPath> child element where it is required in a <Variable> child element of a <JSONPayload> element. For example, there's no <JSONPath> element inside the <Variable name="firstname"> element:

<JSONPayload>
    <Variable name="firstName">
       // Missing element here
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Resolution

In this case, you must specify a <JSONPath> child element:

<JSONPayload>
    <Variable name="firstName">
        <JSONPath>$.firstName</JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: no jsonpaths to evaluate in variable firstName.

 

NoXPathsToEvaluate

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you do not specify a <XPath> child element where it is required in a <Variable> child element of a <XMLPayload> element. For example, there's no <XPath> element inside this <Variable> element:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     // Missing XPath element here
  </Variable>
</XMLPayload>
Resolution

I this case, you must specify an <XPath> child element:

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <policy name>: no xpaths to evaluate in variable <variable name>.

 

EmptyJSONPathExpression

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy with an empty child element <JSONPath> in a <JSONPayload> element:

For example, in this case the first <JSONPath> attribute is empty::

<JSONPayload>
    <Variable name="firstName">
        <JSONPath></JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Resolution

Do not have an empty JSONPath expression in the <JSONPayLoad> element:

<JSONPayload>
    <Variable name="firstName">
        <JSONPath>$.firstName</JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: JSONPath expression is empty in variable <Variable Name>.

 

MissingName

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you try to deploy the proxy when the name attribute is missing from an element that requires it. The name attribute is used to specify the name of a variable in which to store extracted data.

For example, the first <Variable> element that does not have a name attribute:

<JSONPayload>
    <Variable>
        <JSONPath>$.firstName</JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Resolution

Be sure to include the name attribute with the <Variable> element in either the <JSONPayload> or <XMLPayload> elements. Here's an example of a correctly formatted <JSONPayload> element:

<JSONPayload>
    <Variable name="firstName">
        <JSONPath>$.firstName</JSONPath>
    </Variable>
    <Variable name="lastName">
        <JSONPath>$.lastName</JSONPath>
    </Variable>
</JSONPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <policy name>: Required attribute name is missing in <element name>.

 

XPathCompilationFailed

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you do not declare namespaces that are present in an XPath expression:

For example, this XPath expression uses namespaces, but they are not declared in <Namespaces> elements:

<XMLPayload stopPayloadProcessing="false">
    <Variable name="companyId" type="string">
        <XPath>/S:Envelope/S:Body/ns1:login/ns1:credential/ns1:companyId/text()</XPath>
    </Variable>
</XMLPayload>
Resolution

If your XPath expression(s) contain namespaces, you must declare them in one or more <Namespaces> elements. For example:

<XMLPayload stopPayloadProcessing="false">
    <Namespaces>
        <Namespace prefix="S">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
        <Namespace prefix="ns1">urn:xxxx.xxxx.xxxxx.com</Namespace>
    </Namespaces>
    <Variable name="companyId" type="string">
        <XPath>/S:Envelope/S:Body/ns1:login/ns1:credential/ns1:companyId/text()</XPath>
    </Variable>
</XMLPayload>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message ExtractVariables <Policy Name>: Failed to compile xpath <XPath expression>. Context <revision number>.

 

PatternWithoutVariable

Cause

Important: Edge checks for this error when you deploy a proxy. You must fix the problem before you can successfully deploy.

This error happens when you have a <Pattern> element that does not have a variable specified. This is the name of the variable in which extracted data will be stored. For example:

<Header name="Authorization">
   <Pattern ignoreCase="false">Bearer</Pattern>
</Header>
Resolution

In this case, the <Pattern> element specifies a variable called oauthtoken to extract the matched data to:

<Header name="Authorization">
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>
Variables set None. This error prevents you from deploying the proxy.
Default HTTP status None.
Deployment Error message Pattern <pattern name> should have at least one variable in ExtractVariables stepDefinition <policy name>.

 

SourceMessageNotAvailable

Cause

This error means that you have specified a <Source> variable that is out of scope or can't be resolved. For example, if the policy executes in the request flow, the <Source> variable cannot be set to response or error:

// Will cause this error if the policy executes in the request or error flow!
<Source clearPayload="false">response</Source>

This will also cause the error if the variable xyz can't be resolved:

// Will cause this error if the policy executes in the request or error flow!
<Source clearPayload="false">xyz</Source>
Resolution If you set the <Source> element to a flow variable, it must be of type Message and it must be in scope. If you do not set it, then Edge will assume the source should be taken from the current flow. See also Message variables.
Variables set These special flow variables are set when the policy throws this error. You can use these variables catch and handle this error using Fault Rules. See Fault handling.
Variable name Value
fault.name SourceMessageNotAvailable
(What's this?)
*.failed extractvariables.{policy_name}.failed=true
(What's this?)
error.* (What's this?)
message.* (What's this?)
Default HTTP status 500 Internal Server Error
Default error message <message variable name> message is not available for ExtractVariable: <policy name>

Default JSON response

{  
   "fault":{  
      "faultstring":"<message variable name> message is not available for ExtractVariable: <Policy Name>",
      "detail":{  
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      }
   }
}

 

ExecutionFailed

Cause

This error can occur when the policy is asked to parse input that is malformed or otherwise invalid. Another cause could be that the policy is parsing XML with a namespace that is not declared in the <Namespace> element.

Resolution

There could be multiple causes for this error, but generally it occurs when the policy is asked to parse input that is invalid or contains unexpected attributes.

Tip: In Trace, check the value of the error.cause variable for a clue to where the error might have occurred. For example, this error suggests a namespace prefix in an XML payload is different than expected in an XPath expression in the policy:

error.cause = Unresolved Prefix at line 1(possibly around char 102)

or this cause indicates that the policy is trying to parse a malformed XML payload:

error.cause = Unexpected char while looking for open tag ('&lt;') character

Be sure any XML or JSON payload input is valid before parsing it with this policy. Be sure any namespaces in your XML payload are declared in the <Namespace> element. For example, in this payload, the "S" namespace is declared and it is expected to be present in the payload.

<Namespaces>
    <Namespace prefix="S">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
    <Namespace prefix="ns1">urn:xxxx.xxxx.xxxxx.com</Namespace>
</Namespaces>
<Variable name="companyId" type="string">
    <XPath>/S:Envelope/S:Body/ns1:login/ns1:credential/ns1:companyId/text()</XPath>
</Variable>

However, if the incoming XML has a different namespace on the Envelope element, such as "X", the policy will throw an ExecutionFailed error.

<?xml version="1.0" encoding="UTF-8"?>
<X:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
  ...
Variables set These special flow variables are set when the policy throws this error. You can use these variables catch and handle this error using Fault Rules. See Fault handling.
Variable name Value
fault.name ExecutionFailed
(What's this?)
*.failed extractvariables.{policy_name}.failed=true
(What's this?)
error.* (What's this?) Tip: In Trace, check error.cause for possible debugging information.
message.* (What's this?)
Default HTTP status 500 Internal Server Error
Default error message Failed to execute the ExtractVariables: <policy name>

Default JSON response

{  
   "fault":{  
      "faultstring":"Failed to execute the ExtractVariables: <policy name>",
      "detail":{  
         "errorcode":"steps.extractvariables.ExecutionFailed"
      }
   }

 

Additional XML-related errors

  Message
CannotBeConvertedToNodeset ExtractVariables {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}

 

Additional JSON-related errors

  Message
JSONPathCompilationFailed ExtractVariables {0}: Failed to compile jsonpath {1}. Context {2}
JsonPathParsingFailure ExtractVariables {0}: Json path parsing failed for for flow variables {1}
InvalidJSONPath Invalid JSON path {0} in policy {1}.

 

Other errors

Error Code Message
InstantiationFailed Failed to instantiate the ExtractVariables stepDefinition {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}
NonMessageVariable Variable {0} does not resolve to a Message
VariableResolutionFailed Failed to resolve variable {0}
UnsupportedOperation ExtractVariables {0}: Unsupported operation for flow variables {1}
UnableToCast Unable to cast value {0} as {1}.

 

Schemas

See our GitHub repository samples for the most recent schemas.

Related topics

Analyze API message content using custom analytics

Variables reference

 

Help or comments?