Guido van Tricht

Sharing my thoughts about the OrderCloud Headstart application

When you get a demo from Sitecore about OrderCoud, they will probably do this based on the Headstart demo application. They might even suggest you use it as a starting point for your implementation.
Let’s look at what they have built for us.

The Headstart solution consists of three applications:

  1. Middleware; A ASP.NET Core based solution which exposes APIs which can be used by any frontend. It integrates with the OrderCloud SDK as well as OrderCloud Catalyst (both covered later) to integrate and extend OrderCloud.
  2. Buyer; An Angular based frontend application which includes a shopping UX.
  3. Seller; Another Angular based frontend application which demonstrates a UX for Catalog and Order management functionalities.

The Headstart solution also integrates with a couple of different 3rd-party services, like Avalara, Sitecore Send and Sitecore CDP.

Example integrations

The Headstart application contains some very useful examples of how you can implement certain things. For example, how to build Jobs or how to create Integration Events, but it is also a good starting point when you want to understand the flow of data.

It does a good job showing us how to use the many different APIs OrderCloud offers.
While building my own Middleware around OrderCloud, I was often confused as to why something was not working or why it was returning wrong data. Based on the implementation examples of the Headstart solution I was able to figure out how certain APIs should be used. For example, how I should use the SDK clients and access_token options, or which APIs I should use for the catalog experience for a shop frontend (using the ‘Me’ APIs instead of ‘Catalog’ APIs).

The solution also shows examples of some useful secondary functionalities, like Jobs and a ‘Seed’ functionality.
Jobs can be used to schedule certain functionalities. In the Headstart solution you can find examples of Jobs which perform scheduled actions to export things like Orders, Shipments and Payments.
The Seed functionality is a one-time job to populate OrderCloud with some required objects. This functionality I now use in my own application to create any mandatory objects in OrderCloud for any new organization we create. This way I can just run this Seed job whenever I spin-up a new environment instead of having to manually create a lot of objects in OrderCloud (like Security Profiles and Incrementors).

So, using the Headstart solution as a reference definitely has a lot of benefits. When you are stuck on building some functionality, then you most probably can find the solution to your problem in the Headstart repository.
I would therefore also encourage any developers new to OrderCloud to review some of the following features:

  • Environment Seed; Shows how to build a seed function and simultaneously also shows what kind of resources you would always need to create in any new OrderCloud organization. (Headstart.API.Commands.EnvironmentSeedCommand)
  • Payment Capture Job; Shows an example of a Job implementation and is probably something any commerce platform will need (Headstart.Jobs.PaymentCaptureJob)
  • Integration Events; Integration evens has been a difficult thing for me to grasp at first. How should I register these events? When do they trigger? What should be returned? etc. Looking at this example made it a bit easier to understand that process. (Headstart.Common.Controllers.CheckoutIntegrationController)

Not everything is great

The first thing I noticed when looking at the code base of the Middleware application is that it seems really opinionated.
Within this application the Command pattern is used extensively, meaning that every API triggers a Command to perform a task and return a result.
In my opinion however, a middleware application should have some level of abstraction. The middleware should expose endpoints for other applications to integrate with, but those applications, like frontends, should know nothing about which other systems are triggered in the background. With the current setup, the direct OrderCloud based objects are returned, so there is no abstraction whatsoever. Without a proper level of abstraction, you also vendor-lock your application, you make it more difficult to replace OrderCloud with another commerce system for example. But that might of course be a conscious decision you want to make.

A second thing I dislike about the Headstart solution is that the frontends are built on Angular. In my organization the preference for frontend frameworks often goes towards VueJS or React based frameworks, we stopped working with Angular a long time ago. For this reason, we would have to recreate the exact same applications, based on the functionalities of the middleware. In my opinion it would not make much sense to use this setup in that case at all, especially if you also need to integrate this frontend with a CMS, whether it is Sitecore, Content Hub or any other CMS.

Lastly, you need a lot of Azure resources to get this working in a non-prod environment. Even though you might need the functionalities provided by these services and resources, you might want to do it in a different way.
Recently Sitecore has made some changes to the application because of which it is now possible to host a local environment without having to rely on Azure resources, but you are still ‘stuck’ with having to use Storage Account and Cosmos in your platform.

So, would I use this Headstart application as a starting point for any of my solutions? No, probably not. But the application does show many examples which makes building your own application easier as you have something to copy from.
At the same time, it does show what your platform landscape might look like with the different applications necessary. The Headstart solution does a great job showing us that we will probably always require 3 applications, two of which are frontends for different uses and the 3rd is a reusable middleware application.
In a next post I will share some thoughts about why I think you will probably always end up with an architecture like Headstart has.

I want to emphasize that any opinions shared in this or any other article on this site are purely my own and are in no way related to any of the companies I worked for, currently work for or will work for in any future.