buyers

Reading Time: 5 minutes

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 this 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.

To bring across customer addresses into OrderCloud, figure 8 shows that we can create buyer user addresses, via the /me/addresses resource, creating a custom IsPrimary flag in the buyer address xp.

Figure 8: Buyer user address architecture in OrderCloud.

Buyer user addresses, also contain Shipping and Billing properties, which can facilitate filtering addresses for the purpose of being retrieving and setting for an order’s shipping address or billing address respectively. As the SXA Storefront allows customer addresses to be used for both of these addresses, these flags should also 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.

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 User Addresses

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
Shipping	boolean	No	N/A	N/A	N/A	Set to `true`
Billing	boolean	No	N/A	N/A	N/A	Set to `true`
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

Tag: buyers

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