Avoidable Pitfalls when using Custom Data Types

Custom Data Types (CDTs) are a powerful and critical part of any Click(tm) Portal implementation. When used correctly they provide the means of defining robust Object Models. When used incorrectly, however, they can be a source of subtle problems that are difficult to diagnose and painful to correct.

Before you begin defining your Object model, it's a good idea to first understand that there are two primary flavors of Custom Data Types and why that is the case. When creating a new CDT one of the required fields is "Type". In that field, you are presented with two options: Data Entry and Selection. This choice is only made when the new CDT is created and you are locked in after that. For this reason, it's important to understand the difference between the two.

A Data Entry CDT is intended to hold instance data that extends an instance of a primary type. The primary type can be Person, Organization, a Project, or an Activity. The key point to remember about Data Entry CDTs is that each entity is supposed to extend only one root entity, thus that root entity becomes the sole owner of the related data stored as CDT entities. Data Entry CDT entities will refer to the entity that owns them via the owningEntity attribute. Access to a Data Entry CDT entity is drive by the Security policies of the entity that references it (aka, the owning entity).

Conversely, Selection CDT data is intended to be the source for common choice lists and referenced by any number of other entities. In this case, there is no notion of an owning entity.
The reason there are two different types largely center on three core concepts:

• Data Management. By explicitly defining the usage type, Click Portal is able to properly handle the deletion semantics of the CDT entity. A Selection CdT entities must remain in the database even if no other entities refers to it. This is so it remains as a valid selection choice. Data Entry CDT entities, being a mere extention of it’s owner, should be purged from the database by GC once deleted.
• Presentation. The Views use the usage type to drive how the user is presented the data. An attribute that is a reference to a Selection CDT will cause the presentation of a Chooser. Otherwise, the Add/Delete/Update style presentation is used.
• Security. As mentioned above, data entry CDTs are secured by the same rules enforced on the owning entity. Selection CDT data, being available as a selection source, is puplically visible.

Pitfall #1: Using the wrong type of CDT Though the intent of the two types should be clear, I still continue to see cases where a Selection CDT is used to store data collected via a Project View (or SmartForm). This can happen accidentally when the field added to a form is an attribute on the Selection CDT. When configured this way, the form automatically creates or updates a selection CDT entity. When building your views, do not add an editable field using a property on or reached through a Selection CDT.


Pitfall #2: Not setting the display attribute The display attribute is the property containing the value you wish to use to describe the entity as a whole. Click® Portal uses this setting to know how to display the value of a reference to the CDT entity. If not otherwise specified, Click Portal will use the ID attribute which, though unique, does not often provide the most meaningful information to the user.


Pitfall #3: Source controlling selection CDT data that can change in your production site When configuring your Selection CDT in Custom Data Type Center on your development store, you have the option of including the data in source control. For design-time created entities, this allows you to easily deliver those entities to your test and production stores via a standard configuration update. It’s a smart thing to do when the selection CDT entities represent a pre-determined list of choices you wish to present to your users. This option should not be used, however, when the selection CDT entities are subject to change on the production server. If changes are intended to be made at runtime on production, then enabling the option to source control the extent will result in the next configuration update completely wiping out any production created or modified entities. This is obviously a bad thing as it will result in data loss. It’s important to consider how the data will be used before setting that option.


Pitfall #4: Not considering the display name of your CDT A simple common sense thing to remember is that, though you’ve followed your naming conventions for Custom Data Types which will typically result in a name for the benefit of your developers, the display name should be provided in a way that your end users will understand. The reason this is important is that the display name of the CDT is automatically used in the title bar of the detail popup window.


Pitfall #5: Adding an attribute to a Selection CDT that is an entity or set of a Data Entry CDT
This is perhaps the most insidious pitfall of them all. To those watching closely during development, the problems will be painfully obvious. The most glaring problem this causes is when considering what data gets added to source control. If you elect to source control your selection CDT extent and those entities hold references to data entry cdt entities, only the selection cdt data will be added to source control. The Data entry CDT entities will not. This will cause significant problems when applying a configuration update to test and production because the update process will be unable to locate the data entry CDT entities that are assumed to be there due to the fact the selection CDT entities reference them.

These are just 5 pitfalls and I’m sure a few of you have encountered others. If so, please share them with the class. :-)

While some of these pitfalls represent potential causes for data integrity issues, all of them are easily avoided by just taking time to think through how you intend the data to be used in your site. Now go forth and build that killer object model!

Cheers!