Concept - UserPreference Table

1 Introduction

This concept describes the UserPreference table available from Intershop Commerce Management 7.10.35.

The UserPreference table is a commonly usable table for storing user-specific configurations. I.e. user data should not be stored as custom attribute (BasicProfile_AV), but as UserPreference.

Furthermore, optional user preference data is included in the customer import and export.

Note

The UserPreference table does not store localized values, so in some cases custom attributes may be the only option.

1.1 Glossary

A user is related to a customer, see references documents below for details.

The data of a registered user in ICM (Intershop Commerce Management) is stored as BasicProfile and the user's custom attributes as BasicProfile_AV.

1.2 References

2 UserPreference Table

This table is used to store user-related data. (e.g.: configurations, etc.). It only stores non-localized string values. However, the GroupName or the name can contain a LocaleID.

The combination of profileUUID, groupName and name are used as PrimaryKey in the table UserPreference.

The stringValue attribute contains the actual data which can be a maximum of 4000 characters long.

The attributes LastModified and OCA are used for internal purposes.

3 User - UserPreference Relation

Each User(BasicProfile) can have multiple UserPreference table entries.

The UserPreference.profileUUID provides the weak relation to the BasicProfile with its UUID.

BasicProfile_and_UserPreference_relation

4 Observer for Cleanup

At ORM level a UserDeleteObserver object is registered as ObjectListener with the BasicProfilePOFactory.

This removes all user-related UserPreference table entries before the User(BasicProfile) itself gets deleted.

When BasicProfile data is removed by database delete queries, the corresponding UserPreference table entries are not removed.

There is currently no way in Intershop Commerce Management to remove entries by query, but custom project code could do this. As a workaround, refer to Cookbook - UserPreference Table | Recipe: Remove Orphaned DB Entries.

5 Access UserPreferences Table Data

For accessing data in the UserPreference table in Java code, use the UserBO extension described in the next section.

To read the data in ISML templates, simply use a UserBO extension method, and for pipelines, use a KeyMapper to extract the required data.

Template and Pipeline access excample
UserBO:Extension("UserBOPreferencesExtension"):Preference("punchout.locale", "cxml")

Writing UserPreference data is implemented via the UpdateUserBOPreferences pipelet which allows saving data to preferences. It delegates to the setPreference method of the UserBO extension as described in the next section.

Furthermore three optional parameters are available:

Pipelet Parameter NameDescription
UserPreferenceNameTranslates to setPreference method parameter - name
UserPreferenceGroupTranslates to setPreference method parameter - group
UserPreferenceValueTranslates to setPreference method parameter - value

6 Access User Preferences via BO Layer

The API of the UserBO java extension UserBOPreferencesExtension features four methods for accessing the UserPreference table:

MethodDescription
void setPreference(String name, String group, String value)
  • Saves a new entry in UserPreference table
  • Parameter: name and group are required
    • Nothing happens if either is null or empty
  • If value is null the entry gets removed
  • Any other value is saved or overwritten
void removePreference(String name, String group)
  • Removes the entry in UserPreference table
  • Parameter: name and group are required
    • Nothing happens if either is null or empty
String getPreference(String name, String group)
  • Returns the stringValue of the entry in UserPreference table
  • Parameter: name and group are required, to identify the entry
    • null is returned if either is null or empty
  • Otherwise the content of attribute 'stringValue' is returned
Map<String, String> getPreferencesByGroup(String group)
  • Returns a Map with the name as key and the stringValue data as value
  • Parameter: group is required, to identify the entries
    • Empty Map is returned if group is null or empty

Note

Do not use this method excessively. It can cause performance issues.

7 Import

The customer import was extended to import data stored in the UserPreference table.

The optional tag <user-preferences> and its <user-preference ...> sub-tags contain the user preference data.

7.1 Customer XSD

The customeruser.xsd located in (f_business\f_checkout\bc_customer\staticfiles\) share\system\impex\schema\customeruser.xsd has been extended.

customeruser.xsd - enhancements
    ...

<!-- Profile -->
<xsd:complexType name="complexType.Profile" mixed="false">
	<xsd:choice minOccurs="0" maxOccurs="unbounded">

        ...

		<xsd:element name="user-preferences"
			type="complexType.Profile.UserPreferences" minOccurs="0" maxOccurs="1" />
	</xsd:choice>
</xsd:complexType>

    ...

<!-- user preferences -->
<xsd:complexType name="complexType.Profile.UserPreferences" mixed="false">
	<xsd:sequence>
		<xsd:element name="user-preference" type="complexType.Profile.UserPreference"
			minOccurs="0" maxOccurs="unbounded" />
	</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="complexType.Profile.UserPreference" mixed="true">
	<xsd:sequence>
		<xsd:element name="value"
			type="simpleType.Generic.String.4000" minOccurs="0" maxOccurs="1"/>
	</xsd:sequence>
	<xsd:attribute name="name" type="simpleType.Generic.String.256"
		use="required" />
	<xsd:attribute name="group"
		type="simpleType.Generic.String.256" use="required" />
</xsd:complexType>
    ...

7.2 Example Data

For testing purposes, the demo customer OilCorp - user cxmluser(@test.intershop.de) comes with user settings that are imported during DBInit.

Those user-preferences configurations were added for cXML Punchout tests. Hence the common user-preference group cxml.

Customers_b2bext.xml
<user business-partner-no="cxmluser">
	<business-partner-no>cxmluser</business-partner-no>
	<profile>
		<credentials>
			<login>cxmluser@test.intershop.de</login>
             ...
		</credentials>
		...
		<user-preferences>
			<user-preference name="unitmapping" group="cxml">EACH;pcs	BOX;box	DOZ;DOZEN</user-preference>
			<user-preference name="punchout.locale" group="cxml">en_US</user-preference>
		</user-preferences>
	</profile>
    ...
</user>		

8 Staging

Since customer and user are usually created in a live ICM environment, the UserPreference table is not part of the staging (mass data replication).

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets