V8 Event Naming Conventions

With the introduction of the new event models in Version 8 of Tealeaf, new capabilities  and terminology require another look at how events are named. Event naming is strictly “by convention” – you can name an event anything you want, but after you have 500+ events, finding one again a few months later is much easier if the event names all follow some conventions.
Good conventions means that anybody who looks at an event name can get a very good idea of what it does. Good conventions reduce maintenance cost by reducing the number of duplicated events created by different event administrators, and good conventions make it easy to pass along the institutional knowledge when new event administrators are brought on board.  

Terminology and Definitions

All licensed users have access to the online documentation appropriate to their version of tealeaf. One very useful piece of this documentation is the Glossary of Terms. Everyone in your organization who uses tealeaf or consumes the reports generated by  tealeaf should review this document so that everyone shares the same terminology. To access the Glossary, Start the Portal, enter “Glossary” in the Search Online Help and search. While the results page is empty (as of V8.45), enter Glossary again in “Site Search All Spaces”, search, and you will be shown links to the tealeaf glossary.
The important terms, from an event perspective, are:
Hit Attribute: The pattern you are looking for! This is the foundation of the whole eventing system. Three important things:
1) Text String: - a fixed constant pattern of characters, in either the Request or the Response
2) Start Tag/End Tag – a constant pattern of characters that make up the start of the pattern (Start Tag), and another constant pattern of characters that make up the end of the pattern (End Tag). Everything between the Start Tag and End Tag make up the '”value” of that particular Hit Attribute
3) RegEx Pattern – a way to better refine the data between the Start/End tags. Using RegEx (or RegExpr) patterns and match groups, you can pull out just specific portions of the character strings between the Start and End tags, and give the Hit Attribute the value of just some substring(s) of the full data between the Start/End tags
There are a few other things about Hit Attributes you may need for particular scenarios, but these are Big Three that every user needs to understand. When you are looking at reports – you’re looking at how often Hit Attributes and their combinations and permutations occur
Event (Basic) – The Hit Attribute “happened”. That is to say, a user submitted or received an interaction with the Web Site that matched the pattern in the Hit Attribute. Now hold this thought – we’ll come back to it in a minute. (of course, Events can get much more complicated, as we’ll see later)
Dimension – Remember how Hit Attribute could have a Start and End tag, and the “value” of the HA was the stuff between the tags (as possibly refined by the RegEx)? You need a way to store these values, and count them. Dimensions define a virtual storage location. Let’s say that in a hypothetical Hit Attribute, there are three different values. And over the course of an hour, the Hit Attribute has appeared 100 times. The Dimension lets us record how often each value appeared. The sum of these counts will equal to 100. Each value of the “dimension” may appear for 0 to 100 times. For example, your site includes a PointOfSale (POS) pattern in response, and there are three values for the POS (us,ca,mx). You could create a POS dimension, its’ values are us, or ca, or mx, and if you record the dimension for a particular event, you would know how often the event happens for each of the three POS values.
We call dimensions “virtual storage” because they define what is to be recorded. The actual storage and reporting is done in Report Groups.
Report Group – Report Groups are created from Dimensions and attached to Events. They provide the actual storage for counting the values of a Hit Attribute. Any Report Group can have 1, 2, 3, or 4 Dimensions. Any Event can have an unlimited number of Report Groups with a single Dimension, but may only have up to four Report Groups with multiple dimensions. This restriction has a big impact on analysis, as we will see later.
Why have both Report Groups and Dimensions? Lets take for example an event that records visits to our product search page, and another event that records visits to the purchase confirmation page. Both pages have the POS pattern. The number of users (and POS distribution) that visit search is different form the number of users (and POS distribution) that visit the purchase confirmation page. The Dimension tells Tealeaf what to record for each event, and attaching the same Report Group to both events provides the two distinct locations for recording the POS distributions.
Session Attribute – A Session Attribute is a named storage location associated with a session. Session attributes can be populated by events or hit attributes. When populated, the previous value of the SA is overwritten. Thus, the SA is said to store “only the last value”. The Session Attributes can be displayed as columns on Search Result pages.

Basic Naming Convention

The tealeaf system has a number of places where event names are displayed in only about 20 characters, and cannot be widened. So it’s important to try and get your events identified ‘early” in their names
The pattern I recommend looks like this:
FunctionalArea:DescriptiveName(R/V):FrequencyOfOccurrence
FunctionalArea – This refers to the “functional area of your site”. I use the letter G to represent events that can happen anywhere (Global). Beyond that, its completely depended on what your site does, and the list will evolve over time as the site evolves. It is a good idea to create a separate document that lists the functional areas, and some identifying characteristics (either a portion of the URL-path, or a specific tag in the response) of each. If you are fortunate, the development team will incorporate information in each Response that specifically identifies the functional area (and even sub-area) to which that response belongs.
In the interest of keeping the event names short and descriptive, a two-letter or three-letter abbreviation of the functional area should be used, in place of a long name. Keep the list of abbreviations in the same document as your functional areas document.
I also recommend using :Err in the FunctionalArea portion to identify events that record error conditions. so G:Err would be errors that could occur anywhere on the site.
DescriptiveName(R/V) – Everybody has different ideas on what should be placed here. I will start by listing some “Do’s and Don’ts”, based on experiences with evolving sites, then go on to what I recommend.
Don’t use the phrase “step1”, or “step2” in an event name. As soon as the developers release a new feature that inserts itself between two existing steps, or they condense two existing steps into a single page view – then all your “step” number have to get changed. Instead of putting “step” in the event names, use the Tealeaf Reports to organize the events into process steps. The exception is creating “pyramid” session events for processes, which we will discuss later.
Do take great pains to create separate events for the Request for a page and the Delivery of the page. For example, if your site has a page /myaccount, one event DescriptiveName could be “MyAcountR” to measure how often users request that URL, and another event could be “MyAcountV” that measures how often the page is delivered (using a tag or pattern in the actual response). Because you have separated the request from the delivery, you can measure the percentage of how often the page is successfully delivered, and you can perform searches to find sessions where a page is requested but NOT delivered. I like to use the letters R and V at the end of each DescriptiveName to indicate this separation. If a DescriptiveName does not end in R or V, then it is usually a combination of other events, or an event that detects a redirect condition.
FrequencyOfOccurrence – the last portion of the name should show a user, at a glance, if the event will fire on every occurrence of the pattern, or if it fires only once in a session. It’s much better to have this in the event name, than having to go look up the event definition to determine it. I recommend the following abbreviations:

:E – EVERY. The event triggers and is recorded on every occurrence.
:S – Session. The event is evaluated at the END of the session, and the timestamp of the event is recorded as occurring at the end of the session.
:O – Once. The event is evaluated on every hit. the event is recorded the FIRST time it occurs. The timestamp of the event is the time of the hit on which it first appears.

The difference between :S and :O is important! if you are measuring “process steps”, and you plan to create conversion metrics from these events, then use :S. All of the events then happen in the same hour. If you want to be able to find something “the first time it happens in a session”, then use :O. In general, use :S for anything you want to record just once, and only use :O when you are searching for just specifically the very first occurrence.

 

Naming Convention for Error Events

In general, I like to use :Err after the FunctionalArea to indicate an error. it is easy to search for :Err when you are searching for specific error events in places where events are selected.
There is another convention I recommend for error events. Errors can be caused by the user making an entry that is “disallowed”, or an error can be caused by the web application faulting. For error events that are trigged by user disallowed activities, I suggest (USR) as part of the event Name, and (SYS) if the event is caused by a failure of the web application.

Naming Convention for Hit Attributes

In general, naming conventions for hit attributes can be much less restrictive then the conventions for event names. Tealeaf users see Hit Attributes only when they are looking at event definitions. With this in mind, you should consider naming the HAs so they make sense when refereed to as event conditions or event values to record. To continue with our example from above, the POS hit attribute could be named POSExtractedFromResponse or POSFromURLVirtualPath. These names would accurately reflect where the hit attribute is drawing its data from. Sometimes, I will use the StartTag, the elide symbol (…) . and the EndTag for the HA name, e.g., class=”FieldError>…</span. While that name may seem a bit weird, it very accurately describes what the HA extracts from the hit.
Don’t prefix your HA with HA, or use the word Hit Attribute in the name. Your wouldn’t call you kid “Child:John” would you? The fact that it is a Hit Attribute name can be inferred from how it is used.
Using the words Request or Response (REQ or RSP) in the HA is a matter of preference. I usually like to have (REQ) or (RSP) at the end of a HA name just to remind myself where it came from, so I use the right one in an event. For example “nameOnCard(REQ)” vs. “nameOnCard(RSP)” would remind me that on the first case, the HA extracts the information from what the user submitted, while in the second case the HA extracts the names from a pattern found somewhere in the response, perhaps a div or span with that name.

Naming Convention for Dimensions

Keep the Dimension names short. You will see later I recommend that Report Group names be constructed from the Dimension names that make up the Report Group. So having long Dimension names leads to unwieldy Report Group names.
Dimension names are shown to users in the Report Builder. They will be dragging these to the X-axis and to the Segment selector to slice event counts. keep them short, and as descriptive as possible, so users’ know what they are seeing.
There are different ways to populate a Dimension, and it makes sense to include something in the Dimension name to indicate to the user what was used to populate the dimension.

• Dimension is populated by a Hit Attribute. When the event fires, the appropriate HA must be present on the hit. If the HA is not present, the value assigned to the dimension is [null]. I like to use :H as the last characters of the Dimension name.
• Dimension is populated by the value of an event, either “first” or “lastest”. “first” is used occasionally, but “latest” is one of the most important ways to populate a dimension. The system “looks back” to the last time an event fired, and records the value of the “lastest” of that event. These are great for  recording the “state” of the end-user’s session. I like to use :E-F and :E-L as the last characters of the Dimension name when they are populated by events 
• Dimension is populated by a Session Attribute. I’ve never found a need to populate a dimesnion from a session attribute. Instead, I populate the dimension from whatever event is populating the SA.

 

Naming Convention for Report Groups

If you construct the Report Group name from the Dimensions used by that Report Group, it makes it very easy to select the appropriate Report Group(s) to assign to an Event.If you wish to report a single Dimension Report Group, I suggest simply copying the Dimension Name and creating the Report Group with exactly the same name. Using Tealeaf’s built-in Report Group creator appends DG_ in front of the Dimension name. I find this prefix to be of little value, so I prefer to simply copy the Dimension name. Back to a previous rhetorical question: you wouldn’t name your dog as DOG_Spot, would you? That a Report Group can be inferred from context means there is no needs to add the DG_ prefix.
Here are some examples: URL:HI/App:HI/Host:HI/Server:HI; URL:HI/POS:E-L; URL:HI/FirstErrorCodeOnPage:E-L/FirstErrorMessageOnPage:E-L
Because the Report Group Name is only used by administrators (Users see only the Dimension names), there is no reason why the RG name can’t be as long as you want, to be descriptive.

Naming Convention for Session Attributes

Session Attributes are good for holding “the last value seen in a session”. They can be displayed on the search results pages, as well as be searched for. The classic example the Tealeaf supplies is “login”. This holds the last value the user entered for a login (assuming the event is properly created).
There are no specific conventions for Session Attributes. With the V8 ability to create events that look back at the value of previous events, the old V7 use of session attributes to hold state is no longer necessary. Events can now detect a change in a field without having to use session attributes as a storage location. They have become simply repositories for information you wish to display on a search results.

Naming Convention for Advanced Mode events

There is a subtle point for the event popups (however over an event and a popup (tooltip) with information about the event appears) that makes it important to note somewhere that an event uses Advanced mode. When you first create an event, you must assign it some condition on which it fires. If you later turn on advanced mode and modify the event, the original condition remains in the event popup! Say you created the event as firing on condition A. If you edit the event in advanced mode, and change it to fire on condition B, the tooltip for that event does not change – it still shows it as being dependent on condition A. Same for the event value. For these reasons, anytime you create an Advanced mode event, I suggest that the event description start with [ADV]. I recommend the description as the place to record this, because it only needs to be present in the same place the incorrect tooltip appears. The event descriptions also appear in those tooltips. Having [ADV] in the description tells the experienced tealeaf user that the conditions or values shown on the tooltip are not necessarily the conditions or values used by the event.

That’s it for naming conventions. I hope you are able to put these to good use in your organization!