ReadPropertySet policy

Overview

The ReadPropertySet policy reads property sets and populates flow variable with the results.

This policy is a Standard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, see Policy types .

`<ReadPropertySet>` element

Defines a ReadPropertySet policy.

Default Value	See Default Policytab, below
Required?	Required
Type	Complex object
Parent Element	N/A
Child Elements	`<Read>`

The <ReadPropertySet> element uses the following syntax:

Syntax

The <ReadPropertySet> element uses the following syntax:

< ReadPropertySet 
  
 name 
 = 
 "read-property-set" 
>  
< Read 
>  
< Name 
  
 ref 
 = 
 "set-ref" 
> property 
 - 
 set 
 - 
 name 
< / 
 Name 
>  
< Key 
  
 ref 
 = 
 "key-ref" 
> key 
 - 
 name 
< / 
 Key 
>  
< AssignTo>var1 
< / 
 AssignTo 
>  
< DefaultValue>default 
 - 
 value 
< / 
 DefaultValue 
>  
< / 
 Read 
>  
 ... 
  
< IgnoreUnresolvedVariables 
 > 
 true 
< / 
 IgnoreUnresolvedVariables 
>
< / 
 ReadPropertySet 
>

Default Policy

The following example shows the default settings when you add a ReadPropertySet policy to your flow in the Apigee UI:

< ReadPropertySet 
  
 name 
 = 
 "read-property-set" 
>  
< Read 
>  
< Name 
  
 ref 
 = 
 "set-ref" 
> property 
 - 
 set 
 - 
 name 
< / 
 Name 
>  
< Key 
  
 ref 
 = 
 "key-ref" 
> key 
 - 
 name 
< / 
 Key 
>  
< AssignTo>var1 
< / 
 AssignTo 
>  
< DefaultValue>default 
 - 
 value 
< / 
 DefaultValue 
>  
< / 
 Read 
>  
< IgnoreUnresolvedVariables>true 
< / 
 IgnoreUnresolvedVariables 
>
< / 
 ReadPropertySet 
>

When you insert a new ReadPropertySet policy in the Apigee UI, the template contains stubs for all possible operations. See below for information on required elements.

This element has the following attributes that are common to all policies:

Attribute

Default

Required?

Description

name

N/A

Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

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

continueOnError

false

Optional

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. See also:

enabled

true

Optional

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.

async

false

Deprecated

This attribute is deprecated.

The following table provides a high level description of the child elements of <ReadPropertySet> :

Child Element	Required?	Description
`<Read>`	Required	Reads and resolves a property set variable and sets it to a specified flow variable.
`<IgnoreUnresolvedVariables>`	Optional	Determines whether processing stops when a property set is unresolved.

Example

This section provides an example using <ReadPropertySet> .

Example

This example uses <ReadPropertySet> to get propertyset.environment.name.request.headers.api-version and assign it to target_url . If the property set value isn't obtained, https://httpbin.org/get is used instead.

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">environment.name</Name>
    <Key ref="key-ref">request.headers.api-version</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> 
</ReadPropertySet>

Child element reference

This section describes the child elements of <ReadPropertySet> .

`<Read>`

Resolves a property set variable and sets the result in a flow variable.

The <Read> element specifes the property set variable to resolve and the flow variable to set that value to. It also includes an optional default value, which is used in the event of an unresolved property set. You can include multiple <Read> elements in a single <ReadPropertySet> policy.

Default Value	N/A
Required?	Optional
Type	Complex type
Parent Element	`<ReadPropertySet>`
Child Elements	`<Name>` `<Key>` `<AssignTo>` `<DefaultValue>`

The <Read> element uses the following syntax:

Syntax

< Read 
>  
< Name 
  
 ref 
 = 
 "set-ref" 
 > 
 property 
 - 
 set 
 - 
 name 
< / 
 Name 
>  
< Key 
  
 ref 
 = 
 "key-ref" 
 > 
 key 
 - 
 name 
< / 
 Key 
>  
< AssignTo 
 > 
 var1 
< / 
 AssignTo 
>  
< DefaultValue 
 > 
 default 
 - 
 value 
< / 
 DefaultValue 
>
< / 
 Read 
>

Example

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="environment.name">my-property-set-name</Name>
    <Key ref="request.headers.api-version">my-property-set-key</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</ReadPropertySet>

The following table provides a high-level description of the child elements of <Read> .

Child Element	Required?	Description
`<Name>`	Required	String The property set to read from. Provide the `ref` , value, or both. Apigee first tries to resolve the `Name` based on the `ref` , then the value. If neither is resolvable, the `<DefaultValue>` , if provided, applies. `<Name>` and `<Key>` combine to `propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}` .
`<Key>`	Required	String The key of the property set that is used when resolving the variable. Provide the `ref` , value, or both. Apigee first tries to resolve the `Key` based on the `ref` , then the value. If neither is resolvable, the `<DefaultValue>` , if provided, applies. `<Name>` and `<Key>` combine to `propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}` .
`<AssignTo>`	Required	String Specifies the flow variable to assign the resolved variable to.
`<DefaultValue>`	Optional	String Specifies a default value to use when the variable cannot be resolved.

<IgnoreUnresolvedVariables>

Determines whether processing stops when a property set is unresolved. Set to true to ignore unresolved variables and continue processing.

IgnoreUnresolvedVariables is not applicable when <DefaultValue> is provided.

Default Value	False
Required?	Optional
Type	Boolean
Parent Element	`<ReadPropertySet>`
Child Elements	None

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee specific to the <ReadPropertySet> policy. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults .

Runtime errors

These errors can occur when the policy executes.

Fault code

HTTP status

Cause

steps.readpropertyset.UnresolvedVariable

500

This error occurs if a variable specified in the ReadPropertySet policy is either:

Out of scope (not available in the specific flow where the policy is being executed)

Can't be resolved (is not defined).

If <IgnoreUnresolvedVariables> is false and <DefaultValue> is not specified, the resolution fails.

Deployment errors

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

Error name

Cause

steps.readpropertyset.EmptyReads

The policy has no <Read> child elements.

steps.readpropertyset.FieldUnset

This code is returned when any of these are true:

Neither a reference nor name is set for <Name>
Neither a reference nor name is set for <Key>
No value was provided for <AssignTo>

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors .

Variables	Where	Example
`fault.name=" FAULT_NAME "`	`FAULT_NAME` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`readpropertyset. POLICY_NAME .failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`readpropertyset.RPS-SetResponse.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring , because it could change.

  
 { 
  
  
 "fault" 
 : 
  
 { 
  
 "faultstring" 
 : 
  
 "ReadPropertySet[RPS-SetResponse]: unable to resolve variable [variable_name]" 
 , 
  
 "detail" 
 : 
  
 { 
  
 "errorcode" 
 : 
  
 "steps.readpropertyset.UnresolvedVariable" 
  
 } 
  
 } 
  
 }

Example fault rule

<FaultRule name="ReadPropertySet Faults">
      <Step>
          <Name>RPS-CustomSetVariableErrorResponse</Name>
          <Condition>(fault.name = "SetVariableFailed")</Condition>
      </Step>
      <Condition>(readpropertyset.failed = true)</Condition>
  </FaultRule>

Schemas

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

ReadPropertySet policy Stay organized with collections Save and categorize content based on your preferences.

Overview

<ReadPropertySet> element

Syntax

Default Policy

Example

Example

Child element reference

<Read>

Syntax

Example

<IgnoreUnresolvedVariables>

Error reference

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Schemas

ReadPropertySet policy

`<ReadPropertySet>` element

`<Read>`