Transitioning from Sitecore Experience Commerce to OrderCloud: Customers to Buyer Users

 199 views

In this article, we will review and compare Sitecore Experience Commerce customers and OrderCloud buyer users to facilitate developers looking to transition from XC to OrderCloud as well as identify a path for migration of existing XC solutions to OrderCloud.

We will look at a high-level comparison of architecture, functionality, and data models, with greater focus on transitioning from Sitecore Experience Commerce, meaning identifying a close path to parity in OrderCloud, using the Habitat catalog and SXA Storefront.

Customers

The Customer to Storefront Association

In an XC SXA implementation, customer accounts are registered under a security domain, which can be configured in the Content Editor on the /sitecore/Content/<tenant>/<site>/Settings/Site Grouping/<storefront> item.

Figure 1: An example domain configuration for a storefront.

Customers can only be registered to a single security domain and will not be accessible in storefronts configured to a different domain. A separate customer account would need to be created under the other security domains, but it would have no knowledge or relationship to accounts across domains. However, a security domain can be registered to multiple storefronts allowing a customer to share an account across storefronts.

Figure 2: XC Security Domains have a zero to many relationship with Storefronts.

In OrderCloud, customers can be represented as buyer users, which are registered under buyer companies, and can only belong to a single buyer company. This can be compared directly to the relationship between security domains and customers.

The relationship of a buyer to an OrderCloud storefront is not tightly coupled like the SXA storefront. Access to an OrderCloud storefront is managed through API clients, security profiles and their assignments to buyers. See Getting Started > Establishing API Access for more information.

Figure 3: The basic structure comparison between customers to users.

The Customer to Catalog Association

Buyers also contain a DefaultCatalogID property, which will create an associated catalog with an ID matching the buyer ID if not specified during the creation of a buyer. While it may seem like this limits Buyer A to a single catalog (Catalog A), multiple catalogs can be assigned via OrderCloud's catalog assignments, which matches XC's equivalent in supporting both Catalog A and Catalog C associations to Security Domain A via storefronts (figure 4).

The DefaultCatalogID property will be utilised in certain APIs when a catalogID is not supplied in their request, however is can be overridden. For now it is only important to understand that this is not a limiting factor in OrderCloud functionality for migration of data or functionality.

Figure 4: XC relationship between customers and catalogs vs. OrderCloud's relationship between buyer users and catalogs.

OrderCloud User Groups

OrderCloud also allows buyer users to be assigned to one or more buyer user groups, which can be used to supersede assignments to buyer users in bulk, e.g. provide access to special pricing for VIP buyer users.

Figure 5: OrderCloud can group buyer users in buyer user groups.

Over in XC, a common customisation is an implementation of customer groups to assign customers in order to provide customer-group specific pricing, promotions, etc. While the implementation details may have the customer group represented as a separate custom entity or a property on a customer, conceptually both approaches achieve the same outcome (figure 6) and are on par with OrderCloud's architecture (figure 5), allowing a seamless transition path to OrderCloud.

Figure 6: Customer groups are a common customisation in XC, which can be thought of in a simliar respect to OrderCloud's buyer user groups, however it is not part of the default ecosystem.

Customer Addresses

In XC, customers have explicit addresses associations as the address component lives on the customer entity. The IsPrimary flag is used to allow a default address selection in implementations.

Figure 7: Customer addresses in XC.

In OrderCloud, addresses are separate objects that have an immediate association to the buyer, then with buyer address assignments addresses can have direct assignments to the buyer users or indirect assignments via buyer user groups.

Figure 8: Buyer address architecture in OrderCloud.

To bring across customer addresses into OrderCloud figure 9 shows that we would simply create buyer addresses with buyer address assignments for the buyer user only, not the buyer user groups, as well as adding the IsPrimary flag to the buyer address xp.

Figure 9: OrderCloud's representation of XC customer structure.

For buyer address assignments, there are two additional properties to consider, in IsShipping and IsBilling. These properties control whether the address can be assigned to an order as a shipping address or billing address respectively. As the SXA Storefront allows customer addresses to be used for both of these addresses, these flags on the buyer address assignments should be set to true.

Data Mapping

With the conceptual analysis above, we will now review what data mapping would look like for migration and from a comparison standpoint.

In the XC Entity/Component column, components are assumed to live on the primary XC entity being mapped.

OrderCloud IDs do not allow spaces. It is important that the IDs are parsed to remove/replace invalid characters consistently.

Buyers

The DefaultCatalogID property will be reviewed further during the catalog analysis article.

OC Property Data Type Required XC Entity/Component XC Property Data Type Notes
ID string No Customer Domain string
Active string Yes N/A N/A N/A Set to true by default.
Name string No Customer Domain string
DefaultCatalogID string Yes N/A N/A N/A Assign to an existing catalog or PATCH later.
xp object No N/A N/A N/A Any custom fields can be mapped to xp.

Buyer Users

There are a few properties in OrderCloud are required while not mandatory in the SXA Storefront, so considerations for handling these properties will need to be made in these instances, e.g. applying fallback values.

OC Property Data Type Required XC Entity/Component XC Property Data Type Notes
buyerID string Yes Customer Domain string Is a resource parameter, not body property.
ID string No Customer FriendlyId string
Username string Yes Customer LoginName string
Password string No N/A N/A N/A Password should not be migrated.
FirstName string Yes Customer FirstName string Not a mandatory field in SXA, so a fallback value will need to be populated.
LastName string Yes Customer LastName string Not a mandatory field in SXA, so a fallback value will need to be populated.
Email string Yes Customer Email string
Phone string No CustomerDetailsComponent PhoneNumber string The XC PhoneNumber exists under an entity view of the CustomerDetailsComponent, so consider this a rough mapping.
TermsAccepted string No N/A N/A N/A
Active boolean Yes Customer AccountStatus string Set to true where AccountStatus == "ActiveAccount"
xp object No N/A N/A N/A Any custom fields can be mapped to xp.

Buyer Addresses

For buyer addresses, IDs need to be unique, therefore creating a convention to append the customer's FriendlyId and the XC address' unique identifier, AddressName, ensures there will be no conflicts.

OrderCloud only stores the ISO 3166-1 alpha-2 2-letter country code. Retrieving additional country details, such as country name, would best be handled by custom middleware, outside of OrderCloud.

OC Property Data Type Required XC Entity/Component XC Property Data Type Notes
buyerID string Yes Customer Domain string Is a resource parameter, not body property.
ID string No Customer
AddressComponent
FriendlyId
Party.AddressName
string Using the convention <Customer.FriendlyId>_<Party.AddressName> will keep the address ID unique.
FirstName string No AddressComponent FirstName string SXA Storefront does not capture FirstName. May wish to use Customer.FirstName instead.
LastName string Yes AddressComponent LastName string SXA Storefront does not capture LastName. May wish to use Customer.LastName instead.
Street1 string Yes AddressComponent Party.Address1 string
Street2 string No AddressComponent Party.Address2 string
City string Yes AddressComponent Party.City string
State string Yes AddressComponent Party.StateCode string Can also use Party.State for full state name, depending on requirement.
Zip string Yes AddressComponent Party.ZipPostalCode string
Country string Yes AddressComponent Party.CountryCode string
Phone string No AddressComponent Party.PhoneNumber string Will be empty in SXA Storefront default implementation. May wish to use Customer.[CustomerDetailsComponent].PhoneNumber instead.
AddressName string No AddressComponent Party.AddressName string
xp object No N/A N/A N/A Any custom fields can be mapped to xp.
xp.IsPrimary object No AddressComponent Party.IsPrimary boolean

Buyer Address Assignments

Buyer address assignments are a straight forward mapping as per the table below.

OC Property Data Type Required XC Entity/Component XC Property Data Type Notes
buyerID string Yes Customer Domain string Is a resource parameter, not body property.
AddressID string Yes Customer
AddressComponent
FriendlyId
Party.AddressName
string <Customer.FriendlyId>_<Party.AddressName> to keep the address ID unique
UserID string No Customer FriendlyId string
UserGroupID string No N/A N/A N/A
IsShipping string No N/A N/A N/A Set to true.
IsBilling string No N/A N/A N/A Set to true.

References