The Tagging Framework is a new feature in 6.1.1 that allows you to track information about objects in Elastic Path Commerce. Objects can have tag sets, which can contain tags. Each tag contains a piece of information about the object. The values in the tags can be evaluated against a set of rules (called conditional expressions). The outcome of the evaluation can then be used to make decisions about application behavior.

In 6.1.1, the Tagging Framework is used by Dynamic Content Delivery conditions to determine which Dynamic Content is displayed to the shopper, but there are many other potential applications for it. This article looks at some of the main parts of the Tagging Framework. Aside from the javadoc (and this article), the inner workings of the Tagging Framework are currently undocumented, but hopefully, this article will give you a bit of a start.

Main Classes

The classes and interfaces of the Tagging Framework are located in the core library (com.elasticpath.core) under the com.elasticpath.core.tags package.

• Tag: a piece of information about an object

• TagSet: a set of tags associated with an object

• TagDefinition: defines a piece of information that can be stored and tracked by the application

• TagDictionary: a set of tag definitions

• Condition: a rule that can be used to evaluate tag values

• ConditionalExpression: a group of Conditions, joined by a logical operator (AND, OR, or NOT) and evaluated as a single unit

• ConditionDSLBuilder: a service used to convert conditional expressions to strings and vice versa. The strings contain the expression in Elastic Path's domain specific language (DSL) for tag evaluation.

• ConditionEvaluatorService: a service that evaluates a set of tags against a conditional expression and returns true or false.

The service beans are defined in WEB-INF/conf/spring/service/service.xml.

Database Tables

The following database tables are used by the Tagging Framework:

• TTAGALLOWEDVALUE: can be used to restrict the values allowed for a specific setting

  • TTAGCONDITION: contains conditional expressions

• TTAGDEFINITION: contains the definitions of the tags supported by the application

  • TTAGDICTIONARY: contains the available tag dictionaries ("who", "when", and "where")

• TTAGDICTIONARYTAGDEFINITION: associates tags with tag dictionaries.

In addition, the TSELLINGCONTEXTCONDITION table is used to associate conditional expressions stored in TTAGCONDITION with Dynamic Content Delivery.

Defining a Tag

Before you can use a tag, you must define it and add it to a tag dictionary. To define a tag, insert a row into the TTAGDEFINITION table of the Elastic Path Commerce database:

insert into ttagdefinition(uidpk, guid, name, description, data_type)

values(10, 'USER_AGENT', 'USER_AGENT', 'The User-Agent request header.',

'java.lang.String');

The data_type field must contain a valid, fully-qualified Java class name (java.lang.String, java.lang.Integer, etc.).

Adding a Tag to a Tag Dictionary

After a tag is defined, you need to add it to at least one of the three tag dictionaries ("who", "when", and "where"). The "who"  tag dictionary defines tags that describe a shopper. The "where" tag dictionary defines tags that identify the selling channel (which stores). The "when" tag dictionary defines tags that indicate the time. To add a tag to the "who" tag dictionary, insert a row into the TTAGDICTIONARYDEFINITION table:

insert into
ttagdictionarytagdefinition(tagdictionary_guid, tagdefinition_guid)
values('WHO', 'USER_AGENT');

Adding a Tag to a Tag Set

The tag set associated with a shopper can be retrieved from the customer session object. The following code retrieves the tag set, creates a tag, and adds the new tag to the tag set.

import com.elasticpath.tags.TagSet;

import com.elasticpath.tags.Tag;

...

CustomerSession session = shoppingCart.getCustomerSession();

TagSet tagSet = session.getCustomerTagSet();

Tag newTag = new Tag();

newTag.setValue("A value");

tagSet.addTag("NEW_TAG", newTag);

Usually, similar code would be executed inside a tagging event listener.

Implementing a Tagging Event Listener

The Tagging Framework uses an event listener model to populate tag values. Listeners are invoked by the application when specific events occur, such as when the shopper logs on to their store account. To populate a tag, you create a listener and add it to the appropriate collection.

Two types of listeners are supported by Elastic Path Commerce out of the box:

• NewHttpSessionEventListener: these listeners are called when the visitor arrives at the storefront and an HTTP session is created.

• CustomerLoginEventListener: these listeners are called when the visitor signs in to their store account.

Both listener interfaces expose an execute method that takes a CustomerSession and an HttpServletRequest as parameters.

To add a new tag, you first need to determine how the value of the tag will be set. If the value of the tag can be retrieved from the HTTP request, your listener class should implement NewHttpSessionEventListener. If the value of the tag is only available after the customer has logged on to their Elastic Path account, then create a listener class that implements CustomerLoginEventListener. The class must implement the execute method to set the tag value and add it to the tag set.

package com.elasticpath.sfweb.listeners;
 
import javax.servlet.http.HttpServletRequest;
import com.elasticpath.commons.listeners.NewHttpSessionEventListener;
import com.elasticpath.domain.customer.CustomerSession;
import com.elasticpath.tags.Tag;
import com.elasticpath.tags.TagSet;
 
public class UserAgentTagger implements NewHttpSessionEventListener {
 
     private static final String USER_AGENT = "USER_AGENT";
     
     public void execute(CustomerSession session, HttpServletRequest request) {
          // get the user agent header string
          String userAgent = request.getHeader("User-Agent");
          
          // get the shopper's tag set
          TagSet tagSet = session.getCustomerTagSet();
          
          // set the user agent in the shopper's tag set
          Tag userAgentTag = new Tag();
          userAgentTag.setValue(userAgent);
          tagSet.addTag(USER_AGENT, userAgentTag);
     }
}

I'll be following up a little later this week with an example of a potential real-world use of the Tagging Framework and Dynamic Content.