In this post, I will introduce you to some of the handy developers tools provided by Sitecore OrderCloud to help you get up and running quickly with OrderCloud and Next.js. We will look at how to seed OrderCloud with some sample data, use the Console API to query the data, spin up an instance of the headstart-nextjs application and finally deploy the application to Vercel.
Populating OrderCloud with sample data
If you have never worked with Sitecore OrderCloud one of the easiest way to understand the data structure is to populate it with some sample data. OrderCloud provides a handy utility for populating a marketplace with sample data for a B2C scenario. You can run the tool using NodeJS or via an exe (available on Windows, Linux and MacOS). To tool also supports validating data and downloading existing data from a marketplace.
To populate the same data using NodeJS run the command:
npx @ordercloud/seeding seed Simple-B2C -u={Your Username} -p={Your Password}
As you can see from the screenshot it creates a new Marketplace called Simple-B2C and populates it with the following data:
- 3 Security Profiles – are basically sets of Roles that you give a user, granting them access to certain endpoints within their token.
- 1 Admin User – users on an Organization/marketplace level are users that have administrative access to things like adding users, creating catalogs, processing orders or creating products.
- 1 Integration Event – integration events are a great way to delegate specific functions to your external applications. In this example the checkout process has been delegated to an external service url.
- 1 Catalog – a product can belong to any number of Catalogs, and a Catalog can be organized into hierarchical Categories to any arbitrary depth. Catalogs are assigned to Buyers, though visibility and pricing may vary by Buyer, User Group, Category, or individual Product.
- 9 Price Schedules – allow the same product to be sold across multiple channels. A price schedule may include quantity price breaks, min and max quantity per order, whether to apply tax or shipping calculations, or to what type of order the price schedule applies.
- 3 Specs – are used to capture user input when adding a Product to an Order. At its simplest, a spec is a name/value pair.
- 1 Product Facets – is an extended property (value on product.xp) designated to participate in faceted navigation.
- 1 Buyer – buyers, or customers, are the organizations that view the categories and products and place orders.
- 15 Categories – are used within a catalog to group and place content for a specific audience. Content can be in the form of another category, nested categories, products or HTML.
- 10 Spec Options – a spec can have multiple Options for example, if the spec is called ‘Color’, the options might be ‘Blue’, ‘Red’, and ‘Green’.
- 1 User – a user is a person with access to the application. The properties of a user define who they are and what they are able to do with their login to the application.
- 9 Products – represents a physical, digital, or abstract good that is offered for sale by a seller organization and is purchase-able by Buyer Users via an Order. Products can be a static SKU or a version of a static SKU, known as a Variant.
- 1 Catalog Assignments – catalogs are shared between buyers using assignments.
- 3 Api Clients – OrderCloud uses the term API Clients to identify various access points to your organization’s data. These access points have properties that control what parties can use it, how they can gain access, and for how long that access remains valid.
- 3 Security Profile Assignments – the users are assigned profiles.
- 9 Product Catalog Assignments – for Products to become available within a catalog, they need to be assigned to the catalog.
- 9 Product Category Assignments – products and categories are created in isolation from each other. In order to organize the catalog, you make assignments between Products and Categories.
- 7 Spec Product Assignments – are used to assign Specs to Products.
- 1 Api Client Assignment – assign API Clients.
The file used to populate the Sample-B2C data is located in the ordercloud-seed project repo if you want to explore the raw data used.
Using the API Console
The OrderCloud Portal provides an API Console allowing you to easily run any of the RESTful APIs to query and modify the data stored in your OrderCloud marketplace. First you’ll need to select a context, which is the marketplace you want interact with, in this case Sample-B2C. We can easily retrieve and review the sample data, we just created, or add, edit and delete using the appropriate API. The API Console is intuitive and the API reference guide is good source for understanding all the various APIs.
I would encourage you to go in and have a look at the data structures created and play with the API Console.
Running headstart-nextjs application
The OrderCloud headstart-nextjs is a simple buyer application and showcases some of the buyer features available in OrderCloud:
- Automatic Anonymous Authentication
- Registered User Login
- Product List
- Product Detail
- Cart
- Checkout
1. Running the sample nextjs application is straightforward.
2. Clone the headstart-nextjs repo
3.Create a .env file in your cloned project directory with the following variables:
NEXT_PUBLIC_OC_CLIENT_ID=ENTER_YOUR_BUYER_CLIENT_ID_HERE
NEXT_PUBLIC_OC_SCOPE=Shopper,MeAddressAdmin
NEXT_PUBLIC_OC_BASE_API_URL=https://sandboxapi.ordercloud.io
NEXT_PUBLIC_OC_ALLOW_ANONYMOUS=false
Note: You will need to add your Buyer Client Id. This can be retrieved using the Portal API console -> API Clients -> Storefront App -> Client ID copy the Client Id and add it to your .env file.
4. If you don’t already have Next and React installed run:
npm install next react react-dom
5. Now you should be ready to start the Next development server run:
npm run dev
6. This will make the headstart-nextjs application available on http://localhost:3000. Yes, it’s not the prettiest of applications, but its functional and serves its purpose in showing you how to get started building your own NextJS application with an OrderCloud integration AND how to use the various API methods. Its not production ready and is continually evolving.
7. You can quickly retrieve the list of products add a products to your cart etc. As you interact with the Application you can then verify data submitted to your marketplace using the API Console, for example you can then retrieve the cart using the Orders API to get a list of orders and view the contents of the order.
Deploying to Vercel
1. We need to ensure the headstart-next.js application is accessible for Vercel, so i’ve forked the project so it is accessible on my github account.
2. Then we will head over to Vercel and create an account, if you don’t already have have one that is. After signing up, you are taken to Import Project page where you can import a project from you chosen Git Provider or Clone an existing template.
3. We will following the instructions to setup our Git Repository integration with Vercel.
4. Once the Vercel is set up to access my repository, click Import to import the headstart-nextjs application. Vercel auto-detects the app is using Next.js and sets up the build configuration.
5. You are given the option to Create a Team but we will skip this step and Configure the Project. Here we can define the Build and Output settings, we will leave those as default. But remember those Environment variables we had to setup up for our local instance, we need to configure those in Vercel. So we will copy each from our local .env file.
6. Now we are ready to hit the Deploy button and watch as Vercel runs through its Deploy process:
- Fetching Source Code
- Skipping Build Cache
- Building
- Uploading Build Output
7. Once completed, someone at Vercel fires a Confetti Cannon, letting you know the process is complete and your Next.js application has been successfully deployed YEY!! And providing you with a public URL and a fancy dashboard with information about your application.
Useful Resources
Hope you found this useful!
Neil Killen 