Loading...
Area: Optimizely B2B Commerce

Entity extension considerations

Recommended reading 

B2B Commerce is designed to be highly configurable and extensible to accommodate a multitude of business needs.

For example, an SAP ERP implementation stores customer data which includes organizational code. B2B Commerce does not include an organizational code on customer records. Therefore, there is a need to extend the B2B Commerce customer entity to map ERP properties to B2B Commerce properties.

Extension Options

B2B Commerce has two ways in which to extend the entities within the platform. This can be done one of the following ways:

  • Using the Application Dictionary
  • Using B2B Commerce .NET objects and methods

Using the Application Dictionary

The entities that define the blueprint of the digital commerce objects needed to operate the platform can be extended using the Admin Console. Additionally, security permissions for fields are also managed from the Application Dictionary. Extending entities within the Admin Console provides a means to enrich the commerce objects with additional data. These fields, or properties, are then populated using any of the following ways:

  • Users of the Admin Console
  • Developers using B2B Commerce .NET objects and methods
  • Configuration of Integration jobs
NOTE: Only basic types such as Boolean and Strings can be stored using application dictionary control types.

Using B2B Commerce .NET Objects and Methods

Custom properties can also be defined using code. This is usually done within a Handler of the Chain of Responsibility. Defining custom properties in code has the added advantage of storing complex types such as developer defined objects. The limitation here is that those custom properties cannot be edited within the Admin Console.

Implications of Using Custom Properties

From an implementation perspective, custom properties are stored as string values separate from the standard B2B Commerce objects, like Customer and Product. This flexibility in structure allows you to store a wide range of content, but can also cause a loss in application performance. Before using a custom property to store data, you should make the following considerations regarding the data and be certain that a custom property is the solution.

  • Does the data need to be managed in B2B Commerce? Does it need to be displayed in the Storefront or should the data only be managed in the ERP or PIM? If the data is not required as described above, you should consider not storing it in the platform and keeping it in an external system.
  • Does B2B Commerce provide a standard property that can store this data? Each B2B Commerce object provides quite a few properties and by default, some of them are not visible in the Admin Console. You can view them by enabling Master Edit Mode from the Debug Tools menu. Once that mode is enabled, you will see more properties displayed on the various detail pages.
  • If a standard property cannot be found, can the data be stored on one of the standard properties that is not currently in use? This might seem odd, but there may be standard properties not currently being used. If you find a standard property with the correct data type, you could store the data in that property. The name of the property won't match the data, but the performance benefits could outweigh the inconsistency.

Custom properties may still be the correct solution. If this is the case and you start to see performance degrading for requests that retrieve those custom properties, you should consider creating a custom endpoint. The endpoint could be used to return only the custom properties you actually need. For example, on the product detail page, you could have a request that retrieves custom properties for that product. This request would be separate from the main product API request that retrieves the product data. If this solution does not work, you could consider creating a custom database table to store the custom properties. The table could be designed specifically for those custom properties, rather than having a table full of string values.

Always consider the need for custom properties. They are a useful and flexible feature, but they can also cause a loss in application performance. Other solutions are available to help offset this loss.

Database Schema

The following tables are used for extending the entities and objects within B2B Commerce. Specifically these tables represent the schema used for custom properties and security. These entities are managed using the B2B Commerce Application Dictionary.

AppDict.PropertyConfiguration Table

Used to store the custom property definition. This custom property record is associated with the AppDict.EntityConfiguration table.

Column

Data Type

Description

Required

Id

Unique Identifier

The unique identifier.

Yes

EntityConfigurationID

Unique Identifier

The unique identifier of the configurations used for entities.

Yes

Name

nvarchar(256)

The unique name of the property used in code.

Yes

ParentProperty

nvarchar(256)

 

No

Label

nvarchar(256)

The label used to describe the property.

No

ControlType

nvarchar(2048)

The class definition that represents the UI control.

No

IsRequired

bit

Identifies if the property is required.

No

IsTranslatable

bit

Identifies if the property is included in translation services.

No

HintText

nvarchar(2048)

The string used for contextual help.

No

CreatedOn

datetimeoffset(7)

The date and time the property was created.

Yes

CreatedBy

nvarchar(100)

The username used to create the property.

Yes

ModifiedOn

datetimeoffset(7)

The date and time the property was modified.

Yes

ModifiedBy

nvarchar(100)

The username used to update the property.

Yes

ToolTip

nvarchar(256)

The string used as a description to the property.

No

PropertyType

nvarchar(2048)

The underlying data type used to store the property value.

No

IsCustomProperty

bit

Identifies if it is a custom property.

Yes

CanView

bit

Identifies if the property can be viewed when editing or viewing the entity details.

Yes

CanEdit

bit

Identifies if the property can be edited when editing or viewing the entity details.

Yes

AppDict.EntityConfiguration Table

Used to store the entities that can be used and extended within the platform.

Column

Data Type

Description

Required

Id

Unique Identifier

The unique identifier.

Yes

Name

nvarchar(256)

The name of the entity.

Yes

Description

nvarchar(2048)

The description of the entity.

No

Label

nvarchar(256)

The label used to describe the entity.

No

PluralizedLabel

nvarchar(256)

The label used to describe the entity when in a list.

No

DisplayNameFormat

nvarchar(1024)

 

No

InstructionalText

nvarchar(2048)

 

No

CreatedOn

datetimeoffset(7)

The date and time the property was created.

Yes

CreatedBy

nvarchar(100)

The username used to create the property.

Yes

ModifiedOn

datetimeoffset(7)

The date and time the property was modified.

Yes

ModifiedBy

nvarchar(100)

The username used to update the property.

Yes

CanView

bit

Identifies if an object from the entity can be viewed.

Yes

CanEdit

bit

Identifies if the entity can be edited.

Yes

CanCreate

bit

Identifies if an object from the entity can be created.

Yes

CanDelete

bit

Identifies if an object from the entity can be deleted.

Yes

AppDict.PropertyPermission Table

Used to store the permissions related to any custom properties added to the existing entities. By default the following roles are automatically assigned to custom properties (Property Configurations):

  • ISC_System
  • ISC_Integration
  • ISC_Admin
  • ISC_ContentAdmin
  • ISC_User
  • ISC_ContentApprover
  • ISC_ContentEditor

Column

Data Type

Description

Required

Id

Unique Identifier

The unique identifier.

Yes

PropertyConfigurationId

Unique Identifier

The unique identifier of the property configuration associated with the entity.

Yes

RoleName

nvarchar(256)

The role name allowed to interact with the property.

Yes

CreatedOn

datetimeoffset(7)

The date and time the property was created.

Yes

CreatedBy

nvarchar(100)

The username used to create the property.

Yes

ModifiedOn

datetimeoffset(7)

The date and time the property was modified.

Yes

ModifiedBy

nvarchar(100)

The username used to update the property.

Yes

CanView

bit

Identifies if the property can be viewed when editing or viewing the entity details.

Yes

CanEdit

bit

Identifies if the property can be edited when editing or viewing the entity details.

Yes

dbo.CustomProperty Table

Used to store the values for a given record of an extended entity.

Column

Data Type

Description

Required

Id

Unique Identifier

The unique identifier.

Yes

ParentId

Unique Identifier

Unique Id of the record that has been extended.

Yes

Name

nvarchar(100)

The name of the custom property.

Yes

Value

nvarchar(max)

The value of the objects custom property.

Yes

CreatedOn

datetimeoffset(7)

The date and time the property was created.

Yes

CreatedBy

nvarchar(100)

The username used to create the property.

Yes

ModifiedOn

datetimeoffset(7)

The date and time the property was modified.

Yes

ModifiedBy

nvarchar(100)

The username used to update the property.

Yes

ParentTable

nvarchar(100)

SQL table name of the entity that has been extended.

Yes

Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading