Send Docs Feedback

Access Entity policy

What

Retrieves entity profiles you specify from the Apigee Edge data store. The policy places the profile in a variable whose name follows the format AccessEntity.{policy_name}. You can use AccessEntity to access profiles for the following entities:

  • App
  • API product
  • Company
  • Company developer
  • Consumer key
  • Developer

The AccessEntity policy functions as a policy-based runtime database lookup. You can use the profile information returned by this policy to enable dynamic behavior, such as conditional endpoint routing, flow execution, policy enforcement.

You use the AccessEntity policy to get entity profile data as XML and put it into a variable. You identify the entity to get by specifying an entity type and one or more identifiers that specify which entity of that type you want. Later, in another policy, you can retrieve the entity profile data with another policy, such as a Extract Variables policy or Assign Message policy.

For examples of XML representing entity profiles, be sure to see "Example entity profile XML".

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

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

Samples

The following samples show AccessEntity used in conjunction with the ExtractVariables and AssignMessage policies to extract a developer's email and add it to the HTTP header.

Set up the AccessEntity policy to specify which entity profile to get from Edge, as well as where to put the profile data.

In the following example the policy gets a developer entity profile, using an API key passed as a query param to identify the developer. The profile is placed in a variable whose name follows the form AccessEntity.{policy_name}. So the variable set by this policy would be AccessEntity.GetDeveloperProfile.

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Edge datastore. -->
  <EntityType  value="developer"/>
  <!-- We tell the policy to use the API key (presented as query parameter) to identify the developer. -->
  <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/> 
</AccessEntity>

Use another policy to retrieve the entity profile value from the variable set by AccessEntity.

In the following example, an ExtractVariables policy retrieves a value from the AccessEntity.GetDeveloperProfile variable set earlier by AccessEntity.

Note that the value retrieved is specified as an XPath expression in the XMLPayload element. The extracted value is placed in a developer.email variable.

<ExtractVariables name="SetDeveloperProfile">
  <!-- The source element points to the variable populated by AccessEntity policy. 
  The format is <policy-type>.<policy-name>.
  In this case, the variable contains the whole developer profile. -->
  <Source>AccessEntity.GetDeveloperProfile</Source> 
  <VariablePrefix>developer</VariablePrefix>
  <XMLPayload>
    <Variable name="email" type="string"> 
	<!-- You parse elements from the developer profile using XPath. -->
      <XPath>/Developer/Email</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>

The following AssignMessage policy retrieves the developer email set by the ExtraceVariables policy.

<!-- We'll use this policy to return the variables set in the developer profile, 
just so that we can easily see them in the response. -->
<AssignMessage name="EchoVariables">
  <AssignTo createNew="false" type="response"></AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="X-Developer-email">{developer.email}</Header>
    </Headers>
  </Set>
</AssignMessage>

Element reference

The basic of structure of an AccessEntity policy is:

<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifer_type"/> 
  <SecondaryIdentifier ref="secondary_identifier" type="identifer_type"/>
</AccessEntity>

You can access multiple entities of the same type by grouping them in an Identifiers element:

<AccessEntity name="name_of_the_policy">
  <EntityType  value="type_of_entity"/>
  <Identifiers>
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*=”identifer_type”/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifer_type"/><!-- optional -->
    </Identifier >
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*=”identifer_type”/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifer_type"/><!-- optional -->
    </Identifier >
  </Identifiers>
</AccessEntity>

<AccessEntity> attributes

<AccessEntity async="false" continueOnError="false" enabled="true" name="policy_name">

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

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<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

 

<EntityIdentifier> element

Specifies the particular entity -- of the type given in EntityType -- to get.

<EntityIdentifier ref="value_variable" type="identifier_type"/> 

Default

N/A

Presence

Required

Type

String

Attributes

Attribute Description Default Presence Type
ref

The variable that provides the source of the identifier, such as request.queryparam.apikey.

N/A Required. String
type The type populated by the variable in the ref attribute. such as consumerkey. See the Entity types and identifiers for a list of values.   Required. String

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetCompany">
    <DisplayName>GetCompanyProfile</DisplayName>
    <EntityType value="company"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="appid"/> 
</AccessEntity>

<EntityType> element

Specifies the type of entity to retrieve from the data store.

<EntityType  value="entity_type"/>

Default

N/A

Presence

Required

Type

String

Use an EntityIdentifier element to specify which entity of the given type you want. For a reference of entity types, see the Entity types and identifiers.

Attributes

Attribute Description Default Presence Type
value One of the supported entity types. See Entity types and identifiers for a list. None. Required. String

<SecondaryIdentifier> element

In conjunction with EntityIdentifier, specifies a value to identify the desired instance of the given EntityType.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>

Default

N/A

Presence

Optional

Type

String

Use SecondaryIdentifier when specifying only an EntityIdentifier will not guarantee that you get a single entity. See Narrowing results with secondary identifiers for more information.

Using multiple SecondaryIdentifier elements is not supported.

Attributes

Attribute Description Default Presence Type
ref

The variable that provides the source of the identifier, such as request.queryparam.apikey.

N/A Required. String
type The type populated by the variable in the ref attribute. such as consumerkey. See the Entity types and identifiers for a list of values.   Required. String

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetAPIProduct">
    <DisplayName>GetAPIProduct</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>

Usage notes

Narrowing results with secondary identifiers

For some entities, giving one identifier might not be specific enough to get the entity you want. In those cases, you can use a secondary identifier to narrow the results.

Where multiple matches exist for a given EntityIdentifier and SecondaryIdentifier combination, the first match will be populated in the flow. For example, consider a case in which you're wanting to get an API product profile by using an app ID.

Your first, possibly broad policy configuration might look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="appid"/> 
</AccessEntity>

Because an app can be associated with multiple API products, using just the app ID might not return the API product you want (you could get just the first of multiple matched products).

Instead, to get a more exact result, you could use a SecondaryIdentifier. For example, you might have appname and developerid variables in the flow because these are populated by default during an OAuth 2.0 exchange. You could use the values of those variables in an AccessEntity policy to get profile details on the requesting app.

Your more specific policy configuration might look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>

Supported entity types and identifiers

AccessEntity supports the following entity types and identifiers.

EntityType Value EntityIdentifier Types SecondaryIdentifier Types
apiproduct appid apiresource
apiproductname  
appname apiresource
developeremail
developerid
companyname
consumerkey apiresource
app appid  
appname developeremail
developerid
companyname
consumerkey  
authorizationcode authorizationcode  
company appid  
company  
consumerkey  
companydeveloper companyname  
consumerkey consumerkey  
consumerkey_scope consumerkey  
developer appid  
consumerkey  
developeremail  
developerid  
requesttoken requesttoken consumerkey
verifier verifier  

Example entity profile XML

To retrieve the entity profile value you want with XPath, you'll need to know something about the profile XML's structure. For an example of the structure, use a management API call to get XML for the entity you want. For details, refer to the management API reference.

The following sections include code for API calls, along with example XML from the call.

Apps

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password

See also Get App in an Organization by App ID in the Edge management API reference.

Or:

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u email:password

See also Get Developer App Details in the Edge management API reference.

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<App name="thomas-app">
    <AccessType>read</AccessType>
    <ApiProducts/>
    <Credentials>
        <Credential>
            <Attributes/>
            <ConsumerKey>wrqOOOiPArFI0WRoB1gAJMRbOguekJ5w</ConsumerKey>
            <ConsumerSecret>WvOhDrJ8m6kzz7Ni</ConsumerSecret>
            <ApiProducts>
                <ApiProduct>
                    <Name>FreeProduct</Name>
                    <Status>approved</Status>
                </ApiProduct>
            </ApiProducts>
            <Scopes/>
            <Status>approved</Status>
        </Credential>
    </Credentials>
    <AppFamily>default</AppFamily>
    <AppId>ab308c13-bc99-4c50-8434-0e0ed1b86075</AppId>
    <Attributes>
        <Attribute>
            <Name>DisplayName</Name>
            <Value>Tom's Weather App</Value>
        </Attribute>
    </Attributes>
    <CallbackUrl>http://tom.app/login</CallbackUrl>
    <CreatedAt>1362502872727</CreatedAt>
    <CreatedBy>admin@apigee.com</CreatedBy>
    <DeveloperId>PFK8IwOeAOW01JKA</DeveloperId>
    <LastModifiedAt>1362502872727</LastModifiedAt>
    <LastModifiedBy>admin@apigee.com</LastModifiedBy>
    <Scopes/>
    <Status>approved</Status>
</App>

API product

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

See also Get API Product in the Edge management API reference.

Sample XPath, retrieves the second API resource (URI) from the API product named weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

Sample profile returned as XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>

Company

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password

See also Get Company Details in the Edge management API reference.

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>

Company developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u email:password

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

Consumer key

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u email:password

See also Get Key Details for a Developer App in the Edge management API reference.

Sample XPath:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>

Developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

See also Get Developer in the Edge management API reference.

Sample XPath:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
/Developer/Email/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>

Flow variables

When the entity profile specified in the AccessEntity policy is retrieved, the XML-formatted profile object is added to the message context as a variable. It can be accessed like any other variable, with reference to the variable name. The user-provided name of the AccessEntity policy is set as the variable prefix of the variable name.

For example, if an AccessEntity policy with name of GetDeveloper is executed, then the XML-formatted profile is stored in the variable named AccessEntity.GetDeveloper. The XML-formatted profile can then be parsed using an XPath defined in an ExtractVariables policy that specifies AccessEntity.GetDeveloper as its source.

Error codes

The default format for error codes returned by Policies is:

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

The AccessEntity Policy type defines the following error codes:

Error Code Message
InvalidEntityType Invalid type {0} in ACCESSENTITYStepDefinition {1}

Related topics

For working samples of API proxies, see the Samples reference.

Help or comments?