Tech Tip: Changing the data type of a custom attribute

When updating your object model, many of the changes are simple such as adding new attributes to existing types, adding new types, and changing display names of attributes. These kinds of changes can be done directly via the normal check-out, make the change, check-in approach. The Type System in Click Portal will gracefully accommodate the change. Not all types of change are that easy though. The one that I wan to spend time on in this post surfaced in two separate instances this week. It is when you wish to change the data type of an attribute.

When changing the data type of an attribute, the Click Portal Framework needs to successfully accomplish two tasks:

• Update the definition of the Entity Type to reflect the change
• Migrate all data stored in the attribute to the new data type

It’s typically the second task where problems are encountered. For example, the Framework cannot convert data values of type string to integer, date to string, entity reference to entity set. While this is not an exhaustive list, it hopefully illustrates the problem. If the attribute contains no data in any of the entities in the extend being migrated, however, is will be successful as null will always convert.

You will see the error either at the time you are attempting to make the change in development, which means there is data in your development store that cannot be converted, or when attempting to apply a configuration update to a different store, which means that, while there wasn’t data that prevented making the change in development, there is data in the destination store than cannot be migrated.

If you truly want to change the data type of an attribute, you will need to perform a couple of extra steps to be successful. Here are two possible approaches:

Option 1:
Clear Existing Data and Update the Attribute in Place

If you don’t need to keep existing data, you can null out the attribute value for all entities in the extent prior to making the change in development. As part of the configuration update you will need to include an In-Store Pre-Patch method  to clear out the values in the destination store before the new type definition is imported.

Option 2:
Preserve Existing Data by migrating it to a new attribute 

In this approach, which is the most common, you need to implement logic to migrate the data to a new attribute via an In-Store Post Patch method. Here are the basic steps:

1. Rather than update the existing attribute in development, define a new one with the desired data type
2. Define a migration script intended to run as an in-store post patch method that migrates the data in the original attribute to the new one. Depending on the old and new data types, you will likely need to apply business logic to make the “correct” translation.
3. In the next configuration update, you can then delete the original attribute.Note that this approach takes two patches.

In both options, you will also need to make sure that all code, custom searches, branching criteria, property auto-settings, and views that use the new attribute correctly respect the new data type. Test thoroughly on Staging before applying any change like this to Production as the errors can often be subtle.

Cheers!