Demandware Center of Excellence

Custom Objects Utilization - Best Practices

Final Version 0.3

 Custom Object Utilization - Best Practices 2

Major Revision History

Date Description Version Author

Initial version 0.1 Rafi Mohammed

04/19/2016

04/19/2016 Review Performance Engineering 0.2 Markus Steuber

4/22/2016 Added Generic Mapping 0.3 Rafi Mohammed

 Custom Object Utilization - Best Practices 3

Table of Contents

Major Revision History .......................................................................................................................................................... 2

Introduction ............................................................................................................................................................................. 4

Custom Object Use cases ................................................................................................................................................... 5

Custom Objects Management ........................................................................................................................................... 7


Custom Objects APIs ............................................................................................................................................................ 7

Limitations ................................................................................................................................................................................ 8

Custom Object Usage Best Practices ........................................................................................................................... 9

Alternatives to Custom Objects ....................................................................................................................................... 12

 Custom Object Utilization - Best Practices 4

Introduction

Information is stored in the Demandware in several ways and for many reasons. An
important aspect of design is to evaluate if the ecommerce platform is the proper place to
store specific information and if it is aligned with the intended use of the platform. One
needs to understand the quota / performance implications of each type of storage context,
as well the state and lifetime of storage methods.

Business objects define the data structure of the catalog and other data used by
Demandware platform. The platform provides a rich library of objects (called System
Objects) which are designed to address almost all data needs of ecommerce applications.
Using business object definitions provided by the platform greatly speeds up
implementation and empowers you to take advantage of the functionality developed for
these objects. Also, the System Objects allow customization by creating custom attributes.

But there are cases where System Objects or extensions to System Objects (through custom
attributes) will not be sufficient to meet certain specific requirements. One example is the
functionality of Newsletter subscription. The platform does not provide a System Object to
realize the use case, hence the need of Custom Objects. Another example is a cookware
web site which needs to store data on recipes. Platform does not have system tables to map
recipes hence the need to leverage Custom Objects.

Custom Objects enable to extend Demandware data model beyond the System Objects to
meet specific business needs. In simple terms, Custom Object can be considered as a new
table with a primary key and storage attributes (columns) that suit specific business
requirements.

Even though Custom Objects present a powerful feature of Demandware Platform, they
should only be used after careful consideration for the intended use in an e-commerce
storefront, especially if the dataset is predicted to grow over time. A valid use of Custom
Object is to store small, temporary data sets which can be monitored and managed by an
administrator in Business Manager and which can be cleaned up in regular intervals.

Custom Object - Use Cases

Let us go into a couple of use cases where Custom Objects are useful to implement the
required functionality.

1. Newsletter subscription
Use Case: - A web site needs to provide the functionality of newsletter subscription.
Registered and anonymous users should be able to subscribe to the newsletter. The
third party newsletter provider does not have a synchronous interface; it receives the
subscriptions through a scheduled daily feed.

Solution: - It is tempting to add subscription data to the Profile System Object, but
this would imply that only registered users would be able to sign up. In order to allow
anyone to get a newsletter, we need to define a Custom Object. These Custom
Objects should not be replicable, since subscriptions created in Staging need not be
copied to Production. To keep the amount of data stored in Demandware small and
to comply with quotas, the subscriptions have to be removed after they have been
exported to the newsletter provider. This means the creation of a clean-up job that
should run on a schedule which purges the custom objects.

2. Analytics Integrations - Configurations

Use Case: One common use case for Custom Objects for configuration purposes is
analytics integration. Take the case of Omniture; where each template for the site
needs to be tagged with specific client side JavaScript that reports data to Omniture
based on the page. This data is managed directly in the templates but having
Business Manager access to the JavaScript allows an Omniture administrator (who
may not have access to DW studio) adjust the client side JavaScript for each page of
the site.

Solution: - In this case, a Custom Object record is created which holds the client side
Omniture JavaScript for each related template on the site, with the template name
used as the key for the Custom Object. This is an example that utilizes Custom
Objects feature to extend the existing data model that will not result in the amount
of objects totaling over the quota limit (400,000 total Custom Object records). It does
not affect storefront performance since only one Custom Object record is used per
 Custom Object Utilization - Best Practices 6

template request and allows the Custom Object look up to be based on the object
key instead of resource-expensive Custom Object search.

 Custom Object Utilization - Best Practices 7

Custom Objects Management

Custom Object definitions or types need to be created before creating and using Custom
Objects. While Custom Objects can be stored globally (instances available to entire
organization and all sites) or locally (per site), the Custom Object type itself is always
available to entire organization. Custom Object definition can be created from Business
Manager. Details are available in Infocenter.

A Custom Object is a specific instance of Custom Object definition. While Custom Object
can be created programmatically or from Business Manager, Custom Object definition
cannot be created by code. Custom Object has two attributes which affect data replication:
- Scope (Organization or Site) and Replicable (Yes or No). When replicating Custom
Objects, either at the Organization or Site level, only those object instances that are marked
as "replicable" are copied to the target instance. This is based on the selected value of the
Data Replication flag at the time the Custom Object was defined (replicable/not replicable).

Custom Objects APIs

The dw.object package contains two classes CustomObject and CustomObjectMgr to

manage Custom Objects within scripts. CustomObjectMgr class provides methods for
creating, retrieving, deleting and searching for Custom Objects. CustomObject class
represents a Custom Object and its corresponding attributes.

 Custom Object Utilization - Best Practices 8

Limitations

Custom Objects have the following known limitations:

Custom Object attributes cannot be used in search refinements

Localization attributes are not supported
If the Custom Object attribute value type is changed due to some reason, the whole
data stored will be lost as the Platform has to create an empty attribute and delete
the old attribute.

 Custom Object Utilization - Best Practices 9

Custom Object Usage Best Practices

The following provide guidelines in using Custom Objects to meet specific business needs.

1. Always consider if you can leverage System Objects instead of creating new Custom
Objects. System Objects are optimized for performance and offer easier
maintenance. Custom Objects are best used to store static data like configuration
parameters, not for uncontrolled amounts of data like analytics.

2. When working with Custom Objects attributes, back-up your data before changing
the value type property. The data is lost when the value type is changed because
Demandware must create a new, empty attribute and delete the old attribute.

3. Consider object quotas during the design and implementation of Custom Objects.
a. The limit for replicable Custom Objects is 400,000 (warning at 240,000).
b. The limit for object type definitions is 300 (warning at 180)
c. The limit for non-replicable Custom Objects is 400,000 (warning at 240,000).

4. Carefully evaluate whether your Custom Object should be global or site-specific, and
if they should be replicable (managed in Staging and published to production) or
non-replicable (instance-specific, created on Production or have different values in
different environments).

5. Delay the creation of Custom Objects until the user actually needs them. This
approach helps to create fewer objects, so less space is used and cleanup jobs will
run faster.

6. Do not use Custom Objects for query intense use cases, for example ratings and
reviews.

 Custom Object Utilization - Best Practices 10

7. Be sure to access Custom Objects using primary keys. A search using any other
attribute is costly in terms of performance and usage of system resources.

8. It is not advised normally to store payment related information in Custom Objects. If

it needs to be done due to specific business requirements, make sure that the data
stored is in the encrypted form.

9. Make sure that Custom Object size is not grown uncontrollably. Searches on Custom
Objects can be extremely slow if the data set size is huge.

10. You need to consider how to clean up Custom Objects once they have been
exported out of Demandware, they are no longer need to be used or after a certain
expiration period. The basic philosophy is to watch for the size of Custom Objects
stored in the system and take appropriate measures to clean them up after use.

11. Recommendation is to look for ways to limit the size of Custom Objects. Available
options include retention settings and scheduled clean-up jobs to remove outdated
objects.

12. Taking into account the locking aspect of Custom Objects when trying to modify
them within application.

13. If Custom Object queries are used due to some reason, try to re-use the results
throughout the pipeline rather than initiating fresh queries.

14. Avoid large queries of Custom Objects. See if it is possible to adjust the data model
and limit the query using ranges to shrink the amount of data to retrieve.

 Custom Object Utilization - Best Practices 11

15. Site preferences are preferred over Custom Objects to store configuration
parameters like third party service end points and other parameters, especially if the
parameters and values differ from one site to another in a multi-site solution, but
replicable Custom Objects can be considered if the configuration parameter and
values remain same across sites.

 Custom Object Utilization - Best Practices 12

Alternatives to Custom Objects

Creation of Custom Objects can have significant impact on platform performance, is usually
unnecessary, and should be avoided if there is another possible solution. The alternatives
are

Custom Preferences: - If the requirement is to store persistent custom data, Custom

Preferences is a viable option. The feature enables site developers to make
properties of the system modules configurable in Business Manager. Custom
preferences are defined in the context of either OrganizationPreferences System
Object or SitePreferences System Object. Custom Preferences feature allows the
following
o Defining a preference type
o Setting the value for a preference for a particular site
o Reading the value of preference from a script
o Grouping preference types into preference groups

Sessions: - Demandware Session storage is an option if the requirement is to store

session specific transient data. Using Sessions minimizes database access thus
proving faster response. Although session object, which is accessed by
dw.System.Session API supports storing custom values, there are limitations on what
and how much data can be stored in session. For example, persistent object,
collections and scripted objects cannot be stored in session. Please refer Infocenter
for details.

Cookies: - Cookies let you store data across sessions. The information is stored in
users browser and can be leveraged to implement certain use cases.

HTML5: Like cookies, HTML5 can be used to store data locally in users browser. The
advantage is that the stored data can be utilized without having to send the data with
every server request. Also HTML5 allows the storage of large data sets, compared to
cookies.

 Custom Object Utilization - Best Practices 13

External Systems: In some cases it is more efficient to maintain the data in external
systems and use synchronous web services for real time access. But such a design
depends on specific use cases and factors such as reliability, performance etc. and a
decision needs to be reached after carefully considering the pros and cons.

Generic Mapping: - The generic mapping capability enables you to map values to
keys, with the mapping stored in a high-performance, in memory data store that is
independent from the database. This capability supports large datasets, with high
performance for lookup. An example of using this feature is to map SKUs from a
backend system to Demandware SKUs on-the-fly in Demandware script, so that
interaction with the backend system is transparent and does not require adding
Demandware SKUs to the third party system. By using generic mapping,
Demandware customers can access in-memory key/value pairs that complement
product data in the database.