Monday, July 2, 2012

Ambient Data Framework in a Nutshell

In this post I want to briefly cover an important part of Tridion that is ignored in several implementations but that is always present because is a key part of most of the Content Delivery related products like UGC, Smart Target, etc.

What is ADF (Ambient Data Framework?

When we refer to ADF we should think about state management, in general words ADF works as a repository of information related to an specific session or to an specific request that can be accessed or updated during a web operation.

How ADF works?

ADF uses a modular design based on Cartridges that are executed depending on dependencies on the input/optput claims configured in the claim processors. ADF will determine the sequence of execution based on dependencies and registration order. Cartridges are used to manipulate state in the form of claims, claims can contain almost any form of data. The only restriction is that if your claim data is used in .Net the data must be serialized from Java to .Net.

Being technology agnostic ADF cannot access to technology specific objects like HttpServletRequest/HttpServletResponse or HttpContext, that is why we need a java filter or a .Net Http Module to start it. Having this in mind depending on the technology we are using we have to register the starting point for ADF as a Java Filter or as a .Net Http Module after that everything would be the same regardless the technology we are using.

Which are the ADF pieces?

A set of Claim Processors grouped sequentially. ADF can contain zero, one or more cartridges.

A processing entity that will receive the current claim store and will manipulate it. They have 3 important methods that can be implemented. onSessionStart which is executed when a new session starts, onRequestStart at the beginning of each request, onRequestEnd at the ending of each request.

A set of data in form of claims. It is implemented as a Map object in Java.

Data being stored, updated or removed from ADF.

Default Web Claims
ADF comes with a set of default claims called Web Claims. Those claims are stored in a claim store called "WebClaims". You can access to that claim store in the following way.

Server Variables: Map variables = (Map)claims.get(WebClaims.SERVER_VARIABLES);
Session Attributes: Map variables = (Map)claims.get(WebClaims.SESSION_ATTRIBUTES);
Request Url: Map variables = (Map)claims.get(WebClaims.REQUEST_FULL_URL);
Request Headers: Map variables = (Map)claims.get(WebClaims.REQUEST_HEADERS);

Those are the most important ones. Please notice that those claims are populated automatically by the ADF initiator (java filter or http module).


How ADF is configured?

The main configuration file is cd_ambient_conf.xml which should be located in your class path generally in the classes folder in java or in the bin/config folder in .net

cd_ambient_conf.xml example

<?xml version="1.0" encoding="UTF-8"?>
<Configuration Version="6.1"
        <Cartridge File="my_custom_cartridge1_conf.xml"/>
        <Cartridge File="my_custom_cartridge2_conf.xml"/>

This configuration file contains basic configuration just configuring two cartridges to be executed in sequential order. Each cartridge is configured in its own configuration file.


<?xml version="1.0" encoding="UTF-8"?>
<CartridgeDefinition Version="6.1" Uri="taf:extensions:cartridge:mycartridge" Description="My Cartridge"
                    Description="My Claim" />
                            Description="My claim processor.">
                <InputClaims />
                    <ClaimDefinition Uri="taf:extensions:claim:myclaim" />

This cartridge configuration file is defining a SESSION claim called "myclaim" and SESSION claim processor called "myclaimprocessor" which is implemented in the "com.tridion.ambientdata.extensions.myclaimprocessor" class. It is also defining an output claim called my claim which will contain the result of my operations.

Java specific configuration

In java the ADF initiator is configured as a Java filter in the web.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns=""
    <description>Web Site</description>

        <filter-name>Ambient Data Framework</filter-name>
        <filter-name>Ambient Data Framework</filter-name>

.Net specific configuration

In .Net the ADF initiator is configured as a .Net Http Module in the Web.config file.

<?xml version="1.0" encoding="UTF-8"?>
        <compilation debug="true" targetFramework="4.0" />
        <add name="Tridion.ContentDelivery.AmbientData.HttpModule" type="Tridion.ContentDelivery.AmbientData.HttpModule" />

Input/Output claims verification

ADF does a verification of presence of input claims if they are defined as required in the cartridge configuration file. For instance if you define a claim processor like this.

        <ClaimDefinition Uri="taf:extensions:myinputclaim" />
    <OutputClaims />

ADF will verify the presence of a claim called "myinputclaim"  in the current claim store, if it is not present it will throw an exception.

How a claim processor is implemented?

 A claim processor is implemented as a java class which extends AbstractClaimProcessor. All the claim processors implementors must override the 3 methods onRequestStart, onRequestEnd and onSessionStart. As you may notice onRequestStart and onRequestEnd apply to REQUEST scope claim processors and onSessionStart applies to SESSION scope claim processors.

Claim Processor sample:

package com.tridion.ambientdata.extensions;

import com.tridion.ambientdata.AmbientDataException;
import com.tridion.ambientdata.claimstore.ClaimStore;
import com.tridion.ambientdata.processing.AbstractClaimProcessor;
import com.tridion.ambientdata.web.WebClaims;

public class myclaimprocessor extends AbstractClaimProcessor {
    public void onRequestStart(ClaimStore claims) throws AmbientDataException {
    public void onRequestEnd(ClaimStore claims) throws AmbientDataException {

    public void onSessionStart(ClaimStore claims) throws AmbientDataException {
        try {
               claims.put(new URI("taf:extensions:claim:myclaim"), "myclaimdata");
        } catch (Exception ex) {
            throw new AmbientDataException(ex);

How a claim is used outside of ADF?

The idea behind ADF is to share and use common state data regardless of the technology we are using (.net or java) so that once we have completed developed our claim processors and configured our cartridges we are ready to use the data in our own applications.

Java usage sample

ClaimStore claims = AmbientDataContext.getCurrentClaimStore();
if (claims.contains(new URI("taf:extensions:claim:myclaim"))) {
    String claimdata = claims.get(new URI("taf:extensions:claim:deviceproperties")).toString();
    // Logic here.

.Net usage sample

ClaimStore claims = AmbientDataContext.CurrentClaimStore;
if (claims.contains(new URI("taf:extensions:claim:myclaim"))) {
    string claimdata = claims.Get<string>("taf:extensions:claim:deviceproperties");
    // Logic here.



  1. Good stuff, Eric!

    A couple of comments:
    1) The order in which cartridges are executed is actually based on their dependencies. That is why you configure input and output claims: so that other cartridges could depend on your output claims (by declaring them as input claims). The dependencies are resolved and the cartridges are then executed in the right order.

    2) Claim Processors do not have a scope themselves; they are always executed on every request and start of the session. The scope is only defined for claim values and is meant to define the lifetime of the claim. So in the future, a claim set to a "request" scope could be removed automatically once the request is done. At the moment, though, this is not implemented and the scope is mostly informational; but you may as well define the proper scope now so that your cartridges are ready when the scope is enforced.

    I hope that makes sense - and thanks again for sharing!

  2. Hi Peter,

    Thank you for your comments!!!, yes they make sense.

  3. Very good stuff Eric!

    You mention: "ADF will verify the presence of a claim called "myinputclaim" in the current claim store, if it is not present it will throw an exception." However, I don't experience an exception thrown if no dependant input claim was present. The dependency order simply can get messed up, but no error is thrown by the framework.

  4. Excellent stuff!!
    I have a scenario where in one page the custom claims are being added in claimstore and the page is redirected two another page i.e Response.End() is called. In this case the second page doesn't get any custom claim keys/values that means custom claims are not persisted.
    This works when custom claims are saved and fetched in two different requests in two subsequent pages without using Response.Redirect().
    Also I wanted to know in Tridion 2013 SP1 there is a third parameter introduced in Put() - Tridion.ContentDelivery.AmbientData.Runtime.ClaimValueScope which holds two enum values i.e Session and Request. Do we still need to use cartrdge implementing Session scope?