How to Seed Sitecore OrderCloud with Sample Data and Anatomy of a B2C Solution

If you want to quickly get up and running with some test data in OrderCloud, you came to right place. In this post, not only will I show you how to seed OrderCloud with sample data, but I'll also walk through all of the individual data elements created by the seeding process and help you understand how it all ties together.

1.  Create OrderCloud Portal Account

Head over here to create your free OrderCloud portal account.

2.  Get Seeding Tool

You'll need to install Node.js on your machine in order to use the OrderCloud seeding npm package. Alternatively, you can download and run an executable from the OrderCloud seeding GitHub repo here. I'm going to use the npm package for this guide as I already have Node.js installed on my machine.

3.  Seed Data

OrderCloud provides seed data for a B2C use case here. Note that you can also download the provided seed data YAML file and modify it based on your own requirements, validate it using the seeding tool and then upload it from your file system. For the purpose of this tutorial I'll be using the seed data on the OrderCloud GitHub repo as-is.

In order to seed your OrderCloud instance with this sample data set, run the following command in cmd prompt (replacing your OrderCloud portal username and password):

npx @ordercloud/seeding seed Simple-B2C -u={username} -p={password}

You'll see the following success screen after running the command:

4.  Validation and Walkthrough

Now for the fun part- I'll walk you through the portal and help you understand the data that the seeding process has created. Most of these screens will be accessed from the API Console in the portal.

Marketplace

At the heart of all OrderCloud solutions is a marketplace (previously called a Seller). I strongly recommend you to read the post here before proceeding in order to understand the concept of a marketplace in the context of OrderCloud and the different roles the marketplace owner entity has depending on the business strategy implemented, i.e. B2C, B2B or marketplace.

As you can see below, a new marketplace called Simple-B2C has been created. The highlighted areas show key aspects such as environment details and your marketplace permissions. Since I've created the marketplace, I'm the owner.

Security Profiles

The following security profiles have been created for a standard B2C scenario, allowing anonymous & authenticated shopping as well as back office administration.

Security profiles are a combination of security roles that can be created to grant access to specific API endpoints and by extension, specific functionality. Note that security profiles can be assigned at the user, user group, buyer, supplier, or seller level. More details on security profiles can be found here.

Next, I'll drill down into each of these security profiles to show you what access they have. Note that the roles assigned to these security profiles are out of the box roles which are quite extensive, however you do have an option to also create custom roles to suit your unique business requirements.

Anonymous Shopper

The Anonymous Shopper security profile is for buyer users and has only been assigned the Shopper role which grants the base set of permissions required to shop as an anonymous user. More details on the this role can be found here.

Shopper

The Shopper security profile is also for buyer users and grants permissions to allow a shopping experience as an authenticated user. In addition to the base Shopper role, it has been assigned the required Me roles (MeAddressAdmin, MeAdmin, MeCreditCardAdmin, MeXpAdmin) and the PasswordReset role which allows the user to create and manage their account. More details on Me roles can be found here.  

Back Office Admin

Lastly, the Back Office Admin security profile is for administrators of OrderCloud and has been assigned the FullAccess role to allow them to perform all actions.

Admin Users

A single admin user has been created as the default context user for integrations.

Buyers

A single buyer organisation with a default catalog assignment has been created to represent the B2C customer segment and will contain your B2C users. A buyer represents a real world entity that you are selling to as a seller. In a B2B or combination B2B+B2C scenario, you may have multiple buyers with each buyer having one or more users with product visibility and pricing controlled at the buyer level.

Users

A single user has been created under the B2C buyer 'Solitary Storefront' to represent an anonymous shopper. From the assigned roles in the screenshot below, it seems that the user has been assigned the Anonymous Shopper security profile discussed above, however upon inspection of the seed YAML file, it looks like the roles have also been assigned directly to the user.

This user context will be used when making calls to the OrderCloud API from the storefront when a user has not logged in. Another thing to note is the demonstration of extended properties (XP) highlighted below where a custom property has been added to the user resource.

Security Profile Assignments

Security profiles can be assigned at the user, user group, buyer, supplier, or seller level. Usually, it's not recommended to assign them at the user level as management then becomes very cumbersome. It's better to assign them at a higher level such as a user group or buyer/supplier/seller level. More details on creating and assigning security profiles can be found here and here.

In this case, the following security profile assignments have been done at the Buyer level:

• Security profile with ID 'anon-shopper' (anonymous shopper) is assigned to Buyer with ID solitary-storefront
• Security profile with ID 'shopper' (authenticated shopper) is assigned to Buyer with ID solitary-storefront

Eagle eyed readers may have noticed that multiple security profiles have been assigned to the same Buyer. Also, you might remember that specific roles were also assigned to the user directly when discussing the Users section above. How does this work? Basically in this case, a union merge is done of all the roles assigned directly or indirectly- more on this here.

Catalogs

A single catalog called 'Solitary Storefront' owned by the Simple-B2C marketplace (seller) organisation has been created and associated to the solitary-storefront Buyer. Read more about catalogs here and how to manage catalogs and catalog assignments here.

Categories

Various categories have been created under the default 'Solitary Storefront' catalog. Note that this includes nested categories as can be seen by the ParentID and ChildCount fields. More information on managing categories can be found here.

Products, Product Catalog Assignments & Variants

Various products have been created under different categories. At a high level, products can be setup as standalone individual SKUs or as Variants which are different versions of the product SKU. E.g. a shirt may have multiple variants based on colour, size etc. There is also a related concept of Specs which can be used to generate or drive different SKUs/Variants of a product as well- I'll cover Variants and Specs in a dedicated post as it warrants further exploration.

Additionally, you can set various attributes (including custom attributes) on products such as inventory, dimensions, weight etc among others. More information on creating and managing products can be found here and here.

When getting the list of products, you'll notice that the response does not return associated catalogs. This is because the same product may be part of multiple catalogs (in this case however, all products are associated to a single catalog). To get all products that are part of a catalog called 'Solitary Storefront', you can supply the Catalog ID in the request above. Alternatively, you can get this by calling the list product assignments endpoint:

Additionally, you can get a list of variants for a product using the list product variants endpoint:

Category Product Assignments

Products can be associated to one or multiple categories via category product assignments.

Price Schedules

Various price schedules have been created corresponding to each of the products. The price schedules in this case are owned by the marketplace organisation. Various fields can be set here to control aspects such as min/max quantities allowed, price breaks for tiered pricing and flags to control shipping and tax among other things. More details on this can be found here.

In this scenario, we have only one a single Buyer organisation which is the B2C storefront and price schedules are fairly straightforward with a one to one mapping to the product and buyer org. In a B2B or B2B+B2C combination model, you can assign multiple price schedules to the same product by creating separate price schedules with different pricing for different buyers. This allows you set variable pricing for the same product based on the type of buyer. You can read more on this here and here.  

Specs, Spec Options & Spec Product Assignments

Specs are a set of options that can be associated with a product and are used to capture user selections when buying a product. Various Specs are created here to be associated to products in a separate step. One of the examples in this case is multiple colour options for a particular product. When setting up Specs, you can also additional attributes for each option via extended properties (XP) and price markups/markdowns based on the selected option. This can also be used to drive multiple product SKUs (variants) based on spec combinations. More information on this can be found here.

Once Spec Options and Specs are created, the Specs have been assigned to applicable products. We can get all spec assignments using the  list spec product assignments endpoint:

Product Facets

Product facets are used to provided faceted navigation when searching for products. In this case, a facet is created for colour with multiple colour options. More information on product facets can be found here and here.

Catalog Assignments

When getting a list of catalogs, you'll notice that the response does not contain catalogs assignments. This is because catalogs can be shared between buyers. To get the list catalog assignments, you can query the list catalog assignment endpoint. In this case, you'll see the 'Solitary Storefront' catalog is assigned to the default 'Solitary Storefront' B2C buyer.  

Integration Events

A single integration event of type 'OrderCheckout' pointing to a custom implementation endpoint has been created to allow for extension of the checkout.  

Integration events are extension points of the OrderCloud platform through which logic can either be extended or delegated to external systems such as your middleware (e.g. estimating shipping costs during checkout).  

Read more on the OrderCheckout integration event type here, integration events in general here, and the API reference here.

API Clients & API Client Assignments

API clients have to be configured to allow applications to interact with the OrderCloud APIs. API authentication & authorisation is based on OAuth 2.0. The best practice is to setup separate API clients based on the consuming application allowing you to independently define and control access as required.

At a high level, you can define the following for an OrderCloud API client:

• Client ID: Used for OAuth 2.0 flow and OrderCloud impersonation.
• Client Secret: Used to enable OAuth 2.0 client credentials grant flow.
• Token duration: Set token & refresh token expiry/duration.
• User access:
  • Allow/deny access to all Sellers
  • Allow/deny access to all Suppliers
  • Allow access to specific Suppliers only
  • Allow/deny access to all Buyers
  • Allow access to specific Buyers only
• Set default context user: This optional field lets you set the context user when authenticating with a client credentials grant flow for anonymous browsing or ascess from server side applications.
• Anonymous buyer flag: Enables anonymous shopping when a buyer user is set as the default context user.

More information on API clients can be found here and here.

Three API clients have been created as part of the seeding process- one for the storefront app (buyer experience), one for middleware integrations, and one for the back office admin app (seller/admin experience).

The example above shows the interface that allows you to configure each API client. Let's go through settings for each of them individually:

Storefront App

Middleware Integrations

Back Office App

We've covered alot in this post and it'll take a while to absorb it all.  The best way is to get hands on and start exploring yourself. Hopefully this guide gave you a good headstart in understanding how various elements of the platform are set up and how they relate to each other. Stay tuned for future posts where I'll be digging deeper into some interesting use cases such as setting up variable pricing, controlling product visibility, and marketplace nuances among other things.